From bdb328d1652457bb0187b99947fdb90268aa2e4a Mon Sep 17 00:00:00 2001 From: nenharper Date: Tue, 30 Sep 2025 17:43:13 -0500 Subject: [PATCH 1/6] Documentation for Operations API --- .../developers/applications/operations-api.md | 278 +++ .../advanced-json-sql-examples.md | 1775 +++++++++++++++++ .../reference/operations-api/analytics.md | 121 ++ .../operations-api/bulk-operations.md | 255 +++ .../operations-api/certificate-management.md | 124 ++ .../operations-api/clustering-nats.md | 486 +++++ .../reference/operations-api/clustering.md | 355 ++++ .../reference/operations-api/components.md | 543 +++++ .../reference/operations-api/configuration.md | 135 ++ .../operations-api/custom-functions.md | 279 +++ .../operations-api/databases-and-tables.md | 388 ++++ .../reference/operations-api/index.md | 55 + .../reference/operations-api/jobs.md | 87 + .../reference/operations-api/logs.md | 732 +++++++ .../operations-api/nosql-operations.md | 389 ++++ .../operations-api/quickstart-examples.md | 370 ++++ .../reference/operations-api/registration.md | 70 + .../operations-api/sql-operations.md | 127 ++ .../operations-api/system-operations.md | 195 ++ .../operations-api/token-authentication.md | 60 + .../operations-api/users-and-roles.md | 508 +++++ 21 files changed, 7332 insertions(+) create mode 100644 versioned_docs/version-4.6/developers/applications/operations-api.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/advanced-json-sql-examples.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/analytics.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/bulk-operations.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/certificate-management.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/clustering-nats.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/clustering.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/components.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/configuration.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/custom-functions.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/databases-and-tables.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/index.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/jobs.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/logs.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/nosql-operations.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/quickstart-examples.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/registration.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/sql-operations.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/system-operations.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/token-authentication.md create mode 100644 versioned_docs/version-4.6/reference/operations-api/users-and-roles.md diff --git a/versioned_docs/version-4.6/developers/applications/operations-api.md b/versioned_docs/version-4.6/developers/applications/operations-api.md new file mode 100644 index 00000000..dbcd544d --- /dev/null +++ b/versioned_docs/version-4.6/developers/applications/operations-api.md @@ -0,0 +1,278 @@ +--- +title: Operations API +--- + +# Operations API + +Think of the Operations API as the command center for Harper. It’s the layer that lets you create databases and tables, insert and query data, monitor system health, and even fine-tune configuration, all through JSON calls. Instead of jumping between tools or UIs, the API gives you everything you need to shape your data story programmatically. + +To show you how it works, we’ll use a familiar example: building a database for our company’s dogs 🐶. Step by step, we’ll go from nothing to a working system, and along the way, you’ll see how easy it is to extend Harper as your needs grow. + +For full details on every operation, check out the [Operations API reference](../../reference/operations-api/). But for now, let’s walk through the journey. + +## Step 1: Create a Database + +Everything in Harper starts with a database. Think of it as the logical container for your tables and data. If you don’t explicitly create one, Harper defaults to a database called data. But let’s create our own to keep things organized. + +```json +{ + "operation": "create_database", + "database": "dev" +} +``` + +If successful, Harper responds with: + +```json +{ + "message": "database 'dev' successfully created" +} +``` + +👉 See more in the [Databases and Tables reference](../../reference/operations-api/databases-and-tables) + +## Step 2: Create a Table + +Inside our database, we’ll create a table to store information about dogs. Every table needs a primary key. In Harper, this is often an `id`. + +```json +{ + "operation": "create_table", + "database": "dev", + "table": "dog", + "primary_key": "id" +} +``` + +Response: + +```json +{ + "message": "table 'dev.dog' successfully created." +} +``` + +Just like that, you now have a table ready to accept records. + +## Step 3: Insert Data + +Let’s add our first record: Penny, a dog we care about. + +```json +{ + "operation": "insert", + "database": "dev", + "table": "dog", + "records": [ + { + "id": 1, + "dog_name": "Penny", + "owner_name": "Kyle", + "breed_id": 154, + "age": 7, + "weight_lbs": 38 + } + ] +} +``` + +Response: + +```json +{ + "message": "inserted 1 of 1 records", + "inserted_hashes": [1], + "skipped_hashes": [] +} +``` + +Harper makes inserts painless. If you add new attributes not defined in the schema, Harper will create them automatically unless you’ve locked things down with explicit attributes. + +More examples in the [NoSQL Operations reference](../../reference/operations-api/nosql-operations). + +## Step 4: Query Data + +Now that we have data, let’s retrieve it. You can query using NoSQL operations like `search_by_id` or `search_by_value`, or you can use SQL. + +**NoSQL Example**: +```json +{ + "operation": "search_by_id", + "database": "dev", + "table": "dog", + "ids": [1], + "get_attributes": ["dog_name", "owner_name"] +} +``` + +Response: +```json +[ + { + "dog_name": "Penny", + "owner_name": "Kyle" + } +] +``` + +**SQL Example:** +```json +{ + "operation": "sql", + "sql": "SELECT * FROM dev.dog WHERE id = 1" +} +``` + +Response: +```json +[ + { + "id": 1, + "dog_name": "Penny", + "owner_name": "Kyle", + "age": 7, + "weight_lbs": 38, + "breed_id": 154 + } +] +``` + +👉 Explore more in the [SQL Operations reference](../../reference/operations-api/sql-operations) + +## Step 5: Update Data + +Dogs grow and change, and so does data. Updating Penny’s name is as simple as: + +```json +{ + "operation": "update", + "database": "dev", + "table": "dog", + "records": [ + { + "id": 1, + "dog_name": "Penny B" + } + ] +} +``` + +Response: + +```json +{ + "message": "updated 1 of 1 records", + "update_hashes": [1], + "skipped_hashes": [] +} +``` + +## Step 6: Monitor Jobs and Logs + +Harper tracks background jobs (like CSV imports) and system logs (like errors or warnings). + +**Check a job:** + +```json +{ + "operation": "get_job", + "id": "4a982782-929a-4507-8794-26dae1132def" +} +``` + +**Read logs:** +```json +{ + "operation": "read_log", + "limit": 100, + "level": "error" +} +``` + +This is critical when you’re troubleshooting imports or watching for application errors. See [Jobs](../../reference/operations-api/jobs) and [Logs](../../reference/operations-api/logs) for full coverage. + +## Step 7: Tune Configuration and Restart + +As workloads grow, you might want to adjust configuration. For example, increasing logging verbosity or enabling clustering. + +```json +{ + "operation": "set_configuration", + "logging_level": "trace", + "clustering_enabled": true +} +``` + +Changes require a restart: + +```json +{ + "operation": "restart" +} +``` + +Full details in the [Configuration](../../reference/operations-api/configuration) and [System Operations](../../reference/operations-api/system-operations) docs. + +## Step 8: Secure Your Instance + +Harper gives you fine-grained control over who can do what. You can create roles, assign permissions, and manage users. + +Add a role: + +```json +{ + "operation": "add_role", + "role": "developer", + "permission": { + "dev": { + "tables": { + "dog": { + "read": true, + "insert": true, + "update": true, + "delete": false + } + } + } + } +} +``` + +Add a user: + +```json +{ + "operation": "add_user", + "role": "developer", + "username": "hdb_user", + "password": "password", + "active": true +} +``` + +For token-based authentication: + +```json +{ + "operation": "create_authentication_tokens", + "username": "hdb_user", + "password": "password" +} +``` + +More in [Users and Roles](../../reference/operations-api/users-and-roles) and [Token Authentication](../../reference/operations-api/token-authentication). + +## Step 9: Advanced Operations + +Finally, Harper provides deeper operational tools when you need them: +- Backups with `get_backup` +- Audit logs with `read_audit_log` +- License management with `set_license` + +See the [full Operations API reference](../../reference/operations-api/) for every option. + +___ + +From creating a database and table to inserting data, querying with SQL or NoSQL, monitoring logs, tuning the system, and locking down security, the Operations API gives you the complete toolkit to run Harper programmatically. + +It’s simple to start small (one table, one record) and grow into advanced scenarios as your application evolves. And since everything is JSON, you can automate workflows from day one. \ No newline at end of file diff --git a/versioned_docs/version-4.6/reference/operations-api/advanced-json-sql-examples.md b/versioned_docs/version-4.6/reference/operations-api/advanced-json-sql-examples.md new file mode 100644 index 00000000..ec300e2e --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/advanced-json-sql-examples.md @@ -0,0 +1,1775 @@ +--- +title: Advanced JSON SQL Examples +--- + +# Advanced JSON SQL Examples + +## Create movies database + +Create a new database called "movies" using the 'create_database' operation. + +_Note: Creating a database is optional, if one is not created Harper will default to using a database named `data`_ + +### Body + +```json +{ + "operation": "create_database", + "database": "movies" +} +``` + +### Response: 200 + +```json +{ + "message": "database 'movies' successfully created" +} +``` + +--- + +## Create movie Table + +Creates a new table called "movie" inside the database "movies" using the ‘create_table’ operation. + +### Body + +```json +{ + "operation": "create_table", + "database": "movies", + "table": "movie", + "primary_key": "id" +} +``` + +### Response: 200 + +```json +{ + "message": "table 'movies.movie' successfully created." +} +``` + +--- + +## Create credits Table + +Creates a new table called "credits" inside the database "movies" using the ‘create_table’ operation. + +### Body + +```json +{ + "operation": "create_table", + "database": "movies", + "table": "credits", + "primary_key": "movie_id" +} +``` + +### Response: 200 + +```json +{ + "message": "table 'movies.credits' successfully created." +} +``` + +--- + +## Bulk Insert movie Via CSV + +Inserts data from a hosted CSV file into the "movie" table using the 'csv_url_load' operation. + +### Body + +```json +{ + "operation": "csv_url_load", + "database": "movies", + "table": "movie", + "csv_url": "https://search-json-sample-data.s3.us-east-2.amazonaws.com/movie.csv" +} +``` + +### Response: 200 + +```json +{ + "message": "Starting job with id 1889eee4-23c1-4945-9bb7-c805fc20726c" +} +``` + +--- + +## Bulk Insert credits Via CSV + +Inserts data from a hosted CSV file into the "credits" table using the 'csv_url_load' operation. + +### Body + +```json +{ + "operation": "csv_url_load", + "database": "movies", + "table": "credits", + "csv_url": "https://search-json-sample-data.s3.us-east-2.amazonaws.com/credits.csv" +} +``` + +### Response: 200 + +```json +{ + "message": "Starting job with id 3a14cd74-67f3-41e9-8ccd-45ffd0addc2c", + "job_id": "3a14cd74-67f3-41e9-8ccd-45ffd0addc2c" +} +``` + +--- + +## View raw data + +In the following example we will be running expressions on the keywords & production_companies attributes, so for context we are displaying what the raw data looks like. + +### Body + +```json +{ + "operation": "sql", + "sql": "SELECT title, rank, keywords, production_companies FROM movies.movie ORDER BY rank LIMIT 10" +} +``` + +### Response: 200 + +```json +[ + { + "title": "Ad Astra", + "rank": 1, + "keywords": [ + { + "id": 305, + "name": "moon" + }, + { + "id": 697, + "name": "loss of loved one" + }, + { + "id": 839, + "name": "planet mars" + }, + { + "id": 14626, + "name": "astronaut" + }, + { + "id": 157265, + "name": "moon colony" + }, + { + "id": 162429, + "name": "solar system" + }, + { + "id": 240119, + "name": "father son relationship" + }, + { + "id": 244256, + "name": "near future" + }, + { + "id": 257878, + "name": "planet neptune" + }, + { + "id": 260089, + "name": "space walk" + } + ], + "production_companies": [ + { + "id": 490, + "name": "New Regency Productions", + "origin_country": "" + }, + { + "id": 79963, + "name": "Keep Your Head", + "origin_country": "" + }, + { + "id": 73492, + "name": "MadRiver Pictures", + "origin_country": "" + }, + { + "id": 81, + "name": "Plan B Entertainment", + "origin_country": "US" + }, + { + "id": 30666, + "name": "RT Features", + "origin_country": "BR" + }, + { + "id": 30148, + "name": "Bona Film Group", + "origin_country": "CN" + }, + { + "id": 22213, + "name": "TSG Entertainment", + "origin_country": "US" + } + ] + }, + { + "title": "Extraction", + "rank": 2, + "keywords": [ + { + "id": 3070, + "name": "mercenary" + }, + { + "id": 4110, + "name": "mumbai (bombay), india" + }, + { + "id": 9717, + "name": "based on comic" + }, + { + "id": 9730, + "name": "crime boss" + }, + { + "id": 11107, + "name": "rescue mission" + }, + { + "id": 18712, + "name": "based on graphic novel" + }, + { + "id": 265216, + "name": "dhaka (dacca), bangladesh" + } + ], + "production_companies": [ + { + "id": 106544, + "name": "AGBO", + "origin_country": "US" + }, + { + "id": 109172, + "name": "Thematic Entertainment", + "origin_country": "US" + }, + { + "id": 92029, + "name": "TGIM Films", + "origin_country": "US" + } + ] + }, + { + "title": "To the Beat! Back 2 School", + "rank": 3, + "keywords": [ + { + "id": 10873, + "name": "school" + } + ], + "production_companies": [] + }, + { + "title": "Bloodshot", + "rank": 4, + "keywords": [ + { + "id": 2651, + "name": "nanotechnology" + }, + { + "id": 9715, + "name": "superhero" + }, + { + "id": 9717, + "name": "based on comic" + }, + { + "id": 164218, + "name": "psychotronic" + }, + { + "id": 255024, + "name": "shared universe" + }, + { + "id": 258575, + "name": "valiant comics" + } + ], + "production_companies": [ + { + "id": 34, + "name": "Sony Pictures", + "origin_country": "US" + }, + { + "id": 10246, + "name": "Cross Creek Pictures", + "origin_country": "US" + }, + { + "id": 6573, + "name": "Mimran Schur Pictures", + "origin_country": "US" + }, + { + "id": 333, + "name": "Original Film", + "origin_country": "US" + }, + { + "id": 103673, + "name": "The Hideaway Entertainment", + "origin_country": "US" + }, + { + "id": 124335, + "name": "Valiant Entertainment", + "origin_country": "US" + }, + { + "id": 5, + "name": "Columbia Pictures", + "origin_country": "US" + }, + { + "id": 1225, + "name": "One Race", + "origin_country": "US" + }, + { + "id": 30148, + "name": "Bona Film Group", + "origin_country": "CN" + } + ] + }, + { + "title": "The Call of the Wild", + "rank": 5, + "keywords": [ + { + "id": 818, + "name": "based on novel or book" + }, + { + "id": 4542, + "name": "gold rush" + }, + { + "id": 15162, + "name": "dog" + }, + { + "id": 155821, + "name": "sled dogs" + }, + { + "id": 189390, + "name": "yukon" + }, + { + "id": 207928, + "name": "19th century" + }, + { + "id": 259987, + "name": "cgi animation" + }, + { + "id": 263806, + "name": "1890s" + } + ], + "production_companies": [ + { + "id": 787, + "name": "3 Arts Entertainment", + "origin_country": "US" + }, + { + "id": 127928, + "name": "20th Century Studios", + "origin_country": "US" + }, + { + "id": 22213, + "name": "TSG Entertainment", + "origin_country": "US" + } + ] + }, + { + "title": "Sonic the Hedgehog", + "rank": 6, + "keywords": [ + { + "id": 282, + "name": "video game" + }, + { + "id": 6054, + "name": "friendship" + }, + { + "id": 10842, + "name": "good vs evil" + }, + { + "id": 41645, + "name": "based on video game" + }, + { + "id": 167043, + "name": "road movie" + }, + { + "id": 172142, + "name": "farting" + }, + { + "id": 188933, + "name": "bar fight" + }, + { + "id": 226967, + "name": "amistad" + }, + { + "id": 245230, + "name": "live action remake" + }, + { + "id": 258111, + "name": "fantasy" + }, + { + "id": 260223, + "name": "videojuego" + } + ], + "production_companies": [ + { + "id": 333, + "name": "Original Film", + "origin_country": "US" + }, + { + "id": 10644, + "name": "Blur Studios", + "origin_country": "US" + }, + { + "id": 77884, + "name": "Marza Animation Planet", + "origin_country": "JP" + }, + { + "id": 4, + "name": "Paramount", + "origin_country": "US" + }, + { + "id": 113750, + "name": "SEGA", + "origin_country": "JP" + }, + { + "id": 100711, + "name": "DJ2 Entertainment", + "origin_country": "" + }, + { + "id": 24955, + "name": "Paramount Animation", + "origin_country": "US" + } + ] + }, + { + "title": "Birds of Prey (and the Fantabulous Emancipation of One Harley Quinn)", + "rank": 7, + "keywords": [ + { + "id": 849, + "name": "dc comics" + }, + { + "id": 9717, + "name": "based on comic" + }, + { + "id": 187056, + "name": "woman director" + }, + { + "id": 229266, + "name": "dc extended universe" + } + ], + "production_companies": [ + { + "id": 9993, + "name": "DC Entertainment", + "origin_country": "US" + }, + { + "id": 82968, + "name": "LuckyChap Entertainment", + "origin_country": "GB" + }, + { + "id": 103462, + "name": "Kroll & Co Entertainment", + "origin_country": "US" + }, + { + "id": 174, + "name": "Warner Bros. Pictures", + "origin_country": "US" + }, + { + "id": 429, + "name": "DC Comics", + "origin_country": "US" + }, + { + "id": 128064, + "name": "DC Films", + "origin_country": "US" + }, + { + "id": 101831, + "name": "Clubhouse Pictures", + "origin_country": "US" + } + ] + }, + { + "title": "Justice League Dark: Apokolips War", + "rank": 8, + "keywords": [ + { + "id": 849, + "name": "dc comics" + } + ], + "production_companies": [ + { + "id": 2785, + "name": "Warner Bros. Animation", + "origin_country": "US" + }, + { + "id": 9993, + "name": "DC Entertainment", + "origin_country": "US" + }, + { + "id": 429, + "name": "DC Comics", + "origin_country": "US" + } + ] + }, + { + "title": "Parasite", + "rank": 9, + "keywords": [ + { + "id": 1353, + "name": "underground" + }, + { + "id": 5318, + "name": "seoul" + }, + { + "id": 5732, + "name": "birthday party" + }, + { + "id": 5752, + "name": "private lessons" + }, + { + "id": 9866, + "name": "basement" + }, + { + "id": 10453, + "name": "con artist" + }, + { + "id": 11935, + "name": "working class" + }, + { + "id": 12565, + "name": "psychological thriller" + }, + { + "id": 13126, + "name": "limousine driver" + }, + { + "id": 14514, + "name": "class differences" + }, + { + "id": 14864, + "name": "rich poor" + }, + { + "id": 17997, + "name": "housekeeper" + }, + { + "id": 18015, + "name": "tutor" + }, + { + "id": 18035, + "name": "family" + }, + { + "id": 33421, + "name": "crime family" + }, + { + "id": 173272, + "name": "flood" + }, + { + "id": 188861, + "name": "smell" + }, + { + "id": 198673, + "name": "unemployed" + }, + { + "id": 237462, + "name": "wealthy family" + } + ], + "production_companies": [ + { + "id": 7036, + "name": "CJ Entertainment", + "origin_country": "KR" + }, + { + "id": 4399, + "name": "Barunson E&A", + "origin_country": "KR" + } + ] + }, + { + "title": "Star Wars: The Rise of Skywalker", + "rank": 10, + "keywords": [ + { + "id": 161176, + "name": "space opera" + } + ], + "production_companies": [ + { + "id": 1, + "name": "Lucasfilm", + "origin_country": "US" + }, + { + "id": 11461, + "name": "Bad Robot", + "origin_country": "US" + }, + { + "id": 2, + "name": "Walt Disney Pictures", + "origin_country": "US" + }, + { + "id": 120404, + "name": "British Film Commission", + "origin_country": "" + } + ] + } +] +``` + +--- + +## Simple search_json call + +This query uses search_json to convert the keywords object array to a simple string array. The expression '[name]' tells the function to extract all values for the name attribute and wrap them in an array. + +### Body + +```json +{ + "operation": "sql", + "sql": "SELECT title, rank, search_json('[name]', keywords) as keywords FROM movies.movie ORDER BY rank LIMIT 10" +} +``` + +### Response: 200 + +```json +[ + { + "title": "Ad Astra", + "rank": 1, + "keywords": [ + "moon", + "loss of loved one", + "planet mars", + "astronaut", + "moon colony", + "solar system", + "father son relationship", + "near future", + "planet neptune", + "space walk" + ] + }, + { + "title": "Extraction", + "rank": 2, + "keywords": [ + "mercenary", + "mumbai (bombay), india", + "based on comic", + "crime boss", + "rescue mission", + "based on graphic novel", + "dhaka (dacca), bangladesh" + ] + }, + { + "title": "To the Beat! Back 2 School", + "rank": 3, + "keywords": ["school"] + }, + { + "title": "Bloodshot", + "rank": 4, + "keywords": ["nanotechnology", "superhero", "based on comic", "psychotronic", "shared universe", "valiant comics"] + }, + { + "title": "The Call of the Wild", + "rank": 5, + "keywords": [ + "based on novel or book", + "gold rush", + "dog", + "sled dogs", + "yukon", + "19th century", + "cgi animation", + "1890s" + ] + }, + { + "title": "Sonic the Hedgehog", + "rank": 6, + "keywords": [ + "video game", + "friendship", + "good vs evil", + "based on video game", + "road movie", + "farting", + "bar fight", + "amistad", + "live action remake", + "fantasy", + "videojuego" + ] + }, + { + "title": "Birds of Prey (and the Fantabulous Emancipation of One Harley Quinn)", + "rank": 7, + "keywords": ["dc comics", "based on comic", "woman director", "dc extended universe"] + }, + { + "title": "Justice League Dark: Apokolips War", + "rank": 8, + "keywords": ["dc comics"] + }, + { + "title": "Parasite", + "rank": 9, + "keywords": [ + "underground", + "seoul", + "birthday party", + "private lessons", + "basement", + "con artist", + "working class", + "psychological thriller", + "limousine driver", + "class differences", + "rich poor", + "housekeeper", + "tutor", + "family", + "crime family", + "flood", + "smell", + "unemployed", + "wealthy family" + ] + }, + { + "title": "Star Wars: The Rise of Skywalker", + "rank": 10, + "keywords": ["space opera"] + } +] +``` + +--- + +## Use search_json in a where clause + +This example shows how we can use SEARCH_JSON to filter out records in a WHERE clause. The production_companies attribute holds an object array of companies that produced each movie, we want to only see movies which were produced by Marvel Studios. Our expression is a filter '$[name="Marvel Studios"]' this tells the function to iterate the production_companies array and only return entries where the name is "Marvel Studios". + +### Body + +```json +{ + "operation": "sql", + "sql": "SELECT title, release_date FROM movies.movie where search_json('$[name=\"Marvel Studios\"]', production_companies) IS NOT NULL ORDER BY release_date" +} +``` + +### Response: 200 + +```json +[ + { + "title": "Iron Man", + "release_date": "2008-04-30" + }, + { + "title": "The Incredible Hulk", + "release_date": "2008-06-12" + }, + { + "title": "Iron Man 2", + "release_date": "2010-04-28" + }, + { + "title": "Thor", + "release_date": "2011-04-21" + }, + { + "title": "Captain America: The First Avenger", + "release_date": "2011-07-22" + }, + { + "title": "Marvel One-Shot: The Consultant", + "release_date": "2011-09-12" + }, + { + "title": "Marvel One-Shot: A Funny Thing Happened on the Way to Thor's Hammer", + "release_date": "2011-10-25" + }, + { + "title": "The Avengers", + "release_date": "2012-04-25" + }, + { + "title": "Marvel One-Shot: Item 47", + "release_date": "2012-09-13" + }, + { + "title": "Iron Man 3", + "release_date": "2013-04-18" + }, + { + "title": "Marvel One-Shot: Agent Carter", + "release_date": "2013-09-08" + }, + { + "title": "Thor: The Dark World", + "release_date": "2013-10-29" + }, + { + "title": "Marvel One-Shot: All Hail the King", + "release_date": "2014-02-04" + }, + { + "title": "Marvel Studios: Assembling a Universe", + "release_date": "2014-03-18" + }, + { + "title": "Captain America: The Winter Soldier", + "release_date": "2014-03-20" + }, + { + "title": "Guardians of the Galaxy", + "release_date": "2014-07-30" + }, + { + "title": "Avengers: Age of Ultron", + "release_date": "2015-04-22" + }, + { + "title": "Ant-Man", + "release_date": "2015-07-14" + }, + { + "title": "Captain America: Civil War", + "release_date": "2016-04-27" + }, + { + "title": "Team Thor", + "release_date": "2016-08-28" + }, + { + "title": "Doctor Strange", + "release_date": "2016-10-25" + }, + { + "title": "Guardians of the Galaxy Vol. 2", + "release_date": "2017-04-19" + }, + { + "title": "Spider-Man: Homecoming", + "release_date": "2017-07-05" + }, + { + "title": "Thor: Ragnarok", + "release_date": "2017-10-25" + }, + { + "title": "Black Panther", + "release_date": "2018-02-13" + }, + { + "title": "Avengers: Infinity War", + "release_date": "2018-04-25" + }, + { + "title": "Ant-Man and the Wasp", + "release_date": "2018-07-04" + }, + { + "title": "Captain Marvel", + "release_date": "2019-03-06" + }, + { + "title": "Avengers: Endgame", + "release_date": "2019-04-24" + }, + { + "title": "Spider-Man: Far from Home", + "release_date": "2019-06-28" + }, + { + "title": "Black Widow", + "release_date": "2020-10-28" + }, + { + "title": "Untitled Spider-Man 3", + "release_date": "2021-11-04" + }, + { + "title": "Thor: Love and Thunder", + "release_date": "2022-02-10" + }, + { + "title": "Doctor Strange in the Multiverse of Madness", + "release_date": "2022-03-23" + }, + { + "title": "Untitled Marvel Project (3)", + "release_date": "2022-07-29" + }, + { + "title": "Guardians of the Galaxy Vol. 3", + "release_date": "2023-02-16" + } +] +``` + +--- + +## Use search_json to show the movies with the largest casts + +This example shows how we can use SEARCH_JSON to perform a simple calculation on JSON and order by the results. The cast attribute holds an object array of details around the cast of a movie. We use the expression '$count(id)' that counts each id and returns the value back which we alias in SQL as cast_size which in turn gets used to sort the rows. + +### Body + +```json +{ + "operation": "sql", + "sql": "SELECT movie_title, search_json('$count(id)', `cast`) as cast_size FROM movies.credits ORDER BY cast_size DESC LIMIT 10" +} +``` + +### Response: 200 + +```json +[ + { + "movie_title": "Around the World in Eighty Days", + "cast_size": 312 + }, + { + "movie_title": "And the Oscar Goes To...", + "cast_size": 259 + }, + { + "movie_title": "Rock of Ages", + "cast_size": 223 + }, + { + "movie_title": "Mr. Smith Goes to Washington", + "cast_size": 213 + }, + { + "movie_title": "Les Misérables", + "cast_size": 208 + }, + { + "movie_title": "Jason Bourne", + "cast_size": 201 + }, + { + "movie_title": "The Muppets", + "cast_size": 191 + }, + { + "movie_title": "You Don't Mess with the Zohan", + "cast_size": 183 + }, + { + "movie_title": "The Irishman", + "cast_size": 173 + }, + { + "movie_title": "Spider-Man: Far from Home", + "cast_size": 173 + } +] +``` + +--- + +## search_json as a condition, in a select with a table join + +This example shows how we can use SEARCH_JSON to find movies where at least of 2 our favorite actors from Marvel films have acted together then list the movie, its overview, release date, and the actors names and their characters. The WHERE clause performs a count on credits.cast attribute that have the matching actors. The SELECT performs the same filter on the cast attribute and performs a transform on each object to just return the actor's name and their character. + +### Body + +```json +{ + "operation": "sql", + "sql": "SELECT m.title, m.overview, m.release_date, search_json('$[name in [\"Robert Downey Jr.\", \"Chris Evans\", \"Scarlett Johansson\", \"Mark Ruffalo\", \"Chris Hemsworth\", \"Jeremy Renner\", \"Clark Gregg\", \"Samuel L. Jackson\", \"Gwyneth Paltrow\", \"Don Cheadle\"]].{\"actor\": name, \"character\": character}', c.`cast`) as characters FROM movies.credits c INNER JOIN movies.movie m ON c.movie_id = m.id WHERE search_json('$count($[name in [\"Robert Downey Jr.\", \"Chris Evans\", \"Scarlett Johansson\", \"Mark Ruffalo\", \"Chris Hemsworth\", \"Jeremy Renner\", \"Clark Gregg\", \"Samuel L. Jackson\", \"Gwyneth Paltrow\", \"Don Cheadle\"]])', c.`cast`) >= 2" +} +``` + +### Response: 200 + +```json +[ + { + "title": "Out of Sight", + "overview": "Meet Jack Foley, a smooth criminal who bends the law and is determined to make one last heist. Karen Sisco is a federal marshal who chooses all the right moves … and all the wrong guys. Now they're willing to risk it all to find out if there's more between them than just the law.", + "release_date": "1998-06-26", + "characters": [ + { + "actor": "Don Cheadle", + "character": "Maurice Miller" + }, + { + "actor": "Samuel L. Jackson", + "character": "Hejira Henry (uncredited)" + } + ] + }, + { + "title": "Iron Man", + "overview": "After being held captive in an Afghan cave, billionaire engineer Tony Stark creates a unique weaponized suit of armor to fight evil.", + "release_date": "2008-04-30", + "characters": [ + { + "actor": "Robert Downey Jr.", + "character": "Tony Stark / Iron Man" + }, + { + "actor": "Gwyneth Paltrow", + "character": "Virginia \"Pepper\" Potts" + }, + { + "actor": "Clark Gregg", + "character": "Phil Coulson" + }, + { + "actor": "Samuel L. Jackson", + "character": "Nick Fury (uncredited)" + }, + { + "actor": "Samuel L. Jackson", + "character": "Nick Fury" + } + ] + }, + { + "title": "Captain America: The First Avenger", + "overview": "During World War II, Steve Rogers is a sickly man from Brooklyn who's transformed into super-soldier Captain America to aid in the war effort. Rogers must stop the Red Skull – Adolf Hitler's ruthless head of weaponry, and the leader of an organization that intends to use a mysterious device of untold powers for world domination.", + "release_date": "2011-07-22", + "characters": [ + { + "actor": "Chris Evans", + "character": "Steve Rogers / Captain America" + }, + { + "actor": "Samuel L. Jackson", + "character": "Nick Fury" + } + ] + }, + { + "title": "In Good Company", + "overview": "Dan Foreman is a seasoned advertisement sales executive at a high-ranking publication when a corporate takeover results in him being placed under naive supervisor Carter Duryea, who is half his age. Matters are made worse when Dan's new supervisor becomes romantically involved with his daughter an 18 year-old college student Alex.", + "release_date": "2004-12-29", + "characters": [ + { + "actor": "Scarlett Johansson", + "character": "Alex Foreman" + }, + { + "actor": "Clark Gregg", + "character": "Mark Steckle" + } + ] + }, + { + "title": "Zodiac", + "overview": "The true story of the investigation of the \"Zodiac Killer\", a serial killer who terrified the San Francisco Bay Area, taunting police with his ciphers and letters. The case becomes an obsession for three men as their lives and careers are built and destroyed by the endless trail of clues.", + "release_date": "2007-03-02", + "characters": [ + { + "actor": "Mark Ruffalo", + "character": "Dave Toschi" + }, + { + "actor": "Robert Downey Jr.", + "character": "Paul Avery" + } + ] + }, + { + "title": "Hard Eight", + "overview": "A stranger mentors a young Reno gambler who weds a hooker and befriends a vulgar casino regular.", + "release_date": "1996-02-28", + "characters": [ + { + "actor": "Gwyneth Paltrow", + "character": "Clementine" + }, + { + "actor": "Samuel L. Jackson", + "character": "Jimmy" + } + ] + }, + { + "title": "The Spirit", + "overview": "Down these mean streets a man must come. A hero born, murdered, and born again. A Rookie cop named Denny Colt returns from the beyond as The Spirit, a hero whose mission is to fight against the bad forces from the shadows of Central City. The Octopus, who kills anyone unfortunate enough to see his face, has other plans; he is going to wipe out the entire city.", + "release_date": "2008-12-25", + "characters": [ + { + "actor": "Scarlett Johansson", + "character": "Silken Floss" + }, + { + "actor": "Samuel L. Jackson", + "character": "Octopuss" + } + ] + }, + { + "title": "S.W.A.T.", + "overview": "Hondo Harrelson recruits Jim Street to join an elite unit of the Los Angeles Police Department. Together they seek out more members, including tough Deke Kay and single mom Chris Sanchez. The team's first big assignment is to escort crime boss Alex Montel to prison. It seems routine, but when Montel offers a huge reward to anyone who can break him free, criminals of various stripes step up for the prize.", + "release_date": "2003-08-08", + "characters": [ + { + "actor": "Samuel L. Jackson", + "character": "Sgt. Dan 'Hondo' Harrelson" + }, + { + "actor": "Jeremy Renner", + "character": "Brian Gamble" + } + ] + }, + { + "title": "Iron Man 2", + "overview": "With the world now aware of his dual life as the armored superhero Iron Man, billionaire inventor Tony Stark faces pressure from the government, the press and the public to share his technology with the military. Unwilling to let go of his invention, Stark, with Pepper Potts and James 'Rhodey' Rhodes at his side, must forge new alliances – and confront powerful enemies.", + "release_date": "2010-04-28", + "characters": [ + { + "actor": "Robert Downey Jr.", + "character": "Tony Stark / Iron Man" + }, + { + "actor": "Gwyneth Paltrow", + "character": "Virginia \"Pepper\" Potts" + }, + { + "actor": "Don Cheadle", + "character": "James \"Rhodey\" Rhodes / War Machine" + }, + { + "actor": "Scarlett Johansson", + "character": "Natalie Rushman / Natasha Romanoff / Black Widow" + }, + { + "actor": "Samuel L. Jackson", + "character": "Nick Fury" + }, + { + "actor": "Clark Gregg", + "character": "Phil Coulson" + } + ] + }, + { + "title": "Thor", + "overview": "Against his father Odin's will, The Mighty Thor - a powerful but arrogant warrior god - recklessly reignites an ancient war. Thor is cast down to Earth and forced to live among humans as punishment. Once here, Thor learns what it takes to be a true hero when the most dangerous villain of his world sends the darkest forces of Asgard to invade Earth.", + "release_date": "2011-04-21", + "characters": [ + { + "actor": "Chris Hemsworth", + "character": "Thor Odinson" + }, + { + "actor": "Clark Gregg", + "character": "Phil Coulson" + }, + { + "actor": "Jeremy Renner", + "character": "Clint Barton / Hawkeye (uncredited)" + }, + { + "actor": "Samuel L. Jackson", + "character": "Nick Fury (uncredited)" + } + ] + }, + { + "title": "View from the Top", + "overview": "A small-town woman tries to achieve her goal of becoming a flight attendant.", + "release_date": "2003-03-21", + "characters": [ + { + "actor": "Gwyneth Paltrow", + "character": "Donna" + }, + { + "actor": "Mark Ruffalo", + "character": "Ted Stewart" + } + ] + }, + { + "title": "The Nanny Diaries", + "overview": "A college graduate goes to work as a nanny for a rich New York family. Ensconced in their home, she has to juggle their dysfunction, a new romance, and the spoiled brat in her charge.", + "release_date": "2007-08-24", + "characters": [ + { + "actor": "Scarlett Johansson", + "character": "Annie Braddock" + }, + { + "actor": "Chris Evans", + "character": "Hayden \"Harvard Hottie\"" + } + ] + }, + { + "title": "The Perfect Score", + "overview": "Six high school seniors decide to break into the Princeton Testing Center so they can steal the answers to their upcoming SAT tests and all get perfect scores.", + "release_date": "2004-01-30", + "characters": [ + { + "actor": "Chris Evans", + "character": "Kyle" + }, + { + "actor": "Scarlett Johansson", + "character": "Francesca Curtis" + } + ] + }, + { + "title": "The Avengers", + "overview": "When an unexpected enemy emerges and threatens global safety and security, Nick Fury, director of the international peacekeeping agency known as S.H.I.E.L.D., finds himself in need of a team to pull the world back from the brink of disaster. Spanning the globe, a daring recruitment effort begins!", + "release_date": "2012-04-25", + "characters": [ + { + "actor": "Robert Downey Jr.", + "character": "Tony Stark / Iron Man" + }, + { + "actor": "Chris Evans", + "character": "Steve Rogers / Captain America" + }, + { + "actor": "Mark Ruffalo", + "character": "Bruce Banner / The Hulk" + }, + { + "actor": "Chris Hemsworth", + "character": "Thor Odinson" + }, + { + "actor": "Scarlett Johansson", + "character": "Natasha Romanoff / Black Widow" + }, + { + "actor": "Jeremy Renner", + "character": "Clint Barton / Hawkeye" + }, + { + "actor": "Samuel L. Jackson", + "character": "Nick Fury" + }, + { + "actor": "Clark Gregg", + "character": "Phil Coulson" + }, + { + "actor": "Gwyneth Paltrow", + "character": "Virginia \"Pepper\" Potts" + } + ] + }, + { + "title": "Iron Man 3", + "overview": "When Tony Stark's world is torn apart by a formidable terrorist called the Mandarin, he starts an odyssey of rebuilding and retribution.", + "release_date": "2013-04-18", + "characters": [ + { + "actor": "Robert Downey Jr.", + "character": "Tony Stark / Iron Man" + }, + { + "actor": "Gwyneth Paltrow", + "character": "Virginia \"Pepper\" Potts" + }, + { + "actor": "Don Cheadle", + "character": "James \"Rhodey\" Rhodes / Iron Patriot" + }, + { + "actor": "Mark Ruffalo", + "character": "Bruce Banner (uncredited)" + } + ] + }, + { + "title": "Marvel One-Shot: The Consultant", + "overview": "Agent Coulson informs Agent Sitwell that the World Security Council wishes Emil Blonsky to be released from prison to join the Avengers Initiative. As Nick Fury doesn't want to release Blonsky, the two agents decide to send a patsy to sabotage the meeting...", + "release_date": "2011-09-12", + "characters": [ + { + "actor": "Clark Gregg", + "character": "Phil Coulson" + }, + { + "actor": "Robert Downey Jr.", + "character": "Tony Stark (archive footage)" + } + ] + }, + { + "title": "Thor: The Dark World", + "overview": "Thor fights to restore order across the cosmos… but an ancient race led by the vengeful Malekith returns to plunge the universe back into darkness. Faced with an enemy that even Odin and Asgard cannot withstand, Thor must embark on his most perilous and personal journey yet, one that will reunite him with Jane Foster and force him to sacrifice everything to save us all.", + "release_date": "2013-10-29", + "characters": [ + { + "actor": "Chris Hemsworth", + "character": "Thor Odinson" + }, + { + "actor": "Chris Evans", + "character": "Loki as Captain America (uncredited)" + } + ] + }, + { + "title": "Avengers: Age of Ultron", + "overview": "When Tony Stark tries to jumpstart a dormant peacekeeping program, things go awry and Earth’s Mightiest Heroes are put to the ultimate test as the fate of the planet hangs in the balance. As the villainous Ultron emerges, it is up to The Avengers to stop him from enacting his terrible plans, and soon uneasy alliances and unexpected action pave the way for an epic and unique global adventure.", + "release_date": "2015-04-22", + "characters": [ + { + "actor": "Robert Downey Jr.", + "character": "Tony Stark / Iron Man" + }, + { + "actor": "Chris Evans", + "character": "Steve Rogers / Captain America" + }, + { + "actor": "Mark Ruffalo", + "character": "Bruce Banner / The Hulk" + }, + { + "actor": "Chris Hemsworth", + "character": "Thor Odinson" + }, + { + "actor": "Scarlett Johansson", + "character": "Natasha Romanoff / Black Widow" + }, + { + "actor": "Jeremy Renner", + "character": "Clint Barton / Hawkeye" + }, + { + "actor": "Samuel L. Jackson", + "character": "Nick Fury" + }, + { + "actor": "Don Cheadle", + "character": "James \"Rhodey\" Rhodes / War Machine" + } + ] + }, + { + "title": "Captain America: The Winter Soldier", + "overview": "After the cataclysmic events in New York with The Avengers, Steve Rogers, aka Captain America is living quietly in Washington, D.C. and trying to adjust to the modern world. But when a S.H.I.E.L.D. colleague comes under attack, Steve becomes embroiled in a web of intrigue that threatens to put the world at risk. Joining forces with the Black Widow, Captain America struggles to expose the ever-widening conspiracy while fighting off professional assassins sent to silence him at every turn. When the full scope of the villainous plot is revealed, Captain America and the Black Widow enlist the help of a new ally, the Falcon. However, they soon find themselves up against an unexpected and formidable enemy—the Winter Soldier.", + "release_date": "2014-03-20", + "characters": [ + { + "actor": "Chris Evans", + "character": "Steve Rogers / Captain America" + }, + { + "actor": "Samuel L. Jackson", + "character": "Nick Fury" + }, + { + "actor": "Scarlett Johansson", + "character": "Natasha Romanoff / Black Widow" + } + ] + }, + { + "title": "Thanks for Sharing", + "overview": "A romantic comedy that brings together three disparate characters who are learning to face a challenging and often confusing world as they struggle together against a common demon—sex addiction.", + "release_date": "2013-09-19", + "characters": [ + { + "actor": "Mark Ruffalo", + "character": "Adam" + }, + { + "actor": "Gwyneth Paltrow", + "character": "Phoebe" + } + ] + }, + { + "title": "Chef", + "overview": "When Chef Carl Casper suddenly quits his job at a prominent Los Angeles restaurant after refusing to compromise his creative integrity for its controlling owner, he is left to figure out what's next. Finding himself in Miami, he teams up with his ex-wife, his friend and his son to launch a food truck. Taking to the road, Chef Carl goes back to his roots to reignite his passion for the kitchen -- and zest for life and love.", + "release_date": "2014-05-08", + "characters": [ + { + "actor": "Scarlett Johansson", + "character": "Molly" + }, + { + "actor": "Robert Downey Jr.", + "character": "Marvin" + } + ] + }, + { + "title": "Marvel Studios: Assembling a Universe", + "overview": "A look at the story behind Marvel Studios and the Marvel Cinematic Universe, featuring interviews and behind-the-scenes footage from all of the Marvel films, the Marvel One-Shots and \"Marvel's Agents of S.H.I.E.L.D.\"", + "release_date": "2014-03-18", + "characters": [ + { + "actor": "Robert Downey Jr.", + "character": "Himself / Tony Stark / Iron Man" + }, + { + "actor": "Chris Hemsworth", + "character": "Himself / Thor" + }, + { + "actor": "Chris Evans", + "character": "Himself / Steve Rogers / Captain America" + }, + { + "actor": "Mark Ruffalo", + "character": "Himself / Bruce Banner / Hulk" + }, + { + "actor": "Gwyneth Paltrow", + "character": "Herself" + }, + { + "actor": "Clark Gregg", + "character": "Himself" + }, + { + "actor": "Samuel L. Jackson", + "character": "Himself" + }, + { + "actor": "Scarlett Johansson", + "character": "Herself" + }, + { + "actor": "Jeremy Renner", + "character": "Himself" + } + ] + }, + { + "title": "Captain America: Civil War", + "overview": "Following the events of Age of Ultron, the collective governments of the world pass an act designed to regulate all superhuman activity. This polarizes opinion amongst the Avengers, causing two factions to side with Iron Man or Captain America, which causes an epic battle between former allies.", + "release_date": "2016-04-27", + "characters": [ + { + "actor": "Chris Evans", + "character": "Steve Rogers / Captain America" + }, + { + "actor": "Robert Downey Jr.", + "character": "Tony Stark / Iron Man" + }, + { + "actor": "Scarlett Johansson", + "character": "Natasha Romanoff / Black Widow" + }, + { + "actor": "Don Cheadle", + "character": "James \"Rhodey\" Rhodes / War Machine" + }, + { + "actor": "Jeremy Renner", + "character": "Clint Barton / Hawkeye" + } + ] + }, + { + "title": "Thor: Ragnarok", + "overview": "Thor is imprisoned on the other side of the universe and finds himself in a race against time to get back to Asgard to stop Ragnarok, the destruction of his home-world and the end of Asgardian civilization, at the hands of an all-powerful new threat, the ruthless Hela.", + "release_date": "2017-10-25", + "characters": [ + { + "actor": "Chris Hemsworth", + "character": "Thor Odinson" + }, + { + "actor": "Mark Ruffalo", + "character": "Bruce Banner / Hulk" + }, + { + "actor": "Scarlett Johansson", + "character": "Natasha Romanoff / Black Widow (archive footage / uncredited)" + } + ] + }, + { + "title": "Avengers: Endgame", + "overview": "After the devastating events of Avengers: Infinity War, the universe is in ruins due to the efforts of the Mad Titan, Thanos. With the help of remaining allies, the Avengers must assemble once more in order to undo Thanos' actions and restore order to the universe once and for all, no matter what consequences may be in store.", + "release_date": "2019-04-24", + "characters": [ + { + "actor": "Robert Downey Jr.", + "character": "Tony Stark / Iron Man" + }, + { + "actor": "Chris Evans", + "character": "Steve Rogers / Captain America" + }, + { + "actor": "Mark Ruffalo", + "character": "Bruce Banner / Hulk" + }, + { + "actor": "Chris Hemsworth", + "character": "Thor Odinson" + }, + { + "actor": "Scarlett Johansson", + "character": "Natasha Romanoff / Black Widow" + }, + { + "actor": "Jeremy Renner", + "character": "Clint Barton / Hawkeye" + }, + { + "actor": "Don Cheadle", + "character": "James Rhodes / War Machine" + }, + { + "actor": "Gwyneth Paltrow", + "character": "Pepper Potts" + }, + { + "actor": "Samuel L. Jackson", + "character": "Nick Fury" + } + ] + }, + { + "title": "Avengers: Infinity War", + "overview": "As the Avengers and their allies have continued to protect the world from threats too large for any one hero to handle, a new danger has emerged from the cosmic shadows: Thanos. A despot of intergalactic infamy, his goal is to collect all six Infinity Stones, artifacts of unimaginable power, and use them to inflict his twisted will on all of reality. Everything the Avengers have fought for has led up to this moment - the fate of Earth and existence itself has never been more uncertain.", + "release_date": "2018-04-25", + "characters": [ + { + "actor": "Robert Downey Jr.", + "character": "Tony Stark / Iron Man" + }, + { + "actor": "Chris Hemsworth", + "character": "Thor Odinson" + }, + { + "actor": "Chris Evans", + "character": "Steve Rogers / Captain America" + }, + { + "actor": "Scarlett Johansson", + "character": "Natasha Romanoff / Black Widow" + }, + { + "actor": "Don Cheadle", + "character": "James \"Rhodey\" Rhodes / War Machine" + }, + { + "actor": "Gwyneth Paltrow", + "character": "Virginia \"Pepper\" Potts" + }, + { + "actor": "Samuel L. Jackson", + "character": "Nick Fury (uncredited)" + }, + { + "actor": "Mark Ruffalo", + "character": "Bruce Banner / The Hulk" + } + ] + }, + { + "title": "Captain Marvel", + "overview": "The story follows Carol Danvers as she becomes one of the universe’s most powerful heroes when Earth is caught in the middle of a galactic war between two alien races. Set in the 1990s, Captain Marvel is an all-new adventure from a previously unseen period in the history of the Marvel Cinematic Universe.", + "release_date": "2019-03-06", + "characters": [ + { + "actor": "Samuel L. Jackson", + "character": "Nick Fury" + }, + { + "actor": "Clark Gregg", + "character": "Agent Phil Coulson" + }, + { + "actor": "Chris Evans", + "character": "Steve Rogers / Captain America (uncredited)" + }, + { + "actor": "Scarlett Johansson", + "character": "Natasha Romanoff / Black Widow (uncredited)" + }, + { + "actor": "Don Cheadle", + "character": "James 'Rhodey' Rhodes / War Machine (uncredited)" + }, + { + "actor": "Mark Ruffalo", + "character": "Bruce Banner / The Hulk (uncredited)" + } + ] + }, + { + "title": "Spider-Man: Homecoming", + "overview": "Following the events of Captain America: Civil War, Peter Parker, with the help of his mentor Tony Stark, tries to balance his life as an ordinary high school student in Queens, New York City, with fighting crime as his superhero alter ego Spider-Man as a new threat, the Vulture, emerges.", + "release_date": "2017-07-05", + "characters": [ + { + "actor": "Robert Downey Jr.", + "character": "Tony Stark / Iron Man" + }, + { + "actor": "Gwyneth Paltrow", + "character": "Virginia \"Pepper\" Potts" + }, + { + "actor": "Chris Evans", + "character": "Steve Rogers / Captain America" + } + ] + }, + { + "title": "Team Thor", + "overview": "Discover what Thor was up to during the events of Captain America: Civil War.", + "release_date": "2016-08-28", + "characters": [ + { + "actor": "Chris Hemsworth", + "character": "Thor Odinson" + }, + { + "actor": "Mark Ruffalo", + "character": "Bruce Banner" + } + ] + }, + { + "title": "Black Widow", + "overview": "Natasha Romanoff, also known as Black Widow, confronts the darker parts of her ledger when a dangerous conspiracy with ties to her past arises. Pursued by a force that will stop at nothing to bring her down, Natasha must deal with her history as a spy and the broken relationships left in her wake long before she became an Avenger.", + "release_date": "2020-10-28", + "characters": [ + { + "actor": "Scarlett Johansson", + "character": "Natasha Romanoff / Black Widow" + }, + { + "actor": "Robert Downey Jr.", + "character": "Tony Stark / Iron Man" + } + ] + } +] +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/analytics.md b/versioned_docs/version-4.6/reference/operations-api/analytics.md new file mode 100644 index 00000000..59ac6011 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/analytics.md @@ -0,0 +1,121 @@ +--- +title: Analytics Operations +--- + +# Analytics Operations + +## get_analytics + +Retrieves analytics data from the server. + +- `operation` _(required)_ - must always be `get_analytics` +- `metric` _(required)_ - any value returned by `list_metrics` +- `start_time` _(optional)_ - Unix timestamp in seconds +- `end_time` _(optional)_ - Unix timestamp in seconds +- `get_attributes` _(optional)_ - array of attribute names to retrieve +- `conditions` _(optional)_ - array of conditions to filter results (see [search_by_conditions docs](./nosql-operations) for details) + +### Body + +```json +{ + "operation": "get_analytics", + "metric": "resource-usage", + "start_time": 1609459200, + "end_time": 1609545600, + "get_attributes": ["id", "metric", "userCPUTime", "systemCPUTime"], + "conditions": [ + { + "attribute": "node", + "operator": "equals", + "value": "node1.example.com" + } + ] +} +``` + +### Response 200 + +```json +[ + { + "id": "12345", + "metric": "resource-usage", + "userCPUTime": 100, + "systemCPUTime": 50 + }, + { + "id": "67890", + "metric": "resource-usage", + "userCPUTime": 150, + "systemCPUTime": 75 + } +] +``` + +## list_metrics + +Returns a list of available metrics that can be queried. + +- `operation` _(required)_ - must always be `list_metrics` +- `metric_types` _(optional)_ - array of metric types to filter results; one or both of `custom` and `builtin`; default is `builtin` + +### Body + +```json +{ + "operation": "list_metrics", + "metric_types": ["custom", "builtin"] +} +``` + +### Response 200 + +```json +["resource-usage", "table-size", "database-size", "main-thread-utilization", "utilization", "storage-volume"] +``` + +## describe_metric + +Provides detailed information about a specific metric, including its structure and available parameters. + +- `operation` _(required)_ - must always be `describe_metric` +- `metric` _(required)_ - name of the metric to describe + +### Body + +```json +{ + "operation": "describe_metric", + "metric": "resource-usage" +} +``` + +### Response 200 + +```json +{ + "attributes": [ + { + "name": "id", + "type": "number" + }, + { + "name": "metric", + "type": "string" + }, + { + "name": "userCPUTime", + "type": "number" + }, + { + "name": "systemCPUTime", + "type": "number" + }, + { + "name": "node", + "type": "string" + } + ] +} +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/bulk-operations.md b/versioned_docs/version-4.6/reference/operations-api/bulk-operations.md new file mode 100644 index 00000000..b6714552 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/bulk-operations.md @@ -0,0 +1,255 @@ +--- +title: Bulk Operations +--- + +# Bulk Operations + +## Export Local + +Exports data based on a given search operation to a local file in JSON or CSV format. + +- `operation` _(required)_ - must always be `export_local` +- `format` _(required)_ - the format you wish to export the data, options are `json` & `csv` +- `path` _(required)_ - path local to the server to export the data +- `search_operation` _(required)_ - search_operation of `search_by_hash`, `search_by_value`, `search_by_conditions` or `sql` +- `filename` _(optional)_ - the name of the file where your export will be written to (do not include extension in filename). If one is not provided it will be autogenerated based on the epoch. + +### Body + +```json +{ + "operation": "export_local", + "format": "json", + "path": "/data/", + "search_operation": { + "operation": "sql", + "sql": "SELECT * FROM dev.breed" + } +} +``` + +### Response: 200 + +```json +{ + "message": "Starting job with id 6fc18eaa-3504-4374-815c-44840a12e7e5" +} +``` + +--- + +## CSV Data Load + +Ingests CSV data, provided directly in the operation as an `insert`, `update` or `upsert` into the specified database table. + +- `operation` _(required)_ - must always be `csv_data_load` +- `action` _(optional)_ - type of action you want to perform - `insert`, `update` or `upsert`. The default is `insert` +- `database` _(optional)_ - name of the database where you are loading your data. The default is `data` +- `table` _(required)_ - name of the table where you are loading your data +- `data` _(required)_ - csv data to import into Harper + +### Body + +```json +{ + "operation": "csv_data_load", + "database": "dev", + "action": "insert", + "table": "breed", + "data": "id,name,section,country,image\n1,ENGLISH POINTER,British and Irish Pointers and Setters,GREAT BRITAIN,https://www.fci.be/Nomenclature/Illustrations/001g07.jpg\n2,ENGLISH SETTER,British and Irish Pointers and Setters,GREAT BRITAIN,https://www.fci.be/Nomenclature/Illustrations/002g07.jpg\n3,KERRY BLUE TERRIER,Large and medium sized Terriers,IRELAND,\n" +} +``` + +### Response: 200 + +```json +{ + "message": "Starting job with id 2fe25039-566e-4670-8bb3-2db3d4e07e69", + "job_id": "2fe25039-566e-4670-8bb3-2db3d4e07e69" +} +``` + +--- + +## CSV File Load + +Ingests CSV data, provided via a path on the local filesystem, as an `insert`, `update` or `upsert` into the specified database table. + +_Note: The CSV file must reside on the same machine on which Harper is running. For example, the path to a CSV on your computer will produce an error if your Harper instance is a cloud instance._ + +- `operation` _(required)_ - must always be `csv_file_load` +- `action` _(optional)_ - type of action you want to perform - `insert`, `update` or `upsert`. The default is `insert` +- `database` _(optional)_ - name of the database where you are loading your data. The default is `data` +- `table` _(required)_ - name of the table where you are loading your data +- `file_path` _(required)_ - path to the csv file on the host running Harper + +### Body + +```json +{ + "operation": "csv_file_load", + "action": "insert", + "database": "dev", + "table": "breed", + "file_path": "/home/user/imports/breeds.csv" +} +``` + +### Response: 200 + +```json +{ + "message": "Starting job with id 3994d8e2-ec6a-43c4-8563-11c1df81870e", + "job_id": "3994d8e2-ec6a-43c4-8563-11c1df81870e" +} +``` + +--- + +## CSV URL Load + +Ingests CSV data, provided via URL, as an `insert`, `update` or `upsert` into the specified database table. + +- `operation` _(required)_ - must always be `csv_url_load` +- `action` _(optional)_ - type of action you want to perform - `insert`, `update` or `upsert`. The default is `insert` +- `database` _(optional)_ - name of the database where you are loading your data. The default is `data` +- `table` _(required)_ - name of the table where you are loading your data +- `csv_url` _(required)_ - URL to the csv + +### Body + +```json +{ + "operation": "csv_url_load", + "action": "insert", + "database": "dev", + "table": "breed", + "csv_url": "https://s3.amazonaws.com/complimentarydata/breeds.csv" +} +``` + +### Response: 200 + +```json +{ + "message": "Starting job with id 332aa0a2-6833-46cd-88a6-ae375920436a", + "job_id": "332aa0a2-6833-46cd-88a6-ae375920436a" +} +``` + +--- + +## Export To S3 + +Exports data based on a given search operation from table to AWS S3 in JSON or CSV format. + +- `operation` _(required)_ - must always be `export_to_s3` +- `format` _(required)_ - the format you wish to export the data, options are `json` & `csv` +- `s3` _(required)_ - details your access keys, bucket, bucket region and key for saving the data to S3 +- `search_operation` _(required)_ - search_operation of `search_by_hash`, `search_by_value`, `search_by_conditions` or `sql` + +### Body + +```json +{ + "operation": "export_to_s3", + "format": "json", + "s3": { + "aws_access_key_id": "YOUR_KEY", + "aws_secret_access_key": "YOUR_SECRET_KEY", + "bucket": "BUCKET_NAME", + "key": "OBJECT_NAME", + "region": "BUCKET_REGION" + }, + "search_operation": { + "operation": "sql", + "sql": "SELECT * FROM dev.dog" + } +} +``` + +### Response: 200 + +```json +{ + "message": "Starting job with id 9fa85968-4cb1-4008-976e-506c4b13fc4a", + "job_id": "9fa85968-4cb1-4008-976e-506c4b13fc4a" +} +``` + +--- + +## Import from S3 + +This operation allows users to import CSV or JSON files from an AWS S3 bucket as an `insert`, `update` or `upsert`. + +- `operation` _(required)_ - must always be `import_from_s3` +- `action` _(optional)_ - type of action you want to perform - `insert`, `update` or `upsert`. The default is `insert` +- `database` _(optional)_ - name of the database where you are loading your data. The default is `data` +- `table` _(required)_ - name of the table where you are loading your data +- `s3` _(required)_ - object containing required AWS S3 bucket info for operation: + - `aws_access_key_id` - AWS access key for authenticating into your S3 bucket + - `aws_secret_access_key` - AWS secret for authenticating into your S3 bucket + - `bucket` - AWS S3 bucket to import from + - `key` - the name of the file to import - _the file must include a valid file extension ('.csv' or '.json')_ + - `region` - the region of the bucket + +### Body + +```json +{ + "operation": "import_from_s3", + "action": "insert", + "database": "dev", + "table": "dog", + "s3": { + "aws_access_key_id": "YOUR_KEY", + "aws_secret_access_key": "YOUR_SECRET_KEY", + "bucket": "BUCKET_NAME", + "key": "OBJECT_NAME", + "region": "BUCKET_REGION" + } +} +``` + +### Response: 200 + +```json +{ + "message": "Starting job with id 062a1892-6a0a-4282-9791-0f4c93b12e16", + "job_id": "062a1892-6a0a-4282-9791-0f4c93b12e16" +} +``` + +--- + +## Delete Records Before + +Delete data before the specified timestamp on the specified database table exclusively on the node where it is executed. Any clustered nodes with replicated data will retain that data. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `delete_records_before` +- `date` _(required)_ - records older than this date will be deleted. Supported format looks like: `YYYY-MM-DDThh:mm:ss.sZ` +- `schema` _(required)_ - name of the schema where you are deleting your data +- `table` _(required)_ - name of the table where you are deleting your data + +### Body + +```json +{ + "operation": "delete_records_before", + "date": "2021-01-25T23:05:27.464", + "schema": "dev", + "table": "breed" +} +``` + +### Response: 200 + +```json +{ + "message": "Starting job with id d3aed926-e9fe-4ec1-aea7-0fb4451bd373", + "job_id": "d3aed926-e9fe-4ec1-aea7-0fb4451bd373" +} +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/certificate-management.md b/versioned_docs/version-4.6/reference/operations-api/certificate-management.md new file mode 100644 index 00000000..f8eea402 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/certificate-management.md @@ -0,0 +1,124 @@ +--- +title: Certificate Management +--- + +# Certificate Management + +## Add Certificate + +Adds or updates a certificate in the `hdb_certificate` system table. +If a `private_key` is provided it will **not** be stored in `hdb_certificate`, it will be written to file in `/keys/`. +If a `private_key` is not passed the operation will search for one that matches the certificate. If one is not found an error will be returned. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `add_certificate` +- `name` _(required)_ - a unique name for the certificate +- `certificate` _(required)_ - a PEM formatted certificate string +- `is_authority` _(required)_ - a boolean indicating if the certificate is a certificate authority +- `hosts` _(optional)_ - an array of hostnames that the certificate is valid for +- `private_key` _(optional)_ - a PEM formatted private key string + +### Body + +```json +{ + "operation": "add_certificate", + "name": "my-cert", + "certificate": "-----BEGIN CERTIFICATE-----ZDFAay... -----END CERTIFICATE-----", + "is_authority": false, + "private_key": "-----BEGIN RSA PRIVATE KEY-----Y4dMpw5f... -----END RSA PRIVATE KEY-----" +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully added certificate: my-cert" +} +``` + +--- + +## Remove Certificate + +Removes a certificate from the `hdb_certificate` system table and deletes the corresponding private key file. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `remove_certificate` +- `name` _(required)_ - the name of the certificate + +### Body + +```json +{ + "operation": "remove_certificate", + "name": "my-cert" +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully removed my-cert" +} +``` + +--- + +## List Certificates + +Lists all certificates in the `hdb_certificate` system table. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `list_certificates` + +### Body + +```json +{ + "operation": "list_certificates" +} +``` + +### Response: 200 + +```json +[ + { + "name": "HarperDB-Certificate-Authority-node1", + "certificate": "-----BEGIN CERTIFICATE-----\r\nTANBgkqhk... S34==\r\n-----END CERTIFICATE-----\r\n", + "private_key_name": "privateKey.pem", + "is_authority": true, + "details": { + "issuer": "CN=HarperDB-Certificate-Authority-node1 C=USA ST=Colorado L=Denver O=HarperDB\\, Inc.", + "subject": "CN=HarperDB-Certificate-Authority-node1 C=USA ST=Colorado L=Denver O=HarperDB\\, Inc.", + "serial_number": "5235345", + "valid_from": "Aug 27 15:00:00 2024 GMT", + "valid_to": "Aug 25 15:00:00 2034 GMT" + }, + "is_self_signed": true, + "uses": ["https", "wss"] + }, + { + "name": "node1", + "certificate": "-----BEGIN CERTIFICATE-----\r\ngIEcSR1M... 5bv==\r\n-----END CERTIFICATE-----\r\n", + "private_key_name": "privateKey.pem", + "is_authority": false, + "details": { + "issuer": "CN=HarperDB-Certificate-Authority-node1 C=USA ST=Colorado L=Denver O=HarperDB\\, Inc.", + "subject": "CN=node.1 C=USA ST=Colorado L=Denver O=HarperDB\\, Inc.", + "subject_alt_name": "IP Address:127.0.0.1, DNS:localhost, IP Address:0:0:0:0:0:0:0:1, DNS:node.1", + "serial_number": "5243646", + "valid_from": "Aug 27 15:00:00 2024 GMT", + "valid_to": "Aug 25 15:00:00 2034 GMT" + }, + "is_self_signed": true, + "uses": ["https", "wss"] + } +] +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/clustering-nats.md b/versioned_docs/version-4.6/reference/operations-api/clustering-nats.md new file mode 100644 index 00000000..45e160c4 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/clustering-nats.md @@ -0,0 +1,486 @@ +--- +title: Clustering using NATS +--- + +# Clustering using NATS + +## Cluster Set Routes + +Adds a route/routes to either the hub or leaf server cluster configuration. This operation behaves as a PATCH/upsert, meaning it will add new routes to the configuration while leaving existing routes untouched. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `cluster_set_routes` +- `server` _(required)_ - must always be `hub` or `leaf`, in most cases you should use `hub` here +- `routes` _(required)_ - must always be an objects array with a host and port: + - `host` - the host of the remote instance you are clustering to + - `port` - the clustering port of the remote instance you are clustering to, in most cases this is the value in `clustering.hubServer.cluster.network.port` on the remote instance `harperdb-config.yaml` + +### Body + +```json +{ + "operation": "cluster_set_routes", + "server": "hub", + "routes": [ + { + "host": "3.22.181.22", + "port": 12345 + }, + { + "host": "3.137.184.8", + "port": 12345 + }, + { + "host": "18.223.239.195", + "port": 12345 + }, + { + "host": "18.116.24.71", + "port": 12345 + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "cluster routes successfully set", + "set": [ + { + "host": "3.22.181.22", + "port": 12345 + }, + { + "host": "3.137.184.8", + "port": 12345 + }, + { + "host": "18.223.239.195", + "port": 12345 + }, + { + "host": "18.116.24.71", + "port": 12345 + } + ], + "skipped": [] +} +``` + +--- + +## Cluster Get Routes + +Gets all the hub and leaf server routes from the config file. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `cluster_get_routes` + +### Body + +```json +{ + "operation": "cluster_get_routes" +} +``` + +### Response: 200 + +```json +{ + "hub": [ + { + "host": "3.22.181.22", + "port": 12345 + }, + { + "host": "3.137.184.8", + "port": 12345 + }, + { + "host": "18.223.239.195", + "port": 12345 + }, + { + "host": "18.116.24.71", + "port": 12345 + } + ], + "leaf": [] +} +``` + +--- + +## Cluster Delete Routes + +Removes route(s) from hub and/or leaf server routes array in config file. Returns a deletion success message and arrays of deleted and skipped records. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `cluster_delete_routes` +- `routes` _(required)_ - Must be an array of route object(s) + +### Body + +```json +{ + "operation": "cluster_delete_routes", + "routes": [ + { + "host": "18.116.24.71", + "port": 12345 + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "cluster routes successfully deleted", + "deleted": [ + { + "host": "18.116.24.71", + "port": 12345 + } + ], + "skipped": [] +} +``` + +--- + +## Add Node + +Registers an additional Harper instance with associated subscriptions. Learn more about [Harper clustering here](../clustering/). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `add_node` +- `node_name` _(required)_ - the node name of the remote node +- `subscriptions` _(required)_ - The relationship created between nodes. Must be an object array and include `schema`, `table`, `subscribe` and `publish`: + - `schema` - the schema to replicate from + - `table` - the table to replicate from + - `subscribe` - a boolean which determines if transactions on the remote table should be replicated on the local table + - `publish` - a boolean which determines if transactions on the local table should be replicated on the remote table + - `start_time` _(optional)_ - How far back to go to get transactions from node being added. Must be in UTC YYYY-MM-DDTHH:mm:ss.sssZ format + +### Body + +```json +{ + "operation": "add_node", + "node_name": "ec2-3-22-181-22", + "subscriptions": [ + { + "schema": "dev", + "table": "dog", + "subscribe": false, + "publish": true, + "start_time": "2022-09-02T20:06:35.993Z" + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully added 'ec2-3-22-181-22' to manifest" +} +``` + +--- + +## Update Node + +Modifies an existing Harper instance registration and associated subscriptions. This operation behaves as a PATCH/upsert, meaning it will insert or update the specified replication configurations while leaving other table replication configuration untouched. Learn more about [Harper clustering here](../clustering/). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `update_node` +- `node_name` _(required)_ - the node name of the remote node you are updating +- `subscriptions` _(required)_ - The relationship created between nodes. Must be an object array and include `schema`, `table`, `subscribe` and `publish`: + - `schema` - the schema to replicate from + - `table` - the table to replicate from + - `subscribe` - a boolean which determines if transactions on the remote table should be replicated on the local table + - `publish` - a boolean which determines if transactions on the local table should be replicated on the remote table + - `start_time` _(optional)_ - How far back to go to get transactions from node being added. Must be in UTC YYYY-MM-DDTHH:mm:ss.sssZ format + +### Body + +```json +{ + "operation": "update_node", + "node_name": "ec2-18-223-239-195", + "subscriptions": [ + { + "schema": "dev", + "table": "dog", + "subscribe": true, + "publish": false, + "start_time": "2022-09-02T20:06:35.993Z" + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully updated 'ec2-3-22-181-22'" +} +``` + +--- + +## Set Node Replication + +A more adeptly named alias for add and update node. This operation behaves as a PATCH/upsert, meaning it will insert or update the specified replication configurations while leaving other table replication configuration untouched. The `database` (aka `schema`) parameter is optional, it will default to `data`. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `set_node_replication` +- `node_name` _(required)_ - the node name of the remote node you are updating +- `subscriptions` _(required)_ - The relationship created between nodes. Must be an object array and `table`, `subscribe` and `publish`: + - `database` _(optional)_ - the database to replicate from + - `table` _(required)_ - the table to replicate from + - `subscribe` _(required)_ - a boolean which determines if transactions on the remote table should be replicated on the local table + - `publish` _(required)_ - a boolean which determines if transactions on the local table should be replicated on the remote table +- + +### Body + +```json +{ + "operation": "set_node_replication", + "node_name": "node1", + "subscriptions": [ + { + "table": "dog", + "subscribe": true, + "publish": true + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully updated 'ec2-3-22-181-22'" +} +``` + +--- + +## Cluster Status + +Returns an array of status objects from a cluster. A status object will contain the clustering node name, whether or not clustering is enabled, and a list of possible connections. Learn more about [Harper clustering here](../clustering/). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `cluster_status` + +### Body + +```json +{ + "operation": "cluster_status" +} +``` + +### Response: 200 + +```json +{ + "node_name": "ec2-18-221-143-69", + "is_enabled": true, + "connections": [ + { + "node_name": "ec2-3-22-181-22", + "status": "open", + "ports": { + "clustering": 12345, + "operations_api": 9925 + }, + "latency_ms": 13, + "uptime": "30d 1h 18m 8s", + "subscriptions": [ + { + "schema": "dev", + "table": "dog", + "publish": true, + "subscribe": true + } + ] + } + ] +} +``` + +--- + +## Cluster Network + +Returns an object array of enmeshed nodes. Each node object will contain the name of the node, the amount of time (in milliseconds) it took for it to respond, the names of the nodes it is enmeshed with and the routes set in its config file. Learn more about [Harper clustering here](../clustering/). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_- must always be `cluster_network` +- `timeout` _(optional)_ - the amount of time in milliseconds to wait for a response from the network. Must be a number +- `connected_nodes` _(optional)_ - omit `connected_nodes` from the response. Must be a boolean. Defaults to `false` +- `routes` _(optional)_ - omit `routes` from the response. Must be a boolean. Defaults to `false` + +### Body + +```json +{ + "operation": "cluster_network" +} +``` + +### Response: 200 + +```json +{ + "nodes": [ + { + "name": "local_node", + "response_time": 4, + "connected_nodes": ["ec2-3-142-255-78"], + "routes": [ + { + "host": "3.142.255.78", + "port": 9932 + } + ] + }, + { + "name": "ec2-3-142-255-78", + "response_time": 57, + "connected_nodes": ["ec2-3-12-153-124", "ec2-3-139-236-138", "local_node"], + "routes": [] + } + ] +} +``` + +--- + +## Remove Node + +Removes a Harper instance and associated subscriptions from the cluster. Learn more about [Harper clustering here](../clustering/). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `remove_node` +- `node_name` _(required)_ - The name of the node you are de-registering + +### Body + +```json +{ + "operation": "remove_node", + "node_name": "ec2-3-22-181-22" +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully removed 'ec2-3-22-181-22' from manifest" +} +``` + +--- + +## Configure Cluster + +Bulk create/remove subscriptions for any number of remote nodes. Resets and replaces any existing clustering setup. +Learn more about [Harper clustering here](../clustering/). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `configure_cluster` +- `connections` _(required)_ - must be an object array with each object containing `node_name` and `subscriptions` for that node + +### Body + +```json +{ + "operation": "configure_cluster", + "connections": [ + { + "node_name": "ec2-3-137-184-8", + "subscriptions": [ + { + "schema": "dev", + "table": "dog", + "subscribe": true, + "publish": false + } + ] + }, + { + "node_name": "ec2-18-223-239-195", + "subscriptions": [ + { + "schema": "dev", + "table": "dog", + "subscribe": true, + "publish": true + } + ] + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "Cluster successfully configured." +} +``` + +--- + +## Purge Stream + +Will purge messages from a stream + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `purge_stream` +- `database` _(required)_ - the name of the database where the streams table resides +- `table` _(required)_ - the name of the table that belongs to the stream +- `options` _(optional)_ - control how many messages get purged. Options are: + - `keep` - purge will keep this many most recent messages + - `seq` - purge all messages up to, but not including, this sequence + +### Body + +```json +{ + "operation": "purge_stream", + "database": "dev", + "table": "dog", + "options": { + "keep": 100 + } +} +``` + +--- diff --git a/versioned_docs/version-4.6/reference/operations-api/clustering.md b/versioned_docs/version-4.6/reference/operations-api/clustering.md new file mode 100644 index 00000000..8fc5ae49 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/clustering.md @@ -0,0 +1,355 @@ +--- +title: Clustering +--- + +# Clustering + +The following operations are available for configuring and managing [Harper replication](../replication/). + +_**If you are using NATS for clustering, please see the**_ [_**NATS Clustering Operations**_](./clustering-nats) _**documentation.**_ + +## Add Node + +Adds a new Harper instance to the cluster. If `subscriptions` are provided, it will also create the replication relationships between the nodes. If they are not provided a fully replicating system will be created. [Learn more about adding nodes here](../replication/). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `add_node` +- `hostname` or `url` _(required)_ - one of these fields is required. You must provide either the `hostname` or the `url` of the node you want to add +- `verify_tls` _(optional)_ - a boolean which determines if the TLS certificate should be verified. This will allow the Harper default self-signed certificates to be accepted. Defaults to `true` +- `authorization` _(optional)_ - an object or a string which contains the authorization information for the node being added. If it is an object, it should contain `username` and `password` fields. If it is a string, it should use HTTP `Authorization` style credentials +- `retain_authorization` _(optional)_ - a boolean which determines if the authorization credentials should be retained/stored and used everytime a connection is made to this node. If `true`, the authorization will be stored on the node record. Generally this should not be used, as mTLS/certificate based authorization is much more secure and safe, and avoids the need for storing credentials. Defaults to `false`. +- `revoked_certificates` _(optional)_ - an array of revoked certificates serial numbers. If a certificate is revoked, it will not be accepted for any connections. +- `shard` _(optional)_ - a number which can be used to indicate which shard this node belongs to. This is only needed if you are using sharding. +- `subscriptions` _(optional)_ - The relationship created between nodes. If not provided a fully replicated cluster will be setup. Must be an object array and include `database`, `table`, `subscribe` and `publish`: + - `database` - the database to replicate + - `table` - the table to replicate + - `subscribe` - a boolean which determines if transactions on the remote table should be replicated on the local table + - `publish` - a boolean which determines if transactions on the local table should be replicated on the remote table + +### Body + +```json +{ + "operation": "add_node", + "hostname": "server-two", + "verify_tls": false, + "authorization": { + "username": "admin", + "password": "password" + } +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully added 'server-two' to cluster" +} +``` + +--- + +## Update Node + +Modifies an existing Harper instance in the cluster. + +_Operation is restricted to super_user roles only_ + +_Note: will attempt to add the node if it does not exist_ + +- `operation` _(required)_ - must always be `update_node` +- `hostname` _(required)_ - the `hostname` of the remote node you are updating +- `revoked_certificates` _(optional)_ - an array of revoked certificates serial numbers. If a certificate is revoked, it will not be accepted for any connections. +- `shard` _(optional)_ - a number which can be used to indicate which shard this node belongs to. This is only needed if you are using sharding. +- `subscriptions` _(required)_ - The relationship created between nodes. Must be an object array and include `database`, `table`, `subscribe` and `publish`: + - `database` - the database to replicate from + - `table` - the table to replicate from + - `subscribe` - a boolean which determines if transactions on the remote table should be replicated on the local table + - `publish` - a boolean which determines if transactions on the local table should be replicated on the remote table + +### Body + +```json +{ + "operation": "update_node", + "hostname": "server-two", + "subscriptions": [ + { + "database": "dev", + "table": "my-table", + "subscribe": true, + "publish": true + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully updated 'server-two'" +} +``` + +--- + +## Remove Node + +Removes a Harper node from the cluster and stops replication, [Learn more about remove node here](../replication/). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `remove_node` +- `name` _(required)_ - The name of the node you are removing + +### Body + +```json +{ + "operation": "remove_node", + "hostname": "server-two" +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully removed 'server-two' from cluster" +} +``` + +--- + +## Cluster Status + +Returns an array of status objects from a cluster. + +`database_sockets` shows the actual websocket connections that exist between nodes. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `cluster_status` + +### Body + +```json +{ + "operation": "cluster_status" +} +``` + +### Response: 200 + +```json +{ + "type": "cluster-status", + "connections": [ + { + "replicateByDefault": true, + "replicates": true, + "url": "wss://server-2.domain.com:9933", + "name": "server-2.domain.com", + "subscriptions": null, + "database_sockets": [ + { + "database": "data", + "connected": true, + "latency": 0.7, + "thread_id": 1, + "nodes": ["server-2.domain.com"], + "lastCommitConfirmed": "Wed, 12 Feb 2025 19:09:34 GMT", + "lastReceivedRemoteTime": "Wed, 12 Feb 2025 16:49:29 GMT", + "lastReceivedLocalTime": "Wed, 12 Feb 2025 16:50:59 GMT", + "lastSendTime": "Wed, 12 Feb 2025 16:50:59 GMT" + } + ] + } + ], + "node_name": "server-1.domain.com", + "is_enabled": true +} +``` + +There is a separate socket for each database for each node. Each node is represented in the connections array, and each database connection to that node is represented in the `database_sockets` array. Additional timing statistics include: + +- `lastCommitConfirmed`: When a commit is sent out, it should receive a confirmation from the remote server; this is the last receipt of confirmation of an outgoing commit. +- `lastReceivedRemoteTime`: This is the timestamp of the transaction that was last received. The timestamp is from when the original transaction occurred. +- `lastReceivedLocalTime`: This is local time when the last transaction was received. If there is a different between this and `lastReceivedRemoteTime`, it means there is a delay from the original transaction to \* receiving it and so it is probably catching-up/behind. +- `sendingMessage`: The timestamp of transaction is actively being sent. This won't exist if the replicator is waiting for the next transaction to send. + +--- + +## Configure Cluster + +Bulk create/remove subscriptions for any number of remote nodes. Resets and replaces any existing clustering setup. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `configure_cluster` +- `connections` _(required)_ - must be an object array with each object following the `add_node` schema. + +### Body + +```json +{ + "operation": "configure_cluster", + "connections": [ + { + "hostname": "server-two", + "verify_tls": false, + "authorization": { + "username": "admin", + "password": "password2" + }, + "subscriptions": [ + { + "schema": "dev", + "table": "my-table", + "subscribe": true, + "publish": false + } + ] + }, + { + "hostname": "server-three", + "verify_tls": false, + "authorization": { + "username": "admin", + "password": "password3" + }, + "subscriptions": [ + { + "schema": "dev", + "table": "dog", + "subscribe": true, + "publish": true + } + ] + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "Cluster successfully configured." +} +``` + +--- + +## Cluster Set Routes + +Adds a route/routes to the `replication.routes` configuration. This operation behaves as a PATCH/upsert, meaning it will add new routes to the configuration while leaving existing routes untouched. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `cluster_set_routes` +- `routes` _(required)_ - the routes field is an array that specifies the routes for clustering. Each element in the array can be either a string or an object with `hostname` and `port` properties. + +### Body + +```json +{ + "operation": "cluster_set_routes", + "routes": [ + "wss://server-two:9925", + { + "hostname": "server-three", + "port": 9930 + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "cluster routes successfully set", + "set": [ + "wss://server-two:9925", + { + "hostname": "server-three", + "port": 9930 + } + ], + "skipped": [] +} +``` + +--- + +## Cluster Get Routes + +Gets the replication routes from the Harper config file. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `cluster_get_routes` + +### Body + +```json +{ + "operation": "cluster_get_routes" +} +``` + +### Response: 200 + +```json +[ + "wss://server-two:9925", + { + "hostname": "server-three", + "port": 9930 + } +] +``` + +--- + +## Cluster Delete Routes + +Removes route(s) from the Harper config file. Returns a deletion success message and arrays of deleted and skipped records. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `cluster_delete_routes` +- `routes` _(required)_ - Must be an array of route object(s) + +### Body + +```json +{ + "operation": "cluster_delete_routes", + "routes": [ + { + "hostname": "server-three", + "port": 9930 + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "cluster routes successfully deleted", + "deleted": [ + { + "hostname": "server-three", + "port": 9930 + } + ], + "skipped": [] +} +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/components.md b/versioned_docs/version-4.6/reference/operations-api/components.md new file mode 100644 index 00000000..1b964c50 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/components.md @@ -0,0 +1,543 @@ +--- +title: Components +--- + +# Components + +## Add Component + +Creates a new component project in the component root directory using a predefined template. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `add_component` +- `project` _(required)_ - the name of the project you wish to create +- `replicated` _(optional)_ - if true, Harper will replicate the component to all nodes in the cluster. Must be a boolean. + +### Body + +```json +{ + "operation": "add_component", + "project": "my-component" +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully added project: my-component" +} +``` + +--- + +## Deploy Component + +Will deploy a component using either a base64-encoded string representation of a `.tar` file (the output from `package_component`) or a package value, which can be any valid NPM reference, such as a GitHub repo, an NPM package, a tarball, a local directory or a website. + +If deploying with the `payload` option, Harper will decrypt the base64-encoded string, reconstitute the .tar file of your project folder, and extract it to the component root project directory. + +If deploying with the `package` option, the package value will be written to `harperdb-config.yaml`. Then npm install will be utilized to install the component in the `node_modules` directory located in the hdb root. The value is a package reference, which should generally be a [URL reference, as described here](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#urls-as-dependencies) (it is also possible to include NPM registerd packages and file paths). URL package references can directly reference tarballs that can be installed as a package. However, the most common and recommended usage is to install from a Git repository, which can be combined with a tag to deploy a specific version directly from versioned source control. When using tags, we highly recommend that you use the `semver` directive to ensure consistent and reliable installation by NPM. In addition to tags, you can also reference branches or commit numbers. Here is an example URL package reference to a (public) Git repository that doesn't require authentication: + +``` +https://github.com/HarperDB/application-template#semver:v1.0.0 +``` + +or this can be shortened to: + +``` +HarperDB/application-template#semver:v1.0.0 +``` + +You can also install from private repository if you have an installed SSH keys on the server: + +``` +git+ssh://git@github.com:my-org/my-app.git#semver:v1.0.0 +``` + +Or you can use a Github token: + +``` +https://@github.com/my-org/my-app#semver:v1.0.0 +``` + +Or you can use a GitLab Project Access Token: + +``` +https://my-project:@gitlab.com/my-group/my-project#semver:v1.0.0 +``` + +Note that your component will be installed by NPM. If your component has dependencies, NPM will attempt to download and install these as well. NPM normally uses the public registry.npmjs.org registry. If you are installing without network access to this, you may wish to define [custom registry locations](https://docs.npmjs.com/cli/v8/configuring-npm/npmrc) if you have any dependencies that need to be installed. NPM will install the deployed component and any dependencies in node_modules in the hdb root directory (typically `~/hdb/node_modules`). + +_Note: After deploying a component a restart may be required_ + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `deploy_component` +- `project` _(required)_ - the name of the project you wish to deploy +- `package` _(optional)_ - this can be any valid GitHub or NPM reference +- `payload` _(optional)_ - a base64-encoded string representation of the .tar file. Must be a string +- `restart` _(optional)_ - must be either a boolean or the string `rolling`. If set to `rolling`, a rolling restart will be triggered after the component is deployed, meaning that each node in the cluster will be sequentially restarted (waiting for the last restart to start the next). If set to `true`, the restart will not be rolling, all nodes will be restarted in parallel. If `replicated` is `true`, the restart operations will be replicated across the cluster. +- `replicated` _(optional)_ - if true, Harper will replicate the component to all nodes in the cluster. Must be a boolean. +- `install_command` _(optional)_ - A command to use when installing the component. Must be a string. This can be used to install dependencies with pnpm or yarn, for example, like: `"install_command": "npm install -g pnpm && pnpm install"` + +### Body + +```json +{ + "operation": "deploy_component", + "project": "my-component", + "payload": "A very large base64-encoded string representation of the .tar file" +} +``` + +```json +{ + "operation": "deploy_component", + "project": "my-component", + "package": "HarperDB/application-template", + "replicated": true +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully deployed: my-component" +} +``` + +--- + +## Package Component + +Creates a temporary `.tar` file of the specified project folder, then reads it into a base64-encoded string and returns an object with the string and the payload. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `package_component` +- `project` _(required)_ - the name of the project you wish to package +- `skip_node_modules` _(optional)_ - if true, creates option for tar module that will exclude the project's node_modules directory. Must be a boolean + +### Body + +```json +{ + "operation": "package_component", + "project": "my-component", + "skip_node_modules": true +} +``` + +### Response: 200 + +```json +{ + "project": "my-component", + "payload": "LgAAAAAAAAAAAAAAAAAAA...AAAAAAAAAAAAAAAAAAAAAAAAAAAAA==" +} +``` + +--- + +## Drop Component + +Deletes a file from inside the component project or deletes the complete project. + +**If just `project` is provided it will delete all that projects local files and folders** + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `drop_component` +- `project` _(required)_ - the name of the project you wish to delete or to delete from if using the `file` parameter +- `file` _(optional)_ - the path relative to your project folder of the file you wish to delete +- `replicated` _(optional)_ - if true, Harper will replicate the component deletion to all nodes in the cluster. Must be a boolean. +- `restart` _(optional)_ - if true, Harper will restart after dropping the component. Must be a boolean. + +### Body + +```json +{ + "operation": "drop_component", + "project": "my-component", + "file": "utils/myUtils.js" +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully dropped: my-component/utils/myUtils.js" +} +``` + +--- + +## Get Components + +Gets all local component files and folders and any component config from `harperdb-config.yaml` + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `get_components` + +### Body + +```json +{ + "operation": "get_components" +} +``` + +### Response: 200 + +```json +{ + "name": "components", + "entries": [ + { + "package": "HarperDB/application-template", + "name": "deploy-test-gh" + }, + { + "package": "@fastify/compress", + "name": "fast-compress" + }, + { + "name": "my-component", + "entries": [ + { + "name": "LICENSE", + "mtime": "2023-08-22T16:00:40.286Z", + "size": 1070 + }, + { + "name": "index.md", + "mtime": "2023-08-22T16:00:40.287Z", + "size": 1207 + }, + { + "name": "config.yaml", + "mtime": "2023-08-22T16:00:40.287Z", + "size": 1069 + }, + { + "name": "package.json", + "mtime": "2023-08-22T16:00:40.288Z", + "size": 145 + }, + { + "name": "resources.js", + "mtime": "2023-08-22T16:00:40.289Z", + "size": 583 + }, + { + "name": "schema.graphql", + "mtime": "2023-08-22T16:00:40.289Z", + "size": 466 + }, + { + "name": "utils", + "entries": [ + { + "name": "commonUtils.js", + "mtime": "2023-08-22T16:00:40.289Z", + "size": 583 + } + ] + } + ] + } + ] +} +``` + +--- + +## Get Component File + +Gets the contents of a file inside a component project. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `get_component_file` +- `project` _(required)_ - the name of the project where the file is located +- `file` _(required)_ - the path relative to your project folder of the file you wish to view +- `encoding` _(optional)_ - the encoding that will be passed to the read file call. Defaults to `utf8` + +### Body + +```json +{ + "operation": "get_component_file", + "project": "my-component", + "file": "resources.js" +} +``` + +### Response: 200 + +```json +{ + "message": "/**export class MyCustomResource extends tables.TableName {\n\t/ we can define our own custom POST handler\n\tpost(content) {\n\t\t/ do something with the incoming content;\n\t\treturn super.post(content);\n\t}\n\t/ or custom GET handler\n\tget() {\n\t\t/ we can modify this resource before returning\n\t\treturn super.get();\n\t}\n}\n */\n/ we can also define a custom resource without a specific table\nexport class Greeting extends Resource {\n\t/ a \"Hello, world!\" handler\n\tget() {\n\t\treturn { greeting: 'Hello, world!' };\n\t}\n}" +} +``` + +--- + +## Set Component File + +Creates or updates a file inside a component project. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `set_component_file` +- `project` _(required)_ - the name of the project the file is located in +- `file` _(required)_ - the path relative to your project folder of the file you wish to set +- `payload` _(required)_ - what will be written to the file +- `encoding` _(optional)_ - the encoding that will be passed to the write file call. Defaults to `utf8` +- `replicated` _(optional)_ - if true, Harper will replicate the component update to all nodes in the cluster. Must be a boolean. + +### Body + +```json +{ + "operation": "set_component_file", + "project": "my-component", + "file": "test.js", + "payload": "console.log('hello world')" +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully set component: test.js" +} +``` + +--- + +## Add SSH Key + +Adds an SSH key for deploying components from private repositories. This will also create an ssh config file that will be used when deploying the components. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `add_ssh_key` +- `name` _(required)_ - the name of the key +- `key` _(required)_ - the private key contents. Must be an ed25519 key. Line breaks must be delimited with `\n` and have a trailing `\n` +- `host` _(required)_ - the host for the ssh config (see below). Used as part of the `package` url when deploying a component using this key +- `hostname` _(required)_ - the hostname for the ssh config (see below). Used to map `host` to an actual domain (e.g. `github.com`) +- `known_hosts` _(optional)_ - the public SSH keys of the host your component will be retrieved from. If `hostname` is `github.com` this will be retrieved automatically. Line breaks must be delimited with `\n` +- `replicated` _(optional)_ - if true, HarperDB will replicate the key to all nodes in the cluster. Must be a boolean. + _Operation is restricted to super_user roles only_ + +### Body + +```json +{ + "operation": "add_ssh_key", + "name": "harperdb-private-component", + "key": "-----BEGIN OPENSSH PRIVATE KEY-----\nthis\nis\na\nfake\nkey\n-----END OPENSSH PRIVATE KEY-----\n", + "host": "harperdb-private-component.github.com", + "hostname": "github.com" +} +``` + +### Response: 200 + +```json +{ + "message": "Added ssh key: harperdb-private-component" +} +``` + +### Generated Config and Deploy Component "package" string examples + +``` +#harperdb-private-component +Host harperdb-private-component.github.com + HostName github.com + User git + IdentityFile /hdbroot/ssh/harperdb-private-component.key + IdentitiesOnly yes +``` + +``` +"package": "git+ssh://git@:.git#semver:v1.2.3" + +"package": "git+ssh://git@harperdb-private-component.github.com:HarperDB/harperdb-private-component.git#semver:v1.2.3" +``` + +Note that `deploy_component` with a package uses `npm install` so the url must be a valid npm format url. The above is an example of a url using a tag in the repo to install. + +--- + +## Update SSH Key + +Updates the private key contents of an existing SSH key. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `update_ssh_key` +- `name` _(required)_ - the name of the key to be updated +- `key` _(required)_ - the private key contents. Must be an ed25519 key. Line breaks must be delimited with `\n` and have a trailing `\n` +- `replicated` _(optional)_ - if true, Harper will replicate the key update to all nodes in the cluster. Must be a boolean. + +### Body + +```json +{ + "operation": "update_ssh_key", + "name": "harperdb-private-component", + "key": "-----BEGIN OPENSSH PRIVATE KEY-----\nthis\nis\na\nNEWFAKE\nkey\n-----END OPENSSH PRIVATE KEY-----\n", + "host": "harperdb-private-component.github.com", + "hostname": "github.com" +} +``` + +### Response: 200 + +```json +{ + "message": "Updated ssh key: harperdb-private-component" +} +``` + +## Delete SSH Key + +Deletes a SSH key. This will also remove it from the generated SSH config. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `delete_ssh_key` +- `name` _(required)_ - the name of the key to be deleted +- `replicated` _(optional)_ - if true, Harper will replicate the key deletion to all nodes in the cluster. Must be a boolean. + +### Body + +```json +{ + "name": "harperdb-private-component" +} +``` + +### Response: 200 + +```json +{ + "message": "Deleted ssh key: harperdb-private-component" +} +``` + +--- + +## List SSH Keys + +List off the names of added SSH keys + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `list_ssh_keys` + +### Body + +```json +{ + "operation": "list_ssh_keys" +} +``` + +### Response: 200 + +```json +[ + { + "name": "harperdb-private-component" + } +] +``` + +_Note: Additional SSH keys would appear as more objects in this array_ + +--- + +## Set SSH Known Hosts + +Sets the SSH known_hosts file. This will overwrite the file. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `set_ssh_known_hosts` +- `known_hosts` _(required)_ - The contents to set the known_hosts to. Line breaks must be delimite d with +- `replicated` _(optional)_ - if true, Harper will replicate the known hosts to all nodes in the cluster. Must be a boolean. + +### Body + +```json +{ + "operation": "set_ssh_known_hosts", + "known_hosts": "github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=\ngithub.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl\ngithub.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=\n" +} +``` + +### Response: 200 + +```json +{ + "message": "Known hosts successfully set" +} +``` + +## Get SSH Known Hosts + +Gets the contents of the known_hosts file + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `get_ssh_known_hosts` + +### Body + +```json +{ + "operation": "get_ssh_known_hosts" +} +``` + +### Response: 200 + +```json +{ + "known_hosts": "github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=\ngithub.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl\ngithub.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=\n" +} +``` + +--- + +## Install Node Modules + +This operation is deprecated, as it is handled automatically by deploy_component and restart. +Executes npm install against specified custom function projects. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `install_node_modules` +- `projects` _(required)_ - must ba an array of custom functions projects. +- `dry_run` _(optional)_ - refers to the npm --dry-run flag: [https://docs.npmjs.com/cli/v8/commands/npm-install#dry-run](https://docs.npmjs.com/cli/v8/commands/npm-install#dry-run). Defaults to false. + +### Body + +```json +{ + "operation": "install_node_modules", + "projects": ["dogs", "cats"], + "dry_run": true +} +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/configuration.md b/versioned_docs/version-4.6/reference/operations-api/configuration.md new file mode 100644 index 00000000..a09a38a0 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/configuration.md @@ -0,0 +1,135 @@ +--- +title: Configuration +--- + +# Configuration + +## Set Configuration + +Modifies the Harper configuration file parameters. Must follow with a restart or restart_service operation. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `set_configuration` +- `logging_level` _(optional)_ - one or more configuration keywords to be updated in the Harper configuration file +- `clustering_enabled` _(optional)_ - one or more configuration keywords to be updated in the Harper configuration file + +### Body + +```json +{ + "operation": "set_configuration", + "logging_level": "trace", + "clustering_enabled": true +} +``` + +### Response: 200 + +```json +{ + "message": "Configuration successfully set. You must restart HarperDB for new config settings to take effect." +} +``` + +--- + +## Get Configuration + +Returns the Harper configuration parameters. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `get_configuration` + +### Body + +```json +{ + "operation": "get_configuration" +} +``` + +### Response: 200 + +```json +{ + "http": { + "compressionThreshold": 1200, + "cors": false, + "corsAccessList": [null], + "keepAliveTimeout": 30000, + "port": 9926, + "securePort": null, + "timeout": 120000 + }, + "threads": 11, + "authentication": { + "cacheTTL": 30000, + "enableSessions": true, + "operationTokenTimeout": "1d", + "refreshTokenTimeout": "30d" + }, + "analytics": { + "aggregatePeriod": 60 + }, + "replication": { + "hostname": "node1", + "databases": "*", + "routes": null, + "url": "wss://127.0.0.1:9925" + }, + "componentsRoot": "/Users/hdb/components", + "localStudio": { + "enabled": false + }, + "logging": { + "auditAuthEvents": { + "logFailed": false, + "logSuccessful": false + }, + "auditLog": true, + "auditRetention": "3d", + "file": true, + "level": "error", + "root": "/Users/hdb/log", + "rotation": { + "enabled": false, + "compress": false, + "interval": null, + "maxSize": null, + "path": "/Users/hdb/log" + }, + "stdStreams": false + }, + "mqtt": { + "network": { + "port": 1883, + "securePort": 8883 + }, + "webSocket": true, + "requireAuthentication": true + }, + "operationsApi": { + "network": { + "cors": true, + "corsAccessList": ["*"], + "domainSocket": "/Users/hdb/operations-server", + "port": 9925, + "securePort": null + } + }, + "rootPath": "/Users/hdb", + "storage": { + "writeAsync": false, + "caching": true, + "compression": false, + "noReadAhead": true, + "path": "/Users/hdb/database", + "prefetchWrites": true + }, + "tls": { + "privateKey": "/Users/hdb/keys/privateKey.pem" + } +} +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/custom-functions.md b/versioned_docs/version-4.6/reference/operations-api/custom-functions.md new file mode 100644 index 00000000..23709148 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/custom-functions.md @@ -0,0 +1,279 @@ +--- +title: Custom Functions +--- + +# Custom Functions + +_These operations are deprecated._ + +## Custom Functions Status + +Returns the state of the Custom functions server. This includes whether it is enabled, upon which port it is listening, and where its root project directory is located on the host machine. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `custom_function_status` + +### Body + +```json +{ + "operation": "custom_functions_status" +} +``` + +### Response: 200 + +```json +{ + "is_enabled": true, + "port": 9926, + "directory": "/Users/myuser/hdb/custom_functions" +} +``` + +--- + +## Get Custom Functions + +Returns an array of projects within the Custom Functions root project directory. Each project has details including each of the files in the routes and helpers directories, and the total file count in the static folder. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `get_custom_functions` + +### Body + +```json +{ + "operation": "get_custom_functions" +} +``` + +### Response: 200 + +```json +{ + "dogs": { + "routes": ["examples"], + "helpers": ["example"], + "static": 3 + } +} +``` + +--- + +## Get Custom Function + +Returns the content of the specified file as text. HarperDStudio uses this call to render the file content in its built-in code editor. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `get_custom_function` +- `project` _(required)_ - the name of the project containing the file for which you wish to get content +- `type` _(required)_ - the name of the sub-folder containing the file for which you wish to get content - must be either routes or helpers +- `file` _(required)_ - The name of the file for which you wish to get content - should not include the file extension (which is always .js) + +### Body + +```json +{ + "operation": "get_custom_function", + "project": "dogs", + "type": "helpers", + "file": "example" +} +``` + +### Response: 200 + +```json +{ + "message": "'use strict';\n\nconst https = require('https');\n\nconst authRequest = (options) => {\n return new Promise((resolve, reject) => {\n const req = https.request(options, (res) => {\n res.setEncoding('utf8');\n let responseBody = '';\n\n res.on('data', (chunk) => {\n responseBody += chunk;\n });\n\n res.on('end', () => {\n resolve(JSON.parse(responseBody));\n });\n });\n\n req.on('error', (err) => {\n reject(err);\n });\n\n req.end();\n });\n};\n\nconst customValidation = async (request,logger) => {\n const options = {\n hostname: 'jsonplaceholder.typicode.com',\n port: 443,\n path: '/todos/1',\n method: 'GET',\n headers: { authorization: request.headers.authorization },\n };\n\n const result = await authRequest(options);\n\n /*\n * throw an authentication error based on the response body or statusCode\n */\n if (result.error) {\n const errorString = result.error || 'Sorry, there was an error authenticating your request';\n logger.error(errorString);\n throw new Error(errorString);\n }\n return request;\n};\n\nmodule.exports = customValidation;\n" +} +``` + +--- + +## Set Custom Function + +Updates the content of the specified file. Harper Studio uses this call to save any changes made through its built-in code editor. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `set_custom_function` +- `project` _(required)_ - the name of the project containing the file for which you wish to set content +- `type` _(required)_ - the name of the sub-folder containing the file for which you wish to set content - must be either routes or helpers +- `file` _(required)_ - the name of the file for which you wish to set content - should not include the file extension (which is always .js) +- `function_content` _(required)_ - the content you wish to save into the specified file + +### Body + +```json +{ + "operation": "set_custom_function", + "project": "dogs", + "type": "helpers", + "file": "example", + "function_content": "'use strict';\n\nconst https = require('https');\n\nconst authRequest = (options) => {\n return new Promise((resolve, reject) => {\n const req = https.request(options, (res) => {\n res.setEncoding('utf8');\n let responseBody = '';\n\n res.on('data', (chunk) => {\n responseBody += chunk;\n });\n\n res.on('end', () => {\n resolve(JSON.parse(responseBody));\n });\n });\n\n req.on('error', (err) => {\n reject(err);\n });\n\n req.end();\n });\n};\n\nconst customValidation = async (request,logger) => {\n const options = {\n hostname: 'jsonplaceholder.typicode.com',\n port: 443,\n path: '/todos/1',\n method: 'GET',\n headers: { authorization: request.headers.authorization },\n };\n\n const result = await authRequest(options);\n\n /*\n * throw an authentication error based on the response body or statusCode\n */\n if (result.error) {\n const errorString = result.error || 'Sorry, there was an error authenticating your request';\n logger.error(errorString);\n throw new Error(errorString);\n }\n return request;\n};\n\nmodule.exports = customValidation;\n" +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully updated custom function: example.js" +} +``` + +--- + +## Drop Custom Function + +Deletes the specified file. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `drop_custom_function` +- `project` _(required)_ - the name of the project containing the file you wish to delete +- `type` _(required)_ - the name of the sub-folder containing the file you wish to delete. Must be either routes or helpers +- `file` _(required)_ - the name of the file you wish to delete. Should not include the file extension (which is always .js) + +### Body + +```json +{ + "operation": "drop_custom_function", + "project": "dogs", + "type": "helpers", + "file": "example" +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully deleted custom function: example.js" +} +``` + +--- + +## Add Custom Function Project + +Creates a new project folder in the Custom Functions root project directory. It also inserts into the new directory the contents of our Custom Functions Project template, which is available publicly, here: [https://github.com/HarperDB/harperdb-custom-functions-template](https://github.com/HarperDB/harperdb-custom-functions-template). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `add_custom_function_project` +- `project` _(required)_ - the name of the project you wish to create + +### Body + +```json +{ + "operation": "add_custom_function_project", + "project": "dogs" +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully created custom function project: dogs" +} +``` + +--- + +## Drop Custom Function Project + +Deletes the specified project folder and all of its contents. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `drop_custom_function_project` +- `project` _(required)_ - the name of the project you wish to delete + +### Body + +```json +{ + "operation": "drop_custom_function_project", + "project": "dogs" +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully deleted project: dogs" +} +``` + +--- + +## Package Custom Function Project + +Creates a .tar file of the specified project folder, then reads it into a base64-encoded string and returns an object with the string, the payload and the file. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `package_custom_function_project` +- `project` _(required)_ - the name of the project you wish to package up for deployment +- `skip_node_modules` _(optional)_ - if true, creates option for tar module that will exclude the project's node_modules directory. Must be a boolean. + +### Body + +```json +{ + "operation": "package_custom_function_project", + "project": "dogs", + "skip_node_modules": true +} +``` + +### Response: 200 + +```json +{ + "project": "dogs", + "payload": "LgAAAAAAAAAAAAAAAAAAA...AAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", + "file": "/tmp/d27f1154-5d82-43f0-a5fb-a3018f366081.tar" +} +``` + +--- + +## Deploy Custom Function Project + +Takes the output of package_custom_function_project, decrypts the base64-encoded string, reconstitutes the .tar file of your project folder, and extracts it to the Custom Functions root project directory. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `deploy_custom_function_project` +- `project` _(required)_ - the name of the project you wish to deploy. Must be a string +- `payload` _(required)_ - a base64-encoded string representation of the .tar file. Must be a string + +### Body + +```json +{ + "operation": "deploy_custom_function_project", + "project": "dogs", + "payload": "A very large base64-encoded string represenation of the .tar file" +} +``` + +### Response: 200 + +```json +{ + "message": "Successfully deployed project: dogs" +} +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/databases-and-tables.md b/versioned_docs/version-4.6/reference/operations-api/databases-and-tables.md new file mode 100644 index 00000000..7c17fb4d --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/databases-and-tables.md @@ -0,0 +1,388 @@ +--- +title: Databases and Tables +--- + +# Databases and Tables + +## Describe All + +Returns the definitions of all databases and tables within the database. Record counts about 5000 records are estimated, as determining the exact count can be expensive. When the record count is estimated, this is indicated by the inclusion of a confidence interval of `estimated_record_range`. If you need the exact count, you can include an `"exact_count": true` in the operation, but be aware that this requires a full table scan (may be expensive). + +- `operation` _(required)_ - must always be `describe_all` + +### Body + +```json +{ + "operation": "describe_all" +} +``` + +### Response: 200 + +```json +{ + "dev": { + "dog": { + "schema": "dev", + "name": "dog", + "hash_attribute": "id", + "audit": true, + "schema_defined": false, + "attributes": [ + { + "attribute": "id", + "indexed": true, + "is_primary_key": true + }, + { + "attribute": "__createdtime__", + "indexed": true + }, + { + "attribute": "__updatedtime__", + "indexed": true + }, + { + "attribute": "type", + "indexed": true + } + ], + "clustering_stream_name": "dd9e90c2689151ab812e0f2d98816bff", + "record_count": 4000, + "estimated_record_range": [3976, 4033], + "last_updated_record": 1697658683698.4504 + } + } +} +``` + +--- + +## Describe database + +Returns the definitions of all tables within the specified database. + +- `operation` _(required)_ - must always be `describe_database` +- `database` _(optional)_ - database where the table you wish to describe lives. The default is `data` + +### Body + +```json +{ + "operation": "describe_database", + "database": "dev" +} +``` + +### Response: 200 + +```json +{ + "dog": { + "schema": "dev", + "name": "dog", + "hash_attribute": "id", + "audit": true, + "schema_defined": false, + "attributes": [ + { + "attribute": "id", + "indexed": true, + "is_primary_key": true + }, + { + "attribute": "__createdtime__", + "indexed": true + }, + { + "attribute": "__updatedtime__", + "indexed": true + }, + { + "attribute": "type", + "indexed": true + } + ], + "clustering_stream_name": "dd9e90c2689151ab812e0f2d98816bff", + "record_count": 4000, + "estimated_record_range": [3976, 4033], + "last_updated_record": 1697658683698.4504 + } +} +``` + +--- + +## Describe Table + +Returns the definition of the specified table. + +- `operation` _(required)_ - must always be `describe_table` +- `table` _(required)_ - table you wish to describe +- `database` _(optional)_ - database where the table you wish to describe lives. The default is `data` + +### Body + +```json +{ + "operation": "describe_table", + "table": "dog" +} +``` + +### Response: 200 + +```json +{ + "schema": "dev", + "name": "dog", + "hash_attribute": "id", + "audit": true, + "schema_defined": false, + "attributes": [ + { + "attribute": "id", + "indexed": true, + "is_primary_key": true + }, + { + "attribute": "__createdtime__", + "indexed": true + }, + { + "attribute": "__updatedtime__", + "indexed": true + }, + { + "attribute": "type", + "indexed": true + } + ], + "clustering_stream_name": "dd9e90c2689151ab812e0f2d98816bff", + "record_count": 4000, + "estimated_record_range": [3976, 4033], + "last_updated_record": 1697658683698.4504 +} +``` + +--- + +## Create database + +Create a new database. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `create_database` +- `database` _(optional)_ - name of the database you are creating. The default is `data` + +### Body + +```json +{ + "operation": "create_database", + "database": "dev" +} +``` + +### Response: 200 + +```json +{ + "message": "database 'dev' successfully created" +} +``` + +--- + +## Drop database + +Drop an existing database. NOTE: Dropping a database will delete all tables and all of their records in that database. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - this should always be `drop_database` +- `database` _(required)_ - name of the database you are dropping +- `replicated` _(optional)_ - if true, Harper will replicate the component to all nodes in the cluster. Must be a boolean. + +### Body + +```json +{ + "operation": "drop_database", + "database": "dev" +} +``` + +### Response: 200 + +```json +{ + "message": "successfully deleted 'dev'" +} +``` + +--- + +## Create Table + +Create a new table within a database. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `create_table` +- `database` _(optional)_ - name of the database where you want your table to live. If the database does not exist, it will be created. If the `database` property is not provided it will default to `data`. +- `table` _(required)_ - name of the table you are creating +- `primary_key` _(required)_ - primary key for the table +- `attributes` _(optional)_ - an array of attributes that specifies the schema for the table, that is the set of attributes for the table. When attributes are supplied the table will not be considered a "dynamic schema" table, and attributes will not be auto-added when records with new properties are inserted. Each attribute is specified as: + - `name` _(required)_ - the name of the attribute + - `indexed` _(optional)_ - indicates if the attribute should be indexed + - `type` _(optional)_ - specifies the data type of the attribute (can be String, Int, Float, Date, ID, Any) +- `expiration` _(optional)_ - specifies the time-to-live or expiration of records in the table before they are evicted (records are not evicted on any timer if not specified). This is specified in seconds. + +### Body + +```json +{ + "operation": "create_table", + "database": "dev", + "table": "dog", + "primary_key": "id" +} +``` + +### Response: 200 + +```json +{ + "message": "table 'dev.dog' successfully created." +} +``` + +--- + +## Drop Table + +Drop an existing database table. NOTE: Dropping a table will delete all associated records in that table. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - this should always be `drop_table` +- `database` _(optional)_ - database where the table you are dropping lives. The default is `data` +- `table` _(required)_ - name of the table you are dropping +- `replicated` _(optional)_ - if true, Harper will replicate the component to all nodes in the cluster. Must be a boolean. + +### Body + +```json +{ + "operation": "drop_table", + "database": "dev", + "table": "dog" +} +``` + +### Response: 200 + +```json +{ + "message": "successfully deleted table 'dev.dog'" +} +``` + +--- + +## Create Attribute + +Create a new attribute within the specified table. **The create_attribute operation can be used for admins wishing to pre-define database values for setting role-based permissions or for any other reason.** + +_Note: Harper will automatically create new attributes on insert and update if they do not already exist within the database._ + +- `operation` _(required)_ - must always be `create_attribute` +- `database` _(optional)_ - name of the database of the table you want to add your attribute. The default is `data` +- `table` _(required)_ - name of the table where you want to add your attribute to live +- `attribute` _(required)_ - name for the attribute + +### Body + +```json +{ + "operation": "create_attribute", + "database": "dev", + "table": "dog", + "attribute": "is_adorable" +} +``` + +### Response: 200 + +```json +{ + "message": "inserted 1 of 1 records", + "skipped_hashes": [], + "inserted_hashes": ["383c0bef-5781-4e1c-b5c8-987459ad0831"] +} +``` + +--- + +## Drop Attribute + +Drop an existing attribute from the specified table. NOTE: Dropping an attribute will delete all associated attribute values in that table. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - this should always be `drop_attribute` +- `database` _(optional)_ - database where the table you are dropping lives. The default is `data` +- `table` _(required)_ - table where the attribute you are dropping lives +- `attribute` _(required)_ - attribute that you intend to drop + +### Body + +```json +{ + "operation": "drop_attribute", + "database": "dev", + "table": "dog", + "attribute": "is_adorable" +} +``` + +### Response: 200 + +```json +{ + "message": "successfully deleted attribute 'is_adorable'" +} +``` + +--- + +## Get Backup + +This will return a snapshot of the requested database. This provides a means for backing up the database through the operations API. The response will be the raw database file (in binary format), which can later be restored as a database file by copying into the appropriate hdb/databases directory (with Harper not running). The returned file is a snapshot of the database at the moment in time that the get_backup operation begins. This also supports backing up individual tables in a database. However, this is a more expensive operation than backing up a database in whole, and will lose any transactional atomicity between writes across tables, so generally it is recommended that you backup the entire database. + +It is important to note that trying to copy a database file that is in use (Harper actively running and writing to the file) using standard file copying tools is not safe (the copied file will likely be corrupt), which is why using this snapshot operation is recommended for backups (volume snapshots are also a good way to backup Harper databases). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - this should always be `get_backup` +- `database` _(required)_ - this is the database that will be snapshotted and returned +- `table` _(optional)_ - this will specify a specific table to backup +- `tables` _(optional)_ - this will specify a specific set of tables to backup + +### Body + +```json +{ + "operation": "get_backup", + "database": "dev" +} +``` + +### Response: 200 + +``` +The database in raw binary data format +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/index.md b/versioned_docs/version-4.6/reference/operations-api/index.md new file mode 100644 index 00000000..ad44d9de --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/index.md @@ -0,0 +1,55 @@ +--- +title: Operations API +--- + +# Operations API + +The operations API provides a full set of capabilities for configuring, deploying, administering, and controlling Harper. To send operations to the operations API, you send a POST request to the operations API endpoint, which [defaults to port 9925](../deployments/configuration#operationsapi), on the root path, where the body is the operations object. These requests need to authenticated, which can be done with [basic auth](./security#basic-auth) or [JWT authentication](./security#jwt-auth). For example, a request to create a table would be performed as: + +```http +POST https://my-harperdb-server:9925/ +Authorization: Basic YourBase64EncodedInstanceUser:Pass +Content-Type: application/json + +{ + "operation": "create_table", + "table": "my-table" +} +``` + +The operations API reference is available below and categorized by topic: + +- [Quick Start Examples](operations-api/quickstart-examples) +- [Databases and Tables](operations-api/databases-and-tables) +- [NoSQL Operations](operations-api/nosql-operations) +- [Bulk Operations](operations-api/bulk-operations) +- [Users and Roles](operations-api/users-and-roles) +- [Clustering](operations-api/clustering) +- [Clustering with NATS](operations-api/clustering-nats) +- [Components](operations-api/components) +- [Registration](operations-api/registration) +- [Jobs](operations-api/jobs) +- [Logs](operations-api/logs) +- [System Operations](operations-api/system-operations) +- [Configuration](operations-api/configuration) +- [Certificate Management](operations-api/certificate-management) +- [Token Authentication](operations-api/token-authentication) +- [SQL Operations](operations-api/sql-operations) +- [Advanced JSON SQL Examples](operations-api/advanced-json-sql-examples) +- [Analytics](operations-api/analytics) + +• [Past Release API Documentation](https://olddocs.harperdb.io) + +## More Examples + +Here is an example of using `curl` to make an operations API request: + +```bash +curl --location --request POST 'https://instance-subdomain.harperdbcloud.com' \ +--header 'Authorization: Basic YourBase64EncodedInstanceUser:Pass' \ +--header 'Content-Type: application/json' \ +--data-raw '{ +"operation": "create_schema", +"schema": "dev" +}' +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/jobs.md b/versioned_docs/version-4.6/reference/operations-api/jobs.md new file mode 100644 index 00000000..cf71fa00 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/jobs.md @@ -0,0 +1,87 @@ +--- +title: Jobs +--- + +# Jobs + +## Get Job + +Returns job status, metrics, and messages for the specified job ID. + +- `operation` _(required)_ - must always be `get_job` +- `id` _(required)_ - the id of the job you wish to view + +### Body + +```json +{ + "operation": "get_job", + "id": "4a982782-929a-4507-8794-26dae1132def" +} +``` + +### Response: 200 + +```json +[ + { + "__createdtime__": 1611615798782, + "__updatedtime__": 1611615801207, + "created_datetime": 1611615798774, + "end_datetime": 1611615801206, + "id": "4a982782-929a-4507-8794-26dae1132def", + "job_body": null, + "message": "successfully loaded 350 of 350 records", + "start_datetime": 1611615798805, + "status": "COMPLETE", + "type": "csv_url_load", + "user": "HDB_ADMIN", + "start_datetime_converted": "2021-01-25T23:03:18.805Z", + "end_datetime_converted": "2021-01-25T23:03:21.206Z" + } +] +``` + +--- + +## Search Jobs By Start Date + +Returns a list of job statuses, metrics, and messages for all jobs executed within the specified time window. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `search_jobs_by_start_date` +- `from_date` _(required)_ - the date you wish to start the search +- `to_date` _(required)_ - the date you wish to end the search + +### Body + +```json +{ + "operation": "search_jobs_by_start_date", + "from_date": "2021-01-25T22:05:27.464+0000", + "to_date": "2021-01-25T23:05:27.464+0000" +} +``` + +### Response: 200 + +```json +[ + { + "id": "942dd5cb-2368-48a5-8a10-8770ff7eb1f1", + "user": "HDB_ADMIN", + "type": "csv_url_load", + "status": "COMPLETE", + "start_datetime": 1611613284781, + "end_datetime": 1611613287204, + "job_body": null, + "message": "successfully loaded 350 of 350 records", + "created_datetime": 1611613284764, + "__createdtime__": 1611613284767, + "__updatedtime__": 1611613287207, + "start_datetime_converted": "2021-01-25T22:21:24.781Z", + "end_datetime_converted": "2021-01-25T22:21:27.204Z" + } +] +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/logs.md b/versioned_docs/version-4.6/reference/operations-api/logs.md new file mode 100644 index 00000000..52e52740 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/logs.md @@ -0,0 +1,732 @@ +--- +title: Logs +--- + +# Logs + +## Read Harper Log + +Returns log outputs from the primary Harper log based on the provided search criteria. [Read more about Harper logging here](../../administration/logging/standard-logging#read-logs-via-the-api). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `read_Log` +- `start` _(optional)_ - result to start with. Default is 0, the first log in `hdb.log`. Must be a number +- `limit` _(optional)_ - number of results returned. Default behavior is 1000. Must be a number +- `level` _(optional)_ - error level to filter on. Default behavior is all levels. Must be `notify`, `error`, `warn`, `info`, `debug` or `trace` +- `from` _(optional)_ - date to begin showing log results. Must be `YYYY-MM-DD` or `YYYY-MM-DD hh:mm:ss`. Default is first log in `hdb.log` +- `until` _(optional)_ - date to end showing log results. Must be `YYYY-MM-DD` or `YYYY-MM-DD hh:mm:ss`. Default is last log in `hdb.log` +- `order` _(optional)_ - order to display logs desc or asc by timestamp. By default, will maintain `hdb.log` order + +### Body + +```json +{ + "operation": "read_log", + "start": 0, + "limit": 1000, + "level": "error", + "from": "2021-01-25T22:05:27.464+0000", + "until": "2021-01-25T23:05:27.464+0000", + "order": "desc" +} +``` + +### Response: 200 + +```json +[ + { + "level": "notify", + "message": "Connected to cluster server.", + "timestamp": "2021-01-25T23:03:20.710Z", + "thread": "main/0", + "tags": [] + }, + { + "level": "warn", + "message": "Login failed", + "timestamp": "2021-01-25T22:24:45.113Z", + "thread": "http/9", + "tags": [] + }, + { + "level": "error", + "message": "unknown attribute 'name and breed'", + "timestamp": "2021-01-25T22:23:24.167Z", + "thread": "http/9", + "tags": [] + } +] +``` + +--- + +## Read Transaction Log + +Returns all transactions logged for the specified database table. You may filter your results with the optional from, to, and limit fields. [Read more about Harper transaction logs here](./logs#read-transaction-log). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `read_transaction_log` +- `schema` _(required)_ - schema under which the transaction log resides +- `table` _(required)_ - table under which the transaction log resides +- `from` _(optional)_ - time format must be millisecond-based epoch in UTC +- `to` _(optional)_ - time format must be millisecond-based epoch in UTC +- `limit` _(optional)_ - max number of logs you want to receive. Must be a number + +### Body + +```json +{ + "operation": "read_transaction_log", + "schema": "dev", + "table": "dog", + "from": 1560249020865, + "to": 1660585656639, + "limit": 10 +} +``` + +### Response: 200 + +```json +[ + { + "operation": "insert", + "user": "admin", + "timestamp": 1660165619736, + "records": [ + { + "id": 1, + "dog_name": "Penny", + "owner_name": "Kyle", + "breed_id": 154, + "age": 7, + "weight_lbs": 38, + "__updatedtime__": 1660165619688, + "__createdtime__": 1660165619688 + } + ] + }, + { + "operation": "insert", + "user": "admin", + "timestamp": 1660165619813, + "records": [ + { + "id": 2, + "dog_name": "Harper", + "owner_name": "Stephen", + "breed_id": 346, + "age": 7, + "weight_lbs": 55, + "adorable": true, + "__updatedtime__": 1660165619797, + "__createdtime__": 1660165619797 + }, + { + "id": 3, + "dog_name": "Alby", + "owner_name": "Kaylan", + "breed_id": 348, + "age": 7, + "weight_lbs": 84, + "adorable": true, + "__updatedtime__": 1660165619797, + "__createdtime__": 1660165619797 + }, + { + "id": 4, + "dog_name": "Billy", + "owner_name": "Zach", + "breed_id": 347, + "age": 6, + "weight_lbs": 60, + "adorable": true, + "__updatedtime__": 1660165619797, + "__createdtime__": 1660165619797 + }, + { + "id": 5, + "dog_name": "Rose Merry", + "owner_name": "Zach", + "breed_id": 348, + "age": 8, + "weight_lbs": 15, + "adorable": true, + "__updatedtime__": 1660165619797, + "__createdtime__": 1660165619797 + }, + { + "id": 6, + "dog_name": "Kato", + "owner_name": "Kyle", + "breed_id": 351, + "age": 6, + "weight_lbs": 32, + "adorable": true, + "__updatedtime__": 1660165619797, + "__createdtime__": 1660165619797 + }, + { + "id": 7, + "dog_name": "Simon", + "owner_name": "Fred", + "breed_id": 349, + "age": 3, + "weight_lbs": 35, + "adorable": true, + "__updatedtime__": 1660165619797, + "__createdtime__": 1660165619797 + }, + { + "id": 8, + "dog_name": "Gemma", + "owner_name": "Stephen", + "breed_id": 350, + "age": 5, + "weight_lbs": 55, + "adorable": true, + "__updatedtime__": 1660165619797, + "__createdtime__": 1660165619797 + }, + { + "id": 9, + "dog_name": "Yeti", + "owner_name": "Jaxon", + "breed_id": 200, + "age": 5, + "weight_lbs": 55, + "adorable": true, + "__updatedtime__": 1660165619797, + "__createdtime__": 1660165619797 + }, + { + "id": 10, + "dog_name": "Monkey", + "owner_name": "Aron", + "breed_id": 271, + "age": 7, + "weight_lbs": 35, + "adorable": true, + "__updatedtime__": 1660165619797, + "__createdtime__": 1660165619797 + }, + { + "id": 11, + "dog_name": "Bode", + "owner_name": "Margo", + "breed_id": 104, + "age": 8, + "weight_lbs": 75, + "adorable": true, + "__updatedtime__": 1660165619797, + "__createdtime__": 1660165619797 + }, + { + "id": 12, + "dog_name": "Tucker", + "owner_name": "David", + "breed_id": 346, + "age": 2, + "weight_lbs": 60, + "adorable": true, + "__updatedtime__": 1660165619798, + "__createdtime__": 1660165619798 + }, + { + "id": 13, + "dog_name": "Jagger", + "owner_name": "Margo", + "breed_id": 271, + "age": 7, + "weight_lbs": 35, + "adorable": true, + "__updatedtime__": 1660165619798, + "__createdtime__": 1660165619798 + } + ] + }, + { + "operation": "update", + "user": "admin", + "timestamp": 1660165620040, + "records": [ + { + "id": 1, + "dog_name": "Penny B", + "__updatedtime__": 1660165620036 + } + ] + } +] +``` + +--- + +## Delete Transaction Logs Before + +Deletes transaction log data for the specified database table that is older than the specified timestamp. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `delete_transaction_log_before` +- `schema` _(required)_ - schema under which the transaction log resides. Must be a string +- `table` _(required)_ - table under which the transaction log resides. Must be a string +- `timestamp` _(required)_ - records older than this date will be deleted. Format is millisecond-based epoch in UTC + +### Body + +```json +{ + "operation": "delete_transaction_logs_before", + "schema": "dev", + "table": "dog", + "timestamp": 1598290282817 +} +``` + +### Response: 200 + +```json +{ + "message": "Starting job with id 26a6d3a6-6d77-40f9-bee7-8d6ef479a126" +} +``` + +--- + +## Read Audit Log + +AuditLog must be enabled in the Harper configuration file to make this request. Returns a verbose history of all transactions logged for the specified database table, including original data records. You may filter your results with the optional search_type and search_values fields. [Read more about Harper transaction logs here.](../../administration/logging/transaction-logging#read_transaction_log) + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `read_audit_log` +- `schema` _(required)_ - schema under which the transaction log resides +- `table` _(required)_ - table under which the transaction log resides +- `search_type` _(optional)_ - possibilities are `hash_value`, `timestamp` and `username` +- `search_values` _(optional)_ - an array of string or numbers relating to search_type + +### Body + +```json +{ + "operation": "read_audit_log", + "schema": "dev", + "table": "dog" +} +``` + +### Response: 200 + +```json +[ + { + "operation": "insert", + "user_name": "admin", + "timestamp": 1660585635882.288, + "hash_values": [318], + "records": [ + { + "id": 318, + "dog_name": "Polliwog", + "__updatedtime__": 1660585635876, + "__createdtime__": 1660585635876 + } + ] + }, + { + "operation": "insert", + "user_name": "admin", + "timestamp": 1660585716133.01, + "hash_values": [444], + "records": [ + { + "id": 444, + "dog_name": "Davis", + "__updatedtime__": 1660585716128, + "__createdtime__": 1660585716128 + } + ] + }, + { + "operation": "update", + "user_name": "admin", + "timestamp": 1660585740558.415, + "hash_values": [444], + "records": [ + { + "id": 444, + "fur_type": "coarse", + "__updatedtime__": 1660585740556 + } + ], + "original_records": [ + { + "id": 444, + "dog_name": "Davis", + "__updatedtime__": 1660585716128, + "__createdtime__": 1660585716128 + } + ] + }, + { + "operation": "delete", + "user_name": "admin", + "timestamp": 1660585759710.56, + "hash_values": [444], + "original_records": [ + { + "id": 444, + "dog_name": "Davis", + "__updatedtime__": 1660585740556, + "__createdtime__": 1660585716128, + "fur_type": "coarse" + } + ] + } +] +``` + +--- + +## Read Audit Log by timestamp + +AuditLog must be enabled in the Harper configuration file to make this request. Returns the transactions logged for the specified database table between the specified time window. [Read more about Harper transaction logs here](./logs#read-transaction-log). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `read_audit_log` +- `schema` _(required)_ - schema under which the transaction log resides +- `table` _(required)_ - table under which the transaction log resides +- `search_type` _(optional)_ - timestamp +- `search_values` _(optional)_ - an array containing a maximum of two values \[`from_timestamp`, `to_timestamp`] defining the range of transactions you would like to view. + - Timestamp format is millisecond-based epoch in UTC + - If no items are supplied then all transactions are returned + - If only one entry is supplied then all transactions after the supplied timestamp will be returned + +### Body + +```json +{ + "operation": "read_audit_log", + "schema": "dev", + "table": "dog", + "search_type": "timestamp", + "search_values": [1660585740558, 1660585759710.56] +} +``` + +### Response: 200 + +```json +[ + { + "operation": "insert", + "user_name": "admin", + "timestamp": 1660585635882.288, + "hash_values": [318], + "records": [ + { + "id": 318, + "dog_name": "Polliwog", + "__updatedtime__": 1660585635876, + "__createdtime__": 1660585635876 + } + ] + }, + { + "operation": "insert", + "user_name": "admin", + "timestamp": 1660585716133.01, + "hash_values": [444], + "records": [ + { + "id": 444, + "dog_name": "Davis", + "__updatedtime__": 1660585716128, + "__createdtime__": 1660585716128 + } + ] + }, + { + "operation": "update", + "user_name": "admin", + "timestamp": 1660585740558.415, + "hash_values": [444], + "records": [ + { + "id": 444, + "fur_type": "coarse", + "__updatedtime__": 1660585740556 + } + ], + "original_records": [ + { + "id": 444, + "dog_name": "Davis", + "__updatedtime__": 1660585716128, + "__createdtime__": 1660585716128 + } + ] + }, + { + "operation": "delete", + "user_name": "admin", + "timestamp": 1660585759710.56, + "hash_values": [444], + "original_records": [ + { + "id": 444, + "dog_name": "Davis", + "__updatedtime__": 1660585740556, + "__createdtime__": 1660585716128, + "fur_type": "coarse" + } + ] + }, + { + "operation": "update", + "user_name": "admin", + "timestamp": 1660586298457.224, + "hash_values": [318], + "records": [ + { + "id": 318, + "fur_type": "super fluffy", + "__updatedtime__": 1660586298455 + } + ], + "original_records": [ + { + "id": 318, + "dog_name": "Polliwog", + "__updatedtime__": 1660585635876, + "__createdtime__": 1660585635876 + } + ] + } +] +``` + +--- + +## Read Audit Log by username + +AuditLog must be enabled in the Harper configuration file to make this request. Returns the transactions logged for the specified database table which were committed by the specified user. [Read more about Harper transaction logs here](../../administration/logging/transaction-logging#read_transaction_log). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `read_audit_log` +- `schema` _(required)_ - schema under which the transaction log resides +- `table` _(required)_ - table under which the transaction log resides +- `search_type` _(optional)_ - username +- `search_values` _(optional)_ - the Harper user for whom you would like to view transactions + +### Body + +```json +{ + "operation": "read_audit_log", + "schema": "dev", + "table": "dog", + "search_type": "username", + "search_values": ["admin"] +} +``` + +### Response: 200 + +```json +{ + "admin": [ + { + "operation": "insert", + "user_name": "admin", + "timestamp": 1660585635882.288, + "hash_values": [318], + "records": [ + { + "id": 318, + "dog_name": "Polliwog", + "__updatedtime__": 1660585635876, + "__createdtime__": 1660585635876 + } + ] + }, + { + "operation": "insert", + "user_name": "admin", + "timestamp": 1660585716133.01, + "hash_values": [444], + "records": [ + { + "id": 444, + "dog_name": "Davis", + "__updatedtime__": 1660585716128, + "__createdtime__": 1660585716128 + } + ] + }, + { + "operation": "update", + "user_name": "admin", + "timestamp": 1660585740558.415, + "hash_values": [444], + "records": [ + { + "id": 444, + "fur_type": "coarse", + "__updatedtime__": 1660585740556 + } + ], + "original_records": [ + { + "id": 444, + "dog_name": "Davis", + "__updatedtime__": 1660585716128, + "__createdtime__": 1660585716128 + } + ] + }, + { + "operation": "delete", + "user_name": "admin", + "timestamp": 1660585759710.56, + "hash_values": [444], + "original_records": [ + { + "id": 444, + "dog_name": "Davis", + "__updatedtime__": 1660585740556, + "__createdtime__": 1660585716128, + "fur_type": "coarse" + } + ] + }, + { + "operation": "update", + "user_name": "admin", + "timestamp": 1660586298457.224, + "hash_values": [318], + "records": [ + { + "id": 318, + "fur_type": "super fluffy", + "__updatedtime__": 1660586298455 + } + ], + "original_records": [ + { + "id": 318, + "dog_name": "Polliwog", + "__updatedtime__": 1660585635876, + "__createdtime__": 1660585635876 + } + ] + } + ] +} +``` + +--- + +## Read Audit Log by hash_value + +AuditLog must be enabled in the Harper configuration file to make this request. Returns the transactions logged for the specified database table which were committed to the specified hash value(s). [Read more about Harper transaction logs here](../../administration/logging/transaction-logging#read_transaction_log). + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `read_audit_log` +- `schema` _(required)_ - schema under which the transaction log resides +- `table` _(required)_ - table under which the transaction log resides +- `search_type` _(optional)_ - hash_value +- `search_values` _(optional)_ - an array of hash_attributes for which you wish to see transaction logs + +### Body + +```json +{ + "operation": "read_audit_log", + "schema": "dev", + "table": "dog", + "search_type": "hash_value", + "search_values": [318] +} +``` + +### Response: 200 + +```json +{ + "318": [ + { + "operation": "insert", + "user_name": "admin", + "timestamp": 1660585635882.288, + "records": [ + { + "id": 318, + "dog_name": "Polliwog", + "__updatedtime__": 1660585635876, + "__createdtime__": 1660585635876 + } + ] + }, + { + "operation": "update", + "user_name": "admin", + "timestamp": 1660586298457.224, + "records": [ + { + "id": 318, + "fur_type": "super fluffy", + "__updatedtime__": 1660586298455 + } + ], + "original_records": [ + { + "id": 318, + "dog_name": "Polliwog", + "__updatedtime__": 1660585635876, + "__createdtime__": 1660585635876 + } + ] + } + ] +} +``` + +--- + +## Delete Audit Logs Before + +AuditLog must be enabled in the Harper configuration file to make this request. Deletes audit log data for the specified database table that is older than the specified timestamp. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `delete_audit_logs_before` +- `schema` _(required)_ - schema under which the transaction log resides. Must be a string +- `table` _(required)_ - table under which the transaction log resides. Must be a string +- `timestamp` _(required)_ - records older than this date will be deleted. Format is millisecond-based epoch in UTC + +### Body + +```json +{ + "operation": "delete_audit_logs_before", + "schema": "dev", + "table": "dog", + "timestamp": 1660585759710.56 +} +``` + +### Response: 200 + +```json +{ + "message": "Starting job with id 7479e5f8-a86e-4fc9-add7-749493bc100f" +} +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/nosql-operations.md b/versioned_docs/version-4.6/reference/operations-api/nosql-operations.md new file mode 100644 index 00000000..e9272508 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/nosql-operations.md @@ -0,0 +1,389 @@ +--- +title: NoSQL Operations +--- + +# NoSQL Operations + +## Insert + +Adds one or more rows of data to a database table. Primary keys of the inserted JSON record may be supplied on insert. If a primary key is not provided, then a GUID or incremented number (depending on type) will be generated for each record. + +- `operation` _(required)_ - must always be `insert` +- `database` _(optional)_ - database where the table you are inserting records into lives. The default is `data` +- `table` _(required)_ - table where you want to insert records +- `records` _(required)_ - array of one or more records for insert + +### Body + +```json +{ + "operation": "insert", + "database": "dev", + "table": "dog", + "records": [ + { + "id": 8, + "dog_name": "Harper", + "breed_id": 346, + "age": 7 + }, + { + "id": 9, + "dog_name": "Penny", + "breed_id": 154, + "age": 7 + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "inserted 2 of 2 records", + "inserted_hashes": [8, 9], + "skipped_hashes": [] +} +``` + +--- + +## Update + +Changes the values of specified attributes in one or more rows in a database table as identified by the primary key. NOTE: Primary key of the updated JSON record(s) MUST be supplied on update. + +- `operation` _(required)_ - must always be `update` +- `database` _(optional)_ - database of the table you are updating records in. The default is `data` +- `table` _(required)_ - table where you want to update records +- `records` _(required)_ - array of one or more records for update + +### Body + +```json +{ + "operation": "update", + "database": "dev", + "table": "dog", + "records": [ + { + "id": 1, + "weight_lbs": 55 + }, + { + "id": 2, + "owner": "Kyle B", + "weight_lbs": 35 + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "updated 2 of 2 records", + "update_hashes": [1, 3], + "skipped_hashes": [] +} +``` + +--- + +## Upsert + +Changes the values of specified attributes for rows with matching primary keys that exist in the table. Adds rows to the database table for primary keys that do not exist or are not provided. + +- `operation` _(required)_ - must always be `upsert` +- `database` _(optional)_ - database of the table you are updating records in. The default is `data` +- `table` _(required)_ - table where you want to update records +- `records` _(required)_ - array of one or more records for update + +### Body + +```json +{ + "operation": "upsert", + "database": "dev", + "table": "dog", + "records": [ + { + "id": 8, + "weight_lbs": 155 + }, + { + "name": "Bill", + "breed": "Pit Bull", + "id": 10, + "Age": 11, + "weight_lbs": 155 + }, + { + "name": "Harper", + "breed": "Mutt", + "age": 5, + "weight_lbs": 155 + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "upserted 3 of 3 records", + "upserted_hashes": [8, 10, "ea06fc8e-717b-4c6c-b69d-b29014054ab7"] +} +``` + +--- + +## Delete + +Removes one or more rows of data from a specified table. + +- `operation` _(required)_ - must always be `delete` +- `database` _(optional)_ - database where the table you are deleting records lives. The default is `data` +- `table` _(required)_ - table where you want to deleting records +- `ids` _(required)_ - array of one or more primary key values, which identifies records to delete + +### Body + +```json +{ + "operation": "delete", + "database": "dev", + "table": "dog", + "ids": [1, 2] +} +``` + +### Response: 200 + +```json +{ + "message": "2 of 2 records successfully deleted", + "deleted_hashes": [1, 2], + "skipped_hashes": [] +} +``` + +--- + +## Search By ID + +Returns data from a table for one or more primary keys. + +- `operation` _(required)_ - must always be `search_by_id` +- `database` _(optional)_ - database where the table you are searching lives. The default is `data` +- `table` _(required)_ - table you wish to search +- `ids` _(required)_ - array of primary keys to retrieve +- `get_attributes` _(required)_ - define which attributes you want returned. Use `['*']` to return all attributes + +### Body + +```json +{ + "operation": "search_by_id", + "database": "dev", + "table": "dog", + "ids": [1, 2], + "get_attributes": ["dog_name", "breed_id"] +} +``` + +### Response: 200 + +```json +[ + { + "dog_name": "Penny", + "breed_id": 154 + }, + { + "dog_name": "Harper", + "breed_id": 346 + } +] +``` + +--- + +## Search By Value + +Returns data from a table for a matching value. + +- `operation` _(required)_ - must always be `search_by_value` +- `database` _(optional)_ - database where the table you are searching lives. The default is `data` +- `table` _(required)_ - table you wish to search +- `attribute` _(required)_ - attribute you wish to search can be any attribute +- `search_attribute` - deprecated in favor of `attribute` +- `value` _(required)_ - value you wish to search - wild cards are allowed +- `search_value` - deprecated in favor of `value` +- `get_attributes` _(required)_ - define which attributes you want returned. Use `['*']` to return all attributes + +### Body + +```json +{ + "operation": "search_by_value", + "database": "dev", + "table": "dog", + "attribute": "owner_name", + "value": "Ky*", + "get_attributes": ["id", "dog_name"] +} +``` + +### Response: 200 + +```json +[ + { + "dog_name": "Penny" + }, + { + "dog_name": "Kato" + } +] +``` + +--- + +## Search By Conditions + +Returns data from a table for one or more matching conditions. This supports grouping of conditions to indicate order of operations as well. + +- `operation` _(required)_ - must always be `search_by_conditions` +- `database` _(optional)_ - database where the table you are searching lives. The default is `data` +- `table` _(required)_ - table you wish to search +- `operator` _(optional)_ - the operator used between each condition - `and`, `or`. The default is `and` +- `offset` _(optional)_ - the number of records that the query results will skip. The default is `0` +- `limit` _(optional)_ - the number of records that the query results will include. The default is `null`, resulting in no limit +- `sort` _optional_ - This is an object that indicates the sort order. It has the following properties: + - `attribute` _(required)_ - The attribute to sort by + - `descending` _(optional)_ - If true, will sort in descending order (defaults to ascending order) + - `next` _(optional)_ - This can define the next sort object that will be used to break ties for sorting when there are multiple records with the same value for the first attribute (follows the same structure as `sort`). +- `get_attributes` _(required)_ - define which attributes you want returned. Use `['*']` to return all attributes +- `conditions` _(required)_ - the array of conditions objects, specified below, to filter by. Must include one or more object in the array that are a condition or a grouped set of conditions. A condition has the following properties: + - `attribute` _(required)_ - the attribute you wish to search, can be any attribute. + - `search_attribute` - deprecated in favor of `attribute` + - `comparator` _(required)_ - the type of search to perform - `equals`, `contains`, `starts_with`, `ends_with`, `greater_than`, `greater_than_equal`, `less_than`, `less_than_equal`, `between` + - `search_type` - deprecated in favor of `comparator` + - `value` _(required)_ - case-sensitive value you wish to search. If the `comparator` is `between` then use an array of two values to search between + - `search_value` - deprecated in favor of `value` + Or a set of grouped conditions has the following properties: + - `operator` _(optional)_ - the operator used between each condition - `and`, `or`. The default is `and` + - `conditions` _(required)_ - the array of conditions objects as described above. + +### Body + +```json +{ + "operation": "search_by_conditions", + "database": "dev", + "table": "dog", + "operator": "and", + "offset": 0, + "limit": 10, + "sort": { + "attribute": "id", + "next": { + "attribute": "age", + "descending": true + } + }, + "get_attributes": ["*"], + "conditions": [ + { + "attribute": "age", + "comparator": "between", + "value": [5, 8] + }, + { + "attribute": "weight_lbs", + "comparator": "greater_than", + "value": 40 + }, + { + "operator": "or", + "conditions": [ + { + "attribute": "adorable", + "comparator": "equals", + "value": true + }, + { + "attribute": "lovable", + "comparator": "equals", + "value": true + } + ] + } + ] +} +``` + +### Response: 200 + +```json +[ + { + "__createdtime__": 1620227719791, + "__updatedtime__": 1620227719791, + "adorable": true, + "age": 7, + "breed_id": 346, + "dog_name": "Harper", + "id": 2, + "owner_name": "Stephen", + "weight_lbs": 55 + }, + { + "__createdtime__": 1620227719792, + "__updatedtime__": 1620227719792, + "adorable": true, + "age": 7, + "breed_id": 348, + "dog_name": "Alby", + "id": 3, + "owner_name": "Kaylan", + "weight_lbs": 84 + }, + { + "__createdtime__": 1620227719792, + "__updatedtime__": 1620227719792, + "adorable": true, + "age": 6, + "breed_id": 347, + "dog_name": "Billy", + "id": 4, + "owner_name": "Zach", + "weight_lbs": 60 + }, + { + "__createdtime__": 1620227719792, + "__updatedtime__": 1620227719792, + "adorable": true, + "age": 5, + "breed_id": 250, + "dog_name": "Gemma", + "id": 8, + "owner_name": "Stephen", + "weight_lbs": 55 + }, + { + "__createdtime__": 1620227719792, + "__updatedtime__": 1620227719792, + "adorable": true, + "age": 8, + "breed_id": 104, + "dog_name": "Bode", + "id": 11, + "owner_name": "Margo", + "weight_lbs": 75 + } +] +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/quickstart-examples.md b/versioned_docs/version-4.6/reference/operations-api/quickstart-examples.md new file mode 100644 index 00000000..a6c8f637 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/quickstart-examples.md @@ -0,0 +1,370 @@ +--- +title: Quick Start Examples +--- + +# Quick Start Examples + +Harper recommends utilizing [Harper Applications](../../developers/applications/) for defining databases, tables, and other functionality. However, this guide is a great way to get started using on the Harper Operations API. + +## Create dog Table + +We first need to create a table. Since our company is named after our CEO's dog, lets create a table to store all our employees' dogs. We'll call this table, `dogs`. + +Tables in Harper are schema-less, so we don't need to add any attributes other than a primary_key (in pre 4.2 versions this was referred to as the hash_attribute) to create this table. + +Harper does offer a `database` parameter that can be used to hold logical groupings of tables. The parameter is optional and if not provided the operation will default to using a database named `data`. + +If you receive an error response, make sure your Basic Authentication user and password match those you entered during the installation process. + +### Body + +```json +{ + "operation": "create_table", + "table": "dog", + "primary_key": "id" +} +``` + +### Response: 200 + +```json +{ + "message": "table 'data.dog' successfully created." +} +``` + +--- + +## Create breed Table + +Now that we have a table to store our dog data, we also want to create a table to track known breeds. Just as with the dog table, the only attribute we need to specify is the `primary_key`. + +### Body + +```json +{ + "operation": "create_table", + "table": "breed", + "primary_key": "id" +} +``` + +### Response: 200 + +```json +{ + "message": "table 'data.breed' successfully created." +} +``` + +--- + +## Insert 1 Dog + +We're ready to add some dog data. Penny is our CTO's pup, so she gets ID 1 or we're all fired. We are specifying attributes in this call, but this doesn't prevent us from specifying additional attributes in subsequent calls. + +### Body + +```json +{ + "operation": "insert", + "table": "dog", + "records": [ + { + "id": 1, + "dog_name": "Penny", + "owner_name": "Kyle", + "breed_id": 154, + "age": 7, + "weight_lbs": 38 + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "inserted 1 of 1 records", + "inserted_hashes": [1], + "skipped_hashes": [] +} +``` + +--- + +## Insert Multiple Dogs + +Let's add some more Harper doggies! We can add as many dog objects as we want into the records collection. If you're adding a lot of objects, we would recommend using the .csv upload option (see the next section where we populate the breed table). + +### Body + +```json +{ + "operation": "insert", + "table": "dog", + "records": [ + { + "id": 2, + "dog_name": "Harper", + "owner_name": "Stephen", + "breed_id": 346, + "age": 7, + "weight_lbs": 55, + "adorable": true + }, + { + "id": 3, + "dog_name": "Alby", + "owner_name": "Kaylan", + "breed_id": 348, + "age": 7, + "weight_lbs": 84, + "adorable": true + }, + { + "id": 4, + "dog_name": "Billy", + "owner_name": "Zach", + "breed_id": 347, + "age": 6, + "weight_lbs": 60, + "adorable": true + }, + { + "id": 5, + "dog_name": "Rose Merry", + "owner_name": "Zach", + "breed_id": 348, + "age": 8, + "weight_lbs": 15, + "adorable": true + }, + { + "id": 6, + "dog_name": "Kato", + "owner_name": "Kyle", + "breed_id": 351, + "age": 6, + "weight_lbs": 32, + "adorable": true + }, + { + "id": 7, + "dog_name": "Simon", + "owner_name": "Fred", + "breed_id": 349, + "age": 3, + "weight_lbs": 35, + "adorable": true + }, + { + "id": 8, + "dog_name": "Gemma", + "owner_name": "Stephen", + "breed_id": 350, + "age": 5, + "weight_lbs": 55, + "adorable": true + }, + { + "id": 9, + "dog_name": "Yeti", + "owner_name": "Jaxon", + "breed_id": 200, + "age": 5, + "weight_lbs": 55, + "adorable": true + }, + { + "id": 10, + "dog_name": "Monkey", + "owner_name": "Aron", + "breed_id": 271, + "age": 7, + "weight_lbs": 35, + "adorable": true + }, + { + "id": 11, + "dog_name": "Bode", + "owner_name": "Margo", + "breed_id": 104, + "age": 8, + "weight_lbs": 75, + "adorable": true + }, + { + "id": 12, + "dog_name": "Tucker", + "owner_name": "David", + "breed_id": 346, + "age": 2, + "weight_lbs": 60, + "adorable": true + }, + { + "id": 13, + "dog_name": "Jagger", + "owner_name": "Margo", + "breed_id": 271, + "age": 7, + "weight_lbs": 35, + "adorable": true + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "inserted 12 of 12 records", + "inserted_hashes": [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13], + "skipped_hashes": [] +} +``` + +--- + +## Bulk Insert Breeds Via CSV + +We need to populate the 'breed' table with some data so we can reference it later. For larger data sets, we recommend using our CSV upload option. + +Each header in a column will be considered as an attribute, and each row in the file will be a row in the table. Simply specify the file path and the table to upload to, and Harper will take care of the rest. You can pull the breeds.csv file from here: [https://s3.amazonaws.com/complimentarydata/breeds.csv](https://s3.amazonaws.com/complimentarydata/breeds.csv) + +### Body + +```json +{ + "operation": "csv_url_load", + "table": "breed", + "csv_url": "https://s3.amazonaws.com/complimentarydata/breeds.csv" +} +``` + +### Response: 200 + +```json +{ + "message": "Starting job with id e77d63b9-70d5-499c-960f-6736718a4369", + "job_id": "e77d63b9-70d5-499c-960f-6736718a4369" +} +``` + +--- + +## Update 1 Dog Using NoSQL + +Harper supports NoSQL and SQL commands. We're going to update the dog table to show Penny's last initial using our NoSQL API. + +### Body + +```json +{ + "operation": "update", + "table": "dog", + "records": [ + { + "id": 1, + "dog_name": "Penny B" + } + ] +} +``` + +### Response: 200 + +```json +{ + "message": "updated 1 of 1 records", + "update_hashes": [1], + "skipped_hashes": [] +} +``` + +--- + +## Select a Dog by ID Using SQL + +Now we're going to use a simple SQL SELECT call to pull Penny's updated data. Note we now see Penny's last initial in the dog name. + +### Body + +```json +{ + "operation": "sql", + "sql": "SELECT * FROM data.dog where id = 1" +} +``` + +### Response: 200 + +```json +[ + { + "owner_name": "Kyle", + "adorable": null, + "breed_id": 154, + "__updatedtime__": 1610749428575, + "dog_name": "Penny B", + "weight_lbs": 38, + "id": 1, + "age": 7, + "__createdtime__": 1610749386566 + } +] +``` + +--- + +## Select Dogs and Join Breed + +Here's a more complex SQL command joining the breed table with the dog table. We will also pull only the pups belonging to Kyle, Zach, and Stephen. + +### Body + +```json +{ + "operation": "sql", + "sql": "SELECT d.id, d.dog_name, d.owner_name, b.name, b.section FROM data.dog AS d INNER JOIN data.breed AS b ON d.breed_id = b.id WHERE d.owner_name IN ('Kyle', 'Zach', 'Stephen') AND b.section = 'Mutt' ORDER BY d.dog_name" +} +``` + +### Response: 200 + +```json +[ + { + "id": 4, + "dog_name": "Billy", + "owner_name": "Zach", + "name": "LABRADOR / GREAT DANE MIX", + "section": "Mutt" + }, + { + "id": 8, + "dog_name": "Gemma", + "owner_name": "Stephen", + "name": "SHORT HAIRED SETTER MIX", + "section": "Mutt" + }, + { + "id": 2, + "dog_name": "Harper", + "owner_name": "Stephen", + "name": "HUSKY MIX", + "section": "Mutt" + }, + { + "id": 5, + "dog_name": "Rose Merry", + "owner_name": "Zach", + "name": "TERRIER MIX", + "section": "Mutt" + } +] +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/registration.md b/versioned_docs/version-4.6/reference/operations-api/registration.md new file mode 100644 index 00000000..28c6a0e9 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/registration.md @@ -0,0 +1,70 @@ +--- +title: Registration +--- + +# Registration + +## Registration Info + +Returns the registration data of the Harper instance. + +- `operation` _(required)_ - must always be `registration_info` + +### Body + +```json +{ + "operation": "registration_info" +} +``` + +### Response: 200 + +```json +{ + "registered": true, + "version": "4.2.0", + "ram_allocation": 2048, + "license_expiration_date": "2022-01-15" +} +``` + +--- + +## Get Fingerprint + +Returns the Harper fingerprint, uniquely generated based on the machine, for licensing purposes. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `get_fingerprint` + +### Body + +```json +{ + "operation": "get_fingerprint" +} +``` + +--- + +## Set License + +Sets the Harper license as generated by Harper License Management software. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `set_license` +- `key` _(required)_ - your license key +- `company` _(required)_ - the company that was used in the license + +### Body + +```json +{ + "operation": "set_license", + "key": "", + "company": "" +} +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/sql-operations.md b/versioned_docs/version-4.6/reference/operations-api/sql-operations.md new file mode 100644 index 00000000..4b7076bb --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/sql-operations.md @@ -0,0 +1,127 @@ +--- +title: SQL Operations +--- + +:::warning +Harper encourages developers to utilize other querying tools over SQL for performance purposes. Harper SQL is intended for data investigation purposes and uses cases where performance is not a priority. SQL optimizations are on our roadmap for the future. +::: + +# SQL Operations + +## Select + +Executes the provided SQL statement. The SELECT statement is used to query data from the database. + +- `operation` _(required)_ - must always be `sql` +- `sql` _(required)_ - use standard SQL + +### Body + +```json +{ + "operation": "sql", + "sql": "SELECT * FROM dev.dog WHERE id = 1" +} +``` + +### Response: 200 + +```json +[ + { + "id": 1, + "age": 7, + "dog_name": "Penny", + "weight_lbs": 38, + "breed_id": 154, + "owner_name": "Kyle", + "adorable": true, + "__createdtime__": 1611614106043, + "__updatedtime__": 1611614119507 + } +] +``` + +--- + +## Insert + +Executes the provided SQL statement. The INSERT statement is used to add one or more rows to a database table. + +- `operation` _(required)_ - must always be `sql` +- `sql` _(required)_ - use standard SQL + +### Body + +```json +{ + "operation": "sql", + "sql": "INSERT INTO dev.dog (id, dog_name) VALUE (22, 'Simon')" +} +``` + +### Response: 200 + +```json +{ + "message": "inserted 1 of 1 records", + "inserted_hashes": [22], + "skipped_hashes": [] +} +``` + +--- + +## Update + +Executes the provided SQL statement. The UPDATE statement is used to change the values of specified attributes in one or more rows in a database table. + +- `operation` _(required)_ - must always be `sql` +- `sql` _(required)_ - use standard SQL + +### Body + +```json +{ + "operation": "sql", + "sql": "UPDATE dev.dog SET dog_name = 'penelope' WHERE id = 1" +} +``` + +### Response: 200 + +```json +{ + "message": "updated 1 of 1 records", + "update_hashes": [1], + "skipped_hashes": [] +} +``` + +--- + +## Delete + +Executes the provided SQL statement. The DELETE statement is used to remove one or more rows of data from a database table. + +- `operation` _(required)_ - must always be `sql` +- `sql` _(required)_ - use standard SQL + +### Body + +```json +{ + "operation": "sql", + "sql": "DELETE FROM dev.dog WHERE id = 1" +} +``` + +### Response: 200 + +```json +{ + "message": "1 of 1 record successfully deleted", + "deleted_hashes": [1], + "skipped_hashes": [] +} +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/system-operations.md b/versioned_docs/version-4.6/reference/operations-api/system-operations.md new file mode 100644 index 00000000..d39e93cb --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/system-operations.md @@ -0,0 +1,195 @@ +--- +title: System Operations +--- + +# System Operations + +## Restart + +Restarts the Harper instance. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `restart` + +### Body + +```json +{ + "operation": "restart" +} +``` + +### Response: 200 + +```json +{ + "message": "Restarting HarperDB. This may take up to 60 seconds." +} +``` + +--- + +## Restart Service + +Restarts servers for the specified Harper service. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `restart_service` +- `service` _(required)_ - must be one of: `http_workers`, `clustering_config` or `clustering` +- `replicated` _(optional)_ - must be a boolean. If set to `true`, Harper will replicate the restart service operation across all nodes in the cluster. The restart will occur as a rolling restart, ensuring that each node is fully restarted before the next node begins restarting. + +### Body + +```json +{ + "operation": "restart_service", + "service": "http_workers" +} +``` + +### Response: 200 + +```json +{ + "message": "Restarting http_workers" +} +``` + +--- + +## System Information + +Returns detailed metrics on the host system. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `system_information` +- `attributes` _(optional)_ - string array of top level attributes desired in the response, if no value is supplied all attributes will be returned. Available attributes are: ['system', 'time', 'cpu', 'memory', 'disk', 'network', 'harperdb_processes', 'table_size', 'metrics', 'threads', 'replication'] + +### Body + +```json +{ + "operation": "system_information" +} +``` + +--- + +## Set Status + +Sets a status value that can be used for application-specific status tracking. Status values are stored in memory and are not persisted across restarts. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `set_status` +- `id` _(required)_ - the key identifier for the status +- `status` _(required)_ - the status value to set (string between 1-512 characters) + +### Body + +```json +{ + "operation": "set_status", + "id": "primary", + "status": "active" +} +``` + +### Response: 200 + +```json +{ + "id": "primary", + "status": "active", + "__createdtime__": 1621364589543, + "__updatedtime__": 1621364589543 +} +``` + +### Notes + +- The `id` parameter must be one of the allowed status types: 'primary', 'maintenance', or 'availability' +- If no `id` is specified, it defaults to 'primary' +- For 'availability' status, only 'Available' or 'Unavailable' values are accepted +- For other status types, any string value is accepted + +--- + +## Get Status + +Retrieves a status value previously set with the set_status operation. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `get_status` +- `id` _(optional)_ - the key identifier for the status to retrieve (defaults to all statuses if not provided) + +### Body + +```json +{ + "operation": "get_status", + "id": "primary" +} +``` + +### Response: 200 + +```json +{ + "id": "primary", + "status": "active", + "__createdtime__": 1621364589543, + "__updatedtime__": 1621364589543 +} +``` + +If no id parameter is provided, all status values will be returned: + +```json +[ + { + "id": "primary", + "status": "active", + "__createdtime__": 1621364589543, + "__updatedtime__": 1621364589543 + }, + { + "id": "maintenance", + "status": "scheduled", + "__createdtime__": 1621364600123, + "__updatedtime__": 1621364600123 + } +] +``` + +--- + +## Clear Status + +Removes a status entry by its ID. + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `clear_status` +- `id` _(required)_ - the key identifier for the status to remove + +### Body + +```json +{ + "operation": "clear_status", + "id": "primary" +} +``` + +### Response: 200 + +```json +{ + "message": "Status successfully cleared" +} +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/token-authentication.md b/versioned_docs/version-4.6/reference/operations-api/token-authentication.md new file mode 100644 index 00000000..178db842 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/token-authentication.md @@ -0,0 +1,60 @@ +--- +title: Token Authentication +--- + +# Token Authentication + +## Create Authentication Tokens + +Creates the tokens needed for authentication: operation & refresh token. + +_Note - this operation does not require authorization to be set_ + +- `operation` _(required)_ - must always be `create_authentication_tokens` +- `username` _(required)_ - username of user to generate tokens for +- `password` _(required)_ - password of user to generate tokens for + +### Body + +```json +{ + "operation": "create_authentication_tokens", + "username": "", + "password": "" +} +``` + +### Response: 200 + +```json +{ + "operation_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IkhEQl9BRE1JTiIsImlhdCI6MTYwNTA2Mzk0OSwiZXhwIjoxNjA1MTUwMzQ5LCJzdWIiOiJvcGVyYXRpb24ifQ.TlV93BqavQVQntXTt_WeY5IjAuCshfd6RzhihLWFWhu1qEKLHdwg9o5Z4ASaNmfuyKBqbFw65IbOYKd348EXeC_T6d0GO3yUhICYWXkqhQnxVW_T-ECKc7m5Bty9HTgfeaJ2e2yW55nbZYWG_gLtNgObUjCziX20-gGGR25sNTRm78mLQPYQkBJph6WXwAuyQrX704h0NfvNqyAZSwjxgtjuuEftTJ7FutLrQSLGIBIYq9nsHrFkheiDSn-C8_WKJ_zATa4YIofjqn9g5wA6o_7kSNaU2-gWnCm_jbcAcfvOmXh6rd89z8pwPqnC0f131qHIBps9UHaC1oozzmu_C6bsg7905OoAdFFY42Vojs98SMbfRApRvwaS4SprBsam3izODNI64ZUBREu3l4SZDalUf2kN8XPVWkI1LKq_mZsdtqr1r11Z9xslI1wVdxjunYeanjBhs7_j2HTX7ieVGn1a23cWceUk8F1HDGe_KEuPQs03R73V8acq_freh-kPhIa4eLqmcHeBw3WcyNGW8GuP8kyQRkGuO5sQSzZqbr_YSbZdSShZWTWDE6RYYC9ZV9KJtHVxhs0hexUpcoqO8OtJocyltRjtDjhSm9oUxszYRaALu-h8YadZT9dEKzsyQIt30d7LS9ETmmGWx4nKSTME2bV21PnDv_rEc5R6gnE", + "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IkhEQl9BRE1JTiIsImlhdCI6MTYwNTA2Mzk0OSwiZXhwIjoxNjA3NjU1OTQ5LCJzdWIiOiJyZWZyZXNoIn0.znhJhkdSROBPP_GLRzAxYdjgQ3BuqpAbQB7zMSSOQJ3s83HnmZ10Bnpw_3L2aF-tOFgz_t6HUAvn26fNOLsspJD2aOvHPcVS4yLKS5nagpA6ar_pqng9f6Ebfs8ohguLCfHnHRJ8poLxuWRvWW9_9pIlDiwsj4yo3Mbxi3mW8Bbtnk2MwiNHFxTksD12Ne8EWz8q2jic5MjArqBBgR373oYoWU1oxpTM6gIsZCBRowXcc9XFy2vyRoggEUU4ISRFQ4ZY9ayJ-_jleSDCUamJSNQsdb1OUTvc6CxeYlLjCoV0ijRUB6p2XWNVezFhDu8yGqOeyGFJzArhxbVc_pl4UYd5aUVxhrO9DdhG29cY_mHV0FqfXphR9QllK--LJFTP4aFqkCxnVr7HSa17hL0ZVK1HaKrx21PAdCkVNZpD6J3RtRbTkfnIB_C3Be9jhOV3vpTf7ZGn_Bs3CPJi_sL313Z1yKSDAS5rXTPceEOcTPHjzkMP9Wz19KfFq_0kuiZdDmeYNqJeFPAgGJ-S0tO51krzyGqLyCCA32_W104GR8OoQi2gEED6HIx2G0-1rnLnefN6eHQiY5r-Q3Oj9e2y3EvqqgWOmEDw88-SjPTwQVnMbBHYN2RfluU7EmvDh6Saoe79Lhlu8ZeSJ1x6ZgA8-Cirraz1_526Tn8v5FGDfrc" +} +``` + +--- + +## Refresh Operation Token + +This operation creates a new operation token. + +- `operation` _(required)_ - must always be `refresh_operation_token` +- `refresh_token` _(required)_ - the refresh token that was provided when tokens were created + +### Body + +```json +{ + "operation": "refresh_operation_token", + "refresh_token": "EXISTING_REFRESH_TOKEN" +} +``` + +### Response: 200 + +```json +{ + "operation_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6eyJfX2NyZWF0ZWR0aW1lX18iOjE2MDQ1MTc4Nzk1MjMsIl9fdXBkYXRlZHRpbWVfXyI6MTYwNDUxNzg3OTUyMywiYWN0aXZlIjp0cnVlLCJhdXRoX3Rva2VuIjpudWxsLCJyb2xlIjp7Il9fY3JlYXRlZHRpbWVfXyI6MTYwNDUxNzg3OTUyMSwiX191cGRhdGVkdGltZV9fIjoxNjA0NTE3ODc5NTIxLCJpZCI6IjZhYmRjNGJhLWU5MjQtNDlhNi1iOGY0LWM1NWUxYmQ0OTYzZCIsInBlcm1pc3Npb24iOnsic3VwZXJfdXNlciI6dHJ1ZSwic3lzdGVtIjp7InRhYmxlcyI6eyJoZGJfdGFibGUiOnsicmVhZCI6dHJ1ZSwiaW5zZXJ0IjpmYWxzZSwidXBkYXRlIjpmYWxzZSwiZGVsZXRlIjpmYWxzZSwiYXR0cmlidXRlX3Blcm1pc3Npb25zIjpbXX0sImhkYl9hdHRyaWJ1dGUiOnsicmVhZCI6dHJ1ZSwiaW5zZXJ0IjpmYWxzZSwidXBkYXRlIjpmYWxzZSwiZGVsZXRlIjpmYWxzZSwiYXR0cmlidXRlX3Blcm1pc3Npb25zIjpbXX0sImhkYl9zY2hlbWEiOnsicmVhZCI6dHJ1ZSwiaW5zZXJ0IjpmYWxzZSwidXBkYXRlIjpmYWxzZSwiZGVsZXRlIjpmYWxzZSwiYXR0cmlidXRlX3Blcm1pc3Npb25zIjpbXX0sImhkYl91c2VyIjp7InJlYWQiOnRydWUsImluc2VydCI6ZmFsc2UsInVwZGF0ZSI6ZmFsc2UsImRlbGV0ZSI6ZmFsc2UsImF0dHJpYnV0ZV9wZXJtaXNzaW9ucyI6W119LCJoZGJfcm9sZSI6eyJyZWFkIjp0cnVlLCJpbnNlcnQiOmZhbHNlLCJ1cGRhdGUiOmZhbHNlLCJkZWxldGUiOmZhbHNlLCJhdHRyaWJ1dGVfcGVybWlzc2lvbnMiOltdfSwiaGRiX2pvYiI6eyJyZWFkIjp0cnVlLCJpbnNlcnQiOmZhbHNlLCJ1cGRhdGUiOmZhbHNlLCJkZWxldGUiOmZhbHNlLCJhdHRyaWJ1dGVfcGVybWlzc2lvbnMiOltdfSwiaGRiX2xpY2Vuc2UiOnsicmVhZCI6dHJ1ZSwiaW5zZXJ0IjpmYWxzZSwidXBkYXRlIjpmYWxzZSwiZGVsZXRlIjpmYWxzZSwiYXR0cmlidXRlX3Blcm1pc3Npb25zIjpbXX0sImhkYl9pbmZvIjp7InJlYWQiOnRydWUsImluc2VydCI6ZmFsc2UsInVwZGF0ZSI6ZmFsc2UsImRlbGV0ZSI6ZmFsc2UsImF0dHJpYnV0ZV9wZXJtaXNzaW9ucyI6W119LCJoZGJfbm9kZXMiOnsicmVhZCI6dHJ1ZSwiaW5zZXJ0IjpmYWxzZSwidXBkYXRlIjpmYWxzZSwiZGVsZXRlIjpmYWxzZSwiYXR0cmlidXRlX3Blcm1pc3Npb25zIjpbXX0sImhkYl90ZW1wIjp7InJlYWQiOnRydWUsImluc2VydCI6ZmFsc2UsInVwZGF0ZSI6ZmFsc2UsImRlbGV0ZSI6ZmFsc2UsImF0dHJpYnV0ZV9wZXJtaXNzaW9ucyI6W119fX19LCJyb2xlIjoic3VwZXJfdXNlciJ9LCJ1c2VybmFtZSI6IkhEQl9BRE1JTiJ9LCJpYXQiOjE2MDUwNjQ0MjMsImV4cCI6MTYwNTE1MDgyMywic3ViIjoib3BlcmF0aW9uIn0.VVZdhlh7_xFEaGPwhAh6VJ1d7eisiF3ok3ZwLTQAMWZB6umb2S7pPSTbXAmqAGHRlFAK3BYfnwT3YWt0gZbHvk24_0x3s_dej3PYJ8khIxzMjqpkR6qSjQIC2dhKqpwRPNtoqW_xnep9L-qf5iPtqkwsqWhF1c5VSN8nFouLWMZSuJ6Mag04soNhFvY0AF6QiTyzajMTb6uurRMWOnxk8hwMrY_5xtupabqtZheXP_0DV8l10B7GFi_oWf_lDLmwRmNbeUfW8ZyCIJMj36bjN3PsfVIxog87SWKKCwbWZWfJWw0KEph-HvU0ay35deyGWPIaDQmujuh2vtz-B0GoIAC58PJdXNyQRzES_nSb6Oqc_wGZsLM6EsNn_lrIp3mK_3a5jirZ8s6Z2SfcYKaLF2hCevdm05gRjFJ6ijxZrUSOR2S415wLxmqCCWCp_-sEUz8erUrf07_aj-Bv99GUub4b_znOsQF3uABKd4KKff2cNSMhAa-6sro5GDRRJg376dcLi2_9HOZbnSo90zrpVq8RNV900aydyzDdlXkZja8jdHBk4mxSSewYBvM7up6I0G4X-ZlzFOp30T7kjdLa6480Qp34iYRMMtq0Htpb5k2jPt8dNFnzW-Q2eRy1wNBbH3cCH0rd7_BIGuTCrl4hGU8QjlBiF7Gj0_-uJYhKnhg" +} +``` diff --git a/versioned_docs/version-4.6/reference/operations-api/users-and-roles.md b/versioned_docs/version-4.6/reference/operations-api/users-and-roles.md new file mode 100644 index 00000000..91f222b9 --- /dev/null +++ b/versioned_docs/version-4.6/reference/operations-api/users-and-roles.md @@ -0,0 +1,508 @@ +--- +title: Users and Roles +--- + +# Users and Roles + +## List Roles + +Returns a list of all roles. [Learn more about Harper roles here.](../security/users-and-roles) + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `list_roles` + +### Body + +```json +{ + "operation": "list_roles" +} +``` + +### Response: 200 + +```json +[ + { + "__createdtime__": 1611615061106, + "__updatedtime__": 1611615061106, + "id": "05c2ffcd-f780-40b1-9432-cfe8ba5ad890", + "permission": { + "super_user": false, + "dev": { + "tables": { + "dog": { + "read": true, + "insert": true, + "update": true, + "delete": false, + "attribute_permissions": [ + { + "attribute_name": "name", + "read": true, + "insert": true, + "update": true + } + ] + } + } + } + }, + "role": "developer" + }, + { + "__createdtime__": 1610749235614, + "__updatedtime__": 1610749235614, + "id": "136f03fa-a0e9-46c3-bd5d-7f3e7dd5b564", + "permission": { + "cluster_user": true + }, + "role": "cluster_user" + }, + { + "__createdtime__": 1610749235609, + "__updatedtime__": 1610749235609, + "id": "745b3138-a7cf-455a-8256-ac03722eef12", + "permission": { + "super_user": true + }, + "role": "super_user" + } +] +``` + +--- + +## Add Role + +Creates a new role with the specified permissions. [Learn more about Harper roles here.](../security/users-and-roles) + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `add_role` +- `role` _(required)_ - name of role you are defining +- `permission` _(required)_ - object defining permissions for users associated with this role: + - `super_user` _(optional)_ - boolean which, if set to true, gives users associated with this role full access to all operations and methods. If not included, value will be assumed to be false. + - `structure_user` _(optional)_ - boolean OR array of database names (as strings). If boolean, user can create new databases and tables. If array of strings, users can only manage tables within the specified databases. This overrides any individual table permissions for specified databases, or for all databases if the value is true. + +### Body + +```json +{ + "operation": "add_role", + "role": "developer", + "permission": { + "super_user": false, + "structure_user": false, + "dev": { + "tables": { + "dog": { + "read": true, + "insert": true, + "update": true, + "delete": false, + "attribute_permissions": [ + { + "attribute_name": "name", + "read": true, + "insert": true, + "update": true + } + ] + } + } + } + } +} +``` + +### Response: 200 + +```json +{ + "role": "developer", + "permission": { + "super_user": false, + "structure_user": false, + "dev": { + "tables": { + "dog": { + "read": true, + "insert": true, + "update": true, + "delete": false, + "attribute_permissions": [ + { + "attribute_name": "name", + "read": true, + "insert": true, + "update": true + } + ] + } + } + } + }, + "id": "0a9368b0-bd81-482f-9f5a-8722e3582f96", + "__updatedtime__": 1598549532897, + "__createdtime__": 1598549532897 +} +``` + +--- + +## Alter Role + +Modifies an existing role with the specified permissions. updates permissions from an existing role. [Learn more about Harper roles here.](../security/users-and-roles) + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `alter_role` +- `id` _(required)_ - the id value for the role you are altering +- `role` _(optional)_ - name value to update on the role you are altering +- `permission` _(required)_ - object defining permissions for users associated with this role: + - `super_user` _(optional)_ - boolean which, if set to true, gives users associated with this role full access to all operations and methods. If not included, value will be assumed to be false. + - `structure_user` _(optional)_ - boolean OR array of database names (as strings). If boolean, user can create new databases and tables. If array of strings, users can only manage tables within the specified databases. This overrides any individual table permissions for specified databases, or for all databases if the value is true. + +### Body + +```json +{ + "operation": "alter_role", + "id": "f92162e2-cd17-450c-aae0-372a76859038", + "role": "another_developer", + "permission": { + "super_user": false, + "structure_user": false, + "dev": { + "tables": { + "dog": { + "read": true, + "insert": true, + "update": true, + "delete": false, + "attribute_permissions": [ + { + "attribute_name": "name", + "read": false, + "insert": true, + "update": true + } + ] + } + } + } + } +} +``` + +### Response: 200 + +```json +{ + "id": "a7cb91e9-32e4-4dbf-a327-fab4fa9191ea", + "role": "developer", + "permission": { + "super_user": false, + "structure_user": false, + "dev": { + "tables": { + "dog": { + "read": true, + "insert": true, + "update": true, + "delete": false, + "attribute_permissions": [ + { + "attribute_name": "name", + "read": false, + "insert": true, + "update": true + } + ] + } + } + } + }, + "__updatedtime__": 1598549996106 +} +``` + +--- + +## Drop Role + +Deletes an existing role from the database. NOTE: Role with associated users cannot be dropped. [Learn more about Harper roles here.](../security/users-and-roles) + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - this must always be `drop_role` +- `id` _(required)_ - this is the id of the role you are dropping + +### Body + +```json +{ + "operation": "drop_role", + "id": "developer" +} +``` + +### Response: 200 + +```json +{ + "message": "developer successfully deleted" +} +``` + +--- + +## List Users + +Returns a list of all users. [Learn more about Harper roles here.](../security/users-and-roles) + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `list_users` + +### Body + +```json +{ + "operation": "list_users" +} +``` + +### Response: 200 + +```json +[ + { + "__createdtime__": 1635520961165, + "__updatedtime__": 1635520961165, + "active": true, + "role": { + "__createdtime__": 1635520961161, + "__updatedtime__": 1635520961161, + "id": "7c78ef13-c1f3-4063-8ea3-725127a78279", + "permission": { + "super_user": true, + "system": { + "tables": { + "hdb_table": { + "read": true, + "insert": false, + "update": false, + "delete": false, + "attribute_permissions": [] + }, + "hdb_attribute": { + "read": true, + "insert": false, + "update": false, + "delete": false, + "attribute_permissions": [] + }, + "hdb_schema": { + "read": true, + "insert": false, + "update": false, + "delete": false, + "attribute_permissions": [] + }, + "hdb_user": { + "read": true, + "insert": false, + "update": false, + "delete": false, + "attribute_permissions": [] + }, + "hdb_role": { + "read": true, + "insert": false, + "update": false, + "delete": false, + "attribute_permissions": [] + }, + "hdb_job": { + "read": true, + "insert": false, + "update": false, + "delete": false, + "attribute_permissions": [] + }, + "hdb_license": { + "read": true, + "insert": false, + "update": false, + "delete": false, + "attribute_permissions": [] + }, + "hdb_info": { + "read": true, + "insert": false, + "update": false, + "delete": false, + "attribute_permissions": [] + }, + "hdb_nodes": { + "read": true, + "insert": false, + "update": false, + "delete": false, + "attribute_permissions": [] + }, + "hdb_temp": { + "read": true, + "insert": false, + "update": false, + "delete": false, + "attribute_permissions": [] + } + } + } + }, + "role": "super_user" + }, + "username": "HDB_ADMIN" + } +] +``` + +--- + +## User Info + +Returns user data for the associated user credentials. + +- `operation` _(required)_ - must always be `user_info` + +### Body + +```json +{ + "operation": "user_info" +} +``` + +### Response: 200 + +```json +{ + "__createdtime__": 1610749235611, + "__updatedtime__": 1610749235611, + "active": true, + "role": { + "__createdtime__": 1610749235609, + "__updatedtime__": 1610749235609, + "id": "745b3138-a7cf-455a-8256-ac03722eef12", + "permission": { + "super_user": true + }, + "role": "super_user" + }, + "username": "HDB_ADMIN" +} +``` + +--- + +## Add User + +Creates a new user with the specified role and credentials. [Learn more about Harper roles here.](../security/users-and-roles) + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `add_user` +- `role` _(required)_ - 'role' name value of the role you wish to assign to the user. See `add_role` for more detail +- `username` _(required)_ - username assigned to the user. It can not be altered after adding the user. It serves as the hash +- `password` _(required)_ - clear text for password. Harper will encrypt the password upon receipt +- `active` _(required)_ - boolean value for status of user's access to your Harper instance. If set to false, user will not be able to access your instance of Harper. + +### Body + +```json +{ + "operation": "add_user", + "role": "role_name", + "username": "hdb_user", + "password": "password", + "active": true +} +``` + +### Response: 200 + +```json +{ + "message": "hdb_user successfully added" +} +``` + +--- + +## Alter User + +Modifies an existing user's role and/or credentials. [Learn more about Harper roles here.](../security/users-and-roles) + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `alter_user` +- `username` _(required)_ - username assigned to the user. It can not be altered after adding the user. It serves as the hash. +- `password` _(optional)_ - clear text for password. Harper will encrypt the password upon receipt +- `role` _(optional)_ - `role` name value of the role you wish to assign to the user. See `add_role` for more detail +- `active` _(optional)_ - status of user's access to your Harper instance. See `add_role` for more detail + +### Body + +```json +{ + "operation": "alter_user", + "role": "role_name", + "username": "hdb_user", + "password": "password", + "active": true +} +``` + +### Response: 200 + +```json +{ + "message": "updated 1 of 1 records", + "new_attributes": [], + "txn_time": 1611615114397.988, + "update_hashes": ["hdb_user"], + "skipped_hashes": [] +} +``` + +--- + +## Drop User + +Deletes an existing user by username. [Learn more about Harper roles here.](../security/users-and-roles) + +_Operation is restricted to super_user roles only_ + +- `operation` _(required)_ - must always be `drop_user` +- `username` _(required)_ - username assigned to the user + +### Body + +```json +{ + "operation": "drop_user", + "username": "sgoldberg" +} +``` + +### Response: 200 + +```json +{ + "message": "sgoldberg successfully deleted" +} +``` From 2c46b040d435d3cd5ff5b2581ef51bcb9b683d9b Mon Sep 17 00:00:00 2001 From: nenharper Date: Tue, 30 Sep 2025 17:44:29 -0500 Subject: [PATCH 2/6] Documentation for Operations API --- .../developers/applications/operations-api.md | 182 +++++++++--------- 1 file changed, 94 insertions(+), 88 deletions(-) diff --git a/versioned_docs/version-4.6/developers/applications/operations-api.md b/versioned_docs/version-4.6/developers/applications/operations-api.md index dbcd544d..df0ce063 100644 --- a/versioned_docs/version-4.6/developers/applications/operations-api.md +++ b/versioned_docs/version-4.6/developers/applications/operations-api.md @@ -16,8 +16,8 @@ Everything in Harper starts with a database. Think of it as the logical containe ```json { - "operation": "create_database", - "database": "dev" + "operation": "create_database", + "database": "dev" } ``` @@ -25,7 +25,7 @@ If successful, Harper responds with: ```json { - "message": "database 'dev' successfully created" + "message": "database 'dev' successfully created" } ``` @@ -37,10 +37,10 @@ Inside our database, we’ll create a table to store information about dogs. Eve ```json { - "operation": "create_table", - "database": "dev", - "table": "dog", - "primary_key": "id" + "operation": "create_table", + "database": "dev", + "table": "dog", + "primary_key": "id" } ``` @@ -48,7 +48,7 @@ Response: ```json { - "message": "table 'dev.dog' successfully created." + "message": "table 'dev.dog' successfully created." } ``` @@ -60,19 +60,19 @@ Let’s add our first record: Penny, a dog we care about. ```json { - "operation": "insert", - "database": "dev", - "table": "dog", - "records": [ - { - "id": 1, - "dog_name": "Penny", - "owner_name": "Kyle", - "breed_id": 154, - "age": 7, - "weight_lbs": 38 - } - ] + "operation": "insert", + "database": "dev", + "table": "dog", + "records": [ + { + "id": 1, + "dog_name": "Penny", + "owner_name": "Kyle", + "breed_id": 154, + "age": 7, + "weight_lbs": 38 + } + ] } ``` @@ -80,9 +80,9 @@ Response: ```json { - "message": "inserted 1 of 1 records", - "inserted_hashes": [1], - "skipped_hashes": [] + "message": "inserted 1 of 1 records", + "inserted_hashes": [1], + "skipped_hashes": [] } ``` @@ -95,45 +95,49 @@ More examples in the [NoSQL Operations reference](../../reference/operations-api Now that we have data, let’s retrieve it. You can query using NoSQL operations like `search_by_id` or `search_by_value`, or you can use SQL. **NoSQL Example**: + ```json { - "operation": "search_by_id", - "database": "dev", - "table": "dog", - "ids": [1], - "get_attributes": ["dog_name", "owner_name"] + "operation": "search_by_id", + "database": "dev", + "table": "dog", + "ids": [1], + "get_attributes": ["dog_name", "owner_name"] } ``` Response: + ```json [ - { - "dog_name": "Penny", - "owner_name": "Kyle" - } + { + "dog_name": "Penny", + "owner_name": "Kyle" + } ] ``` **SQL Example:** + ```json { - "operation": "sql", - "sql": "SELECT * FROM dev.dog WHERE id = 1" + "operation": "sql", + "sql": "SELECT * FROM dev.dog WHERE id = 1" } ``` Response: + ```json [ - { - "id": 1, - "dog_name": "Penny", - "owner_name": "Kyle", - "age": 7, - "weight_lbs": 38, - "breed_id": 154 - } + { + "id": 1, + "dog_name": "Penny", + "owner_name": "Kyle", + "age": 7, + "weight_lbs": 38, + "breed_id": 154 + } ] ``` @@ -145,15 +149,15 @@ Dogs grow and change, and so does data. Updating Penny’s name is as simple as: ```json { - "operation": "update", - "database": "dev", - "table": "dog", - "records": [ - { - "id": 1, - "dog_name": "Penny B" - } - ] + "operation": "update", + "database": "dev", + "table": "dog", + "records": [ + { + "id": 1, + "dog_name": "Penny B" + } + ] } ``` @@ -161,9 +165,9 @@ Response: ```json { - "message": "updated 1 of 1 records", - "update_hashes": [1], - "skipped_hashes": [] + "message": "updated 1 of 1 records", + "update_hashes": [1], + "skipped_hashes": [] } ``` @@ -175,17 +179,18 @@ Harper tracks background jobs (like CSV imports) and system logs (like errors or ```json { - "operation": "get_job", - "id": "4a982782-929a-4507-8794-26dae1132def" + "operation": "get_job", + "id": "4a982782-929a-4507-8794-26dae1132def" } ``` **Read logs:** + ```json { - "operation": "read_log", - "limit": 100, - "level": "error" + "operation": "read_log", + "limit": 100, + "level": "error" } ``` @@ -197,9 +202,9 @@ As workloads grow, you might want to adjust configuration. For example, increasi ```json { - "operation": "set_configuration", - "logging_level": "trace", - "clustering_enabled": true + "operation": "set_configuration", + "logging_level": "trace", + "clustering_enabled": true } ``` @@ -207,7 +212,7 @@ Changes require a restart: ```json { - "operation": "restart" + "operation": "restart" } ``` @@ -221,20 +226,20 @@ Add a role: ```json { - "operation": "add_role", - "role": "developer", - "permission": { - "dev": { - "tables": { - "dog": { - "read": true, - "insert": true, - "update": true, - "delete": false - } - } - } - } + "operation": "add_role", + "role": "developer", + "permission": { + "dev": { + "tables": { + "dog": { + "read": true, + "insert": true, + "update": true, + "delete": false + } + } + } + } } ``` @@ -242,11 +247,11 @@ Add a user: ```json { - "operation": "add_user", - "role": "developer", - "username": "hdb_user", - "password": "password", - "active": true + "operation": "add_user", + "role": "developer", + "username": "hdb_user", + "password": "password", + "active": true } ``` @@ -254,9 +259,9 @@ For token-based authentication: ```json { - "operation": "create_authentication_tokens", - "username": "hdb_user", - "password": "password" + "operation": "create_authentication_tokens", + "username": "hdb_user", + "password": "password" } ``` @@ -265,14 +270,15 @@ More in [Users and Roles](../../reference/operations-api/users-and-roles) and [T ## Step 9: Advanced Operations Finally, Harper provides deeper operational tools when you need them: + - Backups with `get_backup` - Audit logs with `read_audit_log` - License management with `set_license` See the [full Operations API reference](../../reference/operations-api/) for every option. -___ +--- From creating a database and table to inserting data, querying with SQL or NoSQL, monitoring logs, tuning the system, and locking down security, the Operations API gives you the complete toolkit to run Harper programmatically. -It’s simple to start small (one table, one record) and grow into advanced scenarios as your application evolves. And since everything is JSON, you can automate workflows from day one. \ No newline at end of file +It’s simple to start small (one table, one record) and grow into advanced scenarios as your application evolves. And since everything is JSON, you can automate workflows from day one. From 0ed27a338512d047012fdb20aa03dd98beb10aba Mon Sep 17 00:00:00 2001 From: nenharper Date: Tue, 30 Sep 2025 18:08:01 -0500 Subject: [PATCH 3/6] Documentation for Operations API --- .../advanced-json-sql-examples.md | 1775 ----------------- .../developers/operations-api/analytics.md | 121 -- .../operations-api/bulk-operations.md | 255 --- .../operations-api/certificate-management.md | 124 -- .../operations-api/clustering-nats.md | 486 ----- .../developers/operations-api/clustering.md | 355 ---- .../developers/operations-api/components.md | 543 ----- .../operations-api/configuration.md | 135 -- .../operations-api/custom-functions.md | 279 --- .../operations-api/databases-and-tables.md | 388 ---- .../developers/operations-api/index.md | 55 - .../developers/operations-api/jobs.md | 87 - .../developers/operations-api/logs.md | 732 ------- .../operations-api/nosql-operations.md | 389 ---- .../operations-api/quickstart-examples.md | 370 ---- .../developers/operations-api/registration.md | 70 - .../operations-api/sql-operations.md | 127 -- .../operations-api/system-operations.md | 195 -- .../operations-api/token-authentication.md | 60 - .../operations-api/users-and-roles.md | 508 ----- 20 files changed, 7054 deletions(-) delete mode 100644 versioned_docs/version-4.6/developers/operations-api/advanced-json-sql-examples.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/analytics.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/bulk-operations.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/certificate-management.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/clustering-nats.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/clustering.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/components.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/configuration.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/custom-functions.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/databases-and-tables.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/index.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/jobs.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/logs.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/nosql-operations.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/quickstart-examples.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/registration.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/sql-operations.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/system-operations.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/token-authentication.md delete mode 100644 versioned_docs/version-4.6/developers/operations-api/users-and-roles.md diff --git a/versioned_docs/version-4.6/developers/operations-api/advanced-json-sql-examples.md b/versioned_docs/version-4.6/developers/operations-api/advanced-json-sql-examples.md deleted file mode 100644 index ec300e2e..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/advanced-json-sql-examples.md +++ /dev/null @@ -1,1775 +0,0 @@ ---- -title: Advanced JSON SQL Examples ---- - -# Advanced JSON SQL Examples - -## Create movies database - -Create a new database called "movies" using the 'create_database' operation. - -_Note: Creating a database is optional, if one is not created Harper will default to using a database named `data`_ - -### Body - -```json -{ - "operation": "create_database", - "database": "movies" -} -``` - -### Response: 200 - -```json -{ - "message": "database 'movies' successfully created" -} -``` - ---- - -## Create movie Table - -Creates a new table called "movie" inside the database "movies" using the ‘create_table’ operation. - -### Body - -```json -{ - "operation": "create_table", - "database": "movies", - "table": "movie", - "primary_key": "id" -} -``` - -### Response: 200 - -```json -{ - "message": "table 'movies.movie' successfully created." -} -``` - ---- - -## Create credits Table - -Creates a new table called "credits" inside the database "movies" using the ‘create_table’ operation. - -### Body - -```json -{ - "operation": "create_table", - "database": "movies", - "table": "credits", - "primary_key": "movie_id" -} -``` - -### Response: 200 - -```json -{ - "message": "table 'movies.credits' successfully created." -} -``` - ---- - -## Bulk Insert movie Via CSV - -Inserts data from a hosted CSV file into the "movie" table using the 'csv_url_load' operation. - -### Body - -```json -{ - "operation": "csv_url_load", - "database": "movies", - "table": "movie", - "csv_url": "https://search-json-sample-data.s3.us-east-2.amazonaws.com/movie.csv" -} -``` - -### Response: 200 - -```json -{ - "message": "Starting job with id 1889eee4-23c1-4945-9bb7-c805fc20726c" -} -``` - ---- - -## Bulk Insert credits Via CSV - -Inserts data from a hosted CSV file into the "credits" table using the 'csv_url_load' operation. - -### Body - -```json -{ - "operation": "csv_url_load", - "database": "movies", - "table": "credits", - "csv_url": "https://search-json-sample-data.s3.us-east-2.amazonaws.com/credits.csv" -} -``` - -### Response: 200 - -```json -{ - "message": "Starting job with id 3a14cd74-67f3-41e9-8ccd-45ffd0addc2c", - "job_id": "3a14cd74-67f3-41e9-8ccd-45ffd0addc2c" -} -``` - ---- - -## View raw data - -In the following example we will be running expressions on the keywords & production_companies attributes, so for context we are displaying what the raw data looks like. - -### Body - -```json -{ - "operation": "sql", - "sql": "SELECT title, rank, keywords, production_companies FROM movies.movie ORDER BY rank LIMIT 10" -} -``` - -### Response: 200 - -```json -[ - { - "title": "Ad Astra", - "rank": 1, - "keywords": [ - { - "id": 305, - "name": "moon" - }, - { - "id": 697, - "name": "loss of loved one" - }, - { - "id": 839, - "name": "planet mars" - }, - { - "id": 14626, - "name": "astronaut" - }, - { - "id": 157265, - "name": "moon colony" - }, - { - "id": 162429, - "name": "solar system" - }, - { - "id": 240119, - "name": "father son relationship" - }, - { - "id": 244256, - "name": "near future" - }, - { - "id": 257878, - "name": "planet neptune" - }, - { - "id": 260089, - "name": "space walk" - } - ], - "production_companies": [ - { - "id": 490, - "name": "New Regency Productions", - "origin_country": "" - }, - { - "id": 79963, - "name": "Keep Your Head", - "origin_country": "" - }, - { - "id": 73492, - "name": "MadRiver Pictures", - "origin_country": "" - }, - { - "id": 81, - "name": "Plan B Entertainment", - "origin_country": "US" - }, - { - "id": 30666, - "name": "RT Features", - "origin_country": "BR" - }, - { - "id": 30148, - "name": "Bona Film Group", - "origin_country": "CN" - }, - { - "id": 22213, - "name": "TSG Entertainment", - "origin_country": "US" - } - ] - }, - { - "title": "Extraction", - "rank": 2, - "keywords": [ - { - "id": 3070, - "name": "mercenary" - }, - { - "id": 4110, - "name": "mumbai (bombay), india" - }, - { - "id": 9717, - "name": "based on comic" - }, - { - "id": 9730, - "name": "crime boss" - }, - { - "id": 11107, - "name": "rescue mission" - }, - { - "id": 18712, - "name": "based on graphic novel" - }, - { - "id": 265216, - "name": "dhaka (dacca), bangladesh" - } - ], - "production_companies": [ - { - "id": 106544, - "name": "AGBO", - "origin_country": "US" - }, - { - "id": 109172, - "name": "Thematic Entertainment", - "origin_country": "US" - }, - { - "id": 92029, - "name": "TGIM Films", - "origin_country": "US" - } - ] - }, - { - "title": "To the Beat! Back 2 School", - "rank": 3, - "keywords": [ - { - "id": 10873, - "name": "school" - } - ], - "production_companies": [] - }, - { - "title": "Bloodshot", - "rank": 4, - "keywords": [ - { - "id": 2651, - "name": "nanotechnology" - }, - { - "id": 9715, - "name": "superhero" - }, - { - "id": 9717, - "name": "based on comic" - }, - { - "id": 164218, - "name": "psychotronic" - }, - { - "id": 255024, - "name": "shared universe" - }, - { - "id": 258575, - "name": "valiant comics" - } - ], - "production_companies": [ - { - "id": 34, - "name": "Sony Pictures", - "origin_country": "US" - }, - { - "id": 10246, - "name": "Cross Creek Pictures", - "origin_country": "US" - }, - { - "id": 6573, - "name": "Mimran Schur Pictures", - "origin_country": "US" - }, - { - "id": 333, - "name": "Original Film", - "origin_country": "US" - }, - { - "id": 103673, - "name": "The Hideaway Entertainment", - "origin_country": "US" - }, - { - "id": 124335, - "name": "Valiant Entertainment", - "origin_country": "US" - }, - { - "id": 5, - "name": "Columbia Pictures", - "origin_country": "US" - }, - { - "id": 1225, - "name": "One Race", - "origin_country": "US" - }, - { - "id": 30148, - "name": "Bona Film Group", - "origin_country": "CN" - } - ] - }, - { - "title": "The Call of the Wild", - "rank": 5, - "keywords": [ - { - "id": 818, - "name": "based on novel or book" - }, - { - "id": 4542, - "name": "gold rush" - }, - { - "id": 15162, - "name": "dog" - }, - { - "id": 155821, - "name": "sled dogs" - }, - { - "id": 189390, - "name": "yukon" - }, - { - "id": 207928, - "name": "19th century" - }, - { - "id": 259987, - "name": "cgi animation" - }, - { - "id": 263806, - "name": "1890s" - } - ], - "production_companies": [ - { - "id": 787, - "name": "3 Arts Entertainment", - "origin_country": "US" - }, - { - "id": 127928, - "name": "20th Century Studios", - "origin_country": "US" - }, - { - "id": 22213, - "name": "TSG Entertainment", - "origin_country": "US" - } - ] - }, - { - "title": "Sonic the Hedgehog", - "rank": 6, - "keywords": [ - { - "id": 282, - "name": "video game" - }, - { - "id": 6054, - "name": "friendship" - }, - { - "id": 10842, - "name": "good vs evil" - }, - { - "id": 41645, - "name": "based on video game" - }, - { - "id": 167043, - "name": "road movie" - }, - { - "id": 172142, - "name": "farting" - }, - { - "id": 188933, - "name": "bar fight" - }, - { - "id": 226967, - "name": "amistad" - }, - { - "id": 245230, - "name": "live action remake" - }, - { - "id": 258111, - "name": "fantasy" - }, - { - "id": 260223, - "name": "videojuego" - } - ], - "production_companies": [ - { - "id": 333, - "name": "Original Film", - "origin_country": "US" - }, - { - "id": 10644, - "name": "Blur Studios", - "origin_country": "US" - }, - { - "id": 77884, - "name": "Marza Animation Planet", - "origin_country": "JP" - }, - { - "id": 4, - "name": "Paramount", - "origin_country": "US" - }, - { - "id": 113750, - "name": "SEGA", - "origin_country": "JP" - }, - { - "id": 100711, - "name": "DJ2 Entertainment", - "origin_country": "" - }, - { - "id": 24955, - "name": "Paramount Animation", - "origin_country": "US" - } - ] - }, - { - "title": "Birds of Prey (and the Fantabulous Emancipation of One Harley Quinn)", - "rank": 7, - "keywords": [ - { - "id": 849, - "name": "dc comics" - }, - { - "id": 9717, - "name": "based on comic" - }, - { - "id": 187056, - "name": "woman director" - }, - { - "id": 229266, - "name": "dc extended universe" - } - ], - "production_companies": [ - { - "id": 9993, - "name": "DC Entertainment", - "origin_country": "US" - }, - { - "id": 82968, - "name": "LuckyChap Entertainment", - "origin_country": "GB" - }, - { - "id": 103462, - "name": "Kroll & Co Entertainment", - "origin_country": "US" - }, - { - "id": 174, - "name": "Warner Bros. Pictures", - "origin_country": "US" - }, - { - "id": 429, - "name": "DC Comics", - "origin_country": "US" - }, - { - "id": 128064, - "name": "DC Films", - "origin_country": "US" - }, - { - "id": 101831, - "name": "Clubhouse Pictures", - "origin_country": "US" - } - ] - }, - { - "title": "Justice League Dark: Apokolips War", - "rank": 8, - "keywords": [ - { - "id": 849, - "name": "dc comics" - } - ], - "production_companies": [ - { - "id": 2785, - "name": "Warner Bros. Animation", - "origin_country": "US" - }, - { - "id": 9993, - "name": "DC Entertainment", - "origin_country": "US" - }, - { - "id": 429, - "name": "DC Comics", - "origin_country": "US" - } - ] - }, - { - "title": "Parasite", - "rank": 9, - "keywords": [ - { - "id": 1353, - "name": "underground" - }, - { - "id": 5318, - "name": "seoul" - }, - { - "id": 5732, - "name": "birthday party" - }, - { - "id": 5752, - "name": "private lessons" - }, - { - "id": 9866, - "name": "basement" - }, - { - "id": 10453, - "name": "con artist" - }, - { - "id": 11935, - "name": "working class" - }, - { - "id": 12565, - "name": "psychological thriller" - }, - { - "id": 13126, - "name": "limousine driver" - }, - { - "id": 14514, - "name": "class differences" - }, - { - "id": 14864, - "name": "rich poor" - }, - { - "id": 17997, - "name": "housekeeper" - }, - { - "id": 18015, - "name": "tutor" - }, - { - "id": 18035, - "name": "family" - }, - { - "id": 33421, - "name": "crime family" - }, - { - "id": 173272, - "name": "flood" - }, - { - "id": 188861, - "name": "smell" - }, - { - "id": 198673, - "name": "unemployed" - }, - { - "id": 237462, - "name": "wealthy family" - } - ], - "production_companies": [ - { - "id": 7036, - "name": "CJ Entertainment", - "origin_country": "KR" - }, - { - "id": 4399, - "name": "Barunson E&A", - "origin_country": "KR" - } - ] - }, - { - "title": "Star Wars: The Rise of Skywalker", - "rank": 10, - "keywords": [ - { - "id": 161176, - "name": "space opera" - } - ], - "production_companies": [ - { - "id": 1, - "name": "Lucasfilm", - "origin_country": "US" - }, - { - "id": 11461, - "name": "Bad Robot", - "origin_country": "US" - }, - { - "id": 2, - "name": "Walt Disney Pictures", - "origin_country": "US" - }, - { - "id": 120404, - "name": "British Film Commission", - "origin_country": "" - } - ] - } -] -``` - ---- - -## Simple search_json call - -This query uses search_json to convert the keywords object array to a simple string array. The expression '[name]' tells the function to extract all values for the name attribute and wrap them in an array. - -### Body - -```json -{ - "operation": "sql", - "sql": "SELECT title, rank, search_json('[name]', keywords) as keywords FROM movies.movie ORDER BY rank LIMIT 10" -} -``` - -### Response: 200 - -```json -[ - { - "title": "Ad Astra", - "rank": 1, - "keywords": [ - "moon", - "loss of loved one", - "planet mars", - "astronaut", - "moon colony", - "solar system", - "father son relationship", - "near future", - "planet neptune", - "space walk" - ] - }, - { - "title": "Extraction", - "rank": 2, - "keywords": [ - "mercenary", - "mumbai (bombay), india", - "based on comic", - "crime boss", - "rescue mission", - "based on graphic novel", - "dhaka (dacca), bangladesh" - ] - }, - { - "title": "To the Beat! Back 2 School", - "rank": 3, - "keywords": ["school"] - }, - { - "title": "Bloodshot", - "rank": 4, - "keywords": ["nanotechnology", "superhero", "based on comic", "psychotronic", "shared universe", "valiant comics"] - }, - { - "title": "The Call of the Wild", - "rank": 5, - "keywords": [ - "based on novel or book", - "gold rush", - "dog", - "sled dogs", - "yukon", - "19th century", - "cgi animation", - "1890s" - ] - }, - { - "title": "Sonic the Hedgehog", - "rank": 6, - "keywords": [ - "video game", - "friendship", - "good vs evil", - "based on video game", - "road movie", - "farting", - "bar fight", - "amistad", - "live action remake", - "fantasy", - "videojuego" - ] - }, - { - "title": "Birds of Prey (and the Fantabulous Emancipation of One Harley Quinn)", - "rank": 7, - "keywords": ["dc comics", "based on comic", "woman director", "dc extended universe"] - }, - { - "title": "Justice League Dark: Apokolips War", - "rank": 8, - "keywords": ["dc comics"] - }, - { - "title": "Parasite", - "rank": 9, - "keywords": [ - "underground", - "seoul", - "birthday party", - "private lessons", - "basement", - "con artist", - "working class", - "psychological thriller", - "limousine driver", - "class differences", - "rich poor", - "housekeeper", - "tutor", - "family", - "crime family", - "flood", - "smell", - "unemployed", - "wealthy family" - ] - }, - { - "title": "Star Wars: The Rise of Skywalker", - "rank": 10, - "keywords": ["space opera"] - } -] -``` - ---- - -## Use search_json in a where clause - -This example shows how we can use SEARCH_JSON to filter out records in a WHERE clause. The production_companies attribute holds an object array of companies that produced each movie, we want to only see movies which were produced by Marvel Studios. Our expression is a filter '$[name="Marvel Studios"]' this tells the function to iterate the production_companies array and only return entries where the name is "Marvel Studios". - -### Body - -```json -{ - "operation": "sql", - "sql": "SELECT title, release_date FROM movies.movie where search_json('$[name=\"Marvel Studios\"]', production_companies) IS NOT NULL ORDER BY release_date" -} -``` - -### Response: 200 - -```json -[ - { - "title": "Iron Man", - "release_date": "2008-04-30" - }, - { - "title": "The Incredible Hulk", - "release_date": "2008-06-12" - }, - { - "title": "Iron Man 2", - "release_date": "2010-04-28" - }, - { - "title": "Thor", - "release_date": "2011-04-21" - }, - { - "title": "Captain America: The First Avenger", - "release_date": "2011-07-22" - }, - { - "title": "Marvel One-Shot: The Consultant", - "release_date": "2011-09-12" - }, - { - "title": "Marvel One-Shot: A Funny Thing Happened on the Way to Thor's Hammer", - "release_date": "2011-10-25" - }, - { - "title": "The Avengers", - "release_date": "2012-04-25" - }, - { - "title": "Marvel One-Shot: Item 47", - "release_date": "2012-09-13" - }, - { - "title": "Iron Man 3", - "release_date": "2013-04-18" - }, - { - "title": "Marvel One-Shot: Agent Carter", - "release_date": "2013-09-08" - }, - { - "title": "Thor: The Dark World", - "release_date": "2013-10-29" - }, - { - "title": "Marvel One-Shot: All Hail the King", - "release_date": "2014-02-04" - }, - { - "title": "Marvel Studios: Assembling a Universe", - "release_date": "2014-03-18" - }, - { - "title": "Captain America: The Winter Soldier", - "release_date": "2014-03-20" - }, - { - "title": "Guardians of the Galaxy", - "release_date": "2014-07-30" - }, - { - "title": "Avengers: Age of Ultron", - "release_date": "2015-04-22" - }, - { - "title": "Ant-Man", - "release_date": "2015-07-14" - }, - { - "title": "Captain America: Civil War", - "release_date": "2016-04-27" - }, - { - "title": "Team Thor", - "release_date": "2016-08-28" - }, - { - "title": "Doctor Strange", - "release_date": "2016-10-25" - }, - { - "title": "Guardians of the Galaxy Vol. 2", - "release_date": "2017-04-19" - }, - { - "title": "Spider-Man: Homecoming", - "release_date": "2017-07-05" - }, - { - "title": "Thor: Ragnarok", - "release_date": "2017-10-25" - }, - { - "title": "Black Panther", - "release_date": "2018-02-13" - }, - { - "title": "Avengers: Infinity War", - "release_date": "2018-04-25" - }, - { - "title": "Ant-Man and the Wasp", - "release_date": "2018-07-04" - }, - { - "title": "Captain Marvel", - "release_date": "2019-03-06" - }, - { - "title": "Avengers: Endgame", - "release_date": "2019-04-24" - }, - { - "title": "Spider-Man: Far from Home", - "release_date": "2019-06-28" - }, - { - "title": "Black Widow", - "release_date": "2020-10-28" - }, - { - "title": "Untitled Spider-Man 3", - "release_date": "2021-11-04" - }, - { - "title": "Thor: Love and Thunder", - "release_date": "2022-02-10" - }, - { - "title": "Doctor Strange in the Multiverse of Madness", - "release_date": "2022-03-23" - }, - { - "title": "Untitled Marvel Project (3)", - "release_date": "2022-07-29" - }, - { - "title": "Guardians of the Galaxy Vol. 3", - "release_date": "2023-02-16" - } -] -``` - ---- - -## Use search_json to show the movies with the largest casts - -This example shows how we can use SEARCH_JSON to perform a simple calculation on JSON and order by the results. The cast attribute holds an object array of details around the cast of a movie. We use the expression '$count(id)' that counts each id and returns the value back which we alias in SQL as cast_size which in turn gets used to sort the rows. - -### Body - -```json -{ - "operation": "sql", - "sql": "SELECT movie_title, search_json('$count(id)', `cast`) as cast_size FROM movies.credits ORDER BY cast_size DESC LIMIT 10" -} -``` - -### Response: 200 - -```json -[ - { - "movie_title": "Around the World in Eighty Days", - "cast_size": 312 - }, - { - "movie_title": "And the Oscar Goes To...", - "cast_size": 259 - }, - { - "movie_title": "Rock of Ages", - "cast_size": 223 - }, - { - "movie_title": "Mr. Smith Goes to Washington", - "cast_size": 213 - }, - { - "movie_title": "Les Misérables", - "cast_size": 208 - }, - { - "movie_title": "Jason Bourne", - "cast_size": 201 - }, - { - "movie_title": "The Muppets", - "cast_size": 191 - }, - { - "movie_title": "You Don't Mess with the Zohan", - "cast_size": 183 - }, - { - "movie_title": "The Irishman", - "cast_size": 173 - }, - { - "movie_title": "Spider-Man: Far from Home", - "cast_size": 173 - } -] -``` - ---- - -## search_json as a condition, in a select with a table join - -This example shows how we can use SEARCH_JSON to find movies where at least of 2 our favorite actors from Marvel films have acted together then list the movie, its overview, release date, and the actors names and their characters. The WHERE clause performs a count on credits.cast attribute that have the matching actors. The SELECT performs the same filter on the cast attribute and performs a transform on each object to just return the actor's name and their character. - -### Body - -```json -{ - "operation": "sql", - "sql": "SELECT m.title, m.overview, m.release_date, search_json('$[name in [\"Robert Downey Jr.\", \"Chris Evans\", \"Scarlett Johansson\", \"Mark Ruffalo\", \"Chris Hemsworth\", \"Jeremy Renner\", \"Clark Gregg\", \"Samuel L. Jackson\", \"Gwyneth Paltrow\", \"Don Cheadle\"]].{\"actor\": name, \"character\": character}', c.`cast`) as characters FROM movies.credits c INNER JOIN movies.movie m ON c.movie_id = m.id WHERE search_json('$count($[name in [\"Robert Downey Jr.\", \"Chris Evans\", \"Scarlett Johansson\", \"Mark Ruffalo\", \"Chris Hemsworth\", \"Jeremy Renner\", \"Clark Gregg\", \"Samuel L. Jackson\", \"Gwyneth Paltrow\", \"Don Cheadle\"]])', c.`cast`) >= 2" -} -``` - -### Response: 200 - -```json -[ - { - "title": "Out of Sight", - "overview": "Meet Jack Foley, a smooth criminal who bends the law and is determined to make one last heist. Karen Sisco is a federal marshal who chooses all the right moves … and all the wrong guys. Now they're willing to risk it all to find out if there's more between them than just the law.", - "release_date": "1998-06-26", - "characters": [ - { - "actor": "Don Cheadle", - "character": "Maurice Miller" - }, - { - "actor": "Samuel L. Jackson", - "character": "Hejira Henry (uncredited)" - } - ] - }, - { - "title": "Iron Man", - "overview": "After being held captive in an Afghan cave, billionaire engineer Tony Stark creates a unique weaponized suit of armor to fight evil.", - "release_date": "2008-04-30", - "characters": [ - { - "actor": "Robert Downey Jr.", - "character": "Tony Stark / Iron Man" - }, - { - "actor": "Gwyneth Paltrow", - "character": "Virginia \"Pepper\" Potts" - }, - { - "actor": "Clark Gregg", - "character": "Phil Coulson" - }, - { - "actor": "Samuel L. Jackson", - "character": "Nick Fury (uncredited)" - }, - { - "actor": "Samuel L. Jackson", - "character": "Nick Fury" - } - ] - }, - { - "title": "Captain America: The First Avenger", - "overview": "During World War II, Steve Rogers is a sickly man from Brooklyn who's transformed into super-soldier Captain America to aid in the war effort. Rogers must stop the Red Skull – Adolf Hitler's ruthless head of weaponry, and the leader of an organization that intends to use a mysterious device of untold powers for world domination.", - "release_date": "2011-07-22", - "characters": [ - { - "actor": "Chris Evans", - "character": "Steve Rogers / Captain America" - }, - { - "actor": "Samuel L. Jackson", - "character": "Nick Fury" - } - ] - }, - { - "title": "In Good Company", - "overview": "Dan Foreman is a seasoned advertisement sales executive at a high-ranking publication when a corporate takeover results in him being placed under naive supervisor Carter Duryea, who is half his age. Matters are made worse when Dan's new supervisor becomes romantically involved with his daughter an 18 year-old college student Alex.", - "release_date": "2004-12-29", - "characters": [ - { - "actor": "Scarlett Johansson", - "character": "Alex Foreman" - }, - { - "actor": "Clark Gregg", - "character": "Mark Steckle" - } - ] - }, - { - "title": "Zodiac", - "overview": "The true story of the investigation of the \"Zodiac Killer\", a serial killer who terrified the San Francisco Bay Area, taunting police with his ciphers and letters. The case becomes an obsession for three men as their lives and careers are built and destroyed by the endless trail of clues.", - "release_date": "2007-03-02", - "characters": [ - { - "actor": "Mark Ruffalo", - "character": "Dave Toschi" - }, - { - "actor": "Robert Downey Jr.", - "character": "Paul Avery" - } - ] - }, - { - "title": "Hard Eight", - "overview": "A stranger mentors a young Reno gambler who weds a hooker and befriends a vulgar casino regular.", - "release_date": "1996-02-28", - "characters": [ - { - "actor": "Gwyneth Paltrow", - "character": "Clementine" - }, - { - "actor": "Samuel L. Jackson", - "character": "Jimmy" - } - ] - }, - { - "title": "The Spirit", - "overview": "Down these mean streets a man must come. A hero born, murdered, and born again. A Rookie cop named Denny Colt returns from the beyond as The Spirit, a hero whose mission is to fight against the bad forces from the shadows of Central City. The Octopus, who kills anyone unfortunate enough to see his face, has other plans; he is going to wipe out the entire city.", - "release_date": "2008-12-25", - "characters": [ - { - "actor": "Scarlett Johansson", - "character": "Silken Floss" - }, - { - "actor": "Samuel L. Jackson", - "character": "Octopuss" - } - ] - }, - { - "title": "S.W.A.T.", - "overview": "Hondo Harrelson recruits Jim Street to join an elite unit of the Los Angeles Police Department. Together they seek out more members, including tough Deke Kay and single mom Chris Sanchez. The team's first big assignment is to escort crime boss Alex Montel to prison. It seems routine, but when Montel offers a huge reward to anyone who can break him free, criminals of various stripes step up for the prize.", - "release_date": "2003-08-08", - "characters": [ - { - "actor": "Samuel L. Jackson", - "character": "Sgt. Dan 'Hondo' Harrelson" - }, - { - "actor": "Jeremy Renner", - "character": "Brian Gamble" - } - ] - }, - { - "title": "Iron Man 2", - "overview": "With the world now aware of his dual life as the armored superhero Iron Man, billionaire inventor Tony Stark faces pressure from the government, the press and the public to share his technology with the military. Unwilling to let go of his invention, Stark, with Pepper Potts and James 'Rhodey' Rhodes at his side, must forge new alliances – and confront powerful enemies.", - "release_date": "2010-04-28", - "characters": [ - { - "actor": "Robert Downey Jr.", - "character": "Tony Stark / Iron Man" - }, - { - "actor": "Gwyneth Paltrow", - "character": "Virginia \"Pepper\" Potts" - }, - { - "actor": "Don Cheadle", - "character": "James \"Rhodey\" Rhodes / War Machine" - }, - { - "actor": "Scarlett Johansson", - "character": "Natalie Rushman / Natasha Romanoff / Black Widow" - }, - { - "actor": "Samuel L. Jackson", - "character": "Nick Fury" - }, - { - "actor": "Clark Gregg", - "character": "Phil Coulson" - } - ] - }, - { - "title": "Thor", - "overview": "Against his father Odin's will, The Mighty Thor - a powerful but arrogant warrior god - recklessly reignites an ancient war. Thor is cast down to Earth and forced to live among humans as punishment. Once here, Thor learns what it takes to be a true hero when the most dangerous villain of his world sends the darkest forces of Asgard to invade Earth.", - "release_date": "2011-04-21", - "characters": [ - { - "actor": "Chris Hemsworth", - "character": "Thor Odinson" - }, - { - "actor": "Clark Gregg", - "character": "Phil Coulson" - }, - { - "actor": "Jeremy Renner", - "character": "Clint Barton / Hawkeye (uncredited)" - }, - { - "actor": "Samuel L. Jackson", - "character": "Nick Fury (uncredited)" - } - ] - }, - { - "title": "View from the Top", - "overview": "A small-town woman tries to achieve her goal of becoming a flight attendant.", - "release_date": "2003-03-21", - "characters": [ - { - "actor": "Gwyneth Paltrow", - "character": "Donna" - }, - { - "actor": "Mark Ruffalo", - "character": "Ted Stewart" - } - ] - }, - { - "title": "The Nanny Diaries", - "overview": "A college graduate goes to work as a nanny for a rich New York family. Ensconced in their home, she has to juggle their dysfunction, a new romance, and the spoiled brat in her charge.", - "release_date": "2007-08-24", - "characters": [ - { - "actor": "Scarlett Johansson", - "character": "Annie Braddock" - }, - { - "actor": "Chris Evans", - "character": "Hayden \"Harvard Hottie\"" - } - ] - }, - { - "title": "The Perfect Score", - "overview": "Six high school seniors decide to break into the Princeton Testing Center so they can steal the answers to their upcoming SAT tests and all get perfect scores.", - "release_date": "2004-01-30", - "characters": [ - { - "actor": "Chris Evans", - "character": "Kyle" - }, - { - "actor": "Scarlett Johansson", - "character": "Francesca Curtis" - } - ] - }, - { - "title": "The Avengers", - "overview": "When an unexpected enemy emerges and threatens global safety and security, Nick Fury, director of the international peacekeeping agency known as S.H.I.E.L.D., finds himself in need of a team to pull the world back from the brink of disaster. Spanning the globe, a daring recruitment effort begins!", - "release_date": "2012-04-25", - "characters": [ - { - "actor": "Robert Downey Jr.", - "character": "Tony Stark / Iron Man" - }, - { - "actor": "Chris Evans", - "character": "Steve Rogers / Captain America" - }, - { - "actor": "Mark Ruffalo", - "character": "Bruce Banner / The Hulk" - }, - { - "actor": "Chris Hemsworth", - "character": "Thor Odinson" - }, - { - "actor": "Scarlett Johansson", - "character": "Natasha Romanoff / Black Widow" - }, - { - "actor": "Jeremy Renner", - "character": "Clint Barton / Hawkeye" - }, - { - "actor": "Samuel L. Jackson", - "character": "Nick Fury" - }, - { - "actor": "Clark Gregg", - "character": "Phil Coulson" - }, - { - "actor": "Gwyneth Paltrow", - "character": "Virginia \"Pepper\" Potts" - } - ] - }, - { - "title": "Iron Man 3", - "overview": "When Tony Stark's world is torn apart by a formidable terrorist called the Mandarin, he starts an odyssey of rebuilding and retribution.", - "release_date": "2013-04-18", - "characters": [ - { - "actor": "Robert Downey Jr.", - "character": "Tony Stark / Iron Man" - }, - { - "actor": "Gwyneth Paltrow", - "character": "Virginia \"Pepper\" Potts" - }, - { - "actor": "Don Cheadle", - "character": "James \"Rhodey\" Rhodes / Iron Patriot" - }, - { - "actor": "Mark Ruffalo", - "character": "Bruce Banner (uncredited)" - } - ] - }, - { - "title": "Marvel One-Shot: The Consultant", - "overview": "Agent Coulson informs Agent Sitwell that the World Security Council wishes Emil Blonsky to be released from prison to join the Avengers Initiative. As Nick Fury doesn't want to release Blonsky, the two agents decide to send a patsy to sabotage the meeting...", - "release_date": "2011-09-12", - "characters": [ - { - "actor": "Clark Gregg", - "character": "Phil Coulson" - }, - { - "actor": "Robert Downey Jr.", - "character": "Tony Stark (archive footage)" - } - ] - }, - { - "title": "Thor: The Dark World", - "overview": "Thor fights to restore order across the cosmos… but an ancient race led by the vengeful Malekith returns to plunge the universe back into darkness. Faced with an enemy that even Odin and Asgard cannot withstand, Thor must embark on his most perilous and personal journey yet, one that will reunite him with Jane Foster and force him to sacrifice everything to save us all.", - "release_date": "2013-10-29", - "characters": [ - { - "actor": "Chris Hemsworth", - "character": "Thor Odinson" - }, - { - "actor": "Chris Evans", - "character": "Loki as Captain America (uncredited)" - } - ] - }, - { - "title": "Avengers: Age of Ultron", - "overview": "When Tony Stark tries to jumpstart a dormant peacekeeping program, things go awry and Earth’s Mightiest Heroes are put to the ultimate test as the fate of the planet hangs in the balance. As the villainous Ultron emerges, it is up to The Avengers to stop him from enacting his terrible plans, and soon uneasy alliances and unexpected action pave the way for an epic and unique global adventure.", - "release_date": "2015-04-22", - "characters": [ - { - "actor": "Robert Downey Jr.", - "character": "Tony Stark / Iron Man" - }, - { - "actor": "Chris Evans", - "character": "Steve Rogers / Captain America" - }, - { - "actor": "Mark Ruffalo", - "character": "Bruce Banner / The Hulk" - }, - { - "actor": "Chris Hemsworth", - "character": "Thor Odinson" - }, - { - "actor": "Scarlett Johansson", - "character": "Natasha Romanoff / Black Widow" - }, - { - "actor": "Jeremy Renner", - "character": "Clint Barton / Hawkeye" - }, - { - "actor": "Samuel L. Jackson", - "character": "Nick Fury" - }, - { - "actor": "Don Cheadle", - "character": "James \"Rhodey\" Rhodes / War Machine" - } - ] - }, - { - "title": "Captain America: The Winter Soldier", - "overview": "After the cataclysmic events in New York with The Avengers, Steve Rogers, aka Captain America is living quietly in Washington, D.C. and trying to adjust to the modern world. But when a S.H.I.E.L.D. colleague comes under attack, Steve becomes embroiled in a web of intrigue that threatens to put the world at risk. Joining forces with the Black Widow, Captain America struggles to expose the ever-widening conspiracy while fighting off professional assassins sent to silence him at every turn. When the full scope of the villainous plot is revealed, Captain America and the Black Widow enlist the help of a new ally, the Falcon. However, they soon find themselves up against an unexpected and formidable enemy—the Winter Soldier.", - "release_date": "2014-03-20", - "characters": [ - { - "actor": "Chris Evans", - "character": "Steve Rogers / Captain America" - }, - { - "actor": "Samuel L. Jackson", - "character": "Nick Fury" - }, - { - "actor": "Scarlett Johansson", - "character": "Natasha Romanoff / Black Widow" - } - ] - }, - { - "title": "Thanks for Sharing", - "overview": "A romantic comedy that brings together three disparate characters who are learning to face a challenging and often confusing world as they struggle together against a common demon—sex addiction.", - "release_date": "2013-09-19", - "characters": [ - { - "actor": "Mark Ruffalo", - "character": "Adam" - }, - { - "actor": "Gwyneth Paltrow", - "character": "Phoebe" - } - ] - }, - { - "title": "Chef", - "overview": "When Chef Carl Casper suddenly quits his job at a prominent Los Angeles restaurant after refusing to compromise his creative integrity for its controlling owner, he is left to figure out what's next. Finding himself in Miami, he teams up with his ex-wife, his friend and his son to launch a food truck. Taking to the road, Chef Carl goes back to his roots to reignite his passion for the kitchen -- and zest for life and love.", - "release_date": "2014-05-08", - "characters": [ - { - "actor": "Scarlett Johansson", - "character": "Molly" - }, - { - "actor": "Robert Downey Jr.", - "character": "Marvin" - } - ] - }, - { - "title": "Marvel Studios: Assembling a Universe", - "overview": "A look at the story behind Marvel Studios and the Marvel Cinematic Universe, featuring interviews and behind-the-scenes footage from all of the Marvel films, the Marvel One-Shots and \"Marvel's Agents of S.H.I.E.L.D.\"", - "release_date": "2014-03-18", - "characters": [ - { - "actor": "Robert Downey Jr.", - "character": "Himself / Tony Stark / Iron Man" - }, - { - "actor": "Chris Hemsworth", - "character": "Himself / Thor" - }, - { - "actor": "Chris Evans", - "character": "Himself / Steve Rogers / Captain America" - }, - { - "actor": "Mark Ruffalo", - "character": "Himself / Bruce Banner / Hulk" - }, - { - "actor": "Gwyneth Paltrow", - "character": "Herself" - }, - { - "actor": "Clark Gregg", - "character": "Himself" - }, - { - "actor": "Samuel L. Jackson", - "character": "Himself" - }, - { - "actor": "Scarlett Johansson", - "character": "Herself" - }, - { - "actor": "Jeremy Renner", - "character": "Himself" - } - ] - }, - { - "title": "Captain America: Civil War", - "overview": "Following the events of Age of Ultron, the collective governments of the world pass an act designed to regulate all superhuman activity. This polarizes opinion amongst the Avengers, causing two factions to side with Iron Man or Captain America, which causes an epic battle between former allies.", - "release_date": "2016-04-27", - "characters": [ - { - "actor": "Chris Evans", - "character": "Steve Rogers / Captain America" - }, - { - "actor": "Robert Downey Jr.", - "character": "Tony Stark / Iron Man" - }, - { - "actor": "Scarlett Johansson", - "character": "Natasha Romanoff / Black Widow" - }, - { - "actor": "Don Cheadle", - "character": "James \"Rhodey\" Rhodes / War Machine" - }, - { - "actor": "Jeremy Renner", - "character": "Clint Barton / Hawkeye" - } - ] - }, - { - "title": "Thor: Ragnarok", - "overview": "Thor is imprisoned on the other side of the universe and finds himself in a race against time to get back to Asgard to stop Ragnarok, the destruction of his home-world and the end of Asgardian civilization, at the hands of an all-powerful new threat, the ruthless Hela.", - "release_date": "2017-10-25", - "characters": [ - { - "actor": "Chris Hemsworth", - "character": "Thor Odinson" - }, - { - "actor": "Mark Ruffalo", - "character": "Bruce Banner / Hulk" - }, - { - "actor": "Scarlett Johansson", - "character": "Natasha Romanoff / Black Widow (archive footage / uncredited)" - } - ] - }, - { - "title": "Avengers: Endgame", - "overview": "After the devastating events of Avengers: Infinity War, the universe is in ruins due to the efforts of the Mad Titan, Thanos. With the help of remaining allies, the Avengers must assemble once more in order to undo Thanos' actions and restore order to the universe once and for all, no matter what consequences may be in store.", - "release_date": "2019-04-24", - "characters": [ - { - "actor": "Robert Downey Jr.", - "character": "Tony Stark / Iron Man" - }, - { - "actor": "Chris Evans", - "character": "Steve Rogers / Captain America" - }, - { - "actor": "Mark Ruffalo", - "character": "Bruce Banner / Hulk" - }, - { - "actor": "Chris Hemsworth", - "character": "Thor Odinson" - }, - { - "actor": "Scarlett Johansson", - "character": "Natasha Romanoff / Black Widow" - }, - { - "actor": "Jeremy Renner", - "character": "Clint Barton / Hawkeye" - }, - { - "actor": "Don Cheadle", - "character": "James Rhodes / War Machine" - }, - { - "actor": "Gwyneth Paltrow", - "character": "Pepper Potts" - }, - { - "actor": "Samuel L. Jackson", - "character": "Nick Fury" - } - ] - }, - { - "title": "Avengers: Infinity War", - "overview": "As the Avengers and their allies have continued to protect the world from threats too large for any one hero to handle, a new danger has emerged from the cosmic shadows: Thanos. A despot of intergalactic infamy, his goal is to collect all six Infinity Stones, artifacts of unimaginable power, and use them to inflict his twisted will on all of reality. Everything the Avengers have fought for has led up to this moment - the fate of Earth and existence itself has never been more uncertain.", - "release_date": "2018-04-25", - "characters": [ - { - "actor": "Robert Downey Jr.", - "character": "Tony Stark / Iron Man" - }, - { - "actor": "Chris Hemsworth", - "character": "Thor Odinson" - }, - { - "actor": "Chris Evans", - "character": "Steve Rogers / Captain America" - }, - { - "actor": "Scarlett Johansson", - "character": "Natasha Romanoff / Black Widow" - }, - { - "actor": "Don Cheadle", - "character": "James \"Rhodey\" Rhodes / War Machine" - }, - { - "actor": "Gwyneth Paltrow", - "character": "Virginia \"Pepper\" Potts" - }, - { - "actor": "Samuel L. Jackson", - "character": "Nick Fury (uncredited)" - }, - { - "actor": "Mark Ruffalo", - "character": "Bruce Banner / The Hulk" - } - ] - }, - { - "title": "Captain Marvel", - "overview": "The story follows Carol Danvers as she becomes one of the universe’s most powerful heroes when Earth is caught in the middle of a galactic war between two alien races. Set in the 1990s, Captain Marvel is an all-new adventure from a previously unseen period in the history of the Marvel Cinematic Universe.", - "release_date": "2019-03-06", - "characters": [ - { - "actor": "Samuel L. Jackson", - "character": "Nick Fury" - }, - { - "actor": "Clark Gregg", - "character": "Agent Phil Coulson" - }, - { - "actor": "Chris Evans", - "character": "Steve Rogers / Captain America (uncredited)" - }, - { - "actor": "Scarlett Johansson", - "character": "Natasha Romanoff / Black Widow (uncredited)" - }, - { - "actor": "Don Cheadle", - "character": "James 'Rhodey' Rhodes / War Machine (uncredited)" - }, - { - "actor": "Mark Ruffalo", - "character": "Bruce Banner / The Hulk (uncredited)" - } - ] - }, - { - "title": "Spider-Man: Homecoming", - "overview": "Following the events of Captain America: Civil War, Peter Parker, with the help of his mentor Tony Stark, tries to balance his life as an ordinary high school student in Queens, New York City, with fighting crime as his superhero alter ego Spider-Man as a new threat, the Vulture, emerges.", - "release_date": "2017-07-05", - "characters": [ - { - "actor": "Robert Downey Jr.", - "character": "Tony Stark / Iron Man" - }, - { - "actor": "Gwyneth Paltrow", - "character": "Virginia \"Pepper\" Potts" - }, - { - "actor": "Chris Evans", - "character": "Steve Rogers / Captain America" - } - ] - }, - { - "title": "Team Thor", - "overview": "Discover what Thor was up to during the events of Captain America: Civil War.", - "release_date": "2016-08-28", - "characters": [ - { - "actor": "Chris Hemsworth", - "character": "Thor Odinson" - }, - { - "actor": "Mark Ruffalo", - "character": "Bruce Banner" - } - ] - }, - { - "title": "Black Widow", - "overview": "Natasha Romanoff, also known as Black Widow, confronts the darker parts of her ledger when a dangerous conspiracy with ties to her past arises. Pursued by a force that will stop at nothing to bring her down, Natasha must deal with her history as a spy and the broken relationships left in her wake long before she became an Avenger.", - "release_date": "2020-10-28", - "characters": [ - { - "actor": "Scarlett Johansson", - "character": "Natasha Romanoff / Black Widow" - }, - { - "actor": "Robert Downey Jr.", - "character": "Tony Stark / Iron Man" - } - ] - } -] -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/analytics.md b/versioned_docs/version-4.6/developers/operations-api/analytics.md deleted file mode 100644 index 59ac6011..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/analytics.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Analytics Operations ---- - -# Analytics Operations - -## get_analytics - -Retrieves analytics data from the server. - -- `operation` _(required)_ - must always be `get_analytics` -- `metric` _(required)_ - any value returned by `list_metrics` -- `start_time` _(optional)_ - Unix timestamp in seconds -- `end_time` _(optional)_ - Unix timestamp in seconds -- `get_attributes` _(optional)_ - array of attribute names to retrieve -- `conditions` _(optional)_ - array of conditions to filter results (see [search_by_conditions docs](./nosql-operations) for details) - -### Body - -```json -{ - "operation": "get_analytics", - "metric": "resource-usage", - "start_time": 1609459200, - "end_time": 1609545600, - "get_attributes": ["id", "metric", "userCPUTime", "systemCPUTime"], - "conditions": [ - { - "attribute": "node", - "operator": "equals", - "value": "node1.example.com" - } - ] -} -``` - -### Response 200 - -```json -[ - { - "id": "12345", - "metric": "resource-usage", - "userCPUTime": 100, - "systemCPUTime": 50 - }, - { - "id": "67890", - "metric": "resource-usage", - "userCPUTime": 150, - "systemCPUTime": 75 - } -] -``` - -## list_metrics - -Returns a list of available metrics that can be queried. - -- `operation` _(required)_ - must always be `list_metrics` -- `metric_types` _(optional)_ - array of metric types to filter results; one or both of `custom` and `builtin`; default is `builtin` - -### Body - -```json -{ - "operation": "list_metrics", - "metric_types": ["custom", "builtin"] -} -``` - -### Response 200 - -```json -["resource-usage", "table-size", "database-size", "main-thread-utilization", "utilization", "storage-volume"] -``` - -## describe_metric - -Provides detailed information about a specific metric, including its structure and available parameters. - -- `operation` _(required)_ - must always be `describe_metric` -- `metric` _(required)_ - name of the metric to describe - -### Body - -```json -{ - "operation": "describe_metric", - "metric": "resource-usage" -} -``` - -### Response 200 - -```json -{ - "attributes": [ - { - "name": "id", - "type": "number" - }, - { - "name": "metric", - "type": "string" - }, - { - "name": "userCPUTime", - "type": "number" - }, - { - "name": "systemCPUTime", - "type": "number" - }, - { - "name": "node", - "type": "string" - } - ] -} -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/bulk-operations.md b/versioned_docs/version-4.6/developers/operations-api/bulk-operations.md deleted file mode 100644 index b6714552..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/bulk-operations.md +++ /dev/null @@ -1,255 +0,0 @@ ---- -title: Bulk Operations ---- - -# Bulk Operations - -## Export Local - -Exports data based on a given search operation to a local file in JSON or CSV format. - -- `operation` _(required)_ - must always be `export_local` -- `format` _(required)_ - the format you wish to export the data, options are `json` & `csv` -- `path` _(required)_ - path local to the server to export the data -- `search_operation` _(required)_ - search_operation of `search_by_hash`, `search_by_value`, `search_by_conditions` or `sql` -- `filename` _(optional)_ - the name of the file where your export will be written to (do not include extension in filename). If one is not provided it will be autogenerated based on the epoch. - -### Body - -```json -{ - "operation": "export_local", - "format": "json", - "path": "/data/", - "search_operation": { - "operation": "sql", - "sql": "SELECT * FROM dev.breed" - } -} -``` - -### Response: 200 - -```json -{ - "message": "Starting job with id 6fc18eaa-3504-4374-815c-44840a12e7e5" -} -``` - ---- - -## CSV Data Load - -Ingests CSV data, provided directly in the operation as an `insert`, `update` or `upsert` into the specified database table. - -- `operation` _(required)_ - must always be `csv_data_load` -- `action` _(optional)_ - type of action you want to perform - `insert`, `update` or `upsert`. The default is `insert` -- `database` _(optional)_ - name of the database where you are loading your data. The default is `data` -- `table` _(required)_ - name of the table where you are loading your data -- `data` _(required)_ - csv data to import into Harper - -### Body - -```json -{ - "operation": "csv_data_load", - "database": "dev", - "action": "insert", - "table": "breed", - "data": "id,name,section,country,image\n1,ENGLISH POINTER,British and Irish Pointers and Setters,GREAT BRITAIN,https://www.fci.be/Nomenclature/Illustrations/001g07.jpg\n2,ENGLISH SETTER,British and Irish Pointers and Setters,GREAT BRITAIN,https://www.fci.be/Nomenclature/Illustrations/002g07.jpg\n3,KERRY BLUE TERRIER,Large and medium sized Terriers,IRELAND,\n" -} -``` - -### Response: 200 - -```json -{ - "message": "Starting job with id 2fe25039-566e-4670-8bb3-2db3d4e07e69", - "job_id": "2fe25039-566e-4670-8bb3-2db3d4e07e69" -} -``` - ---- - -## CSV File Load - -Ingests CSV data, provided via a path on the local filesystem, as an `insert`, `update` or `upsert` into the specified database table. - -_Note: The CSV file must reside on the same machine on which Harper is running. For example, the path to a CSV on your computer will produce an error if your Harper instance is a cloud instance._ - -- `operation` _(required)_ - must always be `csv_file_load` -- `action` _(optional)_ - type of action you want to perform - `insert`, `update` or `upsert`. The default is `insert` -- `database` _(optional)_ - name of the database where you are loading your data. The default is `data` -- `table` _(required)_ - name of the table where you are loading your data -- `file_path` _(required)_ - path to the csv file on the host running Harper - -### Body - -```json -{ - "operation": "csv_file_load", - "action": "insert", - "database": "dev", - "table": "breed", - "file_path": "/home/user/imports/breeds.csv" -} -``` - -### Response: 200 - -```json -{ - "message": "Starting job with id 3994d8e2-ec6a-43c4-8563-11c1df81870e", - "job_id": "3994d8e2-ec6a-43c4-8563-11c1df81870e" -} -``` - ---- - -## CSV URL Load - -Ingests CSV data, provided via URL, as an `insert`, `update` or `upsert` into the specified database table. - -- `operation` _(required)_ - must always be `csv_url_load` -- `action` _(optional)_ - type of action you want to perform - `insert`, `update` or `upsert`. The default is `insert` -- `database` _(optional)_ - name of the database where you are loading your data. The default is `data` -- `table` _(required)_ - name of the table where you are loading your data -- `csv_url` _(required)_ - URL to the csv - -### Body - -```json -{ - "operation": "csv_url_load", - "action": "insert", - "database": "dev", - "table": "breed", - "csv_url": "https://s3.amazonaws.com/complimentarydata/breeds.csv" -} -``` - -### Response: 200 - -```json -{ - "message": "Starting job with id 332aa0a2-6833-46cd-88a6-ae375920436a", - "job_id": "332aa0a2-6833-46cd-88a6-ae375920436a" -} -``` - ---- - -## Export To S3 - -Exports data based on a given search operation from table to AWS S3 in JSON or CSV format. - -- `operation` _(required)_ - must always be `export_to_s3` -- `format` _(required)_ - the format you wish to export the data, options are `json` & `csv` -- `s3` _(required)_ - details your access keys, bucket, bucket region and key for saving the data to S3 -- `search_operation` _(required)_ - search_operation of `search_by_hash`, `search_by_value`, `search_by_conditions` or `sql` - -### Body - -```json -{ - "operation": "export_to_s3", - "format": "json", - "s3": { - "aws_access_key_id": "YOUR_KEY", - "aws_secret_access_key": "YOUR_SECRET_KEY", - "bucket": "BUCKET_NAME", - "key": "OBJECT_NAME", - "region": "BUCKET_REGION" - }, - "search_operation": { - "operation": "sql", - "sql": "SELECT * FROM dev.dog" - } -} -``` - -### Response: 200 - -```json -{ - "message": "Starting job with id 9fa85968-4cb1-4008-976e-506c4b13fc4a", - "job_id": "9fa85968-4cb1-4008-976e-506c4b13fc4a" -} -``` - ---- - -## Import from S3 - -This operation allows users to import CSV or JSON files from an AWS S3 bucket as an `insert`, `update` or `upsert`. - -- `operation` _(required)_ - must always be `import_from_s3` -- `action` _(optional)_ - type of action you want to perform - `insert`, `update` or `upsert`. The default is `insert` -- `database` _(optional)_ - name of the database where you are loading your data. The default is `data` -- `table` _(required)_ - name of the table where you are loading your data -- `s3` _(required)_ - object containing required AWS S3 bucket info for operation: - - `aws_access_key_id` - AWS access key for authenticating into your S3 bucket - - `aws_secret_access_key` - AWS secret for authenticating into your S3 bucket - - `bucket` - AWS S3 bucket to import from - - `key` - the name of the file to import - _the file must include a valid file extension ('.csv' or '.json')_ - - `region` - the region of the bucket - -### Body - -```json -{ - "operation": "import_from_s3", - "action": "insert", - "database": "dev", - "table": "dog", - "s3": { - "aws_access_key_id": "YOUR_KEY", - "aws_secret_access_key": "YOUR_SECRET_KEY", - "bucket": "BUCKET_NAME", - "key": "OBJECT_NAME", - "region": "BUCKET_REGION" - } -} -``` - -### Response: 200 - -```json -{ - "message": "Starting job with id 062a1892-6a0a-4282-9791-0f4c93b12e16", - "job_id": "062a1892-6a0a-4282-9791-0f4c93b12e16" -} -``` - ---- - -## Delete Records Before - -Delete data before the specified timestamp on the specified database table exclusively on the node where it is executed. Any clustered nodes with replicated data will retain that data. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `delete_records_before` -- `date` _(required)_ - records older than this date will be deleted. Supported format looks like: `YYYY-MM-DDThh:mm:ss.sZ` -- `schema` _(required)_ - name of the schema where you are deleting your data -- `table` _(required)_ - name of the table where you are deleting your data - -### Body - -```json -{ - "operation": "delete_records_before", - "date": "2021-01-25T23:05:27.464", - "schema": "dev", - "table": "breed" -} -``` - -### Response: 200 - -```json -{ - "message": "Starting job with id d3aed926-e9fe-4ec1-aea7-0fb4451bd373", - "job_id": "d3aed926-e9fe-4ec1-aea7-0fb4451bd373" -} -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/certificate-management.md b/versioned_docs/version-4.6/developers/operations-api/certificate-management.md deleted file mode 100644 index f8eea402..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/certificate-management.md +++ /dev/null @@ -1,124 +0,0 @@ ---- -title: Certificate Management ---- - -# Certificate Management - -## Add Certificate - -Adds or updates a certificate in the `hdb_certificate` system table. -If a `private_key` is provided it will **not** be stored in `hdb_certificate`, it will be written to file in `/keys/`. -If a `private_key` is not passed the operation will search for one that matches the certificate. If one is not found an error will be returned. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `add_certificate` -- `name` _(required)_ - a unique name for the certificate -- `certificate` _(required)_ - a PEM formatted certificate string -- `is_authority` _(required)_ - a boolean indicating if the certificate is a certificate authority -- `hosts` _(optional)_ - an array of hostnames that the certificate is valid for -- `private_key` _(optional)_ - a PEM formatted private key string - -### Body - -```json -{ - "operation": "add_certificate", - "name": "my-cert", - "certificate": "-----BEGIN CERTIFICATE-----ZDFAay... -----END CERTIFICATE-----", - "is_authority": false, - "private_key": "-----BEGIN RSA PRIVATE KEY-----Y4dMpw5f... -----END RSA PRIVATE KEY-----" -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully added certificate: my-cert" -} -``` - ---- - -## Remove Certificate - -Removes a certificate from the `hdb_certificate` system table and deletes the corresponding private key file. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `remove_certificate` -- `name` _(required)_ - the name of the certificate - -### Body - -```json -{ - "operation": "remove_certificate", - "name": "my-cert" -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully removed my-cert" -} -``` - ---- - -## List Certificates - -Lists all certificates in the `hdb_certificate` system table. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `list_certificates` - -### Body - -```json -{ - "operation": "list_certificates" -} -``` - -### Response: 200 - -```json -[ - { - "name": "HarperDB-Certificate-Authority-node1", - "certificate": "-----BEGIN CERTIFICATE-----\r\nTANBgkqhk... S34==\r\n-----END CERTIFICATE-----\r\n", - "private_key_name": "privateKey.pem", - "is_authority": true, - "details": { - "issuer": "CN=HarperDB-Certificate-Authority-node1 C=USA ST=Colorado L=Denver O=HarperDB\\, Inc.", - "subject": "CN=HarperDB-Certificate-Authority-node1 C=USA ST=Colorado L=Denver O=HarperDB\\, Inc.", - "serial_number": "5235345", - "valid_from": "Aug 27 15:00:00 2024 GMT", - "valid_to": "Aug 25 15:00:00 2034 GMT" - }, - "is_self_signed": true, - "uses": ["https", "wss"] - }, - { - "name": "node1", - "certificate": "-----BEGIN CERTIFICATE-----\r\ngIEcSR1M... 5bv==\r\n-----END CERTIFICATE-----\r\n", - "private_key_name": "privateKey.pem", - "is_authority": false, - "details": { - "issuer": "CN=HarperDB-Certificate-Authority-node1 C=USA ST=Colorado L=Denver O=HarperDB\\, Inc.", - "subject": "CN=node.1 C=USA ST=Colorado L=Denver O=HarperDB\\, Inc.", - "subject_alt_name": "IP Address:127.0.0.1, DNS:localhost, IP Address:0:0:0:0:0:0:0:1, DNS:node.1", - "serial_number": "5243646", - "valid_from": "Aug 27 15:00:00 2024 GMT", - "valid_to": "Aug 25 15:00:00 2034 GMT" - }, - "is_self_signed": true, - "uses": ["https", "wss"] - } -] -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/clustering-nats.md b/versioned_docs/version-4.6/developers/operations-api/clustering-nats.md deleted file mode 100644 index 45e160c4..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/clustering-nats.md +++ /dev/null @@ -1,486 +0,0 @@ ---- -title: Clustering using NATS ---- - -# Clustering using NATS - -## Cluster Set Routes - -Adds a route/routes to either the hub or leaf server cluster configuration. This operation behaves as a PATCH/upsert, meaning it will add new routes to the configuration while leaving existing routes untouched. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `cluster_set_routes` -- `server` _(required)_ - must always be `hub` or `leaf`, in most cases you should use `hub` here -- `routes` _(required)_ - must always be an objects array with a host and port: - - `host` - the host of the remote instance you are clustering to - - `port` - the clustering port of the remote instance you are clustering to, in most cases this is the value in `clustering.hubServer.cluster.network.port` on the remote instance `harperdb-config.yaml` - -### Body - -```json -{ - "operation": "cluster_set_routes", - "server": "hub", - "routes": [ - { - "host": "3.22.181.22", - "port": 12345 - }, - { - "host": "3.137.184.8", - "port": 12345 - }, - { - "host": "18.223.239.195", - "port": 12345 - }, - { - "host": "18.116.24.71", - "port": 12345 - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "cluster routes successfully set", - "set": [ - { - "host": "3.22.181.22", - "port": 12345 - }, - { - "host": "3.137.184.8", - "port": 12345 - }, - { - "host": "18.223.239.195", - "port": 12345 - }, - { - "host": "18.116.24.71", - "port": 12345 - } - ], - "skipped": [] -} -``` - ---- - -## Cluster Get Routes - -Gets all the hub and leaf server routes from the config file. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `cluster_get_routes` - -### Body - -```json -{ - "operation": "cluster_get_routes" -} -``` - -### Response: 200 - -```json -{ - "hub": [ - { - "host": "3.22.181.22", - "port": 12345 - }, - { - "host": "3.137.184.8", - "port": 12345 - }, - { - "host": "18.223.239.195", - "port": 12345 - }, - { - "host": "18.116.24.71", - "port": 12345 - } - ], - "leaf": [] -} -``` - ---- - -## Cluster Delete Routes - -Removes route(s) from hub and/or leaf server routes array in config file. Returns a deletion success message and arrays of deleted and skipped records. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `cluster_delete_routes` -- `routes` _(required)_ - Must be an array of route object(s) - -### Body - -```json -{ - "operation": "cluster_delete_routes", - "routes": [ - { - "host": "18.116.24.71", - "port": 12345 - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "cluster routes successfully deleted", - "deleted": [ - { - "host": "18.116.24.71", - "port": 12345 - } - ], - "skipped": [] -} -``` - ---- - -## Add Node - -Registers an additional Harper instance with associated subscriptions. Learn more about [Harper clustering here](../clustering/). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `add_node` -- `node_name` _(required)_ - the node name of the remote node -- `subscriptions` _(required)_ - The relationship created between nodes. Must be an object array and include `schema`, `table`, `subscribe` and `publish`: - - `schema` - the schema to replicate from - - `table` - the table to replicate from - - `subscribe` - a boolean which determines if transactions on the remote table should be replicated on the local table - - `publish` - a boolean which determines if transactions on the local table should be replicated on the remote table - - `start_time` _(optional)_ - How far back to go to get transactions from node being added. Must be in UTC YYYY-MM-DDTHH:mm:ss.sssZ format - -### Body - -```json -{ - "operation": "add_node", - "node_name": "ec2-3-22-181-22", - "subscriptions": [ - { - "schema": "dev", - "table": "dog", - "subscribe": false, - "publish": true, - "start_time": "2022-09-02T20:06:35.993Z" - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully added 'ec2-3-22-181-22' to manifest" -} -``` - ---- - -## Update Node - -Modifies an existing Harper instance registration and associated subscriptions. This operation behaves as a PATCH/upsert, meaning it will insert or update the specified replication configurations while leaving other table replication configuration untouched. Learn more about [Harper clustering here](../clustering/). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `update_node` -- `node_name` _(required)_ - the node name of the remote node you are updating -- `subscriptions` _(required)_ - The relationship created between nodes. Must be an object array and include `schema`, `table`, `subscribe` and `publish`: - - `schema` - the schema to replicate from - - `table` - the table to replicate from - - `subscribe` - a boolean which determines if transactions on the remote table should be replicated on the local table - - `publish` - a boolean which determines if transactions on the local table should be replicated on the remote table - - `start_time` _(optional)_ - How far back to go to get transactions from node being added. Must be in UTC YYYY-MM-DDTHH:mm:ss.sssZ format - -### Body - -```json -{ - "operation": "update_node", - "node_name": "ec2-18-223-239-195", - "subscriptions": [ - { - "schema": "dev", - "table": "dog", - "subscribe": true, - "publish": false, - "start_time": "2022-09-02T20:06:35.993Z" - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully updated 'ec2-3-22-181-22'" -} -``` - ---- - -## Set Node Replication - -A more adeptly named alias for add and update node. This operation behaves as a PATCH/upsert, meaning it will insert or update the specified replication configurations while leaving other table replication configuration untouched. The `database` (aka `schema`) parameter is optional, it will default to `data`. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `set_node_replication` -- `node_name` _(required)_ - the node name of the remote node you are updating -- `subscriptions` _(required)_ - The relationship created between nodes. Must be an object array and `table`, `subscribe` and `publish`: - - `database` _(optional)_ - the database to replicate from - - `table` _(required)_ - the table to replicate from - - `subscribe` _(required)_ - a boolean which determines if transactions on the remote table should be replicated on the local table - - `publish` _(required)_ - a boolean which determines if transactions on the local table should be replicated on the remote table -- - -### Body - -```json -{ - "operation": "set_node_replication", - "node_name": "node1", - "subscriptions": [ - { - "table": "dog", - "subscribe": true, - "publish": true - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully updated 'ec2-3-22-181-22'" -} -``` - ---- - -## Cluster Status - -Returns an array of status objects from a cluster. A status object will contain the clustering node name, whether or not clustering is enabled, and a list of possible connections. Learn more about [Harper clustering here](../clustering/). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `cluster_status` - -### Body - -```json -{ - "operation": "cluster_status" -} -``` - -### Response: 200 - -```json -{ - "node_name": "ec2-18-221-143-69", - "is_enabled": true, - "connections": [ - { - "node_name": "ec2-3-22-181-22", - "status": "open", - "ports": { - "clustering": 12345, - "operations_api": 9925 - }, - "latency_ms": 13, - "uptime": "30d 1h 18m 8s", - "subscriptions": [ - { - "schema": "dev", - "table": "dog", - "publish": true, - "subscribe": true - } - ] - } - ] -} -``` - ---- - -## Cluster Network - -Returns an object array of enmeshed nodes. Each node object will contain the name of the node, the amount of time (in milliseconds) it took for it to respond, the names of the nodes it is enmeshed with and the routes set in its config file. Learn more about [Harper clustering here](../clustering/). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_- must always be `cluster_network` -- `timeout` _(optional)_ - the amount of time in milliseconds to wait for a response from the network. Must be a number -- `connected_nodes` _(optional)_ - omit `connected_nodes` from the response. Must be a boolean. Defaults to `false` -- `routes` _(optional)_ - omit `routes` from the response. Must be a boolean. Defaults to `false` - -### Body - -```json -{ - "operation": "cluster_network" -} -``` - -### Response: 200 - -```json -{ - "nodes": [ - { - "name": "local_node", - "response_time": 4, - "connected_nodes": ["ec2-3-142-255-78"], - "routes": [ - { - "host": "3.142.255.78", - "port": 9932 - } - ] - }, - { - "name": "ec2-3-142-255-78", - "response_time": 57, - "connected_nodes": ["ec2-3-12-153-124", "ec2-3-139-236-138", "local_node"], - "routes": [] - } - ] -} -``` - ---- - -## Remove Node - -Removes a Harper instance and associated subscriptions from the cluster. Learn more about [Harper clustering here](../clustering/). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `remove_node` -- `node_name` _(required)_ - The name of the node you are de-registering - -### Body - -```json -{ - "operation": "remove_node", - "node_name": "ec2-3-22-181-22" -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully removed 'ec2-3-22-181-22' from manifest" -} -``` - ---- - -## Configure Cluster - -Bulk create/remove subscriptions for any number of remote nodes. Resets and replaces any existing clustering setup. -Learn more about [Harper clustering here](../clustering/). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `configure_cluster` -- `connections` _(required)_ - must be an object array with each object containing `node_name` and `subscriptions` for that node - -### Body - -```json -{ - "operation": "configure_cluster", - "connections": [ - { - "node_name": "ec2-3-137-184-8", - "subscriptions": [ - { - "schema": "dev", - "table": "dog", - "subscribe": true, - "publish": false - } - ] - }, - { - "node_name": "ec2-18-223-239-195", - "subscriptions": [ - { - "schema": "dev", - "table": "dog", - "subscribe": true, - "publish": true - } - ] - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "Cluster successfully configured." -} -``` - ---- - -## Purge Stream - -Will purge messages from a stream - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `purge_stream` -- `database` _(required)_ - the name of the database where the streams table resides -- `table` _(required)_ - the name of the table that belongs to the stream -- `options` _(optional)_ - control how many messages get purged. Options are: - - `keep` - purge will keep this many most recent messages - - `seq` - purge all messages up to, but not including, this sequence - -### Body - -```json -{ - "operation": "purge_stream", - "database": "dev", - "table": "dog", - "options": { - "keep": 100 - } -} -``` - ---- diff --git a/versioned_docs/version-4.6/developers/operations-api/clustering.md b/versioned_docs/version-4.6/developers/operations-api/clustering.md deleted file mode 100644 index 8fc5ae49..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/clustering.md +++ /dev/null @@ -1,355 +0,0 @@ ---- -title: Clustering ---- - -# Clustering - -The following operations are available for configuring and managing [Harper replication](../replication/). - -_**If you are using NATS for clustering, please see the**_ [_**NATS Clustering Operations**_](./clustering-nats) _**documentation.**_ - -## Add Node - -Adds a new Harper instance to the cluster. If `subscriptions` are provided, it will also create the replication relationships between the nodes. If they are not provided a fully replicating system will be created. [Learn more about adding nodes here](../replication/). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `add_node` -- `hostname` or `url` _(required)_ - one of these fields is required. You must provide either the `hostname` or the `url` of the node you want to add -- `verify_tls` _(optional)_ - a boolean which determines if the TLS certificate should be verified. This will allow the Harper default self-signed certificates to be accepted. Defaults to `true` -- `authorization` _(optional)_ - an object or a string which contains the authorization information for the node being added. If it is an object, it should contain `username` and `password` fields. If it is a string, it should use HTTP `Authorization` style credentials -- `retain_authorization` _(optional)_ - a boolean which determines if the authorization credentials should be retained/stored and used everytime a connection is made to this node. If `true`, the authorization will be stored on the node record. Generally this should not be used, as mTLS/certificate based authorization is much more secure and safe, and avoids the need for storing credentials. Defaults to `false`. -- `revoked_certificates` _(optional)_ - an array of revoked certificates serial numbers. If a certificate is revoked, it will not be accepted for any connections. -- `shard` _(optional)_ - a number which can be used to indicate which shard this node belongs to. This is only needed if you are using sharding. -- `subscriptions` _(optional)_ - The relationship created between nodes. If not provided a fully replicated cluster will be setup. Must be an object array and include `database`, `table`, `subscribe` and `publish`: - - `database` - the database to replicate - - `table` - the table to replicate - - `subscribe` - a boolean which determines if transactions on the remote table should be replicated on the local table - - `publish` - a boolean which determines if transactions on the local table should be replicated on the remote table - -### Body - -```json -{ - "operation": "add_node", - "hostname": "server-two", - "verify_tls": false, - "authorization": { - "username": "admin", - "password": "password" - } -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully added 'server-two' to cluster" -} -``` - ---- - -## Update Node - -Modifies an existing Harper instance in the cluster. - -_Operation is restricted to super_user roles only_ - -_Note: will attempt to add the node if it does not exist_ - -- `operation` _(required)_ - must always be `update_node` -- `hostname` _(required)_ - the `hostname` of the remote node you are updating -- `revoked_certificates` _(optional)_ - an array of revoked certificates serial numbers. If a certificate is revoked, it will not be accepted for any connections. -- `shard` _(optional)_ - a number which can be used to indicate which shard this node belongs to. This is only needed if you are using sharding. -- `subscriptions` _(required)_ - The relationship created between nodes. Must be an object array and include `database`, `table`, `subscribe` and `publish`: - - `database` - the database to replicate from - - `table` - the table to replicate from - - `subscribe` - a boolean which determines if transactions on the remote table should be replicated on the local table - - `publish` - a boolean which determines if transactions on the local table should be replicated on the remote table - -### Body - -```json -{ - "operation": "update_node", - "hostname": "server-two", - "subscriptions": [ - { - "database": "dev", - "table": "my-table", - "subscribe": true, - "publish": true - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully updated 'server-two'" -} -``` - ---- - -## Remove Node - -Removes a Harper node from the cluster and stops replication, [Learn more about remove node here](../replication/). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `remove_node` -- `name` _(required)_ - The name of the node you are removing - -### Body - -```json -{ - "operation": "remove_node", - "hostname": "server-two" -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully removed 'server-two' from cluster" -} -``` - ---- - -## Cluster Status - -Returns an array of status objects from a cluster. - -`database_sockets` shows the actual websocket connections that exist between nodes. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `cluster_status` - -### Body - -```json -{ - "operation": "cluster_status" -} -``` - -### Response: 200 - -```json -{ - "type": "cluster-status", - "connections": [ - { - "replicateByDefault": true, - "replicates": true, - "url": "wss://server-2.domain.com:9933", - "name": "server-2.domain.com", - "subscriptions": null, - "database_sockets": [ - { - "database": "data", - "connected": true, - "latency": 0.7, - "thread_id": 1, - "nodes": ["server-2.domain.com"], - "lastCommitConfirmed": "Wed, 12 Feb 2025 19:09:34 GMT", - "lastReceivedRemoteTime": "Wed, 12 Feb 2025 16:49:29 GMT", - "lastReceivedLocalTime": "Wed, 12 Feb 2025 16:50:59 GMT", - "lastSendTime": "Wed, 12 Feb 2025 16:50:59 GMT" - } - ] - } - ], - "node_name": "server-1.domain.com", - "is_enabled": true -} -``` - -There is a separate socket for each database for each node. Each node is represented in the connections array, and each database connection to that node is represented in the `database_sockets` array. Additional timing statistics include: - -- `lastCommitConfirmed`: When a commit is sent out, it should receive a confirmation from the remote server; this is the last receipt of confirmation of an outgoing commit. -- `lastReceivedRemoteTime`: This is the timestamp of the transaction that was last received. The timestamp is from when the original transaction occurred. -- `lastReceivedLocalTime`: This is local time when the last transaction was received. If there is a different between this and `lastReceivedRemoteTime`, it means there is a delay from the original transaction to \* receiving it and so it is probably catching-up/behind. -- `sendingMessage`: The timestamp of transaction is actively being sent. This won't exist if the replicator is waiting for the next transaction to send. - ---- - -## Configure Cluster - -Bulk create/remove subscriptions for any number of remote nodes. Resets and replaces any existing clustering setup. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `configure_cluster` -- `connections` _(required)_ - must be an object array with each object following the `add_node` schema. - -### Body - -```json -{ - "operation": "configure_cluster", - "connections": [ - { - "hostname": "server-two", - "verify_tls": false, - "authorization": { - "username": "admin", - "password": "password2" - }, - "subscriptions": [ - { - "schema": "dev", - "table": "my-table", - "subscribe": true, - "publish": false - } - ] - }, - { - "hostname": "server-three", - "verify_tls": false, - "authorization": { - "username": "admin", - "password": "password3" - }, - "subscriptions": [ - { - "schema": "dev", - "table": "dog", - "subscribe": true, - "publish": true - } - ] - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "Cluster successfully configured." -} -``` - ---- - -## Cluster Set Routes - -Adds a route/routes to the `replication.routes` configuration. This operation behaves as a PATCH/upsert, meaning it will add new routes to the configuration while leaving existing routes untouched. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `cluster_set_routes` -- `routes` _(required)_ - the routes field is an array that specifies the routes for clustering. Each element in the array can be either a string or an object with `hostname` and `port` properties. - -### Body - -```json -{ - "operation": "cluster_set_routes", - "routes": [ - "wss://server-two:9925", - { - "hostname": "server-three", - "port": 9930 - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "cluster routes successfully set", - "set": [ - "wss://server-two:9925", - { - "hostname": "server-three", - "port": 9930 - } - ], - "skipped": [] -} -``` - ---- - -## Cluster Get Routes - -Gets the replication routes from the Harper config file. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `cluster_get_routes` - -### Body - -```json -{ - "operation": "cluster_get_routes" -} -``` - -### Response: 200 - -```json -[ - "wss://server-two:9925", - { - "hostname": "server-three", - "port": 9930 - } -] -``` - ---- - -## Cluster Delete Routes - -Removes route(s) from the Harper config file. Returns a deletion success message and arrays of deleted and skipped records. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `cluster_delete_routes` -- `routes` _(required)_ - Must be an array of route object(s) - -### Body - -```json -{ - "operation": "cluster_delete_routes", - "routes": [ - { - "hostname": "server-three", - "port": 9930 - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "cluster routes successfully deleted", - "deleted": [ - { - "hostname": "server-three", - "port": 9930 - } - ], - "skipped": [] -} -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/components.md b/versioned_docs/version-4.6/developers/operations-api/components.md deleted file mode 100644 index 1b964c50..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/components.md +++ /dev/null @@ -1,543 +0,0 @@ ---- -title: Components ---- - -# Components - -## Add Component - -Creates a new component project in the component root directory using a predefined template. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `add_component` -- `project` _(required)_ - the name of the project you wish to create -- `replicated` _(optional)_ - if true, Harper will replicate the component to all nodes in the cluster. Must be a boolean. - -### Body - -```json -{ - "operation": "add_component", - "project": "my-component" -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully added project: my-component" -} -``` - ---- - -## Deploy Component - -Will deploy a component using either a base64-encoded string representation of a `.tar` file (the output from `package_component`) or a package value, which can be any valid NPM reference, such as a GitHub repo, an NPM package, a tarball, a local directory or a website. - -If deploying with the `payload` option, Harper will decrypt the base64-encoded string, reconstitute the .tar file of your project folder, and extract it to the component root project directory. - -If deploying with the `package` option, the package value will be written to `harperdb-config.yaml`. Then npm install will be utilized to install the component in the `node_modules` directory located in the hdb root. The value is a package reference, which should generally be a [URL reference, as described here](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#urls-as-dependencies) (it is also possible to include NPM registerd packages and file paths). URL package references can directly reference tarballs that can be installed as a package. However, the most common and recommended usage is to install from a Git repository, which can be combined with a tag to deploy a specific version directly from versioned source control. When using tags, we highly recommend that you use the `semver` directive to ensure consistent and reliable installation by NPM. In addition to tags, you can also reference branches or commit numbers. Here is an example URL package reference to a (public) Git repository that doesn't require authentication: - -``` -https://github.com/HarperDB/application-template#semver:v1.0.0 -``` - -or this can be shortened to: - -``` -HarperDB/application-template#semver:v1.0.0 -``` - -You can also install from private repository if you have an installed SSH keys on the server: - -``` -git+ssh://git@github.com:my-org/my-app.git#semver:v1.0.0 -``` - -Or you can use a Github token: - -``` -https://@github.com/my-org/my-app#semver:v1.0.0 -``` - -Or you can use a GitLab Project Access Token: - -``` -https://my-project:@gitlab.com/my-group/my-project#semver:v1.0.0 -``` - -Note that your component will be installed by NPM. If your component has dependencies, NPM will attempt to download and install these as well. NPM normally uses the public registry.npmjs.org registry. If you are installing without network access to this, you may wish to define [custom registry locations](https://docs.npmjs.com/cli/v8/configuring-npm/npmrc) if you have any dependencies that need to be installed. NPM will install the deployed component and any dependencies in node_modules in the hdb root directory (typically `~/hdb/node_modules`). - -_Note: After deploying a component a restart may be required_ - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `deploy_component` -- `project` _(required)_ - the name of the project you wish to deploy -- `package` _(optional)_ - this can be any valid GitHub or NPM reference -- `payload` _(optional)_ - a base64-encoded string representation of the .tar file. Must be a string -- `restart` _(optional)_ - must be either a boolean or the string `rolling`. If set to `rolling`, a rolling restart will be triggered after the component is deployed, meaning that each node in the cluster will be sequentially restarted (waiting for the last restart to start the next). If set to `true`, the restart will not be rolling, all nodes will be restarted in parallel. If `replicated` is `true`, the restart operations will be replicated across the cluster. -- `replicated` _(optional)_ - if true, Harper will replicate the component to all nodes in the cluster. Must be a boolean. -- `install_command` _(optional)_ - A command to use when installing the component. Must be a string. This can be used to install dependencies with pnpm or yarn, for example, like: `"install_command": "npm install -g pnpm && pnpm install"` - -### Body - -```json -{ - "operation": "deploy_component", - "project": "my-component", - "payload": "A very large base64-encoded string representation of the .tar file" -} -``` - -```json -{ - "operation": "deploy_component", - "project": "my-component", - "package": "HarperDB/application-template", - "replicated": true -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully deployed: my-component" -} -``` - ---- - -## Package Component - -Creates a temporary `.tar` file of the specified project folder, then reads it into a base64-encoded string and returns an object with the string and the payload. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `package_component` -- `project` _(required)_ - the name of the project you wish to package -- `skip_node_modules` _(optional)_ - if true, creates option for tar module that will exclude the project's node_modules directory. Must be a boolean - -### Body - -```json -{ - "operation": "package_component", - "project": "my-component", - "skip_node_modules": true -} -``` - -### Response: 200 - -```json -{ - "project": "my-component", - "payload": "LgAAAAAAAAAAAAAAAAAAA...AAAAAAAAAAAAAAAAAAAAAAAAAAAAA==" -} -``` - ---- - -## Drop Component - -Deletes a file from inside the component project or deletes the complete project. - -**If just `project` is provided it will delete all that projects local files and folders** - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `drop_component` -- `project` _(required)_ - the name of the project you wish to delete or to delete from if using the `file` parameter -- `file` _(optional)_ - the path relative to your project folder of the file you wish to delete -- `replicated` _(optional)_ - if true, Harper will replicate the component deletion to all nodes in the cluster. Must be a boolean. -- `restart` _(optional)_ - if true, Harper will restart after dropping the component. Must be a boolean. - -### Body - -```json -{ - "operation": "drop_component", - "project": "my-component", - "file": "utils/myUtils.js" -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully dropped: my-component/utils/myUtils.js" -} -``` - ---- - -## Get Components - -Gets all local component files and folders and any component config from `harperdb-config.yaml` - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `get_components` - -### Body - -```json -{ - "operation": "get_components" -} -``` - -### Response: 200 - -```json -{ - "name": "components", - "entries": [ - { - "package": "HarperDB/application-template", - "name": "deploy-test-gh" - }, - { - "package": "@fastify/compress", - "name": "fast-compress" - }, - { - "name": "my-component", - "entries": [ - { - "name": "LICENSE", - "mtime": "2023-08-22T16:00:40.286Z", - "size": 1070 - }, - { - "name": "index.md", - "mtime": "2023-08-22T16:00:40.287Z", - "size": 1207 - }, - { - "name": "config.yaml", - "mtime": "2023-08-22T16:00:40.287Z", - "size": 1069 - }, - { - "name": "package.json", - "mtime": "2023-08-22T16:00:40.288Z", - "size": 145 - }, - { - "name": "resources.js", - "mtime": "2023-08-22T16:00:40.289Z", - "size": 583 - }, - { - "name": "schema.graphql", - "mtime": "2023-08-22T16:00:40.289Z", - "size": 466 - }, - { - "name": "utils", - "entries": [ - { - "name": "commonUtils.js", - "mtime": "2023-08-22T16:00:40.289Z", - "size": 583 - } - ] - } - ] - } - ] -} -``` - ---- - -## Get Component File - -Gets the contents of a file inside a component project. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `get_component_file` -- `project` _(required)_ - the name of the project where the file is located -- `file` _(required)_ - the path relative to your project folder of the file you wish to view -- `encoding` _(optional)_ - the encoding that will be passed to the read file call. Defaults to `utf8` - -### Body - -```json -{ - "operation": "get_component_file", - "project": "my-component", - "file": "resources.js" -} -``` - -### Response: 200 - -```json -{ - "message": "/**export class MyCustomResource extends tables.TableName {\n\t/ we can define our own custom POST handler\n\tpost(content) {\n\t\t/ do something with the incoming content;\n\t\treturn super.post(content);\n\t}\n\t/ or custom GET handler\n\tget() {\n\t\t/ we can modify this resource before returning\n\t\treturn super.get();\n\t}\n}\n */\n/ we can also define a custom resource without a specific table\nexport class Greeting extends Resource {\n\t/ a \"Hello, world!\" handler\n\tget() {\n\t\treturn { greeting: 'Hello, world!' };\n\t}\n}" -} -``` - ---- - -## Set Component File - -Creates or updates a file inside a component project. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `set_component_file` -- `project` _(required)_ - the name of the project the file is located in -- `file` _(required)_ - the path relative to your project folder of the file you wish to set -- `payload` _(required)_ - what will be written to the file -- `encoding` _(optional)_ - the encoding that will be passed to the write file call. Defaults to `utf8` -- `replicated` _(optional)_ - if true, Harper will replicate the component update to all nodes in the cluster. Must be a boolean. - -### Body - -```json -{ - "operation": "set_component_file", - "project": "my-component", - "file": "test.js", - "payload": "console.log('hello world')" -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully set component: test.js" -} -``` - ---- - -## Add SSH Key - -Adds an SSH key for deploying components from private repositories. This will also create an ssh config file that will be used when deploying the components. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `add_ssh_key` -- `name` _(required)_ - the name of the key -- `key` _(required)_ - the private key contents. Must be an ed25519 key. Line breaks must be delimited with `\n` and have a trailing `\n` -- `host` _(required)_ - the host for the ssh config (see below). Used as part of the `package` url when deploying a component using this key -- `hostname` _(required)_ - the hostname for the ssh config (see below). Used to map `host` to an actual domain (e.g. `github.com`) -- `known_hosts` _(optional)_ - the public SSH keys of the host your component will be retrieved from. If `hostname` is `github.com` this will be retrieved automatically. Line breaks must be delimited with `\n` -- `replicated` _(optional)_ - if true, HarperDB will replicate the key to all nodes in the cluster. Must be a boolean. - _Operation is restricted to super_user roles only_ - -### Body - -```json -{ - "operation": "add_ssh_key", - "name": "harperdb-private-component", - "key": "-----BEGIN OPENSSH PRIVATE KEY-----\nthis\nis\na\nfake\nkey\n-----END OPENSSH PRIVATE KEY-----\n", - "host": "harperdb-private-component.github.com", - "hostname": "github.com" -} -``` - -### Response: 200 - -```json -{ - "message": "Added ssh key: harperdb-private-component" -} -``` - -### Generated Config and Deploy Component "package" string examples - -``` -#harperdb-private-component -Host harperdb-private-component.github.com - HostName github.com - User git - IdentityFile /hdbroot/ssh/harperdb-private-component.key - IdentitiesOnly yes -``` - -``` -"package": "git+ssh://git@:.git#semver:v1.2.3" - -"package": "git+ssh://git@harperdb-private-component.github.com:HarperDB/harperdb-private-component.git#semver:v1.2.3" -``` - -Note that `deploy_component` with a package uses `npm install` so the url must be a valid npm format url. The above is an example of a url using a tag in the repo to install. - ---- - -## Update SSH Key - -Updates the private key contents of an existing SSH key. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `update_ssh_key` -- `name` _(required)_ - the name of the key to be updated -- `key` _(required)_ - the private key contents. Must be an ed25519 key. Line breaks must be delimited with `\n` and have a trailing `\n` -- `replicated` _(optional)_ - if true, Harper will replicate the key update to all nodes in the cluster. Must be a boolean. - -### Body - -```json -{ - "operation": "update_ssh_key", - "name": "harperdb-private-component", - "key": "-----BEGIN OPENSSH PRIVATE KEY-----\nthis\nis\na\nNEWFAKE\nkey\n-----END OPENSSH PRIVATE KEY-----\n", - "host": "harperdb-private-component.github.com", - "hostname": "github.com" -} -``` - -### Response: 200 - -```json -{ - "message": "Updated ssh key: harperdb-private-component" -} -``` - -## Delete SSH Key - -Deletes a SSH key. This will also remove it from the generated SSH config. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `delete_ssh_key` -- `name` _(required)_ - the name of the key to be deleted -- `replicated` _(optional)_ - if true, Harper will replicate the key deletion to all nodes in the cluster. Must be a boolean. - -### Body - -```json -{ - "name": "harperdb-private-component" -} -``` - -### Response: 200 - -```json -{ - "message": "Deleted ssh key: harperdb-private-component" -} -``` - ---- - -## List SSH Keys - -List off the names of added SSH keys - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `list_ssh_keys` - -### Body - -```json -{ - "operation": "list_ssh_keys" -} -``` - -### Response: 200 - -```json -[ - { - "name": "harperdb-private-component" - } -] -``` - -_Note: Additional SSH keys would appear as more objects in this array_ - ---- - -## Set SSH Known Hosts - -Sets the SSH known_hosts file. This will overwrite the file. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `set_ssh_known_hosts` -- `known_hosts` _(required)_ - The contents to set the known_hosts to. Line breaks must be delimite d with -- `replicated` _(optional)_ - if true, Harper will replicate the known hosts to all nodes in the cluster. Must be a boolean. - -### Body - -```json -{ - "operation": "set_ssh_known_hosts", - "known_hosts": "github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=\ngithub.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl\ngithub.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=\n" -} -``` - -### Response: 200 - -```json -{ - "message": "Known hosts successfully set" -} -``` - -## Get SSH Known Hosts - -Gets the contents of the known_hosts file - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `get_ssh_known_hosts` - -### Body - -```json -{ - "operation": "get_ssh_known_hosts" -} -``` - -### Response: 200 - -```json -{ - "known_hosts": "github.com ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEmKSENjQEezOmxkZMy7opKgwFB9nkt5YRrYMjNuG5N87uRgg6CLrbo5wAdT/y6v0mKV0U2w0WZ2YB/++Tpockg=\ngithub.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl\ngithub.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=\n" -} -``` - ---- - -## Install Node Modules - -This operation is deprecated, as it is handled automatically by deploy_component and restart. -Executes npm install against specified custom function projects. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `install_node_modules` -- `projects` _(required)_ - must ba an array of custom functions projects. -- `dry_run` _(optional)_ - refers to the npm --dry-run flag: [https://docs.npmjs.com/cli/v8/commands/npm-install#dry-run](https://docs.npmjs.com/cli/v8/commands/npm-install#dry-run). Defaults to false. - -### Body - -```json -{ - "operation": "install_node_modules", - "projects": ["dogs", "cats"], - "dry_run": true -} -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/configuration.md b/versioned_docs/version-4.6/developers/operations-api/configuration.md deleted file mode 100644 index a09a38a0..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/configuration.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Configuration ---- - -# Configuration - -## Set Configuration - -Modifies the Harper configuration file parameters. Must follow with a restart or restart_service operation. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `set_configuration` -- `logging_level` _(optional)_ - one or more configuration keywords to be updated in the Harper configuration file -- `clustering_enabled` _(optional)_ - one or more configuration keywords to be updated in the Harper configuration file - -### Body - -```json -{ - "operation": "set_configuration", - "logging_level": "trace", - "clustering_enabled": true -} -``` - -### Response: 200 - -```json -{ - "message": "Configuration successfully set. You must restart HarperDB for new config settings to take effect." -} -``` - ---- - -## Get Configuration - -Returns the Harper configuration parameters. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `get_configuration` - -### Body - -```json -{ - "operation": "get_configuration" -} -``` - -### Response: 200 - -```json -{ - "http": { - "compressionThreshold": 1200, - "cors": false, - "corsAccessList": [null], - "keepAliveTimeout": 30000, - "port": 9926, - "securePort": null, - "timeout": 120000 - }, - "threads": 11, - "authentication": { - "cacheTTL": 30000, - "enableSessions": true, - "operationTokenTimeout": "1d", - "refreshTokenTimeout": "30d" - }, - "analytics": { - "aggregatePeriod": 60 - }, - "replication": { - "hostname": "node1", - "databases": "*", - "routes": null, - "url": "wss://127.0.0.1:9925" - }, - "componentsRoot": "/Users/hdb/components", - "localStudio": { - "enabled": false - }, - "logging": { - "auditAuthEvents": { - "logFailed": false, - "logSuccessful": false - }, - "auditLog": true, - "auditRetention": "3d", - "file": true, - "level": "error", - "root": "/Users/hdb/log", - "rotation": { - "enabled": false, - "compress": false, - "interval": null, - "maxSize": null, - "path": "/Users/hdb/log" - }, - "stdStreams": false - }, - "mqtt": { - "network": { - "port": 1883, - "securePort": 8883 - }, - "webSocket": true, - "requireAuthentication": true - }, - "operationsApi": { - "network": { - "cors": true, - "corsAccessList": ["*"], - "domainSocket": "/Users/hdb/operations-server", - "port": 9925, - "securePort": null - } - }, - "rootPath": "/Users/hdb", - "storage": { - "writeAsync": false, - "caching": true, - "compression": false, - "noReadAhead": true, - "path": "/Users/hdb/database", - "prefetchWrites": true - }, - "tls": { - "privateKey": "/Users/hdb/keys/privateKey.pem" - } -} -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/custom-functions.md b/versioned_docs/version-4.6/developers/operations-api/custom-functions.md deleted file mode 100644 index 23709148..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/custom-functions.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -title: Custom Functions ---- - -# Custom Functions - -_These operations are deprecated._ - -## Custom Functions Status - -Returns the state of the Custom functions server. This includes whether it is enabled, upon which port it is listening, and where its root project directory is located on the host machine. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `custom_function_status` - -### Body - -```json -{ - "operation": "custom_functions_status" -} -``` - -### Response: 200 - -```json -{ - "is_enabled": true, - "port": 9926, - "directory": "/Users/myuser/hdb/custom_functions" -} -``` - ---- - -## Get Custom Functions - -Returns an array of projects within the Custom Functions root project directory. Each project has details including each of the files in the routes and helpers directories, and the total file count in the static folder. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `get_custom_functions` - -### Body - -```json -{ - "operation": "get_custom_functions" -} -``` - -### Response: 200 - -```json -{ - "dogs": { - "routes": ["examples"], - "helpers": ["example"], - "static": 3 - } -} -``` - ---- - -## Get Custom Function - -Returns the content of the specified file as text. HarperDStudio uses this call to render the file content in its built-in code editor. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `get_custom_function` -- `project` _(required)_ - the name of the project containing the file for which you wish to get content -- `type` _(required)_ - the name of the sub-folder containing the file for which you wish to get content - must be either routes or helpers -- `file` _(required)_ - The name of the file for which you wish to get content - should not include the file extension (which is always .js) - -### Body - -```json -{ - "operation": "get_custom_function", - "project": "dogs", - "type": "helpers", - "file": "example" -} -``` - -### Response: 200 - -```json -{ - "message": "'use strict';\n\nconst https = require('https');\n\nconst authRequest = (options) => {\n return new Promise((resolve, reject) => {\n const req = https.request(options, (res) => {\n res.setEncoding('utf8');\n let responseBody = '';\n\n res.on('data', (chunk) => {\n responseBody += chunk;\n });\n\n res.on('end', () => {\n resolve(JSON.parse(responseBody));\n });\n });\n\n req.on('error', (err) => {\n reject(err);\n });\n\n req.end();\n });\n};\n\nconst customValidation = async (request,logger) => {\n const options = {\n hostname: 'jsonplaceholder.typicode.com',\n port: 443,\n path: '/todos/1',\n method: 'GET',\n headers: { authorization: request.headers.authorization },\n };\n\n const result = await authRequest(options);\n\n /*\n * throw an authentication error based on the response body or statusCode\n */\n if (result.error) {\n const errorString = result.error || 'Sorry, there was an error authenticating your request';\n logger.error(errorString);\n throw new Error(errorString);\n }\n return request;\n};\n\nmodule.exports = customValidation;\n" -} -``` - ---- - -## Set Custom Function - -Updates the content of the specified file. Harper Studio uses this call to save any changes made through its built-in code editor. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `set_custom_function` -- `project` _(required)_ - the name of the project containing the file for which you wish to set content -- `type` _(required)_ - the name of the sub-folder containing the file for which you wish to set content - must be either routes or helpers -- `file` _(required)_ - the name of the file for which you wish to set content - should not include the file extension (which is always .js) -- `function_content` _(required)_ - the content you wish to save into the specified file - -### Body - -```json -{ - "operation": "set_custom_function", - "project": "dogs", - "type": "helpers", - "file": "example", - "function_content": "'use strict';\n\nconst https = require('https');\n\nconst authRequest = (options) => {\n return new Promise((resolve, reject) => {\n const req = https.request(options, (res) => {\n res.setEncoding('utf8');\n let responseBody = '';\n\n res.on('data', (chunk) => {\n responseBody += chunk;\n });\n\n res.on('end', () => {\n resolve(JSON.parse(responseBody));\n });\n });\n\n req.on('error', (err) => {\n reject(err);\n });\n\n req.end();\n });\n};\n\nconst customValidation = async (request,logger) => {\n const options = {\n hostname: 'jsonplaceholder.typicode.com',\n port: 443,\n path: '/todos/1',\n method: 'GET',\n headers: { authorization: request.headers.authorization },\n };\n\n const result = await authRequest(options);\n\n /*\n * throw an authentication error based on the response body or statusCode\n */\n if (result.error) {\n const errorString = result.error || 'Sorry, there was an error authenticating your request';\n logger.error(errorString);\n throw new Error(errorString);\n }\n return request;\n};\n\nmodule.exports = customValidation;\n" -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully updated custom function: example.js" -} -``` - ---- - -## Drop Custom Function - -Deletes the specified file. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `drop_custom_function` -- `project` _(required)_ - the name of the project containing the file you wish to delete -- `type` _(required)_ - the name of the sub-folder containing the file you wish to delete. Must be either routes or helpers -- `file` _(required)_ - the name of the file you wish to delete. Should not include the file extension (which is always .js) - -### Body - -```json -{ - "operation": "drop_custom_function", - "project": "dogs", - "type": "helpers", - "file": "example" -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully deleted custom function: example.js" -} -``` - ---- - -## Add Custom Function Project - -Creates a new project folder in the Custom Functions root project directory. It also inserts into the new directory the contents of our Custom Functions Project template, which is available publicly, here: [https://github.com/HarperDB/harperdb-custom-functions-template](https://github.com/HarperDB/harperdb-custom-functions-template). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `add_custom_function_project` -- `project` _(required)_ - the name of the project you wish to create - -### Body - -```json -{ - "operation": "add_custom_function_project", - "project": "dogs" -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully created custom function project: dogs" -} -``` - ---- - -## Drop Custom Function Project - -Deletes the specified project folder and all of its contents. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `drop_custom_function_project` -- `project` _(required)_ - the name of the project you wish to delete - -### Body - -```json -{ - "operation": "drop_custom_function_project", - "project": "dogs" -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully deleted project: dogs" -} -``` - ---- - -## Package Custom Function Project - -Creates a .tar file of the specified project folder, then reads it into a base64-encoded string and returns an object with the string, the payload and the file. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `package_custom_function_project` -- `project` _(required)_ - the name of the project you wish to package up for deployment -- `skip_node_modules` _(optional)_ - if true, creates option for tar module that will exclude the project's node_modules directory. Must be a boolean. - -### Body - -```json -{ - "operation": "package_custom_function_project", - "project": "dogs", - "skip_node_modules": true -} -``` - -### Response: 200 - -```json -{ - "project": "dogs", - "payload": "LgAAAAAAAAAAAAAAAAAAA...AAAAAAAAAAAAAAAAAAAAAAAAAAAAA==", - "file": "/tmp/d27f1154-5d82-43f0-a5fb-a3018f366081.tar" -} -``` - ---- - -## Deploy Custom Function Project - -Takes the output of package_custom_function_project, decrypts the base64-encoded string, reconstitutes the .tar file of your project folder, and extracts it to the Custom Functions root project directory. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `deploy_custom_function_project` -- `project` _(required)_ - the name of the project you wish to deploy. Must be a string -- `payload` _(required)_ - a base64-encoded string representation of the .tar file. Must be a string - -### Body - -```json -{ - "operation": "deploy_custom_function_project", - "project": "dogs", - "payload": "A very large base64-encoded string represenation of the .tar file" -} -``` - -### Response: 200 - -```json -{ - "message": "Successfully deployed project: dogs" -} -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/databases-and-tables.md b/versioned_docs/version-4.6/developers/operations-api/databases-and-tables.md deleted file mode 100644 index 7c17fb4d..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/databases-and-tables.md +++ /dev/null @@ -1,388 +0,0 @@ ---- -title: Databases and Tables ---- - -# Databases and Tables - -## Describe All - -Returns the definitions of all databases and tables within the database. Record counts about 5000 records are estimated, as determining the exact count can be expensive. When the record count is estimated, this is indicated by the inclusion of a confidence interval of `estimated_record_range`. If you need the exact count, you can include an `"exact_count": true` in the operation, but be aware that this requires a full table scan (may be expensive). - -- `operation` _(required)_ - must always be `describe_all` - -### Body - -```json -{ - "operation": "describe_all" -} -``` - -### Response: 200 - -```json -{ - "dev": { - "dog": { - "schema": "dev", - "name": "dog", - "hash_attribute": "id", - "audit": true, - "schema_defined": false, - "attributes": [ - { - "attribute": "id", - "indexed": true, - "is_primary_key": true - }, - { - "attribute": "__createdtime__", - "indexed": true - }, - { - "attribute": "__updatedtime__", - "indexed": true - }, - { - "attribute": "type", - "indexed": true - } - ], - "clustering_stream_name": "dd9e90c2689151ab812e0f2d98816bff", - "record_count": 4000, - "estimated_record_range": [3976, 4033], - "last_updated_record": 1697658683698.4504 - } - } -} -``` - ---- - -## Describe database - -Returns the definitions of all tables within the specified database. - -- `operation` _(required)_ - must always be `describe_database` -- `database` _(optional)_ - database where the table you wish to describe lives. The default is `data` - -### Body - -```json -{ - "operation": "describe_database", - "database": "dev" -} -``` - -### Response: 200 - -```json -{ - "dog": { - "schema": "dev", - "name": "dog", - "hash_attribute": "id", - "audit": true, - "schema_defined": false, - "attributes": [ - { - "attribute": "id", - "indexed": true, - "is_primary_key": true - }, - { - "attribute": "__createdtime__", - "indexed": true - }, - { - "attribute": "__updatedtime__", - "indexed": true - }, - { - "attribute": "type", - "indexed": true - } - ], - "clustering_stream_name": "dd9e90c2689151ab812e0f2d98816bff", - "record_count": 4000, - "estimated_record_range": [3976, 4033], - "last_updated_record": 1697658683698.4504 - } -} -``` - ---- - -## Describe Table - -Returns the definition of the specified table. - -- `operation` _(required)_ - must always be `describe_table` -- `table` _(required)_ - table you wish to describe -- `database` _(optional)_ - database where the table you wish to describe lives. The default is `data` - -### Body - -```json -{ - "operation": "describe_table", - "table": "dog" -} -``` - -### Response: 200 - -```json -{ - "schema": "dev", - "name": "dog", - "hash_attribute": "id", - "audit": true, - "schema_defined": false, - "attributes": [ - { - "attribute": "id", - "indexed": true, - "is_primary_key": true - }, - { - "attribute": "__createdtime__", - "indexed": true - }, - { - "attribute": "__updatedtime__", - "indexed": true - }, - { - "attribute": "type", - "indexed": true - } - ], - "clustering_stream_name": "dd9e90c2689151ab812e0f2d98816bff", - "record_count": 4000, - "estimated_record_range": [3976, 4033], - "last_updated_record": 1697658683698.4504 -} -``` - ---- - -## Create database - -Create a new database. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `create_database` -- `database` _(optional)_ - name of the database you are creating. The default is `data` - -### Body - -```json -{ - "operation": "create_database", - "database": "dev" -} -``` - -### Response: 200 - -```json -{ - "message": "database 'dev' successfully created" -} -``` - ---- - -## Drop database - -Drop an existing database. NOTE: Dropping a database will delete all tables and all of their records in that database. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - this should always be `drop_database` -- `database` _(required)_ - name of the database you are dropping -- `replicated` _(optional)_ - if true, Harper will replicate the component to all nodes in the cluster. Must be a boolean. - -### Body - -```json -{ - "operation": "drop_database", - "database": "dev" -} -``` - -### Response: 200 - -```json -{ - "message": "successfully deleted 'dev'" -} -``` - ---- - -## Create Table - -Create a new table within a database. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `create_table` -- `database` _(optional)_ - name of the database where you want your table to live. If the database does not exist, it will be created. If the `database` property is not provided it will default to `data`. -- `table` _(required)_ - name of the table you are creating -- `primary_key` _(required)_ - primary key for the table -- `attributes` _(optional)_ - an array of attributes that specifies the schema for the table, that is the set of attributes for the table. When attributes are supplied the table will not be considered a "dynamic schema" table, and attributes will not be auto-added when records with new properties are inserted. Each attribute is specified as: - - `name` _(required)_ - the name of the attribute - - `indexed` _(optional)_ - indicates if the attribute should be indexed - - `type` _(optional)_ - specifies the data type of the attribute (can be String, Int, Float, Date, ID, Any) -- `expiration` _(optional)_ - specifies the time-to-live or expiration of records in the table before they are evicted (records are not evicted on any timer if not specified). This is specified in seconds. - -### Body - -```json -{ - "operation": "create_table", - "database": "dev", - "table": "dog", - "primary_key": "id" -} -``` - -### Response: 200 - -```json -{ - "message": "table 'dev.dog' successfully created." -} -``` - ---- - -## Drop Table - -Drop an existing database table. NOTE: Dropping a table will delete all associated records in that table. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - this should always be `drop_table` -- `database` _(optional)_ - database where the table you are dropping lives. The default is `data` -- `table` _(required)_ - name of the table you are dropping -- `replicated` _(optional)_ - if true, Harper will replicate the component to all nodes in the cluster. Must be a boolean. - -### Body - -```json -{ - "operation": "drop_table", - "database": "dev", - "table": "dog" -} -``` - -### Response: 200 - -```json -{ - "message": "successfully deleted table 'dev.dog'" -} -``` - ---- - -## Create Attribute - -Create a new attribute within the specified table. **The create_attribute operation can be used for admins wishing to pre-define database values for setting role-based permissions or for any other reason.** - -_Note: Harper will automatically create new attributes on insert and update if they do not already exist within the database._ - -- `operation` _(required)_ - must always be `create_attribute` -- `database` _(optional)_ - name of the database of the table you want to add your attribute. The default is `data` -- `table` _(required)_ - name of the table where you want to add your attribute to live -- `attribute` _(required)_ - name for the attribute - -### Body - -```json -{ - "operation": "create_attribute", - "database": "dev", - "table": "dog", - "attribute": "is_adorable" -} -``` - -### Response: 200 - -```json -{ - "message": "inserted 1 of 1 records", - "skipped_hashes": [], - "inserted_hashes": ["383c0bef-5781-4e1c-b5c8-987459ad0831"] -} -``` - ---- - -## Drop Attribute - -Drop an existing attribute from the specified table. NOTE: Dropping an attribute will delete all associated attribute values in that table. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - this should always be `drop_attribute` -- `database` _(optional)_ - database where the table you are dropping lives. The default is `data` -- `table` _(required)_ - table where the attribute you are dropping lives -- `attribute` _(required)_ - attribute that you intend to drop - -### Body - -```json -{ - "operation": "drop_attribute", - "database": "dev", - "table": "dog", - "attribute": "is_adorable" -} -``` - -### Response: 200 - -```json -{ - "message": "successfully deleted attribute 'is_adorable'" -} -``` - ---- - -## Get Backup - -This will return a snapshot of the requested database. This provides a means for backing up the database through the operations API. The response will be the raw database file (in binary format), which can later be restored as a database file by copying into the appropriate hdb/databases directory (with Harper not running). The returned file is a snapshot of the database at the moment in time that the get_backup operation begins. This also supports backing up individual tables in a database. However, this is a more expensive operation than backing up a database in whole, and will lose any transactional atomicity between writes across tables, so generally it is recommended that you backup the entire database. - -It is important to note that trying to copy a database file that is in use (Harper actively running and writing to the file) using standard file copying tools is not safe (the copied file will likely be corrupt), which is why using this snapshot operation is recommended for backups (volume snapshots are also a good way to backup Harper databases). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - this should always be `get_backup` -- `database` _(required)_ - this is the database that will be snapshotted and returned -- `table` _(optional)_ - this will specify a specific table to backup -- `tables` _(optional)_ - this will specify a specific set of tables to backup - -### Body - -```json -{ - "operation": "get_backup", - "database": "dev" -} -``` - -### Response: 200 - -``` -The database in raw binary data format -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/index.md b/versioned_docs/version-4.6/developers/operations-api/index.md deleted file mode 100644 index ad44d9de..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/index.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Operations API ---- - -# Operations API - -The operations API provides a full set of capabilities for configuring, deploying, administering, and controlling Harper. To send operations to the operations API, you send a POST request to the operations API endpoint, which [defaults to port 9925](../deployments/configuration#operationsapi), on the root path, where the body is the operations object. These requests need to authenticated, which can be done with [basic auth](./security#basic-auth) or [JWT authentication](./security#jwt-auth). For example, a request to create a table would be performed as: - -```http -POST https://my-harperdb-server:9925/ -Authorization: Basic YourBase64EncodedInstanceUser:Pass -Content-Type: application/json - -{ - "operation": "create_table", - "table": "my-table" -} -``` - -The operations API reference is available below and categorized by topic: - -- [Quick Start Examples](operations-api/quickstart-examples) -- [Databases and Tables](operations-api/databases-and-tables) -- [NoSQL Operations](operations-api/nosql-operations) -- [Bulk Operations](operations-api/bulk-operations) -- [Users and Roles](operations-api/users-and-roles) -- [Clustering](operations-api/clustering) -- [Clustering with NATS](operations-api/clustering-nats) -- [Components](operations-api/components) -- [Registration](operations-api/registration) -- [Jobs](operations-api/jobs) -- [Logs](operations-api/logs) -- [System Operations](operations-api/system-operations) -- [Configuration](operations-api/configuration) -- [Certificate Management](operations-api/certificate-management) -- [Token Authentication](operations-api/token-authentication) -- [SQL Operations](operations-api/sql-operations) -- [Advanced JSON SQL Examples](operations-api/advanced-json-sql-examples) -- [Analytics](operations-api/analytics) - -• [Past Release API Documentation](https://olddocs.harperdb.io) - -## More Examples - -Here is an example of using `curl` to make an operations API request: - -```bash -curl --location --request POST 'https://instance-subdomain.harperdbcloud.com' \ ---header 'Authorization: Basic YourBase64EncodedInstanceUser:Pass' \ ---header 'Content-Type: application/json' \ ---data-raw '{ -"operation": "create_schema", -"schema": "dev" -}' -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/jobs.md b/versioned_docs/version-4.6/developers/operations-api/jobs.md deleted file mode 100644 index cf71fa00..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/jobs.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Jobs ---- - -# Jobs - -## Get Job - -Returns job status, metrics, and messages for the specified job ID. - -- `operation` _(required)_ - must always be `get_job` -- `id` _(required)_ - the id of the job you wish to view - -### Body - -```json -{ - "operation": "get_job", - "id": "4a982782-929a-4507-8794-26dae1132def" -} -``` - -### Response: 200 - -```json -[ - { - "__createdtime__": 1611615798782, - "__updatedtime__": 1611615801207, - "created_datetime": 1611615798774, - "end_datetime": 1611615801206, - "id": "4a982782-929a-4507-8794-26dae1132def", - "job_body": null, - "message": "successfully loaded 350 of 350 records", - "start_datetime": 1611615798805, - "status": "COMPLETE", - "type": "csv_url_load", - "user": "HDB_ADMIN", - "start_datetime_converted": "2021-01-25T23:03:18.805Z", - "end_datetime_converted": "2021-01-25T23:03:21.206Z" - } -] -``` - ---- - -## Search Jobs By Start Date - -Returns a list of job statuses, metrics, and messages for all jobs executed within the specified time window. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `search_jobs_by_start_date` -- `from_date` _(required)_ - the date you wish to start the search -- `to_date` _(required)_ - the date you wish to end the search - -### Body - -```json -{ - "operation": "search_jobs_by_start_date", - "from_date": "2021-01-25T22:05:27.464+0000", - "to_date": "2021-01-25T23:05:27.464+0000" -} -``` - -### Response: 200 - -```json -[ - { - "id": "942dd5cb-2368-48a5-8a10-8770ff7eb1f1", - "user": "HDB_ADMIN", - "type": "csv_url_load", - "status": "COMPLETE", - "start_datetime": 1611613284781, - "end_datetime": 1611613287204, - "job_body": null, - "message": "successfully loaded 350 of 350 records", - "created_datetime": 1611613284764, - "__createdtime__": 1611613284767, - "__updatedtime__": 1611613287207, - "start_datetime_converted": "2021-01-25T22:21:24.781Z", - "end_datetime_converted": "2021-01-25T22:21:27.204Z" - } -] -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/logs.md b/versioned_docs/version-4.6/developers/operations-api/logs.md deleted file mode 100644 index 52e52740..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/logs.md +++ /dev/null @@ -1,732 +0,0 @@ ---- -title: Logs ---- - -# Logs - -## Read Harper Log - -Returns log outputs from the primary Harper log based on the provided search criteria. [Read more about Harper logging here](../../administration/logging/standard-logging#read-logs-via-the-api). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `read_Log` -- `start` _(optional)_ - result to start with. Default is 0, the first log in `hdb.log`. Must be a number -- `limit` _(optional)_ - number of results returned. Default behavior is 1000. Must be a number -- `level` _(optional)_ - error level to filter on. Default behavior is all levels. Must be `notify`, `error`, `warn`, `info`, `debug` or `trace` -- `from` _(optional)_ - date to begin showing log results. Must be `YYYY-MM-DD` or `YYYY-MM-DD hh:mm:ss`. Default is first log in `hdb.log` -- `until` _(optional)_ - date to end showing log results. Must be `YYYY-MM-DD` or `YYYY-MM-DD hh:mm:ss`. Default is last log in `hdb.log` -- `order` _(optional)_ - order to display logs desc or asc by timestamp. By default, will maintain `hdb.log` order - -### Body - -```json -{ - "operation": "read_log", - "start": 0, - "limit": 1000, - "level": "error", - "from": "2021-01-25T22:05:27.464+0000", - "until": "2021-01-25T23:05:27.464+0000", - "order": "desc" -} -``` - -### Response: 200 - -```json -[ - { - "level": "notify", - "message": "Connected to cluster server.", - "timestamp": "2021-01-25T23:03:20.710Z", - "thread": "main/0", - "tags": [] - }, - { - "level": "warn", - "message": "Login failed", - "timestamp": "2021-01-25T22:24:45.113Z", - "thread": "http/9", - "tags": [] - }, - { - "level": "error", - "message": "unknown attribute 'name and breed'", - "timestamp": "2021-01-25T22:23:24.167Z", - "thread": "http/9", - "tags": [] - } -] -``` - ---- - -## Read Transaction Log - -Returns all transactions logged for the specified database table. You may filter your results with the optional from, to, and limit fields. [Read more about Harper transaction logs here](./logs#read-transaction-log). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `read_transaction_log` -- `schema` _(required)_ - schema under which the transaction log resides -- `table` _(required)_ - table under which the transaction log resides -- `from` _(optional)_ - time format must be millisecond-based epoch in UTC -- `to` _(optional)_ - time format must be millisecond-based epoch in UTC -- `limit` _(optional)_ - max number of logs you want to receive. Must be a number - -### Body - -```json -{ - "operation": "read_transaction_log", - "schema": "dev", - "table": "dog", - "from": 1560249020865, - "to": 1660585656639, - "limit": 10 -} -``` - -### Response: 200 - -```json -[ - { - "operation": "insert", - "user": "admin", - "timestamp": 1660165619736, - "records": [ - { - "id": 1, - "dog_name": "Penny", - "owner_name": "Kyle", - "breed_id": 154, - "age": 7, - "weight_lbs": 38, - "__updatedtime__": 1660165619688, - "__createdtime__": 1660165619688 - } - ] - }, - { - "operation": "insert", - "user": "admin", - "timestamp": 1660165619813, - "records": [ - { - "id": 2, - "dog_name": "Harper", - "owner_name": "Stephen", - "breed_id": 346, - "age": 7, - "weight_lbs": 55, - "adorable": true, - "__updatedtime__": 1660165619797, - "__createdtime__": 1660165619797 - }, - { - "id": 3, - "dog_name": "Alby", - "owner_name": "Kaylan", - "breed_id": 348, - "age": 7, - "weight_lbs": 84, - "adorable": true, - "__updatedtime__": 1660165619797, - "__createdtime__": 1660165619797 - }, - { - "id": 4, - "dog_name": "Billy", - "owner_name": "Zach", - "breed_id": 347, - "age": 6, - "weight_lbs": 60, - "adorable": true, - "__updatedtime__": 1660165619797, - "__createdtime__": 1660165619797 - }, - { - "id": 5, - "dog_name": "Rose Merry", - "owner_name": "Zach", - "breed_id": 348, - "age": 8, - "weight_lbs": 15, - "adorable": true, - "__updatedtime__": 1660165619797, - "__createdtime__": 1660165619797 - }, - { - "id": 6, - "dog_name": "Kato", - "owner_name": "Kyle", - "breed_id": 351, - "age": 6, - "weight_lbs": 32, - "adorable": true, - "__updatedtime__": 1660165619797, - "__createdtime__": 1660165619797 - }, - { - "id": 7, - "dog_name": "Simon", - "owner_name": "Fred", - "breed_id": 349, - "age": 3, - "weight_lbs": 35, - "adorable": true, - "__updatedtime__": 1660165619797, - "__createdtime__": 1660165619797 - }, - { - "id": 8, - "dog_name": "Gemma", - "owner_name": "Stephen", - "breed_id": 350, - "age": 5, - "weight_lbs": 55, - "adorable": true, - "__updatedtime__": 1660165619797, - "__createdtime__": 1660165619797 - }, - { - "id": 9, - "dog_name": "Yeti", - "owner_name": "Jaxon", - "breed_id": 200, - "age": 5, - "weight_lbs": 55, - "adorable": true, - "__updatedtime__": 1660165619797, - "__createdtime__": 1660165619797 - }, - { - "id": 10, - "dog_name": "Monkey", - "owner_name": "Aron", - "breed_id": 271, - "age": 7, - "weight_lbs": 35, - "adorable": true, - "__updatedtime__": 1660165619797, - "__createdtime__": 1660165619797 - }, - { - "id": 11, - "dog_name": "Bode", - "owner_name": "Margo", - "breed_id": 104, - "age": 8, - "weight_lbs": 75, - "adorable": true, - "__updatedtime__": 1660165619797, - "__createdtime__": 1660165619797 - }, - { - "id": 12, - "dog_name": "Tucker", - "owner_name": "David", - "breed_id": 346, - "age": 2, - "weight_lbs": 60, - "adorable": true, - "__updatedtime__": 1660165619798, - "__createdtime__": 1660165619798 - }, - { - "id": 13, - "dog_name": "Jagger", - "owner_name": "Margo", - "breed_id": 271, - "age": 7, - "weight_lbs": 35, - "adorable": true, - "__updatedtime__": 1660165619798, - "__createdtime__": 1660165619798 - } - ] - }, - { - "operation": "update", - "user": "admin", - "timestamp": 1660165620040, - "records": [ - { - "id": 1, - "dog_name": "Penny B", - "__updatedtime__": 1660165620036 - } - ] - } -] -``` - ---- - -## Delete Transaction Logs Before - -Deletes transaction log data for the specified database table that is older than the specified timestamp. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `delete_transaction_log_before` -- `schema` _(required)_ - schema under which the transaction log resides. Must be a string -- `table` _(required)_ - table under which the transaction log resides. Must be a string -- `timestamp` _(required)_ - records older than this date will be deleted. Format is millisecond-based epoch in UTC - -### Body - -```json -{ - "operation": "delete_transaction_logs_before", - "schema": "dev", - "table": "dog", - "timestamp": 1598290282817 -} -``` - -### Response: 200 - -```json -{ - "message": "Starting job with id 26a6d3a6-6d77-40f9-bee7-8d6ef479a126" -} -``` - ---- - -## Read Audit Log - -AuditLog must be enabled in the Harper configuration file to make this request. Returns a verbose history of all transactions logged for the specified database table, including original data records. You may filter your results with the optional search_type and search_values fields. [Read more about Harper transaction logs here.](../../administration/logging/transaction-logging#read_transaction_log) - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `read_audit_log` -- `schema` _(required)_ - schema under which the transaction log resides -- `table` _(required)_ - table under which the transaction log resides -- `search_type` _(optional)_ - possibilities are `hash_value`, `timestamp` and `username` -- `search_values` _(optional)_ - an array of string or numbers relating to search_type - -### Body - -```json -{ - "operation": "read_audit_log", - "schema": "dev", - "table": "dog" -} -``` - -### Response: 200 - -```json -[ - { - "operation": "insert", - "user_name": "admin", - "timestamp": 1660585635882.288, - "hash_values": [318], - "records": [ - { - "id": 318, - "dog_name": "Polliwog", - "__updatedtime__": 1660585635876, - "__createdtime__": 1660585635876 - } - ] - }, - { - "operation": "insert", - "user_name": "admin", - "timestamp": 1660585716133.01, - "hash_values": [444], - "records": [ - { - "id": 444, - "dog_name": "Davis", - "__updatedtime__": 1660585716128, - "__createdtime__": 1660585716128 - } - ] - }, - { - "operation": "update", - "user_name": "admin", - "timestamp": 1660585740558.415, - "hash_values": [444], - "records": [ - { - "id": 444, - "fur_type": "coarse", - "__updatedtime__": 1660585740556 - } - ], - "original_records": [ - { - "id": 444, - "dog_name": "Davis", - "__updatedtime__": 1660585716128, - "__createdtime__": 1660585716128 - } - ] - }, - { - "operation": "delete", - "user_name": "admin", - "timestamp": 1660585759710.56, - "hash_values": [444], - "original_records": [ - { - "id": 444, - "dog_name": "Davis", - "__updatedtime__": 1660585740556, - "__createdtime__": 1660585716128, - "fur_type": "coarse" - } - ] - } -] -``` - ---- - -## Read Audit Log by timestamp - -AuditLog must be enabled in the Harper configuration file to make this request. Returns the transactions logged for the specified database table between the specified time window. [Read more about Harper transaction logs here](./logs#read-transaction-log). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `read_audit_log` -- `schema` _(required)_ - schema under which the transaction log resides -- `table` _(required)_ - table under which the transaction log resides -- `search_type` _(optional)_ - timestamp -- `search_values` _(optional)_ - an array containing a maximum of two values \[`from_timestamp`, `to_timestamp`] defining the range of transactions you would like to view. - - Timestamp format is millisecond-based epoch in UTC - - If no items are supplied then all transactions are returned - - If only one entry is supplied then all transactions after the supplied timestamp will be returned - -### Body - -```json -{ - "operation": "read_audit_log", - "schema": "dev", - "table": "dog", - "search_type": "timestamp", - "search_values": [1660585740558, 1660585759710.56] -} -``` - -### Response: 200 - -```json -[ - { - "operation": "insert", - "user_name": "admin", - "timestamp": 1660585635882.288, - "hash_values": [318], - "records": [ - { - "id": 318, - "dog_name": "Polliwog", - "__updatedtime__": 1660585635876, - "__createdtime__": 1660585635876 - } - ] - }, - { - "operation": "insert", - "user_name": "admin", - "timestamp": 1660585716133.01, - "hash_values": [444], - "records": [ - { - "id": 444, - "dog_name": "Davis", - "__updatedtime__": 1660585716128, - "__createdtime__": 1660585716128 - } - ] - }, - { - "operation": "update", - "user_name": "admin", - "timestamp": 1660585740558.415, - "hash_values": [444], - "records": [ - { - "id": 444, - "fur_type": "coarse", - "__updatedtime__": 1660585740556 - } - ], - "original_records": [ - { - "id": 444, - "dog_name": "Davis", - "__updatedtime__": 1660585716128, - "__createdtime__": 1660585716128 - } - ] - }, - { - "operation": "delete", - "user_name": "admin", - "timestamp": 1660585759710.56, - "hash_values": [444], - "original_records": [ - { - "id": 444, - "dog_name": "Davis", - "__updatedtime__": 1660585740556, - "__createdtime__": 1660585716128, - "fur_type": "coarse" - } - ] - }, - { - "operation": "update", - "user_name": "admin", - "timestamp": 1660586298457.224, - "hash_values": [318], - "records": [ - { - "id": 318, - "fur_type": "super fluffy", - "__updatedtime__": 1660586298455 - } - ], - "original_records": [ - { - "id": 318, - "dog_name": "Polliwog", - "__updatedtime__": 1660585635876, - "__createdtime__": 1660585635876 - } - ] - } -] -``` - ---- - -## Read Audit Log by username - -AuditLog must be enabled in the Harper configuration file to make this request. Returns the transactions logged for the specified database table which were committed by the specified user. [Read more about Harper transaction logs here](../../administration/logging/transaction-logging#read_transaction_log). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `read_audit_log` -- `schema` _(required)_ - schema under which the transaction log resides -- `table` _(required)_ - table under which the transaction log resides -- `search_type` _(optional)_ - username -- `search_values` _(optional)_ - the Harper user for whom you would like to view transactions - -### Body - -```json -{ - "operation": "read_audit_log", - "schema": "dev", - "table": "dog", - "search_type": "username", - "search_values": ["admin"] -} -``` - -### Response: 200 - -```json -{ - "admin": [ - { - "operation": "insert", - "user_name": "admin", - "timestamp": 1660585635882.288, - "hash_values": [318], - "records": [ - { - "id": 318, - "dog_name": "Polliwog", - "__updatedtime__": 1660585635876, - "__createdtime__": 1660585635876 - } - ] - }, - { - "operation": "insert", - "user_name": "admin", - "timestamp": 1660585716133.01, - "hash_values": [444], - "records": [ - { - "id": 444, - "dog_name": "Davis", - "__updatedtime__": 1660585716128, - "__createdtime__": 1660585716128 - } - ] - }, - { - "operation": "update", - "user_name": "admin", - "timestamp": 1660585740558.415, - "hash_values": [444], - "records": [ - { - "id": 444, - "fur_type": "coarse", - "__updatedtime__": 1660585740556 - } - ], - "original_records": [ - { - "id": 444, - "dog_name": "Davis", - "__updatedtime__": 1660585716128, - "__createdtime__": 1660585716128 - } - ] - }, - { - "operation": "delete", - "user_name": "admin", - "timestamp": 1660585759710.56, - "hash_values": [444], - "original_records": [ - { - "id": 444, - "dog_name": "Davis", - "__updatedtime__": 1660585740556, - "__createdtime__": 1660585716128, - "fur_type": "coarse" - } - ] - }, - { - "operation": "update", - "user_name": "admin", - "timestamp": 1660586298457.224, - "hash_values": [318], - "records": [ - { - "id": 318, - "fur_type": "super fluffy", - "__updatedtime__": 1660586298455 - } - ], - "original_records": [ - { - "id": 318, - "dog_name": "Polliwog", - "__updatedtime__": 1660585635876, - "__createdtime__": 1660585635876 - } - ] - } - ] -} -``` - ---- - -## Read Audit Log by hash_value - -AuditLog must be enabled in the Harper configuration file to make this request. Returns the transactions logged for the specified database table which were committed to the specified hash value(s). [Read more about Harper transaction logs here](../../administration/logging/transaction-logging#read_transaction_log). - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `read_audit_log` -- `schema` _(required)_ - schema under which the transaction log resides -- `table` _(required)_ - table under which the transaction log resides -- `search_type` _(optional)_ - hash_value -- `search_values` _(optional)_ - an array of hash_attributes for which you wish to see transaction logs - -### Body - -```json -{ - "operation": "read_audit_log", - "schema": "dev", - "table": "dog", - "search_type": "hash_value", - "search_values": [318] -} -``` - -### Response: 200 - -```json -{ - "318": [ - { - "operation": "insert", - "user_name": "admin", - "timestamp": 1660585635882.288, - "records": [ - { - "id": 318, - "dog_name": "Polliwog", - "__updatedtime__": 1660585635876, - "__createdtime__": 1660585635876 - } - ] - }, - { - "operation": "update", - "user_name": "admin", - "timestamp": 1660586298457.224, - "records": [ - { - "id": 318, - "fur_type": "super fluffy", - "__updatedtime__": 1660586298455 - } - ], - "original_records": [ - { - "id": 318, - "dog_name": "Polliwog", - "__updatedtime__": 1660585635876, - "__createdtime__": 1660585635876 - } - ] - } - ] -} -``` - ---- - -## Delete Audit Logs Before - -AuditLog must be enabled in the Harper configuration file to make this request. Deletes audit log data for the specified database table that is older than the specified timestamp. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `delete_audit_logs_before` -- `schema` _(required)_ - schema under which the transaction log resides. Must be a string -- `table` _(required)_ - table under which the transaction log resides. Must be a string -- `timestamp` _(required)_ - records older than this date will be deleted. Format is millisecond-based epoch in UTC - -### Body - -```json -{ - "operation": "delete_audit_logs_before", - "schema": "dev", - "table": "dog", - "timestamp": 1660585759710.56 -} -``` - -### Response: 200 - -```json -{ - "message": "Starting job with id 7479e5f8-a86e-4fc9-add7-749493bc100f" -} -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/nosql-operations.md b/versioned_docs/version-4.6/developers/operations-api/nosql-operations.md deleted file mode 100644 index e9272508..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/nosql-operations.md +++ /dev/null @@ -1,389 +0,0 @@ ---- -title: NoSQL Operations ---- - -# NoSQL Operations - -## Insert - -Adds one or more rows of data to a database table. Primary keys of the inserted JSON record may be supplied on insert. If a primary key is not provided, then a GUID or incremented number (depending on type) will be generated for each record. - -- `operation` _(required)_ - must always be `insert` -- `database` _(optional)_ - database where the table you are inserting records into lives. The default is `data` -- `table` _(required)_ - table where you want to insert records -- `records` _(required)_ - array of one or more records for insert - -### Body - -```json -{ - "operation": "insert", - "database": "dev", - "table": "dog", - "records": [ - { - "id": 8, - "dog_name": "Harper", - "breed_id": 346, - "age": 7 - }, - { - "id": 9, - "dog_name": "Penny", - "breed_id": 154, - "age": 7 - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "inserted 2 of 2 records", - "inserted_hashes": [8, 9], - "skipped_hashes": [] -} -``` - ---- - -## Update - -Changes the values of specified attributes in one or more rows in a database table as identified by the primary key. NOTE: Primary key of the updated JSON record(s) MUST be supplied on update. - -- `operation` _(required)_ - must always be `update` -- `database` _(optional)_ - database of the table you are updating records in. The default is `data` -- `table` _(required)_ - table where you want to update records -- `records` _(required)_ - array of one or more records for update - -### Body - -```json -{ - "operation": "update", - "database": "dev", - "table": "dog", - "records": [ - { - "id": 1, - "weight_lbs": 55 - }, - { - "id": 2, - "owner": "Kyle B", - "weight_lbs": 35 - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "updated 2 of 2 records", - "update_hashes": [1, 3], - "skipped_hashes": [] -} -``` - ---- - -## Upsert - -Changes the values of specified attributes for rows with matching primary keys that exist in the table. Adds rows to the database table for primary keys that do not exist or are not provided. - -- `operation` _(required)_ - must always be `upsert` -- `database` _(optional)_ - database of the table you are updating records in. The default is `data` -- `table` _(required)_ - table where you want to update records -- `records` _(required)_ - array of one or more records for update - -### Body - -```json -{ - "operation": "upsert", - "database": "dev", - "table": "dog", - "records": [ - { - "id": 8, - "weight_lbs": 155 - }, - { - "name": "Bill", - "breed": "Pit Bull", - "id": 10, - "Age": 11, - "weight_lbs": 155 - }, - { - "name": "Harper", - "breed": "Mutt", - "age": 5, - "weight_lbs": 155 - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "upserted 3 of 3 records", - "upserted_hashes": [8, 10, "ea06fc8e-717b-4c6c-b69d-b29014054ab7"] -} -``` - ---- - -## Delete - -Removes one or more rows of data from a specified table. - -- `operation` _(required)_ - must always be `delete` -- `database` _(optional)_ - database where the table you are deleting records lives. The default is `data` -- `table` _(required)_ - table where you want to deleting records -- `ids` _(required)_ - array of one or more primary key values, which identifies records to delete - -### Body - -```json -{ - "operation": "delete", - "database": "dev", - "table": "dog", - "ids": [1, 2] -} -``` - -### Response: 200 - -```json -{ - "message": "2 of 2 records successfully deleted", - "deleted_hashes": [1, 2], - "skipped_hashes": [] -} -``` - ---- - -## Search By ID - -Returns data from a table for one or more primary keys. - -- `operation` _(required)_ - must always be `search_by_id` -- `database` _(optional)_ - database where the table you are searching lives. The default is `data` -- `table` _(required)_ - table you wish to search -- `ids` _(required)_ - array of primary keys to retrieve -- `get_attributes` _(required)_ - define which attributes you want returned. Use `['*']` to return all attributes - -### Body - -```json -{ - "operation": "search_by_id", - "database": "dev", - "table": "dog", - "ids": [1, 2], - "get_attributes": ["dog_name", "breed_id"] -} -``` - -### Response: 200 - -```json -[ - { - "dog_name": "Penny", - "breed_id": 154 - }, - { - "dog_name": "Harper", - "breed_id": 346 - } -] -``` - ---- - -## Search By Value - -Returns data from a table for a matching value. - -- `operation` _(required)_ - must always be `search_by_value` -- `database` _(optional)_ - database where the table you are searching lives. The default is `data` -- `table` _(required)_ - table you wish to search -- `attribute` _(required)_ - attribute you wish to search can be any attribute -- `search_attribute` - deprecated in favor of `attribute` -- `value` _(required)_ - value you wish to search - wild cards are allowed -- `search_value` - deprecated in favor of `value` -- `get_attributes` _(required)_ - define which attributes you want returned. Use `['*']` to return all attributes - -### Body - -```json -{ - "operation": "search_by_value", - "database": "dev", - "table": "dog", - "attribute": "owner_name", - "value": "Ky*", - "get_attributes": ["id", "dog_name"] -} -``` - -### Response: 200 - -```json -[ - { - "dog_name": "Penny" - }, - { - "dog_name": "Kato" - } -] -``` - ---- - -## Search By Conditions - -Returns data from a table for one or more matching conditions. This supports grouping of conditions to indicate order of operations as well. - -- `operation` _(required)_ - must always be `search_by_conditions` -- `database` _(optional)_ - database where the table you are searching lives. The default is `data` -- `table` _(required)_ - table you wish to search -- `operator` _(optional)_ - the operator used between each condition - `and`, `or`. The default is `and` -- `offset` _(optional)_ - the number of records that the query results will skip. The default is `0` -- `limit` _(optional)_ - the number of records that the query results will include. The default is `null`, resulting in no limit -- `sort` _optional_ - This is an object that indicates the sort order. It has the following properties: - - `attribute` _(required)_ - The attribute to sort by - - `descending` _(optional)_ - If true, will sort in descending order (defaults to ascending order) - - `next` _(optional)_ - This can define the next sort object that will be used to break ties for sorting when there are multiple records with the same value for the first attribute (follows the same structure as `sort`). -- `get_attributes` _(required)_ - define which attributes you want returned. Use `['*']` to return all attributes -- `conditions` _(required)_ - the array of conditions objects, specified below, to filter by. Must include one or more object in the array that are a condition or a grouped set of conditions. A condition has the following properties: - - `attribute` _(required)_ - the attribute you wish to search, can be any attribute. - - `search_attribute` - deprecated in favor of `attribute` - - `comparator` _(required)_ - the type of search to perform - `equals`, `contains`, `starts_with`, `ends_with`, `greater_than`, `greater_than_equal`, `less_than`, `less_than_equal`, `between` - - `search_type` - deprecated in favor of `comparator` - - `value` _(required)_ - case-sensitive value you wish to search. If the `comparator` is `between` then use an array of two values to search between - - `search_value` - deprecated in favor of `value` - Or a set of grouped conditions has the following properties: - - `operator` _(optional)_ - the operator used between each condition - `and`, `or`. The default is `and` - - `conditions` _(required)_ - the array of conditions objects as described above. - -### Body - -```json -{ - "operation": "search_by_conditions", - "database": "dev", - "table": "dog", - "operator": "and", - "offset": 0, - "limit": 10, - "sort": { - "attribute": "id", - "next": { - "attribute": "age", - "descending": true - } - }, - "get_attributes": ["*"], - "conditions": [ - { - "attribute": "age", - "comparator": "between", - "value": [5, 8] - }, - { - "attribute": "weight_lbs", - "comparator": "greater_than", - "value": 40 - }, - { - "operator": "or", - "conditions": [ - { - "attribute": "adorable", - "comparator": "equals", - "value": true - }, - { - "attribute": "lovable", - "comparator": "equals", - "value": true - } - ] - } - ] -} -``` - -### Response: 200 - -```json -[ - { - "__createdtime__": 1620227719791, - "__updatedtime__": 1620227719791, - "adorable": true, - "age": 7, - "breed_id": 346, - "dog_name": "Harper", - "id": 2, - "owner_name": "Stephen", - "weight_lbs": 55 - }, - { - "__createdtime__": 1620227719792, - "__updatedtime__": 1620227719792, - "adorable": true, - "age": 7, - "breed_id": 348, - "dog_name": "Alby", - "id": 3, - "owner_name": "Kaylan", - "weight_lbs": 84 - }, - { - "__createdtime__": 1620227719792, - "__updatedtime__": 1620227719792, - "adorable": true, - "age": 6, - "breed_id": 347, - "dog_name": "Billy", - "id": 4, - "owner_name": "Zach", - "weight_lbs": 60 - }, - { - "__createdtime__": 1620227719792, - "__updatedtime__": 1620227719792, - "adorable": true, - "age": 5, - "breed_id": 250, - "dog_name": "Gemma", - "id": 8, - "owner_name": "Stephen", - "weight_lbs": 55 - }, - { - "__createdtime__": 1620227719792, - "__updatedtime__": 1620227719792, - "adorable": true, - "age": 8, - "breed_id": 104, - "dog_name": "Bode", - "id": 11, - "owner_name": "Margo", - "weight_lbs": 75 - } -] -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/quickstart-examples.md b/versioned_docs/version-4.6/developers/operations-api/quickstart-examples.md deleted file mode 100644 index a6c8f637..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/quickstart-examples.md +++ /dev/null @@ -1,370 +0,0 @@ ---- -title: Quick Start Examples ---- - -# Quick Start Examples - -Harper recommends utilizing [Harper Applications](../../developers/applications/) for defining databases, tables, and other functionality. However, this guide is a great way to get started using on the Harper Operations API. - -## Create dog Table - -We first need to create a table. Since our company is named after our CEO's dog, lets create a table to store all our employees' dogs. We'll call this table, `dogs`. - -Tables in Harper are schema-less, so we don't need to add any attributes other than a primary_key (in pre 4.2 versions this was referred to as the hash_attribute) to create this table. - -Harper does offer a `database` parameter that can be used to hold logical groupings of tables. The parameter is optional and if not provided the operation will default to using a database named `data`. - -If you receive an error response, make sure your Basic Authentication user and password match those you entered during the installation process. - -### Body - -```json -{ - "operation": "create_table", - "table": "dog", - "primary_key": "id" -} -``` - -### Response: 200 - -```json -{ - "message": "table 'data.dog' successfully created." -} -``` - ---- - -## Create breed Table - -Now that we have a table to store our dog data, we also want to create a table to track known breeds. Just as with the dog table, the only attribute we need to specify is the `primary_key`. - -### Body - -```json -{ - "operation": "create_table", - "table": "breed", - "primary_key": "id" -} -``` - -### Response: 200 - -```json -{ - "message": "table 'data.breed' successfully created." -} -``` - ---- - -## Insert 1 Dog - -We're ready to add some dog data. Penny is our CTO's pup, so she gets ID 1 or we're all fired. We are specifying attributes in this call, but this doesn't prevent us from specifying additional attributes in subsequent calls. - -### Body - -```json -{ - "operation": "insert", - "table": "dog", - "records": [ - { - "id": 1, - "dog_name": "Penny", - "owner_name": "Kyle", - "breed_id": 154, - "age": 7, - "weight_lbs": 38 - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "inserted 1 of 1 records", - "inserted_hashes": [1], - "skipped_hashes": [] -} -``` - ---- - -## Insert Multiple Dogs - -Let's add some more Harper doggies! We can add as many dog objects as we want into the records collection. If you're adding a lot of objects, we would recommend using the .csv upload option (see the next section where we populate the breed table). - -### Body - -```json -{ - "operation": "insert", - "table": "dog", - "records": [ - { - "id": 2, - "dog_name": "Harper", - "owner_name": "Stephen", - "breed_id": 346, - "age": 7, - "weight_lbs": 55, - "adorable": true - }, - { - "id": 3, - "dog_name": "Alby", - "owner_name": "Kaylan", - "breed_id": 348, - "age": 7, - "weight_lbs": 84, - "adorable": true - }, - { - "id": 4, - "dog_name": "Billy", - "owner_name": "Zach", - "breed_id": 347, - "age": 6, - "weight_lbs": 60, - "adorable": true - }, - { - "id": 5, - "dog_name": "Rose Merry", - "owner_name": "Zach", - "breed_id": 348, - "age": 8, - "weight_lbs": 15, - "adorable": true - }, - { - "id": 6, - "dog_name": "Kato", - "owner_name": "Kyle", - "breed_id": 351, - "age": 6, - "weight_lbs": 32, - "adorable": true - }, - { - "id": 7, - "dog_name": "Simon", - "owner_name": "Fred", - "breed_id": 349, - "age": 3, - "weight_lbs": 35, - "adorable": true - }, - { - "id": 8, - "dog_name": "Gemma", - "owner_name": "Stephen", - "breed_id": 350, - "age": 5, - "weight_lbs": 55, - "adorable": true - }, - { - "id": 9, - "dog_name": "Yeti", - "owner_name": "Jaxon", - "breed_id": 200, - "age": 5, - "weight_lbs": 55, - "adorable": true - }, - { - "id": 10, - "dog_name": "Monkey", - "owner_name": "Aron", - "breed_id": 271, - "age": 7, - "weight_lbs": 35, - "adorable": true - }, - { - "id": 11, - "dog_name": "Bode", - "owner_name": "Margo", - "breed_id": 104, - "age": 8, - "weight_lbs": 75, - "adorable": true - }, - { - "id": 12, - "dog_name": "Tucker", - "owner_name": "David", - "breed_id": 346, - "age": 2, - "weight_lbs": 60, - "adorable": true - }, - { - "id": 13, - "dog_name": "Jagger", - "owner_name": "Margo", - "breed_id": 271, - "age": 7, - "weight_lbs": 35, - "adorable": true - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "inserted 12 of 12 records", - "inserted_hashes": [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13], - "skipped_hashes": [] -} -``` - ---- - -## Bulk Insert Breeds Via CSV - -We need to populate the 'breed' table with some data so we can reference it later. For larger data sets, we recommend using our CSV upload option. - -Each header in a column will be considered as an attribute, and each row in the file will be a row in the table. Simply specify the file path and the table to upload to, and Harper will take care of the rest. You can pull the breeds.csv file from here: [https://s3.amazonaws.com/complimentarydata/breeds.csv](https://s3.amazonaws.com/complimentarydata/breeds.csv) - -### Body - -```json -{ - "operation": "csv_url_load", - "table": "breed", - "csv_url": "https://s3.amazonaws.com/complimentarydata/breeds.csv" -} -``` - -### Response: 200 - -```json -{ - "message": "Starting job with id e77d63b9-70d5-499c-960f-6736718a4369", - "job_id": "e77d63b9-70d5-499c-960f-6736718a4369" -} -``` - ---- - -## Update 1 Dog Using NoSQL - -Harper supports NoSQL and SQL commands. We're going to update the dog table to show Penny's last initial using our NoSQL API. - -### Body - -```json -{ - "operation": "update", - "table": "dog", - "records": [ - { - "id": 1, - "dog_name": "Penny B" - } - ] -} -``` - -### Response: 200 - -```json -{ - "message": "updated 1 of 1 records", - "update_hashes": [1], - "skipped_hashes": [] -} -``` - ---- - -## Select a Dog by ID Using SQL - -Now we're going to use a simple SQL SELECT call to pull Penny's updated data. Note we now see Penny's last initial in the dog name. - -### Body - -```json -{ - "operation": "sql", - "sql": "SELECT * FROM data.dog where id = 1" -} -``` - -### Response: 200 - -```json -[ - { - "owner_name": "Kyle", - "adorable": null, - "breed_id": 154, - "__updatedtime__": 1610749428575, - "dog_name": "Penny B", - "weight_lbs": 38, - "id": 1, - "age": 7, - "__createdtime__": 1610749386566 - } -] -``` - ---- - -## Select Dogs and Join Breed - -Here's a more complex SQL command joining the breed table with the dog table. We will also pull only the pups belonging to Kyle, Zach, and Stephen. - -### Body - -```json -{ - "operation": "sql", - "sql": "SELECT d.id, d.dog_name, d.owner_name, b.name, b.section FROM data.dog AS d INNER JOIN data.breed AS b ON d.breed_id = b.id WHERE d.owner_name IN ('Kyle', 'Zach', 'Stephen') AND b.section = 'Mutt' ORDER BY d.dog_name" -} -``` - -### Response: 200 - -```json -[ - { - "id": 4, - "dog_name": "Billy", - "owner_name": "Zach", - "name": "LABRADOR / GREAT DANE MIX", - "section": "Mutt" - }, - { - "id": 8, - "dog_name": "Gemma", - "owner_name": "Stephen", - "name": "SHORT HAIRED SETTER MIX", - "section": "Mutt" - }, - { - "id": 2, - "dog_name": "Harper", - "owner_name": "Stephen", - "name": "HUSKY MIX", - "section": "Mutt" - }, - { - "id": 5, - "dog_name": "Rose Merry", - "owner_name": "Zach", - "name": "TERRIER MIX", - "section": "Mutt" - } -] -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/registration.md b/versioned_docs/version-4.6/developers/operations-api/registration.md deleted file mode 100644 index 28c6a0e9..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/registration.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Registration ---- - -# Registration - -## Registration Info - -Returns the registration data of the Harper instance. - -- `operation` _(required)_ - must always be `registration_info` - -### Body - -```json -{ - "operation": "registration_info" -} -``` - -### Response: 200 - -```json -{ - "registered": true, - "version": "4.2.0", - "ram_allocation": 2048, - "license_expiration_date": "2022-01-15" -} -``` - ---- - -## Get Fingerprint - -Returns the Harper fingerprint, uniquely generated based on the machine, for licensing purposes. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `get_fingerprint` - -### Body - -```json -{ - "operation": "get_fingerprint" -} -``` - ---- - -## Set License - -Sets the Harper license as generated by Harper License Management software. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `set_license` -- `key` _(required)_ - your license key -- `company` _(required)_ - the company that was used in the license - -### Body - -```json -{ - "operation": "set_license", - "key": "", - "company": "" -} -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/sql-operations.md b/versioned_docs/version-4.6/developers/operations-api/sql-operations.md deleted file mode 100644 index 4b7076bb..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/sql-operations.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: SQL Operations ---- - -:::warning -Harper encourages developers to utilize other querying tools over SQL for performance purposes. Harper SQL is intended for data investigation purposes and uses cases where performance is not a priority. SQL optimizations are on our roadmap for the future. -::: - -# SQL Operations - -## Select - -Executes the provided SQL statement. The SELECT statement is used to query data from the database. - -- `operation` _(required)_ - must always be `sql` -- `sql` _(required)_ - use standard SQL - -### Body - -```json -{ - "operation": "sql", - "sql": "SELECT * FROM dev.dog WHERE id = 1" -} -``` - -### Response: 200 - -```json -[ - { - "id": 1, - "age": 7, - "dog_name": "Penny", - "weight_lbs": 38, - "breed_id": 154, - "owner_name": "Kyle", - "adorable": true, - "__createdtime__": 1611614106043, - "__updatedtime__": 1611614119507 - } -] -``` - ---- - -## Insert - -Executes the provided SQL statement. The INSERT statement is used to add one or more rows to a database table. - -- `operation` _(required)_ - must always be `sql` -- `sql` _(required)_ - use standard SQL - -### Body - -```json -{ - "operation": "sql", - "sql": "INSERT INTO dev.dog (id, dog_name) VALUE (22, 'Simon')" -} -``` - -### Response: 200 - -```json -{ - "message": "inserted 1 of 1 records", - "inserted_hashes": [22], - "skipped_hashes": [] -} -``` - ---- - -## Update - -Executes the provided SQL statement. The UPDATE statement is used to change the values of specified attributes in one or more rows in a database table. - -- `operation` _(required)_ - must always be `sql` -- `sql` _(required)_ - use standard SQL - -### Body - -```json -{ - "operation": "sql", - "sql": "UPDATE dev.dog SET dog_name = 'penelope' WHERE id = 1" -} -``` - -### Response: 200 - -```json -{ - "message": "updated 1 of 1 records", - "update_hashes": [1], - "skipped_hashes": [] -} -``` - ---- - -## Delete - -Executes the provided SQL statement. The DELETE statement is used to remove one or more rows of data from a database table. - -- `operation` _(required)_ - must always be `sql` -- `sql` _(required)_ - use standard SQL - -### Body - -```json -{ - "operation": "sql", - "sql": "DELETE FROM dev.dog WHERE id = 1" -} -``` - -### Response: 200 - -```json -{ - "message": "1 of 1 record successfully deleted", - "deleted_hashes": [1], - "skipped_hashes": [] -} -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/system-operations.md b/versioned_docs/version-4.6/developers/operations-api/system-operations.md deleted file mode 100644 index d39e93cb..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/system-operations.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: System Operations ---- - -# System Operations - -## Restart - -Restarts the Harper instance. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `restart` - -### Body - -```json -{ - "operation": "restart" -} -``` - -### Response: 200 - -```json -{ - "message": "Restarting HarperDB. This may take up to 60 seconds." -} -``` - ---- - -## Restart Service - -Restarts servers for the specified Harper service. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `restart_service` -- `service` _(required)_ - must be one of: `http_workers`, `clustering_config` or `clustering` -- `replicated` _(optional)_ - must be a boolean. If set to `true`, Harper will replicate the restart service operation across all nodes in the cluster. The restart will occur as a rolling restart, ensuring that each node is fully restarted before the next node begins restarting. - -### Body - -```json -{ - "operation": "restart_service", - "service": "http_workers" -} -``` - -### Response: 200 - -```json -{ - "message": "Restarting http_workers" -} -``` - ---- - -## System Information - -Returns detailed metrics on the host system. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `system_information` -- `attributes` _(optional)_ - string array of top level attributes desired in the response, if no value is supplied all attributes will be returned. Available attributes are: ['system', 'time', 'cpu', 'memory', 'disk', 'network', 'harperdb_processes', 'table_size', 'metrics', 'threads', 'replication'] - -### Body - -```json -{ - "operation": "system_information" -} -``` - ---- - -## Set Status - -Sets a status value that can be used for application-specific status tracking. Status values are stored in memory and are not persisted across restarts. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `set_status` -- `id` _(required)_ - the key identifier for the status -- `status` _(required)_ - the status value to set (string between 1-512 characters) - -### Body - -```json -{ - "operation": "set_status", - "id": "primary", - "status": "active" -} -``` - -### Response: 200 - -```json -{ - "id": "primary", - "status": "active", - "__createdtime__": 1621364589543, - "__updatedtime__": 1621364589543 -} -``` - -### Notes - -- The `id` parameter must be one of the allowed status types: 'primary', 'maintenance', or 'availability' -- If no `id` is specified, it defaults to 'primary' -- For 'availability' status, only 'Available' or 'Unavailable' values are accepted -- For other status types, any string value is accepted - ---- - -## Get Status - -Retrieves a status value previously set with the set_status operation. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `get_status` -- `id` _(optional)_ - the key identifier for the status to retrieve (defaults to all statuses if not provided) - -### Body - -```json -{ - "operation": "get_status", - "id": "primary" -} -``` - -### Response: 200 - -```json -{ - "id": "primary", - "status": "active", - "__createdtime__": 1621364589543, - "__updatedtime__": 1621364589543 -} -``` - -If no id parameter is provided, all status values will be returned: - -```json -[ - { - "id": "primary", - "status": "active", - "__createdtime__": 1621364589543, - "__updatedtime__": 1621364589543 - }, - { - "id": "maintenance", - "status": "scheduled", - "__createdtime__": 1621364600123, - "__updatedtime__": 1621364600123 - } -] -``` - ---- - -## Clear Status - -Removes a status entry by its ID. - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `clear_status` -- `id` _(required)_ - the key identifier for the status to remove - -### Body - -```json -{ - "operation": "clear_status", - "id": "primary" -} -``` - -### Response: 200 - -```json -{ - "message": "Status successfully cleared" -} -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/token-authentication.md b/versioned_docs/version-4.6/developers/operations-api/token-authentication.md deleted file mode 100644 index 178db842..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/token-authentication.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Token Authentication ---- - -# Token Authentication - -## Create Authentication Tokens - -Creates the tokens needed for authentication: operation & refresh token. - -_Note - this operation does not require authorization to be set_ - -- `operation` _(required)_ - must always be `create_authentication_tokens` -- `username` _(required)_ - username of user to generate tokens for -- `password` _(required)_ - password of user to generate tokens for - -### Body - -```json -{ - "operation": "create_authentication_tokens", - "username": "", - "password": "" -} -``` - -### Response: 200 - -```json -{ - "operation_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IkhEQl9BRE1JTiIsImlhdCI6MTYwNTA2Mzk0OSwiZXhwIjoxNjA1MTUwMzQ5LCJzdWIiOiJvcGVyYXRpb24ifQ.TlV93BqavQVQntXTt_WeY5IjAuCshfd6RzhihLWFWhu1qEKLHdwg9o5Z4ASaNmfuyKBqbFw65IbOYKd348EXeC_T6d0GO3yUhICYWXkqhQnxVW_T-ECKc7m5Bty9HTgfeaJ2e2yW55nbZYWG_gLtNgObUjCziX20-gGGR25sNTRm78mLQPYQkBJph6WXwAuyQrX704h0NfvNqyAZSwjxgtjuuEftTJ7FutLrQSLGIBIYq9nsHrFkheiDSn-C8_WKJ_zATa4YIofjqn9g5wA6o_7kSNaU2-gWnCm_jbcAcfvOmXh6rd89z8pwPqnC0f131qHIBps9UHaC1oozzmu_C6bsg7905OoAdFFY42Vojs98SMbfRApRvwaS4SprBsam3izODNI64ZUBREu3l4SZDalUf2kN8XPVWkI1LKq_mZsdtqr1r11Z9xslI1wVdxjunYeanjBhs7_j2HTX7ieVGn1a23cWceUk8F1HDGe_KEuPQs03R73V8acq_freh-kPhIa4eLqmcHeBw3WcyNGW8GuP8kyQRkGuO5sQSzZqbr_YSbZdSShZWTWDE6RYYC9ZV9KJtHVxhs0hexUpcoqO8OtJocyltRjtDjhSm9oUxszYRaALu-h8YadZT9dEKzsyQIt30d7LS9ETmmGWx4nKSTME2bV21PnDv_rEc5R6gnE", - "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6IkhEQl9BRE1JTiIsImlhdCI6MTYwNTA2Mzk0OSwiZXhwIjoxNjA3NjU1OTQ5LCJzdWIiOiJyZWZyZXNoIn0.znhJhkdSROBPP_GLRzAxYdjgQ3BuqpAbQB7zMSSOQJ3s83HnmZ10Bnpw_3L2aF-tOFgz_t6HUAvn26fNOLsspJD2aOvHPcVS4yLKS5nagpA6ar_pqng9f6Ebfs8ohguLCfHnHRJ8poLxuWRvWW9_9pIlDiwsj4yo3Mbxi3mW8Bbtnk2MwiNHFxTksD12Ne8EWz8q2jic5MjArqBBgR373oYoWU1oxpTM6gIsZCBRowXcc9XFy2vyRoggEUU4ISRFQ4ZY9ayJ-_jleSDCUamJSNQsdb1OUTvc6CxeYlLjCoV0ijRUB6p2XWNVezFhDu8yGqOeyGFJzArhxbVc_pl4UYd5aUVxhrO9DdhG29cY_mHV0FqfXphR9QllK--LJFTP4aFqkCxnVr7HSa17hL0ZVK1HaKrx21PAdCkVNZpD6J3RtRbTkfnIB_C3Be9jhOV3vpTf7ZGn_Bs3CPJi_sL313Z1yKSDAS5rXTPceEOcTPHjzkMP9Wz19KfFq_0kuiZdDmeYNqJeFPAgGJ-S0tO51krzyGqLyCCA32_W104GR8OoQi2gEED6HIx2G0-1rnLnefN6eHQiY5r-Q3Oj9e2y3EvqqgWOmEDw88-SjPTwQVnMbBHYN2RfluU7EmvDh6Saoe79Lhlu8ZeSJ1x6ZgA8-Cirraz1_526Tn8v5FGDfrc" -} -``` - ---- - -## Refresh Operation Token - -This operation creates a new operation token. - -- `operation` _(required)_ - must always be `refresh_operation_token` -- `refresh_token` _(required)_ - the refresh token that was provided when tokens were created - -### Body - -```json -{ - "operation": "refresh_operation_token", - "refresh_token": "EXISTING_REFRESH_TOKEN" -} -``` - -### Response: 200 - -```json -{ - "operation_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6eyJfX2NyZWF0ZWR0aW1lX18iOjE2MDQ1MTc4Nzk1MjMsIl9fdXBkYXRlZHRpbWVfXyI6MTYwNDUxNzg3OTUyMywiYWN0aXZlIjp0cnVlLCJhdXRoX3Rva2VuIjpudWxsLCJyb2xlIjp7Il9fY3JlYXRlZHRpbWVfXyI6MTYwNDUxNzg3OTUyMSwiX191cGRhdGVkdGltZV9fIjoxNjA0NTE3ODc5NTIxLCJpZCI6IjZhYmRjNGJhLWU5MjQtNDlhNi1iOGY0LWM1NWUxYmQ0OTYzZCIsInBlcm1pc3Npb24iOnsic3VwZXJfdXNlciI6dHJ1ZSwic3lzdGVtIjp7InRhYmxlcyI6eyJoZGJfdGFibGUiOnsicmVhZCI6dHJ1ZSwiaW5zZXJ0IjpmYWxzZSwidXBkYXRlIjpmYWxzZSwiZGVsZXRlIjpmYWxzZSwiYXR0cmlidXRlX3Blcm1pc3Npb25zIjpbXX0sImhkYl9hdHRyaWJ1dGUiOnsicmVhZCI6dHJ1ZSwiaW5zZXJ0IjpmYWxzZSwidXBkYXRlIjpmYWxzZSwiZGVsZXRlIjpmYWxzZSwiYXR0cmlidXRlX3Blcm1pc3Npb25zIjpbXX0sImhkYl9zY2hlbWEiOnsicmVhZCI6dHJ1ZSwiaW5zZXJ0IjpmYWxzZSwidXBkYXRlIjpmYWxzZSwiZGVsZXRlIjpmYWxzZSwiYXR0cmlidXRlX3Blcm1pc3Npb25zIjpbXX0sImhkYl91c2VyIjp7InJlYWQiOnRydWUsImluc2VydCI6ZmFsc2UsInVwZGF0ZSI6ZmFsc2UsImRlbGV0ZSI6ZmFsc2UsImF0dHJpYnV0ZV9wZXJtaXNzaW9ucyI6W119LCJoZGJfcm9sZSI6eyJyZWFkIjp0cnVlLCJpbnNlcnQiOmZhbHNlLCJ1cGRhdGUiOmZhbHNlLCJkZWxldGUiOmZhbHNlLCJhdHRyaWJ1dGVfcGVybWlzc2lvbnMiOltdfSwiaGRiX2pvYiI6eyJyZWFkIjp0cnVlLCJpbnNlcnQiOmZhbHNlLCJ1cGRhdGUiOmZhbHNlLCJkZWxldGUiOmZhbHNlLCJhdHRyaWJ1dGVfcGVybWlzc2lvbnMiOltdfSwiaGRiX2xpY2Vuc2UiOnsicmVhZCI6dHJ1ZSwiaW5zZXJ0IjpmYWxzZSwidXBkYXRlIjpmYWxzZSwiZGVsZXRlIjpmYWxzZSwiYXR0cmlidXRlX3Blcm1pc3Npb25zIjpbXX0sImhkYl9pbmZvIjp7InJlYWQiOnRydWUsImluc2VydCI6ZmFsc2UsInVwZGF0ZSI6ZmFsc2UsImRlbGV0ZSI6ZmFsc2UsImF0dHJpYnV0ZV9wZXJtaXNzaW9ucyI6W119LCJoZGJfbm9kZXMiOnsicmVhZCI6dHJ1ZSwiaW5zZXJ0IjpmYWxzZSwidXBkYXRlIjpmYWxzZSwiZGVsZXRlIjpmYWxzZSwiYXR0cmlidXRlX3Blcm1pc3Npb25zIjpbXX0sImhkYl90ZW1wIjp7InJlYWQiOnRydWUsImluc2VydCI6ZmFsc2UsInVwZGF0ZSI6ZmFsc2UsImRlbGV0ZSI6ZmFsc2UsImF0dHJpYnV0ZV9wZXJtaXNzaW9ucyI6W119fX19LCJyb2xlIjoic3VwZXJfdXNlciJ9LCJ1c2VybmFtZSI6IkhEQl9BRE1JTiJ9LCJpYXQiOjE2MDUwNjQ0MjMsImV4cCI6MTYwNTE1MDgyMywic3ViIjoib3BlcmF0aW9uIn0.VVZdhlh7_xFEaGPwhAh6VJ1d7eisiF3ok3ZwLTQAMWZB6umb2S7pPSTbXAmqAGHRlFAK3BYfnwT3YWt0gZbHvk24_0x3s_dej3PYJ8khIxzMjqpkR6qSjQIC2dhKqpwRPNtoqW_xnep9L-qf5iPtqkwsqWhF1c5VSN8nFouLWMZSuJ6Mag04soNhFvY0AF6QiTyzajMTb6uurRMWOnxk8hwMrY_5xtupabqtZheXP_0DV8l10B7GFi_oWf_lDLmwRmNbeUfW8ZyCIJMj36bjN3PsfVIxog87SWKKCwbWZWfJWw0KEph-HvU0ay35deyGWPIaDQmujuh2vtz-B0GoIAC58PJdXNyQRzES_nSb6Oqc_wGZsLM6EsNn_lrIp3mK_3a5jirZ8s6Z2SfcYKaLF2hCevdm05gRjFJ6ijxZrUSOR2S415wLxmqCCWCp_-sEUz8erUrf07_aj-Bv99GUub4b_znOsQF3uABKd4KKff2cNSMhAa-6sro5GDRRJg376dcLi2_9HOZbnSo90zrpVq8RNV900aydyzDdlXkZja8jdHBk4mxSSewYBvM7up6I0G4X-ZlzFOp30T7kjdLa6480Qp34iYRMMtq0Htpb5k2jPt8dNFnzW-Q2eRy1wNBbH3cCH0rd7_BIGuTCrl4hGU8QjlBiF7Gj0_-uJYhKnhg" -} -``` diff --git a/versioned_docs/version-4.6/developers/operations-api/users-and-roles.md b/versioned_docs/version-4.6/developers/operations-api/users-and-roles.md deleted file mode 100644 index 91f222b9..00000000 --- a/versioned_docs/version-4.6/developers/operations-api/users-and-roles.md +++ /dev/null @@ -1,508 +0,0 @@ ---- -title: Users and Roles ---- - -# Users and Roles - -## List Roles - -Returns a list of all roles. [Learn more about Harper roles here.](../security/users-and-roles) - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `list_roles` - -### Body - -```json -{ - "operation": "list_roles" -} -``` - -### Response: 200 - -```json -[ - { - "__createdtime__": 1611615061106, - "__updatedtime__": 1611615061106, - "id": "05c2ffcd-f780-40b1-9432-cfe8ba5ad890", - "permission": { - "super_user": false, - "dev": { - "tables": { - "dog": { - "read": true, - "insert": true, - "update": true, - "delete": false, - "attribute_permissions": [ - { - "attribute_name": "name", - "read": true, - "insert": true, - "update": true - } - ] - } - } - } - }, - "role": "developer" - }, - { - "__createdtime__": 1610749235614, - "__updatedtime__": 1610749235614, - "id": "136f03fa-a0e9-46c3-bd5d-7f3e7dd5b564", - "permission": { - "cluster_user": true - }, - "role": "cluster_user" - }, - { - "__createdtime__": 1610749235609, - "__updatedtime__": 1610749235609, - "id": "745b3138-a7cf-455a-8256-ac03722eef12", - "permission": { - "super_user": true - }, - "role": "super_user" - } -] -``` - ---- - -## Add Role - -Creates a new role with the specified permissions. [Learn more about Harper roles here.](../security/users-and-roles) - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `add_role` -- `role` _(required)_ - name of role you are defining -- `permission` _(required)_ - object defining permissions for users associated with this role: - - `super_user` _(optional)_ - boolean which, if set to true, gives users associated with this role full access to all operations and methods. If not included, value will be assumed to be false. - - `structure_user` _(optional)_ - boolean OR array of database names (as strings). If boolean, user can create new databases and tables. If array of strings, users can only manage tables within the specified databases. This overrides any individual table permissions for specified databases, or for all databases if the value is true. - -### Body - -```json -{ - "operation": "add_role", - "role": "developer", - "permission": { - "super_user": false, - "structure_user": false, - "dev": { - "tables": { - "dog": { - "read": true, - "insert": true, - "update": true, - "delete": false, - "attribute_permissions": [ - { - "attribute_name": "name", - "read": true, - "insert": true, - "update": true - } - ] - } - } - } - } -} -``` - -### Response: 200 - -```json -{ - "role": "developer", - "permission": { - "super_user": false, - "structure_user": false, - "dev": { - "tables": { - "dog": { - "read": true, - "insert": true, - "update": true, - "delete": false, - "attribute_permissions": [ - { - "attribute_name": "name", - "read": true, - "insert": true, - "update": true - } - ] - } - } - } - }, - "id": "0a9368b0-bd81-482f-9f5a-8722e3582f96", - "__updatedtime__": 1598549532897, - "__createdtime__": 1598549532897 -} -``` - ---- - -## Alter Role - -Modifies an existing role with the specified permissions. updates permissions from an existing role. [Learn more about Harper roles here.](../security/users-and-roles) - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `alter_role` -- `id` _(required)_ - the id value for the role you are altering -- `role` _(optional)_ - name value to update on the role you are altering -- `permission` _(required)_ - object defining permissions for users associated with this role: - - `super_user` _(optional)_ - boolean which, if set to true, gives users associated with this role full access to all operations and methods. If not included, value will be assumed to be false. - - `structure_user` _(optional)_ - boolean OR array of database names (as strings). If boolean, user can create new databases and tables. If array of strings, users can only manage tables within the specified databases. This overrides any individual table permissions for specified databases, or for all databases if the value is true. - -### Body - -```json -{ - "operation": "alter_role", - "id": "f92162e2-cd17-450c-aae0-372a76859038", - "role": "another_developer", - "permission": { - "super_user": false, - "structure_user": false, - "dev": { - "tables": { - "dog": { - "read": true, - "insert": true, - "update": true, - "delete": false, - "attribute_permissions": [ - { - "attribute_name": "name", - "read": false, - "insert": true, - "update": true - } - ] - } - } - } - } -} -``` - -### Response: 200 - -```json -{ - "id": "a7cb91e9-32e4-4dbf-a327-fab4fa9191ea", - "role": "developer", - "permission": { - "super_user": false, - "structure_user": false, - "dev": { - "tables": { - "dog": { - "read": true, - "insert": true, - "update": true, - "delete": false, - "attribute_permissions": [ - { - "attribute_name": "name", - "read": false, - "insert": true, - "update": true - } - ] - } - } - } - }, - "__updatedtime__": 1598549996106 -} -``` - ---- - -## Drop Role - -Deletes an existing role from the database. NOTE: Role with associated users cannot be dropped. [Learn more about Harper roles here.](../security/users-and-roles) - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - this must always be `drop_role` -- `id` _(required)_ - this is the id of the role you are dropping - -### Body - -```json -{ - "operation": "drop_role", - "id": "developer" -} -``` - -### Response: 200 - -```json -{ - "message": "developer successfully deleted" -} -``` - ---- - -## List Users - -Returns a list of all users. [Learn more about Harper roles here.](../security/users-and-roles) - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `list_users` - -### Body - -```json -{ - "operation": "list_users" -} -``` - -### Response: 200 - -```json -[ - { - "__createdtime__": 1635520961165, - "__updatedtime__": 1635520961165, - "active": true, - "role": { - "__createdtime__": 1635520961161, - "__updatedtime__": 1635520961161, - "id": "7c78ef13-c1f3-4063-8ea3-725127a78279", - "permission": { - "super_user": true, - "system": { - "tables": { - "hdb_table": { - "read": true, - "insert": false, - "update": false, - "delete": false, - "attribute_permissions": [] - }, - "hdb_attribute": { - "read": true, - "insert": false, - "update": false, - "delete": false, - "attribute_permissions": [] - }, - "hdb_schema": { - "read": true, - "insert": false, - "update": false, - "delete": false, - "attribute_permissions": [] - }, - "hdb_user": { - "read": true, - "insert": false, - "update": false, - "delete": false, - "attribute_permissions": [] - }, - "hdb_role": { - "read": true, - "insert": false, - "update": false, - "delete": false, - "attribute_permissions": [] - }, - "hdb_job": { - "read": true, - "insert": false, - "update": false, - "delete": false, - "attribute_permissions": [] - }, - "hdb_license": { - "read": true, - "insert": false, - "update": false, - "delete": false, - "attribute_permissions": [] - }, - "hdb_info": { - "read": true, - "insert": false, - "update": false, - "delete": false, - "attribute_permissions": [] - }, - "hdb_nodes": { - "read": true, - "insert": false, - "update": false, - "delete": false, - "attribute_permissions": [] - }, - "hdb_temp": { - "read": true, - "insert": false, - "update": false, - "delete": false, - "attribute_permissions": [] - } - } - } - }, - "role": "super_user" - }, - "username": "HDB_ADMIN" - } -] -``` - ---- - -## User Info - -Returns user data for the associated user credentials. - -- `operation` _(required)_ - must always be `user_info` - -### Body - -```json -{ - "operation": "user_info" -} -``` - -### Response: 200 - -```json -{ - "__createdtime__": 1610749235611, - "__updatedtime__": 1610749235611, - "active": true, - "role": { - "__createdtime__": 1610749235609, - "__updatedtime__": 1610749235609, - "id": "745b3138-a7cf-455a-8256-ac03722eef12", - "permission": { - "super_user": true - }, - "role": "super_user" - }, - "username": "HDB_ADMIN" -} -``` - ---- - -## Add User - -Creates a new user with the specified role and credentials. [Learn more about Harper roles here.](../security/users-and-roles) - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `add_user` -- `role` _(required)_ - 'role' name value of the role you wish to assign to the user. See `add_role` for more detail -- `username` _(required)_ - username assigned to the user. It can not be altered after adding the user. It serves as the hash -- `password` _(required)_ - clear text for password. Harper will encrypt the password upon receipt -- `active` _(required)_ - boolean value for status of user's access to your Harper instance. If set to false, user will not be able to access your instance of Harper. - -### Body - -```json -{ - "operation": "add_user", - "role": "role_name", - "username": "hdb_user", - "password": "password", - "active": true -} -``` - -### Response: 200 - -```json -{ - "message": "hdb_user successfully added" -} -``` - ---- - -## Alter User - -Modifies an existing user's role and/or credentials. [Learn more about Harper roles here.](../security/users-and-roles) - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `alter_user` -- `username` _(required)_ - username assigned to the user. It can not be altered after adding the user. It serves as the hash. -- `password` _(optional)_ - clear text for password. Harper will encrypt the password upon receipt -- `role` _(optional)_ - `role` name value of the role you wish to assign to the user. See `add_role` for more detail -- `active` _(optional)_ - status of user's access to your Harper instance. See `add_role` for more detail - -### Body - -```json -{ - "operation": "alter_user", - "role": "role_name", - "username": "hdb_user", - "password": "password", - "active": true -} -``` - -### Response: 200 - -```json -{ - "message": "updated 1 of 1 records", - "new_attributes": [], - "txn_time": 1611615114397.988, - "update_hashes": ["hdb_user"], - "skipped_hashes": [] -} -``` - ---- - -## Drop User - -Deletes an existing user by username. [Learn more about Harper roles here.](../security/users-and-roles) - -_Operation is restricted to super_user roles only_ - -- `operation` _(required)_ - must always be `drop_user` -- `username` _(required)_ - username assigned to the user - -### Body - -```json -{ - "operation": "drop_user", - "username": "sgoldberg" -} -``` - -### Response: 200 - -```json -{ - "message": "sgoldberg successfully deleted" -} -``` From 48fcef38d7d9aa8212ef7ab501de4a61a8647bc0 Mon Sep 17 00:00:00 2001 From: nenharper Date: Fri, 3 Oct 2025 14:01:55 -0500 Subject: [PATCH 4/6] Fix broken links --- .../administration/administration.md | 6 +++--- .../administration/harper-studio/instances.md | 2 +- .../version-4.6/administration/jobs.md | 18 +++++++++--------- .../administration/logging/audit-logging.md | 2 +- .../version-4.6/deployments/configuration.md | 2 +- .../deployments/upgrade-hdb-instance.md | 2 +- 6 files changed, 16 insertions(+), 16 deletions(-) diff --git a/versioned_docs/version-4.6/administration/administration.md b/versioned_docs/version-4.6/administration/administration.md index e0084bb5..88267ddd 100644 --- a/versioned_docs/version-4.6/administration/administration.md +++ b/versioned_docs/version-4.6/administration/administration.md @@ -12,7 +12,7 @@ As a distributed database, data protection and recovery can benefit from differe - Availability: As a distributed database Harper is intrinsically built for high-availability and a cluster will continue to run even with complete server(s) failure. This is the first and primary defense for protecting against any downtime or data loss. Harper provides fast horizontal scaling functionality with node cloning, which facilitates ease of establishing high availability clusters. - [Audit log](administration/logging/audit-logging): Harper defaults to tracking data changes so malicious data changes can be found, attributed, and reverted. This provides security-level defense against data loss, allowing for fine-grained isolation and reversion of individual data without the large-scale reversion/loss of data associated with point-in-time recovery approaches. -- Snapshots: When used as a source-of-truth database for crucial data, we recommend using snapshot tools to regularly snapshot databases as a final backup/defense against data loss (this should only be used as a last resort in recovery). Harper has a [`get_backup`](./developers/operations-api/databases-and-tables#get-backup) operation, which provides direct support for making and retrieving database snapshots. An HTTP request can be used to get a snapshot. Alternatively, volume snapshot tools can be used to snapshot data at the OS/VM level. Harper can also provide scripts for replaying transaction logs from snapshots to facilitate point-in-time recovery when necessary (often customization may be preferred in certain recovery situations to minimize data loss). +- Snapshots: When used as a source-of-truth database for crucial data, we recommend using snapshot tools to regularly snapshot databases as a final backup/defense against data loss (this should only be used as a last resort in recovery). Harper has a [`get_backup`](../reference/operations-api/databases-and-tables#get-backup) operation, which provides direct support for making and retrieving database snapshots. An HTTP request can be used to get a snapshot. Alternatively, volume snapshot tools can be used to snapshot data at the OS/VM level. Harper can also provide scripts for replaying transaction logs from snapshots to facilitate point-in-time recovery when necessary (often customization may be preferred in certain recovery situations to minimize data loss). ### Horizontal Scaling with Node Cloning @@ -23,8 +23,8 @@ Harper provides rapid horizontal scaling capabilities through [node cloning func Harper provides robust capabilities for analytics and observability to facilitate effective and informative monitoring: - Analytics provides statistics on usage, request counts, load, memory usage with historical tracking. The analytics data can be [accessed through querying](./reference/analytics). -- A large variety of real-time statistics about load, system information, database metrics, thread usage can be retrieved through the [`system_information` API](./developers/operations-api/system-operations). -- Information about the current cluster configuration and status can be found in the [cluster APIs](./developers/operations-api/clustering). +- A large variety of real-time statistics about load, system information, database metrics, thread usage can be retrieved through the [`system_information` API](../reference/operations-api/system-operations). +- Information about the current cluster configuration and status can be found in the [cluster APIs](../reference/operations-api/clustering). - Analytics and system information can easily be exported to Prometheus with our [Prometheus exporter component](https://github.com/HarperDB-Add-Ons/prometheus_exporter), making it easy visualize and monitor Harper with Graphana. ### Replication Transaction Logging diff --git a/versioned_docs/version-4.6/administration/harper-studio/instances.md b/versioned_docs/version-4.6/administration/harper-studio/instances.md index 07da8097..597b9cbe 100644 --- a/versioned_docs/version-4.6/administration/harper-studio/instances.md +++ b/versioned_docs/version-4.6/administration/harper-studio/instances.md @@ -10,7 +10,7 @@ The Harper Studio allows you to administer all of your HarperDinstances in one p - **5G Wavelength Instance** Managed installations of Harper running on the Verizon network through AWS Wavelength, what we call 5G Wavelength Instances. _Note, these instances are only accessible via the Verizon network._ - **Enterprise Instance** Any Harper installation that is managed by you. These include instances hosted within your cloud provider accounts (for example, from the AWS or Digital Ocean Marketplaces), privately hosted instances, or instances installed locally. -All interactions between the Studio and your instances take place directly from your browser. Harper stores metadata about your instances, which enables the Studio to display these instances when you log in. Beyond that, all traffic is routed from your browser to the Harper instances using the standard [Harper API](../../developers/operations-api/). +All interactions between the Studio and your instances take place directly from your browser. Harper stores metadata about your instances, which enables the Studio to display these instances when you log in. Beyond that, all traffic is routed from your browser to the Harper instances using the standard [Harper API](../../developers/applications/operations-api). ## Organization Instance List diff --git a/versioned_docs/version-4.6/administration/jobs.md b/versioned_docs/version-4.6/administration/jobs.md index c487f424..777dee55 100644 --- a/versioned_docs/version-4.6/administration/jobs.md +++ b/versioned_docs/version-4.6/administration/jobs.md @@ -16,19 +16,19 @@ The job status can be **COMPLETE** or **IN_PROGRESS**. Example job operations include: -[csv data load](../developers/operations-api/bulk-operations#csv-data-load) +[csv data load](../reference/operations-api/bulk-operations#csv-data-load) -[csv file load](../developers/operations-api/bulk-operations#csv-file-load) +[csv file load](../reference/operations-api/bulk-operations#csv-file-load) -[csv url load](../developers/operations-api/bulk-operations#csv-url-load) +[csv url load](../reference/operations-api/bulk-operations#csv-url-load) -[import from s3](../developers/operations-api/bulk-operations#import-from-s3) +[import from s3](../reference/operations-api/bulk-operations#import-from-s3) -[delete_records_before](../developers/operations-api/bulk-operations#delete-records-before) +[delete_records_before](../reference/operations-api/bulk-operations#delete-records-before) -[export_local](../developers/operations-api/bulk-operations#export-local) +[export_local](../reference/operations-api/bulk-operations#export-local) -[export_to_s3](../developers/operations-api/bulk-operations#export-to-s3) +[export_to_s3](../reference/operations-api/bulk-operations#export-to-s3) Example Response from a Job Operation @@ -42,7 +42,7 @@ Whenever one of these operations is initiated, an asynchronous job is created an ## Managing Jobs -To check on a job's status, use the [get_job](../developers/operations-api/jobs#get-job) operation. +To check on a job's status, use the [get_job](../reference/operations-api/jobs#get-job) operation. Get Job Request @@ -77,7 +77,7 @@ Get Job Response ## Finding Jobs -To find jobs (if the ID is not known) use the [search_jobs_by_start_date](../developers/operations-api/jobs#search-jobs-by-start-date) operation. +To find jobs (if the ID is not known) use the [search_jobs_by_start_date](../reference/operations-api/jobs#search-jobs-by-start-date) operation. Search Jobs Request diff --git a/versioned_docs/version-4.6/administration/logging/audit-logging.md b/versioned_docs/version-4.6/administration/logging/audit-logging.md index 209b4981..7d95becd 100644 --- a/versioned_docs/version-4.6/administration/logging/audit-logging.md +++ b/versioned_docs/version-4.6/administration/logging/audit-logging.md @@ -14,7 +14,7 @@ Audit log is enabled by default. To disable the audit log, set `logging.auditLog #### read_audit_log -The `read_audit_log` operation is flexible, enabling users to query with many parameters. All operations search on a single table. Filter options include timestamps, usernames, and table hash values. Additional examples found in the [Harper API documentation](../../developers/operations-api/logs). +The `read_audit_log` operation is flexible, enabling users to query with many parameters. All operations search on a single table. Filter options include timestamps, usernames, and table hash values. Additional examples found in the [Harper API documentation](../../reference/operations-api/logs). **Search by Timestamp** diff --git a/versioned_docs/version-4.6/deployments/configuration.md b/versioned_docs/version-4.6/deployments/configuration.md index 89fe9ca7..b1b86f1b 100644 --- a/versioned_docs/version-4.6/deployments/configuration.md +++ b/versioned_docs/version-4.6/deployments/configuration.md @@ -16,7 +16,7 @@ The configuration elements in `harperdb-config.yaml` use camelcase, such as `ope To change a configuration value, edit the `harperdb-config.yaml` file and save any changes. **HarperDB must be restarted for changes to take effect.** -Alternatively, all configuration values can also be modified using environment variables, command line arguments, or the operations API via the [`set_configuration` operation](../developers/operations-api/configuration#set-configuration). +Alternatively, all configuration values can also be modified using environment variables, command line arguments, or the operations API via the [`set_configuration` operation](../reference/operations-api/configuration#set-configuration). For nested configuration elements, use underscores to represent parent-child relationships. When accessed this way, elements are case-insensitive. diff --git a/versioned_docs/version-4.6/deployments/upgrade-hdb-instance.md b/versioned_docs/version-4.6/deployments/upgrade-hdb-instance.md index 768b9323..6e9fc4ab 100644 --- a/versioned_docs/version-4.6/deployments/upgrade-hdb-instance.md +++ b/versioned_docs/version-4.6/deployments/upgrade-hdb-instance.md @@ -124,7 +124,7 @@ replication: - Disable NATS by setting `clustering.enabled` to `false`. - Stop the instance and upgrade it. - Start the instance. - - Call [`add_node`](../developers/operations-api/clustering#add-node) on the upgraded instance. In this call, omit `subscriptions` so that a fully replicating cluster is built. The target node for this call should be the bridge node. _Note: depending on your setup, you may need to expand this `add_node` call to include_ [_authorization and/or tls information_](../developers/operations-api/clustering#add-node)_._ + - Call [`add_node`](../reference/operations-api/clustering#add-node) on the upgraded instance. In this call, omit `subscriptions` so that a fully replicating cluster is built. The target node for this call should be the bridge node. _Note: depending on your setup, you may need to expand this `add_node` call to include_ [_authorization and/or tls information_](../reference/operations-api/clustering#add-node)_._ ```json { From 1e61f51e09055bb33c597a81176f5a7e806bbaeb Mon Sep 17 00:00:00 2001 From: nenharper Date: Fri, 3 Oct 2025 14:37:25 -0500 Subject: [PATCH 5/6] Fix broken links --- redirects.ts | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/redirects.ts b/redirects.ts index 14762816..e8c4f16d 100644 --- a/redirects.ts +++ b/redirects.ts @@ -55,7 +55,7 @@ function generateDocsRedirects(basePath: string): RedirectRule[] { // Operations API { from: withBase('/developers/operations-api/utilities'), - to: withBase('/developers/operations-api/system-operations'), + to: withBase('/reference/operations-api/system-operations'), }, // Installation paths @@ -142,7 +142,10 @@ function generateDocsRedirects(basePath: string): RedirectRule[] { from: [withBase('/custom-functions/using-npm-git'), withBase('/developers/custom-functions/create-project')], to: withBase('/developers/applications/'), }, - { from: withBase('/custom-functions/custom-functions-operations'), to: withBase('/developers/operations-api/') }, + { + from: withBase('/custom-functions/custom-functions-operations'), + to: withBase('/developers/applications/operations-api/'), + }, { from: withBase('/custom-functions/debugging-custom-function'), to: withBase('/developers/applications/debugging'), @@ -162,9 +165,9 @@ function generateDocsRedirects(basePath: string): RedirectRule[] { { from: withBase('/audit-logging'), to: withBase('/administration/logging/audit-logging') }, { from: withBase('/jobs'), to: withBase('/administration/jobs') }, { from: withBase('/upgrade-hdb-instance'), to: withBase('/deployments/upgrade-hdb-instance') }, - { from: withBase('/operations-api'), to: withBase('/developers/operations-api/') }, + { from: withBase('/operations-api'), to: withBase('/developers/applications/operations-api/') }, { from: withBase('/rest'), to: withBase('/developers/rest') }, - { from: withBase('/api'), to: withBase('/developers/operations-api/') }, + { from: withBase('/api'), to: withBase('/developers/applications/operations-api/') }, // File rename redirect { from: withBase('/administration/logging/logging'), to: withBase('/administration/logging/standard-logging') }, From 6e78987de6b53e4211da2a7d91824ebfb3bfebbb Mon Sep 17 00:00:00 2001 From: nenharper Date: Fri, 3 Oct 2025 18:08:24 -0500 Subject: [PATCH 6/6] Fix broken links --- redirects.ts | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/redirects.ts b/redirects.ts index e8c4f16d..2f941d03 100644 --- a/redirects.ts +++ b/redirects.ts @@ -57,6 +57,26 @@ function generateDocsRedirects(basePath: string): RedirectRule[] { from: withBase('/developers/operations-api/utilities'), to: withBase('/reference/operations-api/system-operations'), }, + { from: withBase('/developers/operations-api'), to: withBase('/developers/applications/operations-api') }, + { + from: withBase('/developers/operations-api/databases-and-tables'), + to: withBase('/reference/operations-api/databases-and-tables'), + }, + { + from: withBase('/developers/operations-api/system-operations'), + to: withBase('/reference/operations-api/system-operations'), + }, + { from: withBase('/developers/operations-api/clustering'), to: withBase('/reference/operations-api/clustering') }, + { from: withBase('/developers/operations-api/components'), to: withBase('/reference/operations-api/components') }, + { from: withBase('/developers/operations-api/logs'), to: withBase('/reference/operations-api/logs') }, + { + from: withBase('/developers/operations-api/bulk-operations'), + to: withBase('/reference/operations-api/bulk-operations'), + }, + { + from: withBase('/developers/operations-api/advanced-json-sql-examples'), + to: withBase('/reference/operations-api/advanced-json-sql-examples'), + }, // Installation paths { from: withBase('/install-harperdb'), to: withBase('/deployments/install-harper/') },