{ "externalDocs": { "description": "ArangoDB Documentation", "url": "https://docs.arango.ai/arangodb/" }, "info": { "contact": { "name": "ArangoDB Inc.", "url": "https://arango.ai" }, "license": { "name": "Business Source License 1.1", "url": "https://github.com/arangodb/arangodb/blob/devel/LICENSE" }, "summary": "The HTTP API of the ArangoDB graph database system", "title": "ArangoDB Core API", "version": "3.12.10 (API v0)" }, "openapi": "3.1.0", "paths": { "/_admin/backup/create": { "post": { "description": "Creates a consistent local backup \"as soon as possible\", very much\nlike a snapshot in time, with a given label. The ambiguity in the\nphrase \"as soon as possible\" refers to the next window during which a\nglobal write lock across all databases can be obtained in order to\nguarantee consistency. Note that the backup at first resides on the\nsame machine and hard drive as the original data. Make sure to upload\nit to a remote site for an actual backup.\n", "operationId": "createBackup", "requestBody": { "content": { "application/json": { "schema": { "properties": { "allowInconsistent": { "default": false, "description": "If this flag is set to `true` and no global transaction lock can be\nacquired within the given timeout, a possibly inconsistent backup\nis taken. The default for this flag is `false` and in this case\na timeout results in an HTTP 408 error.\n", "type": "boolean" }, "force": { "default": false, "description": "If this flag is set to `true` and no global transaction lock can be acquired\nwithin the given timeout, all running transactions are forcefully aborted to\nensure that a consistent backup can be created. This does not include\nJavaScript transactions. It waits for the transactions to be aborted at most\n`timeout` seconds. Thus using `force` the request timeout is doubled.\nTo abort transactions is almost certainly not what you want for your application.\nIn the presence of intermediate commits it can even destroy the atomicity of your\ntransactions. Use at your own risk, and only if you need a consistent backup at\nall costs. The default and recommended value is `false`. If both\n`allowInconsistent` and `force` are set to `true`, then the latter takes\nprecedence and transactions are aborted. This is only available in the cluster.\n", "type": "boolean" }, "label": { "description": "The label for this backup. The label is used together with a\ntimestamp string create a unique backup identifier, `\u003ctimestamp\u003e_\u003clabel\u003e`.\nIf no label is specified, the empty string is assumed and a default\nUUID is created for this part of the ID.\n", "type": "string" }, "timeout": { "default": 120, "description": "The time in seconds that the operation tries to get a consistent\nsnapshot.\n", "type": "integer" } }, "type": "object" } } } }, "responses": { "201": { "description": "If all is well, code 201 is returned.\n" }, "400": { "description": "If the create command is invoked with bad parameters or any HTTP\nmethod other than `POST`, then an *HTTP 400* is returned. The specifics\nare detailed in the returned error document.\n" }, "408": { "description": "If the operation cannot obtain a global transaction lock\nwithin the timeout, then an *HTTP 408* is returned.\n" } }, "summary": "Create a backup", "tags": [ "Hot Backups" ] } }, "/_admin/backup/delete": { "post": { "description": "Delete a specific local backup identified by the given `id`.\n", "operationId": "deleteBackup", "requestBody": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "The identifier for this backup.\n", "type": "string" } }, "required": [ "id" ], "type": "object" } } } }, "responses": { "200": { "description": "If all is well, this code 200 is returned.\n" }, "400": { "description": "If the delete command is invoked with bad parameters or any HTTP\nmethod other than `POST`, then an *HTTP 400* is returned.\n" }, "404": { "description": "If a backup corresponding to the identifier `id` cannot be found.\n" } }, "summary": "Delete a backup", "tags": [ "Hot Backups" ] } }, "/_admin/backup/download": { "post": { "description": "Download a specific local backup from a remote repository, or query\nprogress on a previously scheduled download operation, or abort\na running download operation.\n", "operationId": "downloadBackup", "requestBody": { "content": { "application/json": { "schema": { "properties": { "abort": { "default": false, "description": "Set this to `true` if a running download operation should be aborted. In\nthis case, the only other body parameter which is needed is `downloadId`.\n", "type": "boolean" }, "config": { "description": "Configuration of remote repository. This is required when a download\noperation is scheduled. In this case leave out the `downloadId`\nattribute. See [Rclone Configuration](https://docs.arango.ai/arangodb/3.12/components/tools/arangobackup/examples/#rclone-configuration)\nfor a description of the `config` object.\n", "type": "object" }, "downloadId": { "description": "Download ID to specify for which download operation progress is queried, or\nthe download operation to abort.\nIf you specify this, leave out all the above body parameters.\n", "type": "string" }, "id": { "description": "The identifier for this backup. This is required when a download\noperation is scheduled. In this case leave out the `downloadId`\nattribute.\n", "type": "string" }, "remoteRepository": { "description": "URL of remote repository. This is required when a download operation is\nscheduled. In this case leave out the `downloadId` attribute. Provided\nrepository URLs are normalized and validated as follows: One single colon must\nappear separating the configuration section name and the path. The URL prefix\nup to the colon must exist as a key in the config object below. No slashes must\nappear before the colon. Multiple back to back slashes are collapsed to one, as\n`..` and `.` are applied accordingly. Local repositories must be absolute paths\nand must begin with a `/`. Trailing `/` are removed.\n", "type": "string" } }, "required": [ "remoteRepository", "config" ], "type": "object" } } } }, "responses": { "200": { "description": "If all is well, code 200 is returned if progress is inquired or the\noperation is aborted.\n" }, "202": { "description": "If all is well, code 202 is returned if a new operation is scheduled.\n" }, "400": { "description": "If the download command is invoked with bad parameters or any HTTP\nmethod other than `POST`, then an *HTTP 400* is returned.\n" }, "401": { "description": "If the authentication to the remote repository fails, then an *HTTP\n401* is returned.\n" }, "404": { "description": "If a backup corresponding to the identifier `id` cannot be found, or if\nthere is no known download operation with the given `downloadId`.\n" } }, "summary": "Download a backup from a remote repository", "tags": [ "Hot Backups" ] } }, "/_admin/backup/list": { "post": { "description": "Lists all locally found backups.\n", "operationId": "listBackups", "requestBody": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "The body can either be empty (in which case all available backups are\nlisted), or it can be an object with an attribute `id`, which\nis a string. In the latter case the returned list\nis restricted to the backup with the given id.\n", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "If all is well, code 200 is returned.\n" }, "400": { "description": "If the list command is invoked with bad parameters, then an *HTTP 400*\nis returned.\n" }, "404": { "description": "If an `id` or a list of ids was given and the given ids were not found\nas identifiers of a backup, an *HTTP 404 Not Found* is returned.\n" }, "405": { "description": "If the list command is invoked with any HTTP\nmethod other than `POST`, then an *HTTP 405 Method Not Allowed* is returned.\n" } }, "summary": "List all backups", "tags": [ "Hot Backups" ] } }, "/_admin/backup/restore": { "post": { "description": "Restores a consistent local backup from a\nsnapshot in time, with a given id. The backup snapshot must reside on\nthe ArangoDB service locally.\n", "operationId": "restoreBackup", "requestBody": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "The id of the backup to restore from.\n", "type": "string" } }, "required": [ "id" ], "type": "object" } } } }, "responses": { "200": { "description": "Is returned if the backup could be restored. Note that there is an\ninevitable discrepancy between the single server and the cluster. In a\nsingle server, the request returns successfully, but the restore is\nonly executed afterwards. In the cluster, the request only returns when\nthe restore operation has been completed successfully. The cluster\nbehavior is obviously the desired one, but in a single instance, one\ncannot keep a connection open across a restart.\n" }, "400": { "description": "If the restore command is invoked with bad parameters or any HTTP\nmethod other than `POST`, then an *HTTP 400* is returned. The specifics\nare detailed in the returned error document.\n" } }, "summary": "Restore a backup", "tags": [ "Hot Backups" ] } }, "/_admin/backup/upload": { "post": { "description": "Upload a specific local backup to a remote repository, or query\nprogress on a previously scheduled upload operation, or abort\na running upload operation.\n", "operationId": "uploadBackup", "requestBody": { "content": { "application/json": { "schema": { "properties": { "abort": { "default": false, "description": "Set this to `true` if a running upload operation should be aborted. In\nthis case, the only other body parameter which is needed is `uploadId`.\n", "type": "boolean" }, "config": { "description": "Configuration of remote repository. This is required when an upload\noperation is scheduled. In this case leave out the `uploadId`\nattribute. See [Rclone Configuration](https://docs.arango.ai/arangodb/3.12/components/tools/arangobackup/examples/#rclone-configuration)\nfor a description of the `config` object.\n", "type": "object" }, "id": { "description": "The identifier for this backup. This is required when an upload\noperation is scheduled. In this case leave out the `uploadId`\nattribute.\n", "type": "string" }, "remoteRepository": { "description": "URL of remote repository. This is required when an upload operation is\nscheduled. In this case leave out the `uploadId` attribute. Provided repository\nURLs are normalized and validated as follows: One single colon must appear\nseparating the configuration section name and the path. The URL prefix up to\nthe colon must exist as a key in the config object below. No slashes must\nappear before the colon. Multiple back to back slashes are collapsed to one, as\n`..` and `.` are applied accordingly. Local repositories must be absolute\npaths and must begin with a `/`. Trailing `/` are removed.\n", "type": "string" }, "uploadId": { "description": "Upload ID to specify for which upload operation progress is queried or\nthe upload operation to abort.\nIf you specify this, leave out all the above body parameters.\n", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "If all is well, code 200 is returned if progress is inquired or the\noperation is aborted.\n" }, "202": { "description": "If all is well, code 202 is returned if a new operation is scheduled.\n" }, "400": { "description": "If the upload command is invoked with bad parameters or any HTTP\nmethod other than `POST`, then an *HTTP 400* is returned.\n" }, "401": { "description": "If the authentication to the remote repository fails, then an *HTTP\n400* is returned.\n" }, "404": { "description": "If a backup corresponding to the identifier `id` cannot be found, or if\nthere is no known upload operation with the given `uploadId`.\n" } }, "summary": "Upload a backup to a remote repository", "tags": [ "Hot Backups" ] } }, "/_admin/cluster/health": { "get": { "description": "Queries the health of the cluster as assessed by the supervision (Agency) for\nmonitoring purposes. The response is a JSON object, containing the standard\n`code`, `error`, `errorNum`, and `errorMessage` fields as appropriate.\nThe endpoint-specific fields are as follows:\n\n- `ClusterId`: A UUID string identifying the cluster\n- `Health`: An object containing a descriptive sub-object for each node in the cluster.\n - `\u003cnodeID\u003e`: Each entry in `Health` will be keyed by the node ID and contain the following attributes:\n - `Endpoint`: A string representing the network endpoint of the server.\n - `Role`: The role the server plays. Possible values are `\"AGENT\"`, `\"COORDINATOR\"`, and `\"DBSERVER\"`.\n - `CanBeDeleted`: Boolean representing whether the node can safely be removed from the cluster.\n - `Version`: Version String of ArangoDB used by that node.\n - `Engine`: Storage Engine used by that node.\n - `Status`: A string indicating the health of the node as assessed by the supervision (Agency). This should be considered primary source of truth for Coordinator and DB-Servers node health. If the node is responding normally to requests, it is `\"GOOD\"`. If it has missed one heartbeat, it is `\"BAD\"`. If it has been declared failed by the supervision, which occurs after missing heartbeats for about 15 seconds, it will be marked `\"FAILED\"`.\n\n Additionally it will also have the following attributes for:\n\n **Coordinators** and **DB-Servers**\n - `SyncStatus`: The last sync status reported by the node. This value is primarily used to determine the value of `Status`. Possible values include `\"UNKNOWN\"`, `\"UNDEFINED\"`, `\"STARTUP\"`, `\"STOPPING\"`, `\"STOPPED\"`, `\"SERVING\"`, `\"SHUTDOWN\"`.\n - `LastAckedTime`: ISO 8601 timestamp specifying the last heartbeat received.\n - `ShortName`: A string representing the shortname of the server, e.g. `\"Coordinator0001\"`.\n - `Timestamp`: ISO 8601 timestamp specifying the last heartbeat received. (deprecated)\n - `Host`: An optional string, specifying the host machine if known.\n - `SyncTime`: ISO 8601 timestamp of the last sync time reported by the node.\n\n **Coordinators** only\n - `AdvertisedEndpoint`: A string representing the advertised endpoint, if set. (e.g. external IP address or load balancer, optional)\n\n **Agents**\n - `Leader`: ID of the Agent this node regards as leader.\n - `Leading`: Whether this Agent is the leader (true) or not (false).\n - `LastAckedTime`: Time since last `acked` in seconds.\n", "operationId": "getClusterHealth", "responses": { "200": { "description": "is returned when everything went well.\n" } }, "summary": "Get the cluster health", "tags": [ "Cluster" ] } }, "/_admin/cluster/maintenance": { "put": { "description": "Enable or disable the cluster supervision (Agency) maintenance mode.\n\nThis endpoint allows you to temporarily enable the supervision maintenance mode.\nPlease be aware that no automatic failovers of any kind will take place\nwhile the maintenance mode is enabled. The cluster supervision reactivates\nitself automatically at some point after disabling it.\n", "operationId": "setClusterMaintenance", "requestBody": { "content": { "application/json": { "schema": { "description": "The mode to set for the cluster supervision.\n\nPossible values (always lowercase and in double quotes):\n- `\"on\"`: Enable the maintenance mode for 60 minutes, i.e. the\n supervision maintenance will reactivate itself after one hour.\n- `\"off\"`: Disable the maintenance mode.\n- `\"\u003cnumber\u003e\"`: Enable the maintenance mode for a different\n duration (in seconds) than the default 60 minutes. For example,\n `\"7200\"` enables the maintenance mode for 7200 seconds (2 hours).\n", "example": "on", "type": "string" } } } }, "responses": { "200": { "description": "is returned when everything went well.\n" }, "400": { "description": "if the request contained an invalid body\n" }, "501": { "description": "if the request was sent to a node other than a Coordinator or single-server\n" }, "504": { "description": "if the request timed out while enabling the maintenance mode\n" } }, "summary": "Set the cluster maintenance mode", "tags": [ "Cluster" ] } }, "/_admin/cluster/maintenance/{DB-Server-ID}": { "get": { "description": "Check whether the specified DB-Server is in maintenance mode and until when.\n", "operationId": "getDbserverMaintenance", "parameters": [ { "description": "The ID of a DB-Server.\n", "in": "path", "name": "DB-Server-ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "The result object with the status. This attribute is omitted if the DB-Server\nis in normal mode.\n", "properties": { "Mode": { "description": "The mode of the DB-Server. The value is `\"maintenance\"`.\n", "type": "string" }, "Until": { "description": "Until what date and time the maintenance mode currently lasts, in the\nISO 8601 date/time format.\n", "type": "string" } }, "required": [ "Mode", "Until" ], "type": "object" } }, "required": [ "error", "code" ], "type": "object" } } }, "description": "The request was successful.\n" }, "400": { "description": "if the request contained an invalid body\n" }, "412": { "description": "if the request was sent to an Agent node\n" }, "504": { "description": "if the request timed out while enabling the maintenance mode\n" } }, "summary": "Get the maintenance status of a DB-Server", "tags": [ "Cluster" ] }, "put": { "description": "Enable or disable the maintenance mode of a DB-Server.\n\nFor rolling upgrades or rolling restarts, DB-Servers can be put into\nmaintenance mode, so that no attempts are made to re-distribute the data in a\ncluster for such planned events. DB-Servers in maintenance mode are not\nconsidered viable failover targets because they are likely restarted soon.\n", "operationId": "setDbserverMaintenance", "parameters": [ { "description": "The ID of a DB-Server.\n", "in": "path", "name": "DB-Server-ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "mode": { "description": "The mode to set for the DB-Server.\n", "enum": [ "maintenance", "normal" ], "type": "string" }, "timeout": { "default": 3600, "description": "After how many seconds the maintenance mode shall automatically end.\nYou can send another request when the DB-Server is already in maintenance mode\nto extend the timeout.\n", "type": "integer" } }, "required": [ "mode" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The status code. `200` in this case.\n", "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" } }, "required": [ "error", "code" ], "type": "object" } } }, "description": "The request was successful.\n" }, "400": { "description": "if the request contained an invalid body\n" }, "412": { "description": "if the request was sent to an Agency node\n" }, "504": { "description": "if the request timed out while enabling the maintenance mode\n" } }, "summary": "Set the maintenance status of a DB-Server", "tags": [ "Cluster" ] } }, "/_admin/cluster/rebalance": { "get": { "description": "Computes the current cluster imbalance and returns the result.\nIt additionally shows the amount of ongoing and pending move shard operations.\n", "operationId": "getClusterImbalance", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "pendingMoveShards": { "description": "The number of pending move shard operations.\n", "type": "number" }, "result": { "description": "The result object.\n", "properties": { "leader": { "description": "Information about the leader imbalance.\n", "properties": { "imbalance": { "description": "The measure of the total imbalance. A high value indicates a high imbalance.\n", "type": "integer" }, "leaderDupl": { "description": "The measure of the leader shard distribution. The higher the number, the worse\nthe distribution.\n", "items": { "type": "integer" }, "type": "array" }, "numberShards": { "description": "The number of leader shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "targetWeight": { "description": "The ideal weight of leader shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "totalShards": { "description": "The sum of shards, counting leader shards only.\n", "type": "integer" }, "totalWeight": { "description": "The sum of all weights.\n", "type": "integer" }, "weightUsed": { "description": "The weight of leader shards per DB-Server. A leader has a weight of 1 by default\nbut it is higher if collections can only be moved together because of\n`distributeShardsLike`.\n", "items": { "type": "integer" }, "type": "array" } }, "required": [ "weightUsed", "targetWeight", "numberShards", "leaderDupl", "totalWeight", "imbalance", "totalShards" ], "type": "object" }, "shards": { "description": "Information about the shard imbalance.\n", "properties": { "imbalance": { "description": "The measure of the total imbalance. A high value indicates a high imbalance.\n", "type": "integer" }, "numberShards": { "description": "The number of leader and follower shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "sizeUsed": { "description": "The size of shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "targetSize": { "description": "The ideal size of shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "totalShards": { "description": "The sum of shards, counting leader and follower shards.\n", "type": "integer" }, "totalShardsFromSystemCollections": { "description": "The sum of system collection shards, counting leader shards only.\n", "type": "integer" }, "totalUsed": { "description": "The sum of the sizes.\n", "type": "integer" } }, "required": [ "sizeUsed", "targetSize", "numberShards", "totalUsed", "totalShards", "totalShardsFromSystemCollections", "imbalance" ], "type": "object" } }, "required": [ "leader", "shards" ], "type": "object" }, "todoMoveShards": { "description": "The number of planned move shard operations.\n", "type": "number" } }, "required": [ "code", "error", "result", "pendingMoveShards", "todoMoveShards" ], "type": "object" } } }, "description": "This API returns HTTP 200.\n" } }, "summary": "Get the current cluster imbalance", "tags": [ "Cluster" ] }, "post": { "description": "Compute a set of move shard operations to improve balance.\n", "operationId": "computeClusterRebalancePlan", "requestBody": { "content": { "application/json": { "schema": { "description": "The options for the rebalance plan.\n", "properties": { "databasesExcluded": { "default": [], "description": "A list of database names to exclude from the analysis.\n", "items": { "type": "string" }, "type": "array" }, "excludeSystemCollections": { "default": false, "description": "Ignore system collections in the rebalance plan.\n", "type": "boolean" }, "leaderChanges": { "default": true, "description": "Allow leader changes without moving data.\n", "type": "boolean" }, "maximumNumberOfMoves": { "default": 1000, "description": "Maximum number of moves to be computed.\n", "type": "integer" }, "moveFollowers": { "default": false, "description": "Allow moving followers.\n", "type": "boolean" }, "moveLeaders": { "default": false, "description": "Allow moving leaders.\n", "type": "boolean" }, "piFactor": { "default": 256000000, "description": "A weighting factor that should remain untouched.\n\nIf a collection has more shards than there are DB-Servers, there can be a subtle\nform of leader imbalance. Some DB-Servers may be responsible for more shards as\nleader than others. The `piFactor` adjusts how much weight such imbalances get\nin the overall imbalance score.\n", "type": "integer" }, "version": { "description": "Must be set to `1`.\n", "type": "number" } }, "required": [ "version" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The rebalance plan.\n", "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "The result object.\n", "properties": { "imbalanceAfter": { "description": "Expected imbalance after the suggested move shard operations are applied.\n", "properties": { "leader": { "description": "Information about the leader imbalance.\n", "properties": { "imbalance": { "description": "The measure of the total imbalance. A high value indicates a high imbalance.\n", "type": "integer" }, "leaderDupl": { "description": "The measure of the leader shard distribution. The higher the number, the worse\nthe distribution.\n", "items": { "type": "integer" }, "type": "array" }, "numberShards": { "description": "The number of leader shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "targetWeight": { "description": "The ideal weight of leader shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "totalShards": { "description": "The sum of shards, counting leader shards only.\n", "type": "integer" }, "totalWeight": { "description": "The sum of all weights.\n", "type": "integer" }, "weightUsed": { "description": "The weight of leader shards per DB-Server. A leader has a weight of 1 by default\nbut it is higher if collections can only be moved together because of\n`distributeShardsLike`.\n", "items": { "type": "integer" }, "type": "array" } }, "required": [ "weightUsed", "targetWeight", "numberShards", "leaderDupl", "totalWeight", "imbalance", "totalShards" ], "type": "object" }, "shards": { "description": "Information about the shard imbalance.\n", "properties": { "imbalance": { "description": "The measure of the total imbalance. A high value indicates a high imbalance.\n", "type": "integer" }, "numberShards": { "description": "The number of leader and follower shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "sizeUsed": { "description": "The size of shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "targetSize": { "description": "The ideal size of shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "totalShards": { "description": "The sum of shards, counting leader and follower shards.\n", "type": "integer" }, "totalShardsFromSystemCollections": { "description": "The sum of system collection shards, counting leader shards only.\n", "type": "integer" }, "totalUsed": { "description": "The sum of the sizes.\n", "type": "integer" } }, "required": [ "sizeUsed", "targetSize", "numberShards", "totalUsed", "totalShards", "totalShardsFromSystemCollections", "imbalance" ], "type": "object" } }, "required": [ "leader", "shards" ], "type": "object" }, "imbalanceBefore": { "description": "Imbalance before the suggested move shard operations are applied.\n", "properties": { "leader": { "description": "Information about the leader imbalance.\n", "properties": { "imbalance": { "description": "The measure of the total imbalance. A high value indicates a high imbalance.\n", "type": "integer" }, "leaderDupl": { "description": "The measure of the leader shard distribution. The higher the number, the worse\nthe distribution.\n", "items": { "type": "integer" }, "type": "array" }, "numberShards": { "description": "The number of leader shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "targetWeight": { "description": "The ideal weight of leader shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "totalShards": { "description": "The sum of shards, counting leader shards only.\n", "type": "integer" }, "totalWeight": { "description": "The sum of all weights.\n", "type": "integer" }, "weightUsed": { "description": "The weight of leader shards per DB-Server. A leader has a weight of 1 by default\nbut it is higher if collections can only be moved together because of\n`distributeShardsLike`.\n", "items": { "type": "integer" }, "type": "array" } }, "required": [ "weightUsed", "targetWeight", "numberShards", "leaderDupl", "totalWeight", "imbalance", "totalShards" ], "type": "object" }, "shards": { "description": "Information about the shard imbalance.\n", "properties": { "imbalance": { "description": "The measure of the total imbalance. A high value indicates a high imbalance.\n", "type": "integer" }, "numberShards": { "description": "The number of leader and follower shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "sizeUsed": { "description": "The size of shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "targetSize": { "description": "The ideal size of shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "totalShards": { "description": "The sum of shards, counting leader and follower shards.\n", "type": "integer" }, "totalShardsFromSystemCollections": { "description": "The sum of system collection shards, counting leader shards only.\n", "type": "integer" }, "totalUsed": { "description": "The sum of the sizes.\n", "type": "integer" } }, "required": [ "sizeUsed", "targetSize", "numberShards", "totalUsed", "totalShards", "totalShardsFromSystemCollections", "imbalance" ], "type": "object" } }, "required": [ "leader", "shards" ], "type": "object" }, "moves": { "description": "The suggested move shard operations.\n", "items": { "properties": { "collection": { "description": "Collection ID of the collection the shard belongs to.\n", "type": "number" }, "from": { "description": "The server name from which to move.\n", "type": "string" }, "isLeader": { "description": "True if this is a leader move shard operation.\n", "type": "boolean" }, "shard": { "description": "Shard ID of the shard to be moved.\n", "type": "string" }, "to": { "description": "The ID of the destination server.\n", "type": "string" } }, "required": [ "from", "to", "shard", "collection", "isLeader" ], "type": "object" }, "type": "array" } }, "required": [ "imbalanceBefore", "imbalanceAfter", "moves" ], "type": "object" } }, "required": [ "code", "error", "result" ], "type": "object" } } }, "description": "This API returns HTTP 200.\n" } }, "summary": "Compute a set of move shard operations to improve balance", "tags": [ "Cluster" ] }, "put": { "description": "Compute a set of move shard operations to improve balance.\nThese moves are then immediately executed.\n", "operationId": "startClusterRebalance", "requestBody": { "content": { "application/json": { "schema": { "description": "The options for the rebalancing.\n", "properties": { "databasesExcluded": { "default": [], "description": "A list of database names to exclude from the analysis.\n", "items": { "type": "string" }, "type": "array" }, "excludeSystemCollections": { "default": false, "description": "Ignore system collections in the rebalance plan.\n", "type": "boolean" }, "leaderChanges": { "default": true, "description": "Allow leader changes without moving data.\n", "type": "boolean" }, "maximumNumberOfMoves": { "default": 1000, "description": "Maximum number of moves to be computed.\n", "type": "integer" }, "moveFollowers": { "default": false, "description": "Allow moving followers.\n", "type": "boolean" }, "moveLeaders": { "default": false, "description": "Allow moving leaders.\n", "type": "boolean" }, "piFactor": { "default": 256000000, "description": "A weighting factor that should remain untouched.\n\nIf a collection has more shards than there are DB-Servers, there can be a subtle\nform of leader imbalance. Some DB-Servers may be responsible for more shards as\nleader than others. The `piFactor` adjusts how much weight such imbalances get\nin the overall imbalance score.\n", "type": "integer" }, "version": { "description": "Must be set to `1`.\n", "type": "number" } }, "required": [ "version" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The executed move shard operations.\n", "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "The result object.\n", "properties": { "imbalanceAfter": { "description": "Expected imbalance after the suggested move shard operations are applied.\n", "properties": { "leader": { "description": "Information about the leader imbalance.\n", "properties": { "imbalance": { "description": "The measure of the total imbalance. A high value indicates a high imbalance.\n", "type": "integer" }, "leaderDupl": { "description": "The measure of the leader shard distribution. The higher the number, the worse\nthe distribution.\n", "items": { "type": "integer" }, "type": "array" }, "numberShards": { "description": "The number of leader shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "targetWeight": { "description": "The ideal weight of leader shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "totalShards": { "description": "The sum of shards, counting leader shards only.\n", "type": "integer" }, "totalWeight": { "description": "The sum of all weights.\n", "type": "integer" }, "weightUsed": { "description": "The weight of leader shards per DB-Server. A leader has a weight of 1 by default\nbut it is higher if collections can only be moved together because of\n`distributeShardsLike`.\n", "items": { "type": "integer" }, "type": "array" } }, "required": [ "weightUsed", "targetWeight", "numberShards", "leaderDupl", "totalWeight", "imbalance", "totalShards" ], "type": "object" }, "shards": { "description": "Information about the shard imbalance.\n", "properties": { "imbalance": { "description": "The measure of the total imbalance. A high value indicates a high imbalance.\n", "type": "integer" }, "numberShards": { "description": "The number of leader and follower shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "sizeUsed": { "description": "The size of shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "targetSize": { "description": "The ideal size of shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "totalShards": { "description": "The sum of shards, counting leader and follower shards.\n", "type": "integer" }, "totalShardsFromSystemCollections": { "description": "The sum of system collection shards, counting leader shards only.\n", "type": "integer" }, "totalUsed": { "description": "The sum of the sizes.\n", "type": "integer" } }, "required": [ "sizeUsed", "targetSize", "numberShards", "totalUsed", "totalShards", "totalShardsFromSystemCollections", "imbalance" ], "type": "object" } }, "required": [ "leader", "shards" ], "type": "object" }, "imbalanceBefore": { "description": "Imbalance before the suggested move shard operations are applied.\n", "properties": { "leader": { "description": "Information about the leader imbalance.\n", "properties": { "imbalance": { "description": "The measure of the total imbalance. A high value indicates a high imbalance.\n", "type": "integer" }, "leaderDupl": { "description": "The measure of the leader shard distribution. The higher the number, the worse\nthe distribution.\n", "items": { "type": "integer" }, "type": "array" }, "numberShards": { "description": "The number of leader shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "targetWeight": { "description": "The ideal weight of leader shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "totalShards": { "description": "The sum of shards, counting leader shards only.\n", "type": "integer" }, "totalWeight": { "description": "The sum of all weights.\n", "type": "integer" }, "weightUsed": { "description": "The weight of leader shards per DB-Server. A leader has a weight of 1 by default\nbut it is higher if collections can only be moved together because of\n`distributeShardsLike`.\n", "items": { "type": "integer" }, "type": "array" } }, "required": [ "weightUsed", "targetWeight", "numberShards", "leaderDupl", "totalWeight", "imbalance", "totalShards" ], "type": "object" }, "shards": { "description": "Information about the shard imbalance.\n", "properties": { "imbalance": { "description": "The measure of the total imbalance. A high value indicates a high imbalance.\n", "type": "integer" }, "numberShards": { "description": "The number of leader and follower shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "sizeUsed": { "description": "The size of shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "targetSize": { "description": "The ideal size of shards per DB-Server.\n", "items": { "type": "integer" }, "type": "array" }, "totalShards": { "description": "The sum of shards, counting leader and follower shards.\n", "type": "integer" }, "totalShardsFromSystemCollections": { "description": "The sum of system collection shards, counting leader shards only.\n", "type": "integer" }, "totalUsed": { "description": "The sum of the sizes.\n", "type": "integer" } }, "required": [ "sizeUsed", "targetSize", "numberShards", "totalUsed", "totalShards", "totalShardsFromSystemCollections", "imbalance" ], "type": "object" } }, "required": [ "leader", "shards" ], "type": "object" }, "moves": { "description": "The suggested move shard operations.\n", "items": { "properties": { "collection": { "description": "Collection ID of the collection the shard belongs to.\n", "type": "number" }, "from": { "description": "The server name from which to move.\n", "type": "string" }, "isLeader": { "description": "True if this is a leader move shard operation.\n", "type": "boolean" }, "shard": { "description": "Shard ID of the shard to be moved.\n", "type": "string" }, "to": { "description": "The ID of the destination server.\n", "type": "string" } }, "required": [ "from", "to", "shard", "collection", "isLeader" ], "type": "object" }, "type": "array" } }, "required": [ "imbalanceBefore", "imbalanceAfter", "moves" ], "type": "object" } }, "required": [ "code", "error", "result" ], "type": "object" } } }, "description": "This API returns HTTP 200.\n" } }, "summary": "Compute and execute a set of move shard operations to improve balance", "tags": [ "Cluster" ] } }, "/_admin/cluster/rebalance/execute": { "post": { "description": "Execute the given set of move shard operations. You can use the\n`POST /_admin/cluster/rebalance` endpoint to calculate these operations to improve\nthe balance of shards, leader shards, and follower shards.\n", "operationId": "executeClusterRebalancePlan", "requestBody": { "content": { "application/json": { "schema": { "properties": { "moves": { "description": "A set of move shard operations to execute.\n", "items": { "properties": { "collection": { "description": "Collection ID of the collection the shard belongs to.\n", "type": "number" }, "from": { "description": "The server name from which to move.\n", "type": "string" }, "isLeader": { "description": "True if this is a leader move shard operation.\n", "type": "boolean" }, "shard": { "description": "Shard ID of the shard to be moved.\n", "type": "string" }, "to": { "description": "The ID of the destination server.\n", "type": "string" } }, "required": [ "from", "to", "shard", "collection", "isLeader" ], "type": "object" }, "type": "array" }, "version": { "description": "Must be set to `1`.\n", "type": "number" } }, "required": [ "version", "moves" ], "type": "object" } } } }, "responses": { "200": { "description": "This API returns HTTP 200 if no operations are provided.\n" }, "202": { "description": "This API returns HTTP 202 if the operations have been accepted and scheduled for execution.\n" } }, "summary": "Execute a set of move shard operations", "tags": [ "Cluster" ] } }, "/_admin/cluster/statistics": { "get": { "deprecated": true, "description": "\u003e **WARNING:**\nThis endpoint is deprecated and removed in ArangoDB v4.0.\nUse `GET /_admin/metrics` instead, which provides the data exposed by\nthis API and a lot more.\n\n\nQueries the statistics of the given DB-Server\n", "operationId": "getClusterStatistics", "parameters": [ { "description": "The ID of a DB-Server.\n", "in": "query", "name": "DBserver", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned when everything went well.\n" }, "400": { "description": "The `DBserver` parameter was not specified or is not the ID of a DB-Server.\n" }, "403": { "description": "The specified server is not a DB-Server.\n" } }, "summary": "Get the statistics of a DB-Server", "tags": [ "Cluster" ] } }, "/_admin/cluster/uniqId": { "put": { "description": "Reserve or skip globally unique identifiers that are used as automatically\ngenerated document keys when using the `traditional` or `padded` key generators.\n\nEither the `number` or the `minimum` query parameter needs to be specified.\n\n\u003e **WARNING:**\nOnly use this endpoint to resolve issues with the key generation,\nin particular of cluster deployments created with v3.12.5-2 or older.\n", "operationId": "reserveUniqueIDs", "parameters": [ { "description": "Reserve as many globally unique IDs as specified.\n", "in": "query", "name": "number", "schema": { "maximum": 1000000, "minimum": 1, "type": "integer" } }, { "description": "Make sure that globally unique IDs used in the future will always be\nat least as large as the specified value.\n\nCoordinators and DB-Servers will use these larger IDs only after a restart.\n", "in": "query", "name": "minimum", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The range of the reserved/skipped IDs.\n", "properties": { "code": { "description": "The status code.\n", "example": 200, "type": "integer" }, "error": { "description": "Whether an error occurred. `false` in this case.\n", "type": "boolean" }, "largest": { "description": "The upper bound of the IDs that have been reserved (`number`)\nrespectively skipped (`minimum`).\n", "type": "string" }, "smallest": { "description": "The lower bound of the IDs that have been reserved (`number`)\nrespectively skipped (`minimum`).\n", "type": "string" } }, "required": [ "code", "error", "smallest", "largest" ], "type": "object" } } }, "description": "Successfully reserved/skipped the globally unique IDs.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Either the `number` or the `minimum` query parameter must be provided.\n" } }, "summary": "Reserve globally unique IDs", "tags": [ "Cluster" ] } }, "/_admin/compact": { "put": { "description": "\u003e **WARNING:**\nThis command can cause a full rewrite of all data in all databases, which may\ntake very long for large databases. It should thus only be used with care and\nonly when additional I/O load can be tolerated for a prolonged time.\n\n\nThis endpoint can be used to reclaim disk space after substantial data\ndeletions have taken place, by compacting the entire database system data.\n\nThe endpoint requires superuser access.\n", "operationId": "compactAllDatabases", "requestBody": { "content": { "application/json": { "schema": { "properties": { "changeLevel": { "default": false, "description": "whether or not compacted data should be moved to the minimum possible level.\n", "type": "boolean" }, "compactBottomMostLevel": { "default": false, "description": "Whether or not to compact the bottommost level of data.\n", "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Compaction started successfully\n" }, "401": { "description": "if the request was not authenticated as a user with sufficient rights\n" } }, "summary": "Compact all databases", "tags": [ "Administration" ] } }, "/_admin/database/target-version": { "get": { "deprecated": true, "description": "\u003e **WARNING:**\nThis endpoint is deprecated and should no longer be used.\nIt is removed in ArangoDB v4.0. Use `GET /_api/version` instead.\n\n\nReturns the database version that this server requires.\nThe version is returned in the `version` attribute of the result.\n", "operationId": "getDatabaseVersion", "responses": { "200": { "description": "Is returned in all cases.\n" } }, "summary": "Get the required database version (deprecated)", "tags": [ "Administration" ] } }, "/_admin/log": { "get": { "deprecated": true, "description": "\u003e **WARNING:**\nThis endpoint should no longer be used. It is deprecated from version\n3.8.0 onward and removed in ArangoDB 4.0.\nUse `/_admin/log/entries` instead, which provides the same data in a more\nintuitive and easier to process format.\n\n\nReturns fatal, error, warning or info log messages from the server's global log.\nThe result is a JSON object with the attributes described below.\n\nThis API can be turned off via the startup option `--log.api-enabled`. In case\nthe API is disabled, all requests will be responded to with HTTP 403. If the\nAPI is enabled, accessing it requires admin privileges, or even superuser\nprivileges, depending on the value of the `--log.api-enabled` startup option.\n", "operationId": "getLog", "parameters": [ { "description": "Returns all log entries up to log level `upto`. Note that `upto` must be:\n- `fatal` or `0`\n- `error` or `1`\n- `warning` or `2`\n- `info` or `3`\n- `debug` or `4`\n- `trace` or `5`\n", "in": "query", "name": "upto", "required": false, "schema": { "default": "info" } }, { "description": "Returns all log entries of log level `level`. Note that the query parameters\n`upto` and `level` are mutually exclusive.\n", "in": "query", "name": "level", "required": false, "schema": { "type": "string" } }, { "description": "Returns all log entries such that their log entry identifier (`lid` value)\nis greater or equal to `start`.\n", "in": "query", "name": "start", "required": false, "schema": { "default": 0, "type": "number" } }, { "description": "Restricts the result to at most `size` log entries.\n", "in": "query", "name": "size", "required": false, "schema": { "type": "number" } }, { "description": "Starts to return log entries skipping the first `offset` log entries. `offset`\nand `size` can be used for pagination.\n", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "type": "number" } }, { "description": "Only return the log entries containing the text specified in `search`.\n", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } }, { "description": "Sort the log entries either ascending (if `sort` is `asc`) or descending\n(if `sort` is `desc`) according to their `lid` values. Note that the `lid`\nimposes a chronological order.\n", "in": "query", "name": "sort", "required": false, "schema": { "default": "asc", "type": "string" } }, { "description": "Returns all log entries of the specified server. All other query parameters\nremain valid. If no serverId is given, the asked server\nwill reply. This parameter is only meaningful on Coordinators.\n", "in": "query", "name": "serverId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "level": { "description": "A list of the log levels for all log entries.\n", "type": "string" }, "lid": { "description": "a list of log entry identifiers. Each log message is uniquely\nidentified by its @LIT{lid} and the identifiers are in ascending\norder.\n", "items": { "type": "string" }, "type": "array" }, "text": { "description": "a list of the texts of all log entries\n", "type": "string" }, "timestamp": { "description": "a list of the timestamps as seconds since 1970-01-01 for all log\nentries.\n", "items": { "type": "string" }, "type": "array" }, "topic": { "description": "a list of the topics of all log entries\n", "type": "string" }, "totalAmount": { "description": "the total amount of log entries before pagination.\n", "type": "integer" } }, "required": [ "lid", "level", "timestamp", "text", "topic", "totalAmount" ], "type": "object" } } }, "description": "" }, "400": { "description": "is returned if invalid values are specified for `upto` or `level`.\n" }, "403": { "description": "is returned if there are insufficient privileges to access the logs.\n" } }, "summary": "Get the global server logs (deprecated)", "tags": [ "Monitoring" ] } }, "/_admin/log/entries": { "get": { "description": "Returns fatal, error, warning or info log messages from the server's global log.\nThe result is a JSON object with the following properties:\n\n- **total**: the total amount of log entries before pagination\n- **messages**: an array with log messages that matched the criteria\n\nThis API can be turned off via the startup option `--log.api-enabled`. In case\nthe API is disabled, all requests will be responded to with HTTP 403. If the\nAPI is enabled, accessing it requires admin privileges, or even superuser\nprivileges, depending on the value of the `--log.api-enabled` startup option.\n", "operationId": "getLogEntries", "parameters": [ { "description": "Returns all log entries up to log level `upto`. Note that `upto` must be:\n- `fatal` or `0`\n- `error` or `1`\n- `warning` or `2`\n- `info` or `3`\n- `debug` or `4`\n- `trace` or `5`\n", "in": "query", "name": "upto", "required": false, "schema": { "default": "info" } }, { "description": "Returns all log entries of log level `level`. Note that the query parameters\n`upto` and `level` are mutually exclusive.\n", "in": "query", "name": "level", "required": false, "schema": { "type": "string" } }, { "description": "Returns all log entries such that their log entry identifier (`id` value)\nis greater or equal to `start`.\n", "in": "query", "name": "start", "required": false, "schema": { "default": 0, "type": "number" } }, { "description": "Restricts the result to at most `size` log entries.\n", "in": "query", "name": "size", "required": false, "schema": { "type": "number" } }, { "description": "Starts to return log entries skipping the first `offset` log entries. `offset`\nand `size` can be used for pagination.\n", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "type": "number" } }, { "description": "Only return the log entries containing the text specified in `search`.\n", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } }, { "description": "Sort the log entries either ascending (if `sort` is `asc`) or descending\n(if `sort` is `desc`) according to their `id` values. Note that the `id`\nimposes a chronological order.\n", "in": "query", "name": "sort", "required": false, "schema": { "default": "asc", "type": "string" } }, { "description": "Returns all log entries of the specified server. All other query parameters\nremain valid. If no serverId is given, the asked server\nwill reply. This parameter is only meaningful on Coordinators.\n", "in": "query", "name": "serverId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the request is valid.\n" }, "400": { "description": "is returned if invalid values are specified for `upto` or `level`.\n" }, "403": { "description": "is returned if there are insufficient privileges to access the logs.\n" } }, "summary": "Get the global server logs", "tags": [ "Monitoring" ] } }, "/_admin/log/level": { "delete": { "description": "Revert the server's log level settings to the values they had at startup,\nas determined by the startup options specified on the command-line, a\nconfiguration file, and the factory defaults.\n\nThe result is a JSON object with the log topics being the object keys, and\nthe log levels being the object values.\n\nThis API can be turned off via the startup option `--log.api-enabled`. In case\nthe API is disabled, all requests will be responded to with HTTP 403. If the\nAPI is enabled, accessing it requires admin privileges, or even superuser\nprivileges, depending on the value of the `--log.api-enabled` startup option.\n", "operationId": "resetLogLevel", "parameters": [ { "description": "Forwards the request to the specified server.\n", "in": "query", "name": "serverId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The log levels have been reset successfully.\n" }, "403": { "description": "You have insufficient privileges to reset the log levels.\n" } }, "summary": "Reset the server log levels", "tags": [ "Monitoring" ] }, "get": { "description": "Returns the server's current log level settings.\nThe result is a JSON object with the log topics being the object keys, and\nthe log levels being the object values.\n\nThis API can be turned off via the startup option `--log.api-enabled`. In case\nthe API is disabled, all requests will be responded to with HTTP 403. If the\nAPI is enabled, accessing it requires admin privileges, or even superuser\nprivileges, depending on the value of the `--log.api-enabled` startup option.\n", "operationId": "getLogLevel", "parameters": [ { "description": "Forwards the request to the specified server.\n", "in": "query", "name": "serverId", "required": false, "schema": { "type": "string" } }, { "description": "Set this option to `true` to return the individual log level settings\nof all log outputs (`appenders`) as well as the `global` settings.\n\nThe response structure is as follows:\n\n```json\n{\n \"global\": {\n \"agency\": \"INFO\",\n \"agencycomm\": \"INFO\",\n \"agencystore\": \"WARNING\",\n ...\n },\n \"appenders\": {\n \"-\": {\n \"agency\": \"INFO\",\n \"agencycomm\": \"INFO\",\n \"agencystore\": \"WARNING\",\n ...\n },\n \"file:///path/to/file\": {\n \"agency\": \"INFO\",\n \"agencycomm\": \"INFO\",\n \"agencystore\": \"WARNING\",\n ...\n },\n ...\n }\n}\n```\n", "in": "query", "name": "withAppenders", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "is returned if the request is valid\n" }, "403": { "description": "is returned if there are insufficient privileges to read log levels.\n" } }, "summary": "Get the server log levels", "tags": [ "Monitoring" ] }, "put": { "description": "Modifies and returns the server's current log level settings.\nThe request body must be a JSON string with a log level or a JSON object with the\nlog topics being the object keys and the log levels being the object values.\n\nIf only a JSON string is specified as input, the log level is adjusted for the\n\"general\" log topic only. If a JSON object is specified as input, the log levels will\nbe set only for the log topic mentioned in the input object, but preserved for every\nother log topic.\nTo set the log level for all log levels to a specific value, it is possible to hand\nin the special pseudo log topic \"all\".\n\nThe result is a JSON object with all available log topics being the object keys, and\nthe adjusted log levels being the object values.\n\nPossible log levels are:\n- `FATAL` - Only critical errors are logged after which the _arangod_\n process terminates.\n- `ERROR` - Only errors are logged. You should investigate and fix errors\n as they may harm your production.\n- `WARNING` - Errors and warnings are logged. Warnings may be serious\n application-wise and can indicate issues that might lead to errors\n later on.\n- `INFO` - Errors, warnings, and general information is logged.\n- `DEBUG` - Outputs debug messages used in the development of ArangoDB\n in addition to the above.\n- `TRACE` - Logs detailed tracing of operations in addition to the above.\n This can flood the log. Don't use this log level in production.\n\nThis API can be turned off via the startup option `--log.api-enabled`. In case\nthe API is disabled, all requests will be responded to with HTTP 403. If the\nAPI is enabled, accessing it requires admin privileges, or even superuser\nprivileges, depending on the value of the `--log.api-enabled` startup option.\n", "operationId": "setLogLevel", "parameters": [ { "description": "Forwards the request to the specified server.\n", "in": "query", "name": "serverId", "required": false, "schema": { "type": "string" } }, { "description": "Set this option to `true` to set individual log level settings\nfor log outputs (`appenders`). The request and response structure is\nas follows:\n\n```json\n{\n \"global\": {\n \"agency\": \"INFO\",\n \"agencycomm\": \"INFO\",\n \"agencystore\": \"WARNING\",\n ...\n },\n \"appenders\": {\n \"-\": {\n \"agency\": \"INFO\",\n \"agencycomm\": \"INFO\",\n \"agencystore\": \"WARNING\",\n ...\n },\n \"file:///path/to/file\": {\n \"agency\": \"INFO\",\n \"agencycomm\": \"INFO\",\n \"agencystore\": \"WARNING\",\n ...\n },\n ...\n }\n}\n```\n\nChanging the `global` settings affects all outputs and is the same\nas setting a log level with this option turned off.\n", "in": "query", "name": "withAppenders", "required": false, "schema": { "default": false, "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "agency": { "description": "Agents use this log topic to inform about any activity\nincluding the RAFT consensus gossip.\n", "type": "string" }, "agencycomm": { "description": "DB-Servers and Coordinators log the requests they send to the\nAgency.\n", "type": "string" }, "agencystore": { "description": "Optional verbose logging of Agency write operations.\n", "type": "string" }, "all": { "description": "Pseudo-topic to address all log topics.\n", "type": "string" }, "aql": { "description": "Logs information about the AQL query optimization and\nexecution. DB-Servers and Coordinators log the cluster-internal\ncommunication around AQL queries. It also reports the AQL\nmemory limit on startup.\n", "type": "string" }, "arangosearch": { "description": "Logs information related to ArangoSearch including Analyzers,\nthe column cache, and the commit and consolidation threads.\n", "type": "string" }, "audit-authentication": { "description": "Controls whether events such as successful logins and\nmissing or wrong credentials are written to the audit log.\n", "type": "string" }, "audit-authorization": { "description": "Controls whether events such as users trying to access databases\nwithout the necessary permissions are written to the audit log.\n", "type": "string" }, "audit-collection": { "description": "Controls whether events about collections creation, truncation,\nand deletion are written to the audit log.\n", "type": "string" }, "audit-database": { "description": "Controls whether events about database creation and deletion\nare written to the audit log.\n", "type": "string" }, "audit-document": { "description": "Controls whether document read and write events are written\nto the audit log.\n", "type": "string" }, "audit-hotbackup": { "description": "Controls whether the Hot Backup creation, restore, and delete\nevents are written to the audit log.\n", "type": "string" }, "audit-service": { "description": "Controls whether the start and stop events of the audit\nservice are written to the audit log.\n", "type": "string" }, "audit-view": { "description": "Controls whether events about View creation and deletion\nare written to the audit log.\n", "type": "string" }, "authentication": { "description": "Logs events related to authentication, for example, when a\nJWT secret is generated or a token is validated against a secret.\n", "type": "string" }, "authorization": { "description": "Logs when a user has insufficient permissions for a request.\n", "type": "string" }, "backup": { "description": "Logs events related to Hot Backup.\n", "type": "string" }, "bench": { "description": "Logs events related to benchmarking with _arangobench_.\n", "type": "string" }, "cache": { "description": "Logs events related to caching documents and index entries\nas well as the cache configuration on startup.\n", "type": "string" }, "cluster": { "description": "Logs information related to the cluster-internal communication\nas well as cluster operations. This includes changes to the\nstate and readiness of DB-Servers and connectivity checks\non Coordinators.\n", "type": "string" }, "communication": { "description": "Logs lower-level network connection and communication events.\n", "type": "string" }, "config": { "description": "Logs information related to the startup options and server\nconfiguration.\n", "type": "string" }, "crash": { "description": "Logs information about a fatal error including a backtrace\nbefore the process terminates.\n", "type": "string" }, "deprecation": { "description": "Warns about deprecated features and the usage of options that\nwill not be allowed or have no effect in a future version.\n", "type": "string" }, "development": { "description": "This log topic is reserved for the development of ArangoDB.\n", "type": "string" }, "dump": { "description": "Logs events related to dumping data with _arangodump_.\n", "type": "string" }, "engines": { "description": "Logs various information related to ArangoDB's use of the\nRocksDB storage engine, like the initialization and\nfile operations.\n\nRocksDB's internal log messages are passed through using the\n`rocksdb` log topic.\n", "type": "string" }, "flush": { "description": "Logs events related to flushing data from memory to disk.\n", "type": "string" }, "general": { "description": "Logs all messages of general interest and that don't fit\nunder any of the other log topics. For example, it reports\nthe ArangoDB version and the detected operating system and\nmemory on startup.\n", "type": "string" }, "graphs": { "description": "Logs information related to graph operations including\ngraph traversal and path search tracing.\n", "type": "string" }, "heartbeat": { "description": "Logs everything related to the cluster heartbeat for\nmonitoring the intra-connectivity.\n", "type": "string" }, "httpclient": { "description": "Logs the activity of the HTTP request subsystem that is used\nin replication, client tools, and V8.\n", "type": "string" }, "libiresearch": { "description": "Logs the internal log messages of IResearch, the underlying\nlibrary of ArangoSearch.\n", "type": "string" }, "license": { "description": "Logs events related to the license management like the\nexpiration of a license.\n", "type": "string" }, "maintenance": { "description": "Logs the operations of the cluster maintenance including\nshard locking and collection creation.\n", "type": "string" }, "memory": { "description": "Logs the memory configuration on startup and reports\nproblems with memory alignment and operating system settings.\n", "type": "string" }, "queries": { "description": "Logs slow queries as well as internal details about the\nexecution of AQL queries at low log levels.\n", "type": "string" }, "replication": { "description": "Logs information related to the data replication within a cluster.\n", "type": "string" }, "requests": { "description": "Logs the handling of internal and external requests and\ncan include IP addresses, endpoints, and HTTP headers and\nbodies when using low log levels.\n\nIt overlaps with the network `communication` log topic.\n", "type": "string" }, "restore": { "description": "This log topic is only used by _arangorestore_.\n", "type": "string" }, "rocksdb": { "description": "Logs RocksDB's internal log messages as well RocksDB\nbackground errors.\n\nInformation related to ArangoDB's use of the\nRocksDB storage engine uses the `engines` log topic.\n", "type": "string" }, "security": { "description": "Logs the security configuration for V8.\n", "type": "string" }, "ssl": { "description": "Logs information related to the in-transit encryption of\nnetwork communication using SSL/TLS.\n", "type": "string" }, "startup": { "description": "Logs information related to the startup and shutdown of a\nserver process as well as anything related to upgrading the\ndatabase directory.\n", "type": "string" }, "statistics": { "description": "Logs events related to processing server statistics.\nThis is independent of server metrics.\n", "type": "string" }, "supervision": { "description": "Logs information related to the Agency's cluster supervision.\n", "type": "string" }, "syscall": { "description": "Logs events related to calling operating system functions.\nIt reports problems related to file descriptors and the\nserver process monitoring.\n", "type": "string" }, "threads": { "description": "Logs information related to the use of operating system\nthreads and the threading configuration of ArangoDB.\n", "type": "string" }, "trx": { "description": "Logs information about transaction management.\n", "type": "string" }, "ttl": { "description": "Logs the activity of the background thread for\ntime-to-live (TTL) indexes.\n", "type": "string" }, "v8": { "description": "Logs various information related to ArangoDB's use of the\nV8 JavaScript engine, like the initialization as well as\nentering and exiting contexts.\n", "type": "string" }, "validation": { "description": "Logs when the schema validation fails for a document.\n", "type": "string" }, "views": { "description": "Logs certain events related to ArangoSearch Views.\n", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "is returned if the request is valid\n" }, "400": { "description": "is returned when the request body contains invalid JSON.\n" }, "403": { "description": "is returned if there are insufficient privileges to adjust log levels.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" } }, "summary": "Set the server log levels", "tags": [ "Monitoring" ] } }, "/_admin/log/structured": { "get": { "description": "Returns the server's current structured log settings.\nThe result is a JSON object with the log parameters being the object keys, and\n`true` or `false` being the object values, meaning the parameters are either\nenabled or disabled.\n\nThis API can be turned off via the startup option `--log.api-enabled`. In case\nthe API is disabled, all requests will be responded to with HTTP 403. If the\nAPI is enabled, accessing it requires admin privileges, or even superuser\nprivileges, depending on the value of the `--log.api-enabled` startup option.\n", "operationId": "getStructuredLog", "responses": { "200": { "description": "is returned if the request is valid\n" }, "403": { "description": "is returned if there are insufficient privileges to read structured log\nparameters.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" } }, "summary": "Get the structured log settings", "tags": [ "Monitoring" ] }, "put": { "description": "Modifies and returns the server's current structured log settings.\nThe request body must be a JSON object with the structured log parameters\nbeing the object keys and `true` or `false` object values, for either\nenabling or disabling the parameters.\n\nThe result is a JSON object with all available structured log parameters being\nthe object keys, and `true` or `false` being the object values, meaning the\nparameter in the object key is either enabled or disabled.\n\nThis API can be turned off via the startup option `--log.api-enabled`. In case\nthe API is disabled, all requests will be responded to with HTTP 403. If the\nAPI is enabled, accessing it requires admin privileges, or even superuser\nprivileges, depending on the value of the `--log.api-enabled` startup option.\n", "operationId": "setStructuredLog", "requestBody": { "content": { "application/json": { "schema": { "properties": { "database": { "description": "One of the possible log parameters.\n", "type": "boolean" }, "url": { "description": "One of the possible log parameters.\n", "type": "boolean" }, "username": { "description": "One of the possible log parameters.\n", "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "is returned if the request is valid\n" }, "403": { "description": "is returned if there are insufficient privileges to adjust log levels.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" } }, "summary": "Set the structured log settings", "tags": [ "Monitoring" ] } }, "/_admin/server/availability": { "get": { "description": "Return availability information about a server.\n\nThe response is a JSON object with an attribute \"mode\". The \"mode\" can either\nbe \"readonly\", if the server is in read-only mode, or \"default\", if it is not.\nPlease note that the JSON object with \"mode\" is only returned in case the server\ndoes not respond with HTTP response code 503.\n\nThis is a public API so it does *not* require authentication. It is meant to be\nused only in the context of server monitoring.\n", "operationId": "getServerAvailability", "responses": { "200": { "description": "This API will return HTTP 200 in case the server is up and running and usable for\narbitrary operations, is not set to read-only mode.\n" }, "503": { "description": "HTTP 503 will be returned during startup and shutdown, and in case\nthe server is set to read-only mode.\n\nIn addition, HTTP 503 will be returned in case the fill grade of the scheduler\nqueue exceeds the configured high-water mark (adjustable via startup option\n`--server.unavailability-queue-fill-grade`), which by default is set to 75 % of\nthe maximum queue length.\n" } }, "summary": "Return whether or not a server is available", "tags": [ "Administration" ] } }, "/_admin/server/encryption": { "post": { "description": "Change the user-supplied encryption at rest key by sending a request without\npayload to this endpoint. The file supplied via `--rocksdb.encryption-keyfolder`\nwill be reloaded and the internal encryption key will be re-encrypted with the\nnew user key.\n\nThis is a protected API and can only be executed with superuser rights.\nThis API is not available on Coordinator nodes.\n", "operationId": "rotateEncryptionAtRestKey", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "The result object.\n", "properties": { "encryption-keys": { "description": "An array of objects with the SHA-256 hashes of the key secrets.\nCan be empty.\n", "items": { "type": "object" }, "type": "array" } }, "required": [ "encryption-keys" ], "type": "object" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "This API will return HTTP 200 if everything is ok\n" }, "403": { "description": "This API will return HTTP 403 FORBIDDEN if it is not called with\nsuperuser rights.\n" }, "404": { "description": "This API will return HTTP 404 in case encryption key rotation is disabled.\n" } }, "summary": "Rotate the encryption at rest key", "tags": [ "Security" ] } }, "/_admin/server/id": { "get": { "description": "Returns the ID of a server in a cluster. The request will fail if the\nserver is not running in cluster mode.\n", "operationId": "getServerId", "responses": { "200": { "description": "Is returned when the server is running in cluster mode.\n" }, "500": { "description": "Is returned when the server is not running in cluster mode.\n" } }, "summary": "Get the server ID", "tags": [ "Cluster" ] } }, "/_admin/server/jwt": { "post": { "description": "Sending a request without payload to this endpoint reloads the JWT secret(s)\nfrom disk. Only the files specified via the arangod startup option\n`--server.jwt-secret-keyfile` or `--server.jwt-secret-folder` are used.\nIt is not possible to change the locations where files are loaded from\nwithout restarting the process.\n\nTo utilize the API a superuser JWT token is necessary, otherwise the response\nwill be _HTTP 403 Forbidden_.\n", "operationId": "reloadServerJwtSecrets", "responses": { "200": { "content": { "application/json": { "schema": { "description": "The reply with the JWT secrets information.\n", "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "The result object.\n", "properties": { "active": { "description": "An object with the SHA-256 hash of the active secret.\n", "type": "object" }, "passive": { "description": "An array of objects with the SHA-256 hashes of the passive secrets.\n\nCan be empty.\n", "items": { "type": "object" }, "type": "array" } }, "required": [ "active", "passive" ], "type": "object" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "Successfully reloaded the JWT secrets.\n" }, "403": { "description": "if the request was not authenticated as a user with sufficient rights\n" } }, "summary": "Hot-reload the JWT secret(s) from disk", "tags": [ "Authentication" ] } }, "/_admin/server/role": { "get": { "description": "Returns the role of a server in a cluster.\nThe server role is returned in the `role` attribute of the result.\n", "operationId": "getServerRole", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" }, "role": { "description": "The server role.\n- `SINGLE`: the server is a standalone server without clustering\n- `COORDINATOR`: the server is a Coordinator in a cluster\n- `PRIMARY`: the server is a DB-Server in a cluster\n- `SECONDARY`: this role is not used anymore\n- `AGENT`: the server is an Agency node in a cluster\n- `UNDEFINED`: in a cluster, this is returned if the server role cannot be\n determined.\n", "enum": [ "SINGLE", "COORDINATOR", "PRIMARY", "SECONDARY", "AGENT", "UNDEFINED" ], "type": "string" } }, "required": [ "error", "code", "errorNum", "role" ], "type": "object" } } }, "description": "Is returned in all cases.\n" } }, "summary": "Get the server role", "tags": [ "Cluster" ] } }, "/_admin/server/tls": { "post": { "description": "This API call triggers a reload of all the TLS data (server key, client-auth CA)\nand then returns a summary. The JSON response is exactly as in the corresponding\nGET request.\n\nThis is a protected API and can only be executed with superuser rights.\n", "operationId": "reloadServerTls", "responses": { "200": { "description": "This API will return HTTP 200 if everything is ok\n" }, "403": { "description": "This API will return HTTP 403 Forbidden if it is not called with\nsuperuser rights.\n" } }, "summary": "Reload the TLS data", "tags": [ "Security" ] } }, "/_api/cluster/endpoints": { "get": { "description": "Returns an object with an attribute `endpoints`, which contains an\narray of objects, which each have the attribute `endpoint`, whose value\nis a string with the endpoint description. There is an entry for each\nCoordinator in the cluster. This method only works on Coordinators in\ncluster mode. In case of an error the `error` attribute is set to\n`true`.\n", "operationId": "listClusterEndpoints", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "endpoints": { "description": "A list of active cluster endpoints.\n", "items": { "properties": { "endpoint": { "description": "The bind of the Coordinator, like `tcp://[::1]:8530`\n", "type": "string" } }, "required": [ "endpoint" ], "type": "object" }, "type": "array" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" } }, "required": [ "error", "code", "endpoints" ], "type": "object" } } }, "description": "is returned when everything went well.\n" }, "501": { "description": "server is not a Coordinator or method was not GET.\n" } }, "summary": "List all Coordinator endpoints", "tags": [ "Cluster" ] } }, "/_api/token/{user}": { "get": { "description": "List the access tokens for a given user.\n\nThis only returns the access token metadata.\nThe actual access token strings are only shown when creating tokens. \n\nThe user account you authenticate with needs to have administrate access\nto the `_system` database if you want to list the access tokens for a\ndifferent user. You can always list your own access tokens,\nregardless of database access levels.\n", "operationId": "listAccessTokens", "parameters": [ { "description": "The name of the user.\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "tokens": { "description": "A list with information about the user's access tokens.\n", "items": { "properties": { "active": { "description": "Whether the access token is valid based on the expiration date\nand time (`valid_until`).\n", "type": "boolean" }, "created_at": { "description": "A Unix timestamp in seconds with the creation date and time of the access token.\n", "type": "integer" }, "fingerprint": { "description": "The beginning and end of the access token string, showing the\nversion and the last few hexadecimal digits for identification,\nlike `v1...54227d`.\n", "type": "string" }, "id": { "description": "A unique identifier. It is only needed for calling the\nendpoint for revoking an access token.\n", "type": "integer" }, "name": { "description": "The name for the access token you specified to make\nidentification easier.\n", "type": "string" }, "valid_until": { "description": "A Unix timestamp in seconds with the configured expiration date and time.\n", "type": "integer" } }, "required": [ "id", "name", "valid_until", "created_at", "fingerprint", "active" ], "type": "object" }, "type": "array" } }, "required": [ "tokens" ], "type": "object" } } }, "description": "The metadata of the user's access tokens.\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The request is not authenticated correctly (e.g. wrong credentials, inactive user account).\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The user's access level for the `_system` database is too low.\nIt needs to be *Administrate* to manage access tokens for other users.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The user specified in the path does not exist.\n" } }, "summary": "List all access tokens", "tags": [ "Authentication" ] }, "post": { "description": "Create a new access token for the given user.\n\nThe response includes the actual access token string that you need to\nstore in a secure manner. It is only shown once.\n\nThe user account you authenticate with needs to have administrate access\nto the `_system` database if you want to create an access token for a\ndifferent user. You can always create an access token for yourself,\nregardless of database access levels.\n", "operationId": "createAccessToken", "parameters": [ { "description": "The name of the user.\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "A name for the access token to make identification easier,\nlike a short description.\n", "type": "string" }, "valid_until": { "description": "A Unix timestamp in seconds to set the expiration date and time.\n", "type": "integer" } }, "required": [ "name", "valid_until" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "active": { "description": "Whether the access token is valid based on the expiration date\nand time (`valid_until`).\n", "type": "boolean" }, "created_at": { "description": "A Unix timestamp in seconds with the creation date and time of the access token.\n", "type": "integer" }, "fingerprint": { "description": "The beginning and end of the access token string, showing the\nversion and the last few hexadecimal digits for identification,\nlike `v1...54227d`.\n", "type": "string" }, "id": { "description": "A unique identifier. It is only needed for calling the\nendpoint for revoking an access token.\n", "type": "integer" }, "name": { "description": "The name for the access token you specified to make\nidentification easier.\n", "type": "string" }, "token": { "description": "The actual access token string. Store it in a secure manner.\nThis is the only time it is shown to you.\n", "type": "string" }, "valid_until": { "description": "A Unix timestamp in seconds with the configured expiration date and time.\n", "type": "integer" } }, "required": [ "id", "name", "valid_until", "created_at", "fingerprint", "active", "token" ], "type": "object" } } }, "description": "Is returned if the user data can be replaced by the server.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The JSON representation is malformed or mandatory data is missing from the request.\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The request is not authenticated correctly (e.g. wrong credentials, inactive user account).\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The user's access level for the `_system` database is too low.\nIt needs to be *Administrate* to manage access tokens for other users.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The user specified in the path does not exist.\n" }, "409": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 409, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Duplicate access token `name`.\n" } }, "summary": "Create an access token", "tags": [ "Authentication" ] } }, "/_api/token/{user}/{token-id}": { "delete": { "description": "Delete an access token with the specified identifier for the given user.\n\nThe user account you authenticate with needs to have administrate access\nto the `_system` database if you want to delete an access token for a\ndifferent user. You can always delete your own access tokens,\nregardless of database access levels.\n", "operationId": "deleteAccessToken", "parameters": [ { "description": "The name of the user.\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "The identifier of the access token.\n", "in": "path", "name": "token-id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The response does not have a body.\n" } } }, "description": "The request is valid and the access token has been deleted if it\nexisted. However, the request also succeeds if the specified user\ndoesn't have an access token with the given identifier.\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The request is not authenticated correctly (e.g. wrong credentials, inactive user account).\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The user's access level for the `_system` database is too low.\nIt needs to be *Administrate* to manage access tokens for other users.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The user specified in the path does not exist.\n" } }, "summary": "Delete an access token", "tags": [ "Authentication" ] } }, "/_db/_system/_admin/options": { "get": { "description": "Return the effective configuration of the queried _arangod_ instance as\nset by startup options on the command-line and via a configuration file.\n\n{{\u003c security \u003e}}\nThis endpoint may reveal sensitive information about the deployment!\n{{\u003c /security \u003e}}\n\nThe endpoint can only be accessed via the `_system` database. In addition, the\n[`--server.options-api` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--serveroptions-api)\ncontrols the required privileges to access the option endpoints and allows\nyou to disable them entirely. The option can have the following values:\n- `disabled`: This endpoint is disabled.\n- `jwt`: This endpoint can only be accessed using a superuser JWT (default).\n- `admin`: This endpoint can only be accessed by users with\n write access to the `_system` database.\n- `public`: Every user with read access to the `_system` database can\n access this endpoint.\n", "operationId": "getEffectiveStartupOptions", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "An object with startup option names as keys and their effective\nvalue as values. The values can be of different data types, typically\nnumbers, strings, or arrays thereof.\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "You tried to authenticate with user credentials but a superuser token\ncreated from the JWT secret is required (`--server.options-api` set\nto `jwt`), you lack read access to the `_system` database\n(`--server.options-api` set to `public`), the credentials are wrong,\nor the user account is inactive.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "You don't have write access to the `_system` database\n(`--server.options-api` set to `admin`) or you tried to access the\nendpoint using a database other than `_system`.\n" }, "405": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 405, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if the HTTP method is not `GET`.\n" } }, "summary": "Get the startup option configuration", "tags": [ "Administration" ] } }, "/_db/_system/_admin/options-description": { "get": { "description": "Return the startup options available to configure the queried _arangod_\ninstance, similar to the `--dump-options` startup option.\n\nThe endpoint can only be accessed via the `_system` database. In addition, the\n[`--server.options-api` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--serveroptions-api)\ncontrols the required privileges to access the option endpoints and allows\nyou to disable them entirely. The option can have the following values:\n- `disabled`: This endpoint is disabled.\n- `jwt`: This endpoint can only be accessed using a superuser JWT (default).\n- `admin`: This endpoint can only be accessed by users with\n write access to the `_system` database.\n- `public`: Every user with read access to the `_system` database can\n access this endpoint.\n", "operationId": "getAvailableStartupOptions", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "An object with startup option names as keys and sub-objects as values.\nThe structure of each sub-object is as follows:\n- `section` (string): The part before the dot of a startup option\n (`--section.param`), or `\"\"` if it is a general option that doesn't\n belong to a section\n- `description` (string): A succinct explanation of the startup option\n- `longDescription` (string, *optional*): Additional details about the\n startup option if available\n- `category` (string): Either `\"option\"` for regular options or `\"command\"`\n if using the option performs an action and then terminates the process\n- `hidden` (boolean): Whether the option is uncommon. If yes, then\n the `--help` command does not list it, but `--help-all` lists every\n startup option\n- `type` (string): the data type of the option, typically one of\n `\"uint64\"`, `\"uint32\"`, `\"int64\"`, `\"int32\"`, `\"double\"`, `\"boolean\"`,\n `\"string\"`, `\"string...\"`\n- `experimental` (boolean): Whether the option relates to a feature\n that is not ready for production yet\n- `obsolete` (boolean): Whether the option has been deprecated and\n no effect anymore\n- `enterpriseOnly` (boolean): Whether the option is implemented in\n the non-public enterprise code.\n- `requiresValue` (boolean): Whether the option can be specified\n without a value to enable it\n- `os` (array of strings): The operating systems the startup option\n is supported on, always `[\"linux\"]`\n- `component` (array of strings): A list of server roles the startup\n option is available on. If it is supported by all cluster node types\n as well as the single server deployment mode, then the value is\n `[\"coordinator\", \"dbserver\", \"agent\", \"single\"]`\n- `introducedIn` (array of strings\\|null): A list of versions the\n startup option has been added in. Does not include later minor and\n major versions then the current version, and the information may\n get removed once all listed versions reach their end of life\n- `deprecatedIn` (array of strings\\|null): A list of versions the\n startup option has been marked for deprecation in. It can still\n be used until fully removed. Does not include later minor and\n major versions then the current version, and the information may\n get removed once all listed versions reach their end of life\n- `values` (string, *optional*):\n A description of the possible values you can set\n- `default` (any, *optional*): The standard value if the option is not set\n- `dynamic` (boolean): Whether the default value is calculated based\n on the target host configuration, e.g. available memory\n- `required` (boolean): Whether the option must be specified\n- `base` (number, *optional*): the unit for a numeric option\n- `minValue` (number, *optional*): The minimum value for a numeric option\n- `maxValue` (number, *optional*): The maximum value for a numeric option\n- `minInclusive` (boolean, *optional*): Whether the minimum value is\n included in the allowed value range\n- `maxInclusive` (boolean, *optional*): Whether the maximum value is\n included in the allowed value range\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "You tried to authenticate with user credentials but a superuser token\nis required, the credentials are wrong, or the user account is inactive.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "You don't have write access to the `_system` database or you tried\nto access the endpoint using a database other than `_system`.\n" }, "405": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 405, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if the HTTP method is not `GET`.\n" } }, "summary": "Get the available startup options", "tags": [ "Administration" ] } }, "/_db/_system/_admin/support-info": { "get": { "description": "Retrieves deployment information for support purposes. The endpoint returns data\nabout the ArangoDB version used, the host (operating system, server ID, CPU and\nstorage capacity, current utilization, a few metrics) and the other servers in\nthe deployment (in case of cluster deployments).\n\nAs this API may reveal sensitive data about the deployment, it can only be\naccessed from inside the `_system` database. In addition, there is a policy\ncontrol startup option `--server.support-info-api` that controls if and to whom\nthe API is made available.\n", "operationId": "getSupportInfo", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "date": { "description": "ISO 8601 datetime string of when the information was requested.\n", "type": "string" }, "deployment": { "description": "An object with at least a `type` attribute, indicating the deployment mode.\n\nIn case of a `\"single\"` server, additional information is provided in the\ntop-level `host` attribute.\n\nIn case of a `\"cluster\"`, there is a `servers` object that contains a nested\nobject for each Coordinator and DB-Server, using the server ID as key. Each\nobject holds information about the ArangoDB instance as well as the host machine.\nThere are additional attributes for the number of `agents`, `coordinators`,\n`dbServers`, and `shards`.\n", "type": "object" }, "host": { "description": "An object that holds information about the ArangoDB instance as well as the\nhost machine. Only set in case of single servers.\n", "type": "object" } }, "required": [ "date", "deployment" ], "type": "object" } } }, "description": "" }, "404": { "description": "The support info API is turned off.\n" } }, "summary": "Get information about the deployment", "tags": [ "Administration" ] } }, "/_db/_system/_api/database": { "get": { "description": "Retrieves the list of all existing databases\n\n\u003e **INFO:**\nRetrieving the list of databases is only possible from within the `_system` database.\n", "operationId": "listDatabases", "responses": { "200": { "description": "is returned if the list of database was compiled successfully.\n" }, "400": { "description": "is returned if the request is invalid.\n" }, "403": { "description": "is returned if the request was not executed in the `_system` database.\n" } }, "summary": "List all databases", "tags": [ "Databases" ] }, "post": { "description": "Creates a new database.\n\nThe response is a JSON object with the attribute `result` set to `true`.\n\n\u003e **INFO:**\nCreating a new database is only possible from within the `_system` database.\n", "operationId": "createDatabase", "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Has to contain a valid database name. The name must conform to the selected\nnaming convention for databases. If the name contains Unicode characters, the\nname must be [NFC-normalized](https://en.wikipedia.org/wiki/Unicode_equivalence#Normal_forms).\nNon-normalized names are rejected.\n", "type": "string" }, "options": { "description": "Optional object which can contain the following attributes:\n", "properties": { "replicationFactor": { "description": "Default replication factor for new collections created in this database.\n_(cluster only)_\n\nSpecial values:\n- `\"satellite\"`: Replicate the collection to every DB-Server\n- `1`: Disable replication\n\nYou can configure the global default with the\n`--cluster.default-replication-factor` startup option.\n", "type": "integer" }, "sharding": { "default": "", "description": "The sharding method to use for new collections in this database. _(cluster only)_\nValid values are:\n- `\"\"` or `\"flexible\"`: Create a database where collections can\n be sharded independently.\n- `\"single\"`: Create a OneShard database where all collections have a\n single shard and all leader shards are co-located on the same DB-Server.\n", "enum": [ "", "flexible", "single" ], "type": "string" }, "writeConcern": { "description": "Default write concern for new collections created in this database.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\n\nFor SatelliteCollections, the `writeConcern` is automatically controlled to\nequal the number of DB-Servers and has a value of `0`.\nOtherwise, the default value is controlled by the `--cluster.write-concern`\nstartup option, which defaults to `1`. _(cluster only)_\n", "type": "number" } }, "type": "object" }, "users": { "description": "An array of user objects. The users are granted *Administrate* permissions\nfor the new database. Users that do not exist yet are created.\nIf `users` is not specified or does not contain any users, the default user\n`root` is used to ensure that the new database is accessible after it\nis created. The `root` user is created with an empty password should it not\nexist. Each user object can contain the following attributes:\n", "items": { "properties": { "active": { "default": true, "description": "Whether the user account should be able to log in to the database system.\n\nThe attribute is ignored for users that already exist.\n", "type": "boolean" }, "extra": { "description": "A JSON object with extra user information. It is used by the web interface\nto store graph viewer settings and saved queries. Should not be set or\nmodified by end users, as custom attributes are not preserved.\n", "type": "object" }, "passwd": { "description": "The user password as a string. If not specified, it defaults to an empty\nstring. The attribute is ignored for users that already exist.\n", "type": "string" }, "username": { "description": "Login name of an existing user or one to be created.\n", "type": "string" } }, "required": [ "username" ], "type": "object" }, "type": "array" } }, "required": [ "name" ], "type": "object" } } } }, "responses": { "201": { "description": "is returned if the database was created successfully.\n" }, "400": { "description": "is returned if the request parameters are invalid, if a database with the\nspecified name already exists, or if the configured limit to the number\nof databases has been reached.\n" }, "403": { "description": "is returned if the request was not executed in the `_system` database.\n" }, "409": { "description": "is returned if a database with the specified name already exists.\n" } }, "summary": "Create a database", "tags": [ "Databases" ] } }, "/_db/_system/_api/database/{database-name}": { "delete": { "description": "Drops the database along with all data stored in it.\n\n\u003e **INFO:**\nDropping a database is only possible from within the `_system` database.\nThe `_system` database itself cannot be dropped.\n", "operationId": "deleteDatabase", "parameters": [ { "description": "The name of the database\n", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the database was dropped successfully.\n" }, "400": { "description": "is returned if the request is malformed.\n" }, "403": { "description": "is returned if the request was not executed in the `_system` database.\n" }, "404": { "description": "is returned if the database could not be found.\n" } }, "summary": "Drop a database", "tags": [ "Databases" ] } }, "/_db/_system/_api/endpoint": { "get": { "deprecated": true, "description": "\u003e **WARNING:**\nThis route should no longer be used.\nIt is considered as deprecated from version 3.4.0 on.\n\n\nReturns an array of all configured endpoints the server is listening on.\n\nThe result is a JSON array of JSON objects, each with `\"entrypoint\"` as\nthe only attribute, and with the value being a string describing the\nendpoint.\n\n\u003e **INFO:**\nRetrieving the array of all endpoints is allowed in the system database\nonly. Calling this action in any other database will make the server return\nan error.\n", "operationId": "listEndpoints", "responses": { "200": { "description": "is returned when the array of endpoints can be determined successfully.\n" }, "400": { "description": "is returned if the action is not carried out in the system database.\n" }, "405": { "description": "The server will respond with *HTTP 405* if an unsupported HTTP method is used.\n" } }, "summary": "List the endpoints of a single server (deprecated)", "tags": [ "Administration" ] } }, "/_db/{database-name}/_admin/crashes": { "get": { "description": "\u003csmall\u003eIntroduced in: v3.12.8\u003c/small\u003e\n\nReturn the list of crash dump directory identifiers (UUIDs).\n\nWhen the server crashes, the crash handler writes diagnostic data into\na per-crash directory under `\u003cdatabase-directory\u003e/crashes/\u003cuuid\u003e/`.\nEach dump includes information such as recent API calls and AQL queries,\na backtrace, and system information.\n\nThe server keeps the most recent 10 crash dumps. Older ones are removed\nduring startup.\n\nThis endpoint requires *administrate* access to the `_system` database.\n", "operationId": "listCrashDumps", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and write access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "example": 200, "type": "integer" }, "error": { "example": false, "type": "boolean" }, "result": { "description": "Array of crash dump identifiers (UUIDs).\n", "items": { "format": "uuid", "type": "string" }, "type": "array" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "Returns a list of crash dump identifiers (UUIDs).\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if authentication is enabled and the user does not have at\nleast read access to the specified database, the credentials are\nwrong, or the user account is inactive.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if authentication is enabled and the user does not have\nwrite access to the `_system` database.\n" }, "503": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 503, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The crash handler feature is not ready or has been disabled via the\n[`--crash-handler.enable-dumps` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--crash-handlerenable-dumps).\n" } }, "summary": "List crash dumps", "tags": [ "Administration" ] } }, "/_db/{database-name}/_admin/crashes/{crashId}": { "delete": { "description": "\u003csmall\u003eIntroduced in: v3.12.8\u003c/small\u003e\n\nDelete a specific crash dump directory and its contents. Crash dumps are\nstored under `\u003cdatabase-directory\u003e/crashes/\u003cuuid\u003e/`. The server keeps the\nmost recent 10 crash dumps. Older ones are removed during startup.\n\nThis endpoint requires *administrate* access to the `_system` database.\n", "operationId": "deleteCrashDump", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and write access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The UUID of the crash dump directory to delete.\n", "in": "path", "name": "crashId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "example": 200, "type": "integer" }, "error": { "example": false, "type": "boolean" }, "result": { "properties": { "crashId": { "format": "uuid", "type": "string" }, "deleted": { "example": true, "type": "boolean" } }, "required": [ "deleted", "crashId" ], "type": "object" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "The crash dump was deleted successfully.\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if authentication is enabled and the user does not have at\nleast read access to the specified database, the credentials are\nwrong, or the user account is inactive.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if authentication is enabled and the user does not have\nwrite access to the `_system` database.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if the crash dump folder based on the specified `crashId`\ncannot be found.\n" }, "503": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 503, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The crash handler feature is not ready or has been disabled via the\n[`--crash-handler.enable-dumps` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--crash-handlerenable-dumps).\n" } }, "summary": "Delete a crash dump", "tags": [ "Administration" ] }, "get": { "description": "\u003csmall\u003eIntroduced in: v3.12.8\u003c/small\u003e\n\nReturn the contents of a specific crash dump. The response includes all\nfiles from the crash directory (e.g. `backtrace.txt`, `system_info.txt`,\n`ApiRecording.json`, `AsyncRegistry.json`) as an object mapping filenames\nto their contents. Crash dumps are stored under\n`\u003cdatabase-directory\u003e/crashes/\u003cuuid\u003e/`.\n\nThis endpoint requires *administrate* access to the `_system` database.\n", "operationId": "getCrashDump", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and write access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The UUID of the crash dump directory.\n", "in": "path", "name": "crashId", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "example": 200, "type": "integer" }, "error": { "example": false, "type": "boolean" }, "result": { "properties": { "crashId": { "description": "The crash dump identifier (UUID).\n", "format": "uuid", "type": "string" }, "files": { "additionalProperties": { "type": "string" }, "description": "Object mapping file names to their contents (e.g.\n`backtrace.txt`, `system_info.txt`, `ApiRecording.json`,\n`Activities.json`, `AsyncRegistry.json`).\n", "type": "object" } }, "required": [ "crashId", "files" ], "type": "object" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "Returns the crash dump contents.\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if authentication is enabled and the user does not have at\nleast read access to the specified database, the credentials are\nwrong, or the user account is inactive.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if authentication is enabled and the user does not have\nwrite access to the `_system` database.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if the crash dump folder based on the specified `crashId`\ncannot be found.\n" }, "503": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 503, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The crash handler feature is not ready or has been disabled via the\n[`--crash-handler.enable-dumps` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--crash-handlerenable-dumps).\n" } }, "summary": "Get a crash dump", "tags": [ "Administration" ] } }, "/_db/{database-name}/_admin/deployment/id": { "get": { "description": "Get the unique identifier of this ArangoDB deployment.\n", "operationId": "getDeploymentId", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "id": { "description": "The UUID that uniquely identifies the deployment.\n", "format": "uuid", "type": "string" } }, "required": [ "id" ], "type": "object" } } }, "description": "The deployment ID has been retrieved successfully.\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The user account has insufficient permissions for the selected database.\n" } }, "summary": "Get the deployment ID", "tags": [ "Administration" ] } }, "/_db/{database-name}/_admin/echo": { "post": { "deprecated": true, "description": "\u003e **WARNING:**\nThe Action feature, including this debug endpoint, is deprecated and\nremoved in ArangoDB v4.0.\n\n\nThe call returns an object with the servers request information\n", "operationId": "echoRequest", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "description": "The request body can be of any type and is simply forwarded.\n" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "authorized": { "description": "Whether the session is authorized\n", "type": "boolean" }, "client": { "description": "Attributes of the client connection\n", "properties": { "address": { "description": "The IP address of the client\n", "type": "integer" }, "id": { "description": "A server generated ID\n", "type": "string" }, "port": { "description": "The port of the TCP connection on the client-side\n", "type": "integer" } }, "required": [ "address", "port", "id" ], "type": "object" }, "cookies": { "description": "A list of the cookies you sent\n", "type": "object" }, "database": { "description": "The name of the database this request was executed on\n", "type": "string" }, "headers": { "description": "The list of the HTTP headers you sent\n", "type": "object" }, "internals": { "description": "Contents of the server internals struct\n", "type": "object" }, "isAdminUser": { "description": "Whether the current user is an administrator\n", "type": "boolean" }, "parameters": { "description": "An object containing the query parameters\n", "type": "object" }, "path": { "description": "The relative path of this request (decoded, excluding `/_admin/echo`)\n", "type": "string" }, "portType": { "description": "The type of the socket, one of `\"tcp/ip\"`, `\"unix\"`, `\"unknown\"`\n", "type": "string" }, "prefix": { "description": "The prefix of the database\n", "type": "object" }, "protocol": { "description": "The transport protocol, one of `\"http\"`, `\"https\"`\n", "type": "string" }, "rawRequestBody": { "description": "The sent payload as a JSON-encoded Buffer object\n", "type": "object" }, "rawSuffix": { "description": "A list of the percent-encoded URL path suffixes\n", "items": { "type": "string" }, "type": "array" }, "requestBody": { "description": "Stringified version of the request body you sent\n", "type": "string" }, "requestType": { "description": "The HTTP method that was used for the request (`\"POST\"`). The endpoint can be\nqueried using other verbs, too (`\"GET\"`, `\"PUT\"`, `\"PATCH\"`, `\"DELETE\"`).\n", "type": "string" }, "server": { "description": "Attributes of the server connection\n", "properties": { "address": { "description": "The bind address of the endpoint this request was sent to\n", "type": "string" }, "endpoint": { "description": "The endpoint this request was sent to\n", "type": "string" }, "port": { "description": "The port this request was sent to\n", "type": "integer" } }, "required": [ "address", "port", "endpoint" ], "type": "object" }, "suffix": { "description": "A list of the decoded URL path suffixes. You can query the endpoint with\narbitrary suffixes, e.g. `/_admin/echo/foo/123`\n", "items": { "type": "string" }, "type": "array" }, "url": { "description": "The raw request URL\n", "type": "string" }, "user": { "description": "The name of the current user that sent this request\n", "type": "string" } }, "required": [ "authorized", "user", "isAdminUser", "database", "url", "protocol", "portType", "server", "client", "internals", "prefix", "headers", "requestType", "requestBody", "rawRequestBody", "parameters", "cookies", "suffix", "rawSuffix", "path" ], "type": "object" } } }, "description": "Echo was returned successfully.\n" } }, "summary": "Echo a request", "tags": [ "Administration" ] } }, "/_db/{database-name}/_admin/execute": { "post": { "deprecated": true, "description": "\u003e **WARNING:**\nThe `/_admin/execute` endpoint is deprecated and removed in ArangoDB v4.0.\n\n\nExecutes the JavaScript code in the body on the server as the body\nof a function with no arguments. If you have a `return` statement\nthen the return value you produce will be returned as content type\n`application/json`. If the parameter `returnAsJSON` is set to\n`true`, the result will be a JSON object describing the return value\ndirectly, otherwise a string produced by JSON.stringify will be\nreturned.\n\nNote that this API endpoint is available if the server has been\nstarted with the `--javascript.allow-admin-execute` startup options\nenabled.\n\nThe default value of this option is `false`, which disables the execution of\nuser-defined code and disables this API endpoint entirely.\nThis is also the recommended setting for production.\n", "operationId": "executeCode", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/javascript": { "schema": { "description": "The request body is the JavaScript code to be executed.\n" } } } }, "responses": { "200": { "description": "is returned when everything went well, or if a timeout occurred. In the\nlatter case a body of type application/json indicating the timeout\nis returned. depending on `returnAsJSON` this is a json object or a plain string.\n" }, "403": { "description": "is returned if ArangoDB is not running in cluster mode.\n" }, "404": { "description": "is returned if ArangoDB was not compiled for cluster operation.\n" } }, "summary": "Execute a script", "tags": [ "Administration" ] } }, "/_db/{database-name}/_admin/license": { "get": { "description": "View the license information and status of the ArangoDB deployment.\n\nCan be called on single servers, Coordinators, and DB-Servers.\n\nIn the Community Edition before v3.12.5, only `{\"license\":\"none\"}`\nis returned.\n", "operationId": "getLicense", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database. If the `--server.harden` startup option is enabled,\nadministrate access to the `_system` database is required.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "diskUsage": { "description": "Information about the dataset size limit if you use the\nCommunity Edition.\n\nThis attribute is not present if an Enterprise Edition\nlicense is applied.\n", "properties": { "bytesLimit": { "description": "The maximum dataset size for your Community Edition deployment.\n", "type": "integer" }, "bytesUsed": { "description": "The determined dataset size of your deployment.\n", "type": "integer" }, "limitReached": { "description": "Whether the dataset size exceeds the limit.\n", "type": "boolean" }, "secondsUntilReadOnly": { "description": "The time until read-only mode is entered if you are over the limit.\n", "type": "integer" }, "secondsUntilShutDown": { "description": "The time until shutdown if you are over the limit.\n", "type": "integer" }, "status": { "description": "The state of your Community Edition deployment with regard to\nthe dataset size limit at a glance.\n\n- `good`: The dataset size of your deployment is below the 100 GiB limit.\n- `limit-reached`: Your deployment exceeds the size limit and you have two days\n to bring the deployment back below 100 GiB. Consider acquiring an\n Enterprise Edition license to lift the limit.\n- `read-only`: Your deployment is in read-only mode because it exceeded the\n size limit for two days. All read operations to the instance keep functioning\n for two more days. However, no data or data definition changes can be made.\n- `shutdown`: The server shuts down after two days of read-only mode.\n", "enum": [ "good", "limit-reached", "read-only", "shutdown" ], "type": "string" } }, "required": [ "bytesUsed", "bytesLimit", "limitReached", "secondsUntilReadOnly", "secondsUntilShutDown", "status" ], "type": "object" }, "features": { "description": "The properties of the license.\n\nThis attribute is only present if an Enterprise Edition license is applied.\n", "properties": { "expires": { "description": "The `expires` key lists the expiry date as Unix timestamp (seconds since\nJanuary 1st, 1970 UTC).\n", "example": 1683173040, "type": "number" } }, "required": [ "expires" ], "type": "object" }, "hash": { "description": "The hash value of the license.\n\nThis attribute is only present if an Enterprise Edition license is applied.\n", "example": "982db5...44f3", "type": "string" }, "license": { "description": "The encrypted license key in Base64 encoding.\n\nThis attribute is only present if an Enterprise Edition license is applied\n(or has a value of `\"none\"` in the Community Edition before v3.12.5).\n", "example": "V0h/W...wEDw==", "type": "string" }, "status": { "description": "The `status` attribute allows you to confirm the state of the\napplied license at a glance.\n\n- `good`: The license is still valid for more than a week.\n- `expiring`: The license is valid for less than a week.\n This status is not applicable if you use license activation\n (managed license, from v3.12.6 onward) rather than a license key,\n in which case the transition is directly from `good` to\n `read-only` when the activation expires.\n- `read-only`: The license has expired. The instance is now\n restricted to read-only mode.\n\nThis attribute is only present if an Enterprise Edition license is applied.\n", "enum": [ "good", "expiring", "read-only" ], "example": "good", "type": "string" }, "upgrading": { "description": "Whether the server is performing a database upgrade.\n", "example": false, "type": "boolean" }, "version": { "description": "The license version number.\n\nThis attribute is only present if an Enterprise Edition license is applied.\n", "example": 1, "type": "number" } }, "type": "object" } } }, "description": "Returns the license information.\n" } }, "summary": "Get information about the current license", "tags": [ "Administration" ] }, "put": { "description": "Set a new license for an Enterprise Edition instance.\nCan be called on single servers, Coordinators, and DB-Servers.\n", "operationId": "setLicense", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database. If the `--server.harden` startup option is enabled,\nadministrate access to the `_system` database is required.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Whether to change the license even if it expires sooner than the current one.\n", "in": "query", "name": "force", "required": false, "schema": { "default": false, "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The request body has to contain the Base64-encoded license string wrapped in double quotes.\n", "example": "eyJncmFudCI6...(Base64-encoded license string)...", "type": "string" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "result": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 201, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" } }, "required": [ "error", "code" ], "type": "object" } }, "required": [ "result" ], "type": "object" } } }, "description": "License successfully deployed.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "If the license expires earlier than the previously installed one,\nor if the supplied license string is invalid.\n" }, "501": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 501, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "If you try to apply a license using a custom build of the public source code.\n" } }, "summary": "Set a new license", "tags": [ "Administration" ] } }, "/_db/{database-name}/_admin/metrics": { "get": { "description": "Returns the instance's current metrics in Prometheus format. The\nreturned document collects all instance metrics, which are measured\nat any given time and exposes them for collection by Prometheus.\n\nThe document contains different metrics and metrics groups dependent\non the role of the queried instance. All exported metrics are\npublished with a `arangodb_` or `rocksdb_` prefix to distinguish them\nfrom other collected data.\n\nThe API then needs to be added to the Prometheus configuration file\nfor collection.\n", "operationId": "getMetrics", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database. If the `--server.harden` startup option is enabled,\nadministrate access to the `_system` database is required.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Returns metrics of the specified server. If no serverId is given, the asked\nserver will reply. This parameter is only meaningful on Coordinators.\n", "in": "query", "name": "serverId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Metrics were returned successfully.\n" }, "404": { "description": "The metrics API may be disabled using `--server.export-metrics-api false`\nsetting in the server. In this case, the result of the call indicates the API\nto be not found.\n" } }, "summary": "Get the metrics", "tags": [ "Monitoring" ] } }, "/_db/{database-name}/_admin/metrics/v2": { "get": { "deprecated": true, "description": "\u003e **WARNING:**\nThe `GET /_admin/metrics` and `GET /_admin/metrics/v2` endpoints return\nthe same metrics since ArangoDB v3.10.0. The latter is deprecated and\nremoved in v4.0.\n\n\nReturns the instance's current metrics in Prometheus format. The\nreturned document collects all instance metrics, which are measured\nat any given time and exposes them for collection by Prometheus.\n\nThe document contains different metrics and metrics groups dependent\non the role of the queried instance. All exported metrics are\npublished with a `arangodb_` or `rocksdb_` prefix to distinguish\nthem from other collected data.\n\nThe API then needs to be added to the Prometheus configuration file\nfor collection.\n", "operationId": "getMetricsV2", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database. If the `--server.harden` startup option is enabled,\nadministrate access to the `_system` database is required.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Returns metrics of the specified server. If no serverId is given, the asked\nserver will reply. This parameter is only meaningful on Coordinators.\n", "in": "query", "name": "serverId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Metrics were returned successfully.\n" }, "404": { "description": "The metrics API may be disabled using `--server.export-metrics-api false`\nsetting in the server. In this case, the result of the call indicates the API\nto be not found.\n" } }, "summary": "Get the metrics (deprecated)", "tags": [ "Monitoring" ] } }, "/_db/{database-name}/_admin/options-public": { "get": { "description": "Return a small, curated subset of the configured server startup options\nthat are safe to expose to any authenticated user with read access to the\nrequested database.\n\nAdministrative tools can use this endpoint to adapt their behavior to the server\nconfiguration. For example, they can show the valid range for `replicationFactor`\nwhen creating a collection, or respect `--database.extended-names` when\nvalidating names on the client-side.\n\nThis endpoint is available regardless of the\n[`--server.options-api` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--serveroptions-api)\nsetting, so that the Arango Contextual Data Platform web interface for\ninstance can always access the public options.\n", "operationId": "getPublicStartupOptions", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cluster.api-jwt-policy": { "description": "The permissions required for accessing `/_admin/cluster/*` endpoints.\n", "type": "string" }, "cluster.max-number-of-shards": { "description": "Maximum number of shards per collection.\n", "type": "integer" }, "cluster.max-replication-factor": { "description": "Maximum replication factor for collections.\n", "type": "integer" }, "cluster.min-replication-factor": { "description": "Minimum replication factor for collections.\n", "type": "integer" }, "database.extended-names": { "description": "Whether the traditional or extended naming constraints\napply for collections, Views, etc.\n", "type": "boolean" }, "server.session-timeout": { "description": "The timeout for JWT session tokens in seconds.\n", "type": "number" } }, "type": "object" } } }, "description": "An object with public startup option names as keys and their\neffective values.\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Authentication is enabled and the user account you authenticated with\ndoesn't have at least read access to the specified database, the\ncredentials are wrong, or the user account is inactive.\n" }, "405": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 405, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if the HTTP method is not `GET`.\n" } }, "summary": "Get the public startup option configuration", "tags": [ "Administration" ] } }, "/_db/{database-name}/_admin/routing/reload": { "post": { "deprecated": true, "description": "\u003e **WARNING:**\nThe Action and Foxx microservice features, including this endpoint for\nroute reloading, are deprecated and removed in ArangoDB v4.0.\n\n\nReloads the routing information from the `_routing` system collection if it\nexists, and makes Foxx rebuild its local routing table on the next request.\n", "operationId": "reloadRouting", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The routing information has been reloaded successfully.\n" } }, "summary": "Reload the routing table", "tags": [ "Administration" ] } }, "/_db/{database-name}/_admin/server/api-calls": { "get": { "description": "Get a list of the most recent requests with a timestamp and the endpoint.\nIn cluster deployments, the list contains only those requests that were\nsubmitted to the Coordinator you call this endpoint on.\nThis feature is for debugging purposes.\n\nYou can control how much memory is used to record API calls with the\n`--server.api-recording-memory-limit` startup option.\n\nYou can disable this and the `/_admin/server/aql-queries` endpoint\nwith the `--log.recording-api-enabled` startup option.\n\nWhether API calls are recorded is independently controlled by the\n`--server.api-call-recording` startup option.\nThe endpoint returns an empty list of calls if turned off.\n", "operationId": "getRecentApiCalls", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\nIf `--log.recording-api-enabled` is set to `jwt`, you need to use\na superuser token to access the endpoint.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "The request result.\n", "properties": { "calls": { "description": "A list of the recent API calls. Empty if API call recording is disabled.\n", "items": { "properties": { "database": { "description": "The database name.\n", "type": "string" }, "path": { "description": "The HTTP request path excluding the database prefix (`/_db/\u003cdatabase-name\u003e`).\n", "type": "string" }, "requestType": { "description": "The HTTP request method.\n", "enum": [ "GET", "PATCH", "PUT", "DELETE", "HEAD" ], "type": "string" }, "timeStamp": { "description": "The date and time of the request in ISO 8601 format.\n", "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "calls" ], "type": "object" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "Returns the recorded API calls.\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The user account has insufficient permissions for the selected database.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The recording API has been disabled.\n" }, "501": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 501, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The method has not been called on a Coordinator or single server.\n" } }, "summary": "Get recent API calls", "tags": [ "Monitoring" ] } }, "/_db/{database-name}/_admin/server/aql-queries": { "get": { "description": "Get a list of the most recent AQL queries with a timestamp and\ninformation about the submitted query. In cluster deployments, the list\ncontains only those queries that were submitted to the Coordinator you\ncall this endpoint on. This feature is for debugging purposes.\n\nYou can control how much memory is used to record AQL queries with the\n`--server.aql-recording-memory-limit` startup option.\n\nYou can disable this and the `/_admin/server/api-calls` endpoint\nwith the `--log.recording-api-enabled` startup option.\n\nWhether AQL queries are recorded is independently controlled by the\n`--server.aql-query-recording` startup option.\nThe endpoint returns an empty list of queries if turned off.\n", "operationId": "getRecentAqlQueries", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\nIf `--log.recording-api-enabled` is set to `jwt`, you need to use\na superuser token to access the endpoint.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "The request result.\n", "properties": { "queries": { "description": "A list of the recent AQL queries.\nEmpty if AQL query recording is disabled.\n", "items": { "properties": { "bindVars": { "description": "Key/value pairs representing the bind variables.\n", "type": "object" }, "database": { "description": "The database name.\n", "type": "string" }, "query": { "description": "The AQL query.\n", "type": "string" }, "timeStamp": { "description": "The date and time of the request in ISO 8601 format.\n", "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "queries" ], "type": "object" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "Returns the recorded AQL queries.\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The user account has insufficient permissions for the selected database.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The recording API has been disabled.\n" }, "501": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 501, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The method has not been called on a Coordinator or single server.\n" } }, "summary": "Get recent AQL queries", "tags": [ "Monitoring" ] } }, "/_db/{database-name}/_admin/server/jwt": { "get": { "description": "Get information about the currently loaded secrets.\n\nTo utilize the API a superuser JWT token is necessary, otherwise the response\nwill be _HTTP 403 Forbidden_.\n", "operationId": "getServerJwtSecrets", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database. If the `--server.harden` startup option is enabled,\nadministrate access to the `_system` database is required.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The reply with the JWT secrets information.\n", "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "The result object.\n", "properties": { "active": { "description": "An object with the SHA-256 hash of the active secret.\n", "type": "object" }, "passive": { "description": "An array of objects with the SHA-256 hashes of the passive secrets.\n\nCan be empty.\n", "items": { "type": "object" }, "type": "array" } }, "required": [ "active", "passive" ], "type": "object" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "Successfully retrieved the JWT secret information.\n" }, "403": { "description": "if the request was not authenticated as a user with sufficient rights\n" } }, "summary": "Get information about the loaded JWT secrets", "tags": [ "Authentication" ] } }, "/_db/{database-name}/_admin/server/mode": { "get": { "description": "Return mode information about a server. The json response will contain\na field `mode` with the value `readonly` or `default`. In a read-only server\nall write operations will fail with an error code of `1004` (_ERROR_READ_ONLY_).\nCreating or dropping of databases and collections will also fail with error code `11` (_ERROR_FORBIDDEN_).\n\nThis API requires authentication.\n", "operationId": "getServerMode", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "This API will return HTTP 200 if everything is ok\n" } }, "summary": "Return whether or not a server is in read-only mode", "tags": [ "Administration" ] }, "put": { "description": "Update mode information about a server. The JSON response will contain\na field `mode` with the value `readonly` or `default`. In a read-only server\nall write operations will fail with an error code of `1004` (_ERROR_READ_ONLY_).\nCreating or dropping of databases and collections will also fail with error\ncode `11` (_ERROR_FORBIDDEN_).\n\nThis is a protected API. It requires authentication and administrative\nserver rights.\n", "operationId": "setServerMode", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "mode": { "description": "The mode of the server `readonly` or `default`.\n", "type": "string" } }, "required": [ "mode" ], "type": "object" } } } }, "responses": { "200": { "description": "This API will return HTTP 200 if everything is ok\n" }, "401": { "description": "if the request was not authenticated as a user with sufficient rights\n" } }, "summary": "Set the server mode to read-only or default", "tags": [ "Administration" ] } }, "/_db/{database-name}/_admin/server/tls": { "get": { "description": "Return a summary of the TLS data. The JSON response will contain a field\n`result` with the following components:\n\n - `keyfile`: Information about the key file.\n - `clientCA`: Information about the Certificate Authority (CA) for\n client certificate verification.\n\nIf server name indication (SNI) is used and multiple key files are\nconfigured for different server names, then there is an additional\nattribute `SNI`, which contains for each configured server name\nthe corresponding information about the key file for that server name.\n\nIn all cases the value of the attribute will be a JSON object, which\nhas a subset of the following attributes (whatever is appropriate):\n\n - `sha256`: The value is a string with the SHA256 of the whole input\n file.\n - `certificates`: The value is a JSON array with the public\n certificates in the chain in the file.\n - `privateKeySha256`: In cases where there is a private key (`keyfile`\n but not `clientCA`), this field is present and contains a\n JSON string with the SHA256 of the private key.\n\nThis API requires authentication.\n", "operationId": "getServerTls", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database. If the `--server.harden` startup option is enabled,\nadministrate access to the `_system` database is required.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "This API will return HTTP 200 if everything is ok\n" } }, "summary": "Get the TLS data", "tags": [ "Security" ] } }, "/_db/{database-name}/_admin/shutdown": { "delete": { "description": "This call initiates a clean shutdown sequence. Requires administrative privileges.\n", "operationId": "startShutdown", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "\u003csmall\u003eIntroduced in: v3.7.12, v3.8.1, v3.9.0\u003c/small\u003e\n\nIf set to `true`, this initiates a soft shutdown. This is only available\non Coordinators. When issued, the Coordinator tracks a number of ongoing\noperations, waits until all have finished, and then shuts itself down\nnormally. It will still accept new operations.\n\nThis feature can be used to make restart operations of Coordinators less\nintrusive for clients. It is designed for setups with a load balancer in front\nof Coordinators. Remove the designated Coordinator from the load balancer before\nissuing the soft-shutdown. The remaining Coordinators will internally forward\nrequests that need to be handled by the designated Coordinator. All other\nrequests will be handled by the remaining Coordinators, reducing the designated\nCoordinator's load.\n\nThe following types of operations are tracked:\n\n - AQL cursors (in particular streaming cursors)\n - Transactions (in particular stream transactions)\n - Ongoing asynchronous requests (using the `x-arango-async: store` HTTP header)\n - Finished asynchronous requests, whose result has not yet been\n collected\n - Queued low priority requests (most normal requests)\n - Ongoing low priority requests\n", "in": "query", "name": "soft", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "is returned in all cases, `OK` will be returned in the result buffer on success.\n" } }, "summary": "Start the shutdown sequence", "tags": [ "Administration" ] }, "get": { "description": "\u003csmall\u003eIntroduced in: v3.7.12, v3.8.1, v3.9.0\u003c/small\u003e\n\nThis call reports progress about a soft Coordinator shutdown (see\ndocumentation of `DELETE /_admin/shutdown?soft=true`).\nIn this case, the following types of operations are tracked:\n\n - AQL cursors (in particular streaming cursors)\n - Transactions (in particular stream transactions)\n - Ongoing asynchronous requests (using the `x-arango-async: store` HTTP header)\n - Finished asynchronous requests, whose result has not yet been\n collected\n - Queued low priority requests (most normal requests)\n - Ongoing low priority requests\n\nThis API is only available on Coordinators.\n", "operationId": "getShutdownProgress", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "AQLcursors": { "description": "Number of AQL cursors that are still active.\n", "type": "number" }, "allClear": { "description": "Whether all active operations finished.\n", "type": "boolean" }, "doneJobs": { "description": "Number of finished asynchronous requests, whose result has not yet been collected.\n", "type": "number" }, "lowPrioOngoingRequests": { "description": "Number of queued low priority requests.\n", "type": "number" }, "lowPrioQueuedRequests": { "description": "Number of ongoing low priority requests.\n", "type": "number" }, "pendingJobs": { "description": "Number of ongoing asynchronous requests.\n", "type": "number" }, "softShutdownOngoing": { "description": "Whether a soft shutdown of the Coordinator is in progress.\n", "type": "boolean" }, "transactions": { "description": "Number of ongoing transactions.\n", "type": "number" } }, "required": [ "softShutdownOngoing", "AQLcursors", "transactions", "pendingJobs", "doneJobs", "lowPrioOngoingRequests", "lowPrioQueuedRequests", "allClear" ], "type": "object" } } }, "description": "The response indicates the fact that a soft shutdown is ongoing and the\nnumber of active operations of the various types. Once all numbers have gone\nto 0, the flag `allClear` is set and the Coordinator shuts down automatically.\n" } }, "summary": "Query the soft shutdown progress", "tags": [ "Administration" ] } }, "/_db/{database-name}/_admin/statistics": { "get": { "deprecated": true, "description": "\u003e **WARNING:**\nThis endpoint should no longer be used. It is deprecated from\nversion 3.8.0 onward and removed in ArangoDB v4.0.\nUse `GET /_admin/metrics` instead, which provides the data exposed by\nthis API and a lot more.\n\n\nReturns the statistics information. The returned object contains the\nstatistics figures grouped together according to the description returned by\n`/_admin/statistics-description`. For instance, to access a figure `userTime`\nfrom the group `system`, you first select the sub-object describing the\ngroup stored in `system` and in that sub-object the value for `userTime` is\nstored in the attribute of the same name.\n\nIn case of a distribution, the returned object contains the total count in\n`count` and the distribution list in `counts`. The sum (or total) of the\nindividual values is returned in `sum`.\n\nThe transaction statistics show the local started, committed and aborted\ntransactions as well as intermediate commits done for the server queried. The\nintermediate commit count will only take non zero values for the RocksDB\nstorage engine. Coordinators do almost no local transactions themselves in\ntheir local databases, therefore cluster transactions (transactions started on a\nCoordinator that require DB-Servers to finish before the transactions is\ncommitted cluster wide) are just added to their local statistics. This means\nthat the statistics you would see for a single server is roughly what you can\nexpect in a cluster setup using a single Coordinator querying this Coordinator.\nJust with the difference that cluster transactions have no notion of\nintermediate commits and will not increase the value.\n", "operationId": "getStatistics", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database. If the `--server.harden` startup option is enabled,\nadministrate access to the `_system` database is required.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "client": { "description": "information about the connected clients and their resource usage\n", "properties": { "bytesReceived": { "description": "number of bytes received from the clients\n", "properties": { "count": { "description": "number of values summarized\n", "type": "integer" }, "counts": { "description": "array containing the values\n", "items": { "type": "integer" }, "type": "array" }, "sum": { "description": "summarized value of all counts\n", "type": "number" } }, "required": [ "sum", "count", "counts" ], "type": "object" }, "bytesSent": { "description": "number of bytes sent to the clients\n", "properties": { "count": { "description": "number of values summarized\n", "type": "integer" }, "counts": { "description": "array containing the values\n", "items": { "type": "integer" }, "type": "array" }, "sum": { "description": "summarized value of all counts\n", "type": "number" } }, "required": [ "sum", "count", "counts" ], "type": "object" }, "connectionTime": { "description": "total connection times\n", "properties": { "count": { "description": "number of values summarized\n", "type": "integer" }, "counts": { "description": "array containing the values\n", "items": { "type": "integer" }, "type": "array" }, "sum": { "description": "summarized value of all counts\n", "type": "number" } }, "required": [ "sum", "count", "counts" ], "type": "object" }, "httpConnections": { "description": "the number of open http connections\n", "type": "integer" }, "ioTime": { "description": "IO Time\n", "properties": { "count": { "description": "number of values summarized\n", "type": "integer" }, "counts": { "description": "array containing the values\n", "items": { "type": "integer" }, "type": "array" }, "sum": { "description": "summarized value of all counts\n", "type": "number" } }, "required": [ "sum", "count", "counts" ], "type": "object" }, "queueTime": { "description": "the time requests were queued waiting for processing\n", "properties": { "count": { "description": "number of values summarized\n", "type": "integer" }, "counts": { "description": "array containing the values\n", "items": { "type": "integer" }, "type": "array" }, "sum": { "description": "summarized value of all counts\n", "type": "number" } }, "required": [ "sum", "count", "counts" ], "type": "object" }, "requestTime": { "description": "the request times\n", "properties": { "count": { "description": "number of values summarized\n", "type": "integer" }, "counts": { "description": "array containing the values\n", "items": { "type": "integer" }, "type": "array" }, "sum": { "description": "summarized value of all counts\n", "type": "number" } }, "required": [ "sum", "count", "counts" ], "type": "object" }, "totalTime": { "description": "the system time\n", "properties": { "count": { "description": "number of values summarized\n", "type": "integer" }, "counts": { "description": "array containing the values\n", "items": { "type": "integer" }, "type": "array" }, "sum": { "description": "summarized value of all counts\n", "type": "number" } }, "required": [ "sum", "count", "counts" ], "type": "object" } }, "required": [ "connectionTime", "totalTime", "requestTime", "queueTime", "ioTime", "bytesSent", "bytesReceived", "httpConnections" ], "type": "object" }, "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "enabled": { "description": "`true` if the server has the statistics module enabled. If not, don't expect any values.\n", "type": "boolean" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "http": { "description": "the numbers of requests by Verb\n", "properties": { "requestsAsync": { "description": "total number of asynchronous http requests\n", "type": "integer" }, "requestsDelete": { "description": "No of requests using the DELETE-verb\n", "type": "integer" }, "requestsGet": { "description": "No of requests using the GET-verb\n", "type": "integer" }, "requestsHead": { "description": "No of requests using the HEAD-verb\n", "type": "integer" }, "requestsOptions": { "description": "No of requests using the OPTIONS-verb\n", "type": "integer" }, "requestsOther": { "description": "No of requests using the none of the above identified verbs\n", "type": "integer" }, "requestsPatch": { "description": "No of requests using the PATCH-verb\n", "type": "integer" }, "requestsPost": { "description": "No of requests using the POST-verb\n", "type": "integer" }, "requestsPut": { "description": "No of requests using the PUT-verb\n", "type": "integer" }, "requestsTotal": { "description": "total number of http requests\n", "type": "integer" } }, "required": [ "requestsTotal", "requestsAsync", "requestsGet", "requestsHead", "requestsPost", "requestsPut", "requestsPatch", "requestsDelete", "requestsOptions", "requestsOther" ], "type": "object" }, "server": { "description": "statistics of the server\n", "properties": { "physicalMemory": { "description": "available physical memory on the server\n", "type": "integer" }, "threads": { "description": "Statistics about the server worker threads (excluding V8 specific or jemalloc specific threads and system threads)\n", "properties": { "in-progress": { "description": "The number of currently busy worker threads\n", "type": "integer" }, "queued": { "description": "The number of jobs queued up waiting for worker threads becoming available\n", "type": "integer" }, "scheduler-threads": { "description": "The number of spawned worker threads\n", "type": "integer" } }, "required": [ "scheduler-threads", "in-progress", "queued" ], "type": "object" }, "transactions": { "description": "Statistics about transactions\n", "properties": { "aborted": { "description": "the number of aborted transactions\n", "type": "integer" }, "committed": { "description": "the number of committed transactions\n", "type": "integer" }, "intermediateCommits": { "description": "the number of intermediate commits done\n", "type": "integer" }, "started": { "description": "the number of started transactions\n", "type": "integer" } }, "required": [ "started", "committed", "aborted", "intermediateCommits" ], "type": "object" }, "uptime": { "description": "time the server is up and running\n", "type": "integer" }, "v8Context": { "description": "Statistics about the V8 javascript contexts\n", "properties": { "available": { "description": "the number of currently spawned V8 contexts\n", "type": "integer" }, "busy": { "description": "the number of currently active V8 contexts\n", "type": "integer" }, "dirty": { "description": "the number of contexts that were previously used, and should now be garbage collected before being re-used\n", "type": "integer" }, "free": { "description": "the number of V8 contexts that are free to use\n", "type": "integer" }, "max": { "description": "the maximum number of V8 concurrent contexts we may spawn as configured by --javascript.v8-contexts\n", "type": "integer" }, "memory": { "description": "a list of V8 memory / garbage collection watermarks; Refreshed on every garbage collection run;\nPreserves min/max memory used at that time for 10 seconds\n", "items": { "properties": { "contextId": { "description": "ID of the context this set of memory statistics is from\n", "type": "integer" }, "countOfTimes": { "description": "how many times was the garbage collection run in these 10 seconds\n", "type": "integer" }, "heapMax": { "description": "High watermark of all garbage collection runs in 10 seconds\n", "type": "integer" }, "heapMin": { "description": "Low watermark of all garbage collection runs in these 10 seconds\n", "type": "integer" }, "tMax": { "description": "the timestamp where the 10 seconds interval started\n", "type": "number" } }, "required": [ "contextId", "tMax", "countOfTimes", "heapMax", "heapMin" ], "type": "object" }, "type": "array" }, "min": { "description": "the minimum number of V8 contexts that are spawned as configured by --javascript.v8-contexts-minimum\n", "type": "integer" } }, "required": [ "available", "busy", "dirty", "free", "max", "min", "memory" ], "type": "object" } }, "required": [ "uptime", "physicalMemory", "transactions", "v8Context", "threads" ], "type": "object" }, "system": { "description": "metrics gathered from the system about this process; may depend on the host OS\n", "properties": { "majorPageFaults": { "description": "pagefaults\n", "type": "integer" }, "minorPageFaults": { "description": "pagefaults\n", "type": "integer" }, "numberOfThreads": { "description": "the number of threads in the server\n", "type": "integer" }, "residentSize": { "description": "RSS of process\n", "type": "integer" }, "residentSizePercent": { "description": "RSS of process in %\n", "type": "number" }, "systemTime": { "description": "the system CPU time used by the server process\n", "type": "number" }, "userTime": { "description": "the user CPU time used by the server process\n", "type": "number" }, "virtualSize": { "description": "VSS of the process\n", "type": "integer" } }, "required": [ "minorPageFaults", "majorPageFaults", "userTime", "systemTime", "numberOfThreads", "residentSize", "residentSizePercent", "virtualSize" ], "type": "object" }, "time": { "description": "the current server timestamp\n", "type": "integer" } }, "required": [ "error", "code", "time", "errorMessage", "enabled", "system", "client", "http", "server" ], "type": "object" } } }, "description": "Statistics were returned successfully.\n" }, "404": { "description": "Statistics are disabled on the instance.\n" } }, "summary": "Get the statistics", "tags": [ "Monitoring" ] } }, "/_db/{database-name}/_admin/statistics-description": { "get": { "deprecated": true, "description": "\u003e **WARNING:**\nThis endpoint should no longer be used. It is deprecated from\nversion 3.8.0 onward and removed in ArangoDB v4.0.\nUse `GET /_admin/metrics` instead, which provides the data exposed by the\nstatistics API and a lot more.\n\n\nReturns a description of the statistics returned by `/_admin/statistics`.\nThe returned objects contains an array of statistics groups in the attribute\n`groups` and an array of statistics figures in the attribute `figures`.\n\nA statistics group is described by\n\n- `group`: The identifier of the group.\n- `name`: The name of the group.\n- `description`: A description of the group.\n\nA statistics figure is described by\n\n- `group`: The identifier of the group to which this figure belongs.\n- `identifier`: The identifier of the figure. It is unique within the group.\n- `name`: The name of the figure.\n- `description`: A description of the figure.\n- `type`: Either `current`, `accumulated`, or `distribution`.\n- `cuts`: The distribution vector.\n- `units`: Units in which the figure is measured.\n", "operationId": "getStatisticsDescription", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database. If the `--server.harden` startup option is enabled,\nadministrate access to the `_system` database is required.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "the error, `false` in this case\n", "type": "boolean" }, "figures": { "description": "A statistics figure\n", "items": { "properties": { "cuts": { "description": "The distribution vector.\n", "type": "string" }, "description": { "description": "A description of the figure.\n", "type": "string" }, "group": { "description": "The identifier of the group to which this figure belongs.\n", "type": "string" }, "identifier": { "description": "The identifier of the figure. It is unique within the group.\n", "type": "string" }, "name": { "description": "The name of the figure.\n", "type": "string" }, "type": { "description": "Either `current`, `accumulated`, or `distribution`.\n", "type": "string" }, "units": { "description": "Units in which the figure is measured.\n", "type": "string" } }, "required": [ "group", "identifier", "name", "description", "type", "cuts", "units" ], "type": "object" }, "type": "array" }, "groups": { "description": "A statistics group\n", "items": { "properties": { "description": { "description": "A description of the group.\n", "type": "string" }, "group": { "description": "The identifier of the group.\n", "type": "string" }, "name": { "description": "The name of the group.\n", "type": "string" } }, "required": [ "group", "name", "description" ], "type": "object" }, "type": "array" } }, "required": [ "groups", "figures", "code", "error" ], "type": "object" } } }, "description": "Description was returned successfully.\n" } }, "summary": "Get the statistics description", "tags": [ "Monitoring" ] } }, "/_db/{database-name}/_admin/status": { "get": { "description": "Returns status information about the server.\n", "operationId": "getStatus", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database. If the `--server.harden` startup option is enabled,\nadministrate access to the `_system` database is required.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "agency": { "description": "Information about the Agency.\n*Cluster only* (Coordinators and DB-Servers).\n", "properties": { "agencyComm": { "description": "Information about the communication with the Agency.\n*Cluster only* (Coordinators and DB-Servers).\n", "properties": { "endpoints": { "description": "A list of possible Agency endpoints.\n", "items": { "type": "string" }, "type": "array" } }, "type": "object" } }, "type": "object" }, "agent": { "description": "Information about the Agents.\n*Cluster only* (Agents)\n", "properties": { "endpoint": { "description": "The endpoint of the queried Agent.\n", "type": "string" }, "id": { "description": "Server ID of the queried Agent.\n", "type": "string" }, "leaderId": { "description": "Server ID of the leading Agent.\n", "type": "string" }, "leading": { "description": "Whether the queried Agent is the leader.\n", "type": "boolean" }, "term": { "description": "The current term number.\n", "type": "number" } }, "type": "object" }, "coordinator": { "description": "Information about the Coordinators.\n*Cluster only* (Coordinators)\n", "properties": { "foxxmaster": { "description": "The server ID of the Coordinator that is the Foxx master.\n**Deprecated**\n", "items": { "type": "string" }, "type": "array" }, "isFoxxmaster": { "description": "Whether the queried Coordinator is the Foxx master.\n**Deprecated**\n", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "foxxApi": { "description": "Whether the Foxx API is enabled. **Deprecated**\n", "type": "boolean" }, "host": { "description": "A host identifier defined by the `HOST` or `NODE_NAME` environment variable,\nor a fallback value using a machine identifier or the cluster/Agency address.\n", "type": "string" }, "hostname": { "description": "A hostname defined by the `HOSTNAME` environment variable.\n", "type": "string" }, "license": { "description": "ArangoDB Edition, either `\"community\"` or `\"enterprise\"`.\n", "type": "string" }, "mode": { "description": "Either `\"server\"` or `\"console\"`. **Deprecated**\n", "type": "string" }, "operationMode": { "description": "Either `\"server\"` or `\"console\"`. **Deprecated**\n", "type": "string" }, "pid": { "description": "The process ID of _arangod_.\n", "type": "number" }, "server": { "description": "Always `\"arango\"`.\n", "type": "string" }, "serverInfo": { "description": "Information about the server status.\n", "properties": { "address": { "description": "The address of the server, e.g. `tcp://[::1]:8530`.\n*Cluster only* (Coordinators and DB-Servers).\n", "type": "string" }, "maintenance": { "description": "Whether the maintenance mode is enabled.\n", "type": "boolean" }, "persistedId": { "description": "The persisted ID, e. g. `\"CRDN-e427b441-5087-4a9a-9983-2fb1682f3e2a\"`.\n*Cluster only* (Agents, Coordinators, and DB-Servers).\n", "type": "string" }, "progress": { "description": "Startup and recovery information.\n\nYou can check for changes to determine whether progress was made between two\ncalls, but you should not rely on specific values as they may change between\nArangoDB versions. The values are only expected to change during the startup and\nshutdown, i.e. while `maintenance` is `true`.\n\nYou need to start _arangod_ with the `--server.early-connections` startup option\nenabled to be able to query the endpoint during the startup process.\nIf authentication is enabled, then you need to use the super-user JWT for the\nrequest because the user management is not available during the startup.\n", "properties": { "feature": { "description": "Internal name of the feature that is currently being prepared, started,\nstopped or unprepared.\n", "type": "string" }, "phase": { "description": "Name of the lifecycle phase the instance is currently in. Normally one of\n`\"in prepare\"`, `\"in start\"`, `\"in wait\"`, `\"in shutdown\"`, `\"in stop\"`,\nor `\"in unprepare\"`.\n", "type": "string" }, "recoveryTick": { "description": "Current recovery sequence number value, if the instance is currently recovering.\nIf the instance is already past the recovery, this attribute will contain the\nlast handled recovery sequence number.\n", "type": "number" } }, "required": [ "phase", "feature", "recoveryTick" ], "type": "object" }, "readOnly": { "description": "Whether writes are disabled.\n", "type": "boolean" }, "rebootId": { "description": "The reboot ID. Changes on every restart.\n*Cluster only* (Agents, Coordinators, and DB-Servers).\n", "type": "number" }, "role": { "description": "Either `\"SINGLE\"`, `\"COORDINATOR\"`, `\"PRIMARY\"` (DB-Server), or `\"AGENT\"`.\n", "type": "string" }, "serverId": { "description": "The server ID, e.g. `\"CRDN-e427b441-5087-4a9a-9983-2fb1682f3e2a\"`.\n*Cluster only* (Coordinators and DB-Servers).\n", "type": "string" }, "state": { "description": "Either `\"STARTUP\"`, `\"SERVING\"`, or `\"SHUTDOWN\"`.\n*Cluster only* (Coordinators and DB-Servers).\n", "type": "string" }, "writeOpsEnabled": { "description": "Whether writes are enabled. **Deprecated**, use `readOnly` instead.\n", "type": "boolean" } }, "required": [ "progress", "role", "writeOpsEnabled", "readOnly", "maintenance" ], "type": "object" }, "version": { "description": "The server version as a string.\n", "type": "string" } }, "required": [ "server", "license", "version", "mode", "operationMode", "foxxApi", "host", "pid", "serverInfo" ], "type": "object" } } }, "description": "Status information was returned successfully.\n" } }, "summary": "Get server status information", "tags": [ "Administration" ] } }, "/_db/{database-name}/_admin/time": { "get": { "description": "The call returns an object with the `time` attribute. This contains the\ncurrent system time as a Unix timestamp with microsecond precision.\n", "operationId": "getTime", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "time": { "description": "The current system time as a Unix timestamp with microsecond precision of the server\n", "type": "number" } }, "required": [ "error", "code", "time" ], "type": "object" } } }, "description": "Time was returned successfully.\n" } }, "summary": "Get the system time", "tags": [ "Administration" ] } }, "/_db/{database-name}/_admin/usage-metrics": { "get": { "description": "Returns detailed shard usage metrics on DB-Servers.\n\nThese metrics can be enabled by setting the\n[`--server.export-shard-usage-metrics` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--serverexport-shard-usage-metrics)\nto `enabled-per-shard` to make DB-Servers collect per-shard\nusage metrics, or to `enabled-per-shard-per-user` to make DB-Servers collect\nusage metrics per shard and per user whenever a shard is accessed.\n", "operationId": "getUsageMetrics", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database. If the `--server.harden` startup option is enabled,\nadministrate access to the `_system` database is required.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Returns the usage metrics of the specified server (`PRMR-...`).\nIf no `serverId` is specified, the asked server replies.\nThis parameter is only meaningful on Coordinators.\n", "in": "query", "name": "serverId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Metrics were returned successfully.\n" } }, "summary": "Get the usage metrics", "tags": [ "Monitoring" ] } }, "/_db/{database-name}/_api/analyzer": { "get": { "description": "Retrieves a an array of all Analyzer definitions.\nThe resulting array contains objects with the following attributes:\n- `name`: the Analyzer name\n- `type`: the Analyzer type\n- `properties`: the properties used to configure the specified type\n- `features`: the set of features to set on the Analyzer generated fields\n", "operationId": "listAnalyzers", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Analyzer definitions was retrieved successfully.\n" } }, "summary": "List all Analyzers", "tags": [ "Analyzers" ] }, "post": { "description": "Creates a new Analyzer based on the provided configuration.\n", "operationId": "createAnalyzer", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "features": { "default": [], "description": "The set of features to set on the Analyzer generated fields.\n", "items": { "enum": [ "frequency", "norm", "position", "offset" ], "type": "string" }, "type": "array", "uniqueItems": true }, "name": { "description": "The Analyzer name.\n", "type": "string" }, "properties": { "description": "The properties used to configure the specified Analyzer type.\n", "type": "object" }, "type": { "description": "The Analyzer type.\n", "type": "string" } }, "required": [ "name", "type" ], "type": "object" } } } }, "responses": { "200": { "description": "An Analyzer with a matching name and definition already exists.\n" }, "201": { "description": "A new Analyzer definition was successfully created.\n" }, "400": { "description": "One or more of the required parameters is missing or one or more of the parameters\nis not valid.\n" }, "403": { "description": "The user does not have permission to create and Analyzer with this configuration.\n" } }, "summary": "Create an Analyzer", "tags": [ "Analyzers" ] } }, "/_db/{database-name}/_api/analyzer/{analyzer-name}": { "delete": { "description": "Removes an Analyzer configuration identified by `analyzer-name`.\n\nIf the Analyzer definition was successfully dropped, an object is returned with\nthe following attributes:\n- `error`: `false`\n- `name`: The name of the removed Analyzer\n", "operationId": "deleteAnalyzer", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the Analyzer to remove.\n", "in": "path", "name": "analyzer-name", "required": true, "schema": { "type": "string" } }, { "description": "The Analyzer configuration should be removed even if it is in-use.\n", "in": "query", "name": "force", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "The Analyzer configuration was removed successfully.\n" }, "400": { "description": "The `analyzer-name` was not supplied or another request parameter was not\nvalid.\n" }, "403": { "description": "The user does not have permission to remove this Analyzer configuration.\n" }, "404": { "description": "Such an Analyzer configuration does not exist.\n" }, "409": { "description": "The specified Analyzer configuration is still in use and `force` was omitted or\n`false` specified.\n" } }, "summary": "Remove an Analyzer", "tags": [ "Analyzers" ] }, "get": { "description": "Retrieves the full definition for the specified Analyzer name.\nThe resulting object contains the following attributes:\n- `name`: the Analyzer name\n- `type`: the Analyzer type\n- `properties`: the properties used to configure the specified type\n- `features`: the set of features to set on the Analyzer generated fields\n", "operationId": "getAnalyzer", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the Analyzer to retrieve.\n", "in": "path", "name": "analyzer-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Analyzer definition was retrieved successfully.\n" }, "404": { "description": "Such an Analyzer configuration does not exist.\n" } }, "summary": "Get an Analyzer definition", "tags": [ "Analyzers" ] } }, "/_db/{database-name}/_api/aqlfunction": { "get": { "deprecated": true, "description": "Returns all registered user-defined functions (UDFs) for the use in AQL of the\ncurrent database.\n\nThe call returns a JSON array with status codes and all user functions found under `result`.\n", "operationId": "listAqlUserFunctions", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Returns all registered AQL user functions from the specified namespace.\n", "in": "query", "name": "namespace", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "All functions, or the ones matching the `namespace` parameter\n", "items": { "properties": { "code": { "description": "A string representation of the function body\n", "type": "string" }, "isDeterministic": { "description": "Whether the function results are fully deterministic, i.e.\nthe function return value solely depends on the input value\nand the return value is the same for repeated calls with same\ninput.\n\nThis attribute is currently not used but may be used for\noptimizations in the future.\n", "type": "boolean" }, "name": { "description": "The fully qualified name of the user function\n", "type": "string" } }, "required": [ "name", "code", "isDeterministic" ], "type": "object" }, "type": "array" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "on success *HTTP 200* is returned.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "If the user function name is malformed, the server will respond with *HTTP 400*.\n" } }, "summary": "List the registered user-defined AQL functions", "tags": [ "Queries" ] }, "post": { "deprecated": true, "description": "Registers a user-defined function (UDF) written in JavaScript for the use in\nAQL queries in the current database.\n\nIn case of success, HTTP 200 is returned.\nIf the function isn't valid etc. HTTP 400 including a detailed error message will be returned.\n", "operationId": "createAqlUserFunction", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "A string representation of the JavaScript function definition.\n", "type": "string" }, "isDeterministic": { "default": false, "description": "Whether the function results are fully deterministic, i.e.\nthe function return value solely depends on the input value\nand the return value is the same for repeated calls with same\ninput.\n\nThis attribute is currently not used but may be used for\noptimizations in the future.\n", "type": "boolean" }, "name": { "description": "The fully qualified name of the user functions.\n", "type": "string" } }, "required": [ "name", "code" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "isNewlyCreated": { "description": "boolean flag to indicate whether the function was newly created (`false` in this case)\n", "type": "boolean" } }, "required": [ "error", "code", "isNewlyCreated" ], "type": "object" } } }, "description": "If the function already existed and was replaced by the\ncall, the server will respond with *HTTP 200*.\n" }, "201": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 201, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "isNewlyCreated": { "description": "boolean flag to indicate whether the function was newly created (`true` in this case)\n", "type": "boolean" } }, "required": [ "error", "code", "isNewlyCreated" ], "type": "object" } } }, "description": "If the function can be registered by the server, the server will respond with\n*HTTP 201*.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "If the JSON representation is malformed or mandatory data is missing from the\nrequest, the server will respond with *HTTP 400*.\n" } }, "summary": "Create a user-defined AQL function", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/aqlfunction/{name}": { "delete": { "deprecated": true, "description": "Deletes an existing user-defined function (UDF) or function group identified by\n`name` from the current database.\n", "operationId": "deleteAqlUserFunction", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "the name of the AQL user function.\n", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "Possible values:\n- `true`: The function name provided in `name` is treated as\n a namespace prefix, and all functions in the specified namespace will be deleted.\n The returned number of deleted functions may become 0 if none matches the string.\n- `false`: The function name provided in `name` must be fully\n qualified, including any namespaces. If none matches the `name`, HTTP 404 is returned.\n", "in": "query", "name": "group", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "deletedCount": { "description": "The number of deleted user functions, always `1` when `group` is set to `false`.\nAny number `\u003e= 0` when `group` is set to `true`.\n", "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" } }, "required": [ "error", "code", "deletedCount" ], "type": "object" } } }, "description": "If the function can be removed by the server, the server will respond with\n*HTTP 200*.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "If the user function name is malformed, the server will respond with *HTTP 400*.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "If the specified user function does not exist, the server will respond with *HTTP 404*.\n" } }, "summary": "Remove a user-defined AQL function", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/batch": { "post": { "deprecated": true, "description": "\u003e **WARNING:**\nThe `/_api/batch` endpoint was deprecated in v3.8.0 and has been removed\nin v3.12.3.\n\n\nExecutes a batch request. A batch request can contain any number of\nother requests that can be sent to ArangoDB in isolation. The benefit of\nusing batch requests is that batching requests requires less client/server\nroundtrips than when sending isolated requests.\n\nAll parts of a batch request are executed serially on the server. The\nserver will return the results of all parts in a single response when all\nparts are finished.\n\nTechnically, a batch request is a multipart HTTP request, with\ncontent-type `multipart/form-data`. A batch request consists of an\nenvelope and the individual batch part actions. Batch part actions\nare \"regular\" HTTP requests, including full header and an optional body.\nMultiple batch parts are separated by a boundary identifier. The\nboundary identifier is declared in the batch envelope. The MIME content-type\nfor each individual batch part must be `application/x-arango-batchpart`.\n\nPlease note that when constructing the individual batch parts, you must\nuse CRLF (`\\r\\n`) as the line terminator as in regular HTTP messages.\n\nThe response sent by the server will be an `HTTP 200` response, with an\noptional error summary header `x-arango-errors`. This header contains the\nnumber of batch part operations that failed with an HTTP error code of at\nleast 400. This header is only present in the response if the number of\nerrors is greater than zero.\n\nThe response sent by the server is a multipart response, too. It contains\nthe individual HTTP responses for all batch parts, including the full HTTP\nresult header (with status code and other potential headers) and an\noptional result body. The individual batch parts in the result are\nseparated using the same boundary value as specified in the request.\n\nThe order of batch parts in the response will be the same as in the\noriginal client request. Client can additionally use the `Content-Id`\nMIME header in a batch part to define an individual id for each batch part.\nThe server will return this id is the batch part responses, too.\n", "operationId": "executeBatchRequest", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "text/plain; charset=utf-8": { "schema": { "description": "The multipart batch request, consisting of the envelope and the individual\nbatch parts.\n" } } } }, "responses": { "200": { "description": "is returned if the batch was received successfully. HTTP 200 is returned\neven if one or multiple batch part actions failed.\n" }, "400": { "description": "is returned if the batch envelope is malformed or incorrectly formatted.\nThis code will also be returned if the content-type of the overall batch\nrequest or the individual MIME parts is not as expected.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" } }, "summary": "Execute a batch request", "tags": [ "Batch Requests" ] } }, "/_db/{database-name}/_api/collection": { "get": { "description": "Returns basic information for all collections in the current database,\noptionally excluding system collections.\n", "operationId": "listCollections", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Whether system collections should be excluded from the result.\n", "in": "query", "name": "excludeSystem", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "A list with every item holding basic collection metadata.\n", "items": { "properties": { "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "example": false, "type": "boolean" }, "name": { "description": "The name of the collection.\n", "example": "coll", "type": "string" }, "status": { "description": "The status of the collection.\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "type": { "description": "The type of the collection:\n- `0`: \"unknown\"\n- `2`: regular document collection\n- `3`: edge collection\n", "example": 2, "type": "integer" } }, "required": [ "id", "name", "status", "type", "isSystem", "globallyUniqueId" ], "type": "object" }, "type": "array" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "The list of collections.\n" } }, "summary": "List all collections", "tags": [ "Collections" ] }, "post": { "description": "Creates a new collection with a given name. The request must contain an\nobject with the following attributes.\n", "operationId": "createCollection", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The default is `true`, which means the server only reports success back to the\nclient when all replicas have created the collection. Set it to `false` if you want\nfaster server responses and don't care about full replication.\n", "in": "query", "name": "waitForSyncReplication", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "The default is `true`, which means the server checks if there are enough replicas\navailable at creation time and bail out otherwise. Set it to `false` to disable\nthis extra check.\n", "in": "query", "name": "enforceReplicationFactor", "required": false, "schema": { "default": true, "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cacheEnabled": { "default": false, "description": "Whether the in-memory hash cache for documents should be enabled for this\ncollection. Can be controlled globally with the `--cache.size`\nstartup option. The cache can speed up repeated reads of the same documents via\ntheir document keys. If the same documents are not fetched often or are\nmodified frequently, then you may disable the cache to avoid the maintenance\ncosts.\n", "type": "boolean" }, "computedValues": { "description": "An optional list of objects, each representing a computed value.\n", "items": { "properties": { "computeOn": { "default": [ "insert", "update", "replace" ], "description": "An array of strings to define on which write operations the value shall be\ncomputed.\n", "items": { "enum": [ "insert", "update", "replace" ], "type": "string" }, "type": "array", "uniqueItems": true }, "expression": { "description": "An AQL `RETURN` operation with an expression that computes the desired value.\nSee [Computed Value Expressions](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/computed-values/#computed-value-expressions) for details.\n", "type": "string" }, "failOnWarning": { "default": false, "description": "Whether to let the write operation fail if the expression produces a warning.\n", "type": "boolean" }, "keepNull": { "default": true, "description": "Whether the target attribute shall be set if the expression evaluates to `null`.\nYou can set the option to `false` to not set (or unset) the target attribute if\nthe expression returns `null`.\n", "type": "boolean" }, "name": { "description": "The name of the target attribute. Can only be a top-level attribute, but you\nmay return a nested object. Cannot be `_key`, `_id`, `_rev`, `_from`, `_to`,\nor a shard key attribute.\n", "type": "string" }, "overwrite": { "description": "Whether the computed value shall take precedence over a user-provided or\nexisting attribute.\n", "type": "boolean" } }, "required": [ "name", "expression", "overwrite" ], "type": "object" }, "type": "array" }, "distributeShardsLike": { "default": "", "description": "The name of another collection. If this property is set in a cluster, the\ncollection follows the `replicationFactor`, `numberOfShards` and `shardingStrategy`\nproperties of the specified collection (referred to as the\n_prototype collection_ or sometimes _initial collection_)\nand distributes the shards of this collection in the same way as the shards of\nthe other collection. This data co-location is utilized to optimize queries.\n\nYou need to use the same number of `shardKeys` as the prototype collection, but\nyou can use different attributes.\n\n\u003e **INFO:**\nUsing this parameter has consequences for the prototype\ncollection. It can no longer be dropped, before the sharding-imitating\ncollections are dropped. Equally, backups and restores of imitating\ncollections alone generate warnings (which can be overridden)\nabout a missing sharding prototype.\n", "type": "string" }, "isDisjoint": { "description": "Whether the collection is for a Disjoint SmartGraph.\nThis is an internal property.\n", "type": "boolean" }, "isSmart": { "description": "Whether the collection is for a SmartGraph or EnterpriseGraph.\nThis is an internal property.\n", "type": "boolean" }, "isSystem": { "default": false, "description": "If `true`, create a system collection. In this case, the `collection-name`\nshould start with an underscore. End-users should normally create non-system\ncollections only. API implementors may be required to create system\ncollections in very special occasions, but normally a regular collection will do.\n", "type": "boolean" }, "keyOptions": { "description": "additional options for key generation. If specified, then `keyOptions`\nshould be a JSON object containing the following attributes:\n", "properties": { "allowUserKeys": { "default": true, "description": "If set to `true`, then you are allowed to supply own key values in the\n`_key` attribute of documents. If set to `false`, then the key generator\nis solely responsible for generating keys and an error is raised if you\nsupply own key values in the `_key` attribute of documents.\n\n\n\u003e **WARNING:**\nYou should not use both user-specified and automatically generated document keys\nin the same collection in cluster deployments for collections with more than a\nsingle shard. Mixing the two can lead to conflicts because Coordinators that\nauto-generate keys in this case are not aware of all keys which are already used.\n", "type": "boolean" }, "increment": { "default": 1, "description": "The increment value for the `autoincrement` key generator.\nNot allowed for other key generator types.\n", "type": "integer" }, "offset": { "default": 0, "description": "The initial offset value for the `autoincrement` key generator.\nNot allowed for other key generator types.\n", "type": "integer" }, "type": { "default": "traditional", "description": "specifies the type of the key generator. The currently available generators are\n`traditional`, `autoincrement`, `uuid` and `padded`.\n\n- The `traditional` key generator generates numerical keys in ascending order.\n The sequence of keys is not guaranteed to be gap-free.\n\n- The `autoincrement` key generator generates numerical keys in ascending order,\n the initial offset and the spacing can be configured (**note**: `autoincrement`\n is only supported for non-sharded collections).\n The sequence of generated keys is not guaranteed to be gap-free, because a new key\n will be generated on every document insert attempt, not just for successful\n inserts.\n\n- The `padded` key generator generates keys of a fixed length (16 bytes) in\n ascending lexicographical sort order. This is ideal for the RocksDB storage engine,\n which will slightly benefit keys that are inserted in lexicographically\n ascending order. The key generator can be used in a single-server or cluster.\n The sequence of generated keys is not guaranteed to be gap-free.\n\n- The `uuid` key generator generates universally unique 128 bit keys, which\n are stored in hexadecimal human-readable format. This key generator can be used\n in a single-server or cluster to generate \"seemingly random\" keys. The keys\n produced by this key generator are not lexicographically sorted.\n\nPlease note that keys are only guaranteed to be truly ascending in single\nserver deployments and for collections that only have a single shard (that includes\ncollections in a OneShard database).\nThe reason is that for collections with more than a single shard, document keys\nare generated on Coordinator(s). For collections with a single shard, the document\nkeys are generated on the leader DB-Server, which has full control over the key\nsequence.\n", "type": "string" } }, "type": "object" }, "name": { "description": "The name of the collection.\n", "type": "string" }, "numberOfShards": { "default": 1, "description": "In a cluster, this value determines the\nnumber of shards to create for the collection.\n\nDefault:\nIf `distributeShardsLike` is set, the `numberOfShards`\nis that of the indicated prototype collection.\n", "type": "integer" }, "replicationFactor": { "description": "In a cluster, this attribute determines how many copies\nof each shard are kept on different DB-Servers. The value 1 means that only one\ncopy (no synchronous replication) is kept. A value of k means that k-1 replicas\nare kept. For SatelliteCollections, it needs to be the string `\"satellite\"`,\nwhich matches the replication factor to the number of DB-Servers.\n\nAny two copies reside on different DB-Servers. Replication between them is\nsynchronous, that is, every write operation to the \"leader\" copy will be replicated\nto all \"follower\" replicas, before the write operation is reported successful.\n\nIf a server fails, this is detected automatically and one of the servers holding\ncopies take over, usually without an error being reported.\n\nDefault:\nIf `distributeShardsLike` is set, the default `replicationFactor`\nis that of the indicated prototype collection. Otherwise,\nthe default `replicationFactor` is defined by the database.\n", "type": "integer" }, "schema": { "description": "The configuration of the collection-level schema validation for documents.\n", "properties": { "level": { "default": "strict", "description": "The level controls when the validation is triggered:\n- `\"none\"`: The rule is inactive and validation thus turned off.\n- `\"new\"`: Only newly inserted documents are validated.\n- `\"moderate\"`: New and modified documents must pass validation,\n except for modified documents where the OLD value did not pass\n validation already. This level is useful if you have documents\n which do not match your target structure, but you want to stop\n the insertion of more invalid documents and prohibit that valid\n documents are changed to invalid documents.\n- `\"strict\"`: All new and modified document must strictly pass\n validation. No exceptions are made.\n", "enum": [ "none", "new", "moderate", "strict" ], "type": "string" }, "message": { "description": "The error message to raise if the schema validation fails\nfor a document.\n", "type": "string" }, "rule": { "description": "A [JSON Schema](https://json-schema.org/specification-links#draft-4)\nobject (draft-4, without remote schemas).\n\nSee [Document Schema Validation](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/schema-validation/)\nfor details.\n", "type": "object" } }, "required": [ "rule" ], "type": "object" }, "shardKeys": { "default": [ "_key" ], "description": "In a cluster, this attribute determines\nwhich document attributes are used to determine the target shard for documents.\nDocuments are sent to shards based on the values of their shard key attributes.\nThe values of all shard key attributes in a document are hashed,\nand the hash value is used to determine the target shard.\n\n\u003e **INFO:**\nValues of shard key attributes cannot be changed once set.\n", "type": "string" }, "shardingStrategy": { "description": "This attribute specifies the name of the sharding strategy to use for\nthe collection. There are different sharding strategies\nto select from when creating a new collection. The selected `shardingStrategy`\nvalue remains fixed for the collection and cannot be changed afterwards.\nThis is important to make the collection keep its sharding settings and\nalways find documents already distributed to shards using the same\ninitial sharding algorithm.\n\nThe available sharding strategies are:\n- `community-compat`: default sharding used by ArangoDB\n Community Edition before version 3.4\n- `enterprise-compat`: default sharding used by ArangoDB\n Enterprise Edition before version 3.4\n- `enterprise-smart-edge-compat`: default sharding used by smart edge\n collections in ArangoDB Enterprise Edition before version 3.4\n- `hash`: default sharding used for new collections starting from version 3.4\n (excluding smart edge collections)\n- `enterprise-hash-smart-edge`: default sharding used for new\n smart edge collections starting from version 3.4\n- `enterprise-hex-smart-vertex`: sharding used for node collections of\n EnterpriseGraphs\n\nDefault:\nIf `distributeShardsLike` is set, the `shardingStrategy`\nis that of the indicated prototype collection. Otherwise,\nif no sharding strategy is specified, the default is `hash` for\nall normal collections, `enterprise-hash-smart-edge` for all smart edge\ncollections, and `enterprise-hex-smart-vertex` for EnterpriseGraph\nnode collections.\nManually overriding the sharding strategy does not yet provide a\nbenefit, but it may later in case other sharding strategies are added.\n", "type": "string" }, "smartGraphAttribute": { "description": "The attribute that is used for sharding: nodes with the same value of\nthis attribute are placed in the same shard. All nodes are required to\nhave this attribute set and it has to be a string. Edges derive the\nattribute from their connected nodes.\n", "type": "string" }, "smartJoinAttribute": { "description": "In a cluster, this attribute determines an attribute\nof the collection that must contain the shard key value of the referred-to\nSmartJoin collection. Additionally, the shard key for a document in this\ncollection must contain the value of this attribute, followed by a colon,\nfollowed by the actual primary key of the document.\n\nThis feature requires the\n`distributeShardsLike` attribute of the collection to be set to the name\nof another collection. It also requires the `shardKeys` attribute of the\ncollection to be set to a single shard key attribute, with an additional `:`\nat the end.\nA further restriction is that whenever documents are stored or updated in the\ncollection, the value stored in the `smartJoinAttribute` must be a string.\n", "type": "string" }, "type": { "default": 2, "description": "The type of the collection to create.\nThe following values for `type` are valid:\n\n- `2`: document collection\n- `3`: edge collection\n", "type": "integer" }, "waitForSync": { "default": false, "description": "If set to `true`, then the data is synchronized to disk before returning from a\ndocument create, update, replace or removal operation.\n", "type": "boolean" }, "writeConcern": { "description": "Determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\n\nDefault: If `distributeShardsLike` is set when the collection is created,\nthe initial `writeConcern` defaults to that of the indicated\nprototype collection. Afterwards, `writeConcern` is independent\nfrom the prototype collection and can differ from it.\n\nFor SatelliteCollections, the `writeConcern` is automatically controlled to\nequal the number of DB-Servers and has a value of `0`.\nOtherwise, the default value is controlled by the current database's\ndefault `writeConcern`, which uses the `--cluster.write-concern`\nstartup option as default, which defaults to `1`. _(cluster only)_\n", "type": "integer" } }, "required": [ "name" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cacheEnabled": { "description": "Whether the in-memory hash cache for documents is enabled for this\ncollection.\n", "type": "boolean" }, "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "computedValues": { "description": "A list of objects, each representing a computed value.\n", "items": { "properties": { "computeOn": { "description": "An array of strings that defines on which write operations the value is\ncomputed.\n", "example": [ "insert", "update", "replace" ], "items": { "enum": [ "insert", "update", "replace" ], "type": "string" }, "type": "array", "uniqueItems": true }, "expression": { "description": "An AQL `RETURN` operation with an expression that computes the desired value.\n", "type": "string" }, "failOnWarning": { "description": "Whether the write operation fails if the expression produces a warning.\n", "type": "boolean" }, "keepNull": { "description": "Whether the target attribute is set if the expression evaluates to `null`.\n", "type": "boolean" }, "name": { "description": "The name of the target attribute.\n", "type": "string" }, "overwrite": { "description": "Whether the computed value takes precedence over a user-provided or\nexisting attribute.\n", "type": "boolean" } }, "required": [ "name", "expression", "overwrite" ], "type": "object" }, "type": "array" }, "distributeShardsLike": { "description": "The name of another collection. This collection uses the `replicationFactor`,\n`numberOfShards` and `shardingStrategy` properties of the other collection and\nthe shards of this collection are distributed in the same way as the shards of\nthe other collection.\n", "type": "string" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isDisjoint": { "description": "Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSmart": { "description": "Whether the collection is used in a SmartGraph or EnterpriseGraph.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "type": "boolean" }, "keyOptions": { "description": "An object which contains key generation options.\n", "properties": { "allowUserKeys": { "description": "If set to `true`, then you are allowed to supply\nown key values in the `_key` attribute of a document. If set to\n`false`, then the key generator is solely responsible for\ngenerating keys and an error is raised if you supply own key values in the\n`_key` attribute of documents.\n\n\u003e **WARNING:**\nYou should not use both user-specified and automatically generated document keys\nin the same collection in cluster deployments for collections with more than a\nsingle shard. Mixing the two can lead to conflicts because Coordinators that\nauto-generate keys in this case are not aware of all keys which are already used.\n", "type": "boolean" }, "increment": { "description": "The increment value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "lastValue": { "description": "The offset value for the `autoincrement` or `padded` key generator.\nThis is an internal property for restoring dumps properly.\n", "type": "integer" }, "offset": { "description": "The initial offset value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "type": { "description": "Specifies the type of the key generator.\n", "enum": [ "traditional", "autoincrement", "uuid", "padded" ], "type": "string" } }, "required": [ "type", "allowUserKeys" ], "type": "object" }, "name": { "description": "The name of this collection.\n", "type": "string" }, "numberOfShards": { "description": "The number of shards of the collection. _(cluster only)_\n", "type": "integer" }, "replicationFactor": { "description": "Contains how many copies of each shard are kept on different DB-Servers.\nIt is an integer number in the range of 1-10 or the string `\"satellite\"`\nfor SatelliteCollections. _(cluster only)_\n\nIf `distributeShardsLike` is set, the actual replication factor\nis that of the indicated prototype collection. Query the\nprototype collection to get the current `replicationFactor`\nfor this collection. The reported `replicationFactor` of\nthis collection is the value as of the time at which the\ncollection was created, but it may have been changed\nfor the prototype collection in the meantime.\n", "type": "integer" }, "schema": { "description": "The configuration of the collection-level schema validation for documents.\n", "properties": { "level": { "default": "strict", "description": "The level controls when the validation is triggered:\n- `\"none\"`: The rule is inactive and validation thus turned off.\n- `\"new\"`: Only newly inserted documents are validated.\n- `\"moderate\"`: New and modified documents must pass validation,\n except for modified documents where the OLD value did not pass\n validation already. This level is useful if you have documents\n which do not match your target structure, but you want to stop\n the insertion of more invalid documents and prohibit that valid\n documents are changed to invalid documents.\n- `\"strict\"`: All new and modified document must strictly pass\n validation. No exceptions are made.\n", "enum": [ "none", "new", "moderate", "strict" ], "type": "string" }, "message": { "description": "The error message to raise if the schema validation fails\nfor a document.\n", "type": "string" }, "rule": { "description": "A [JSON Schema](https://json-schema.org/specification-links#draft-4)\nobject (draft-4, without remote schemas).\n\nSee [Document Schema Validation](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/schema-validation/)\nfor details.\n", "type": "object" }, "type": { "const": "json", "description": "The schema validation type. Only JSON Schema is supported.\n", "type": "string" } }, "required": [ "rule", "level", "message", "type" ], "type": "object" }, "shardKeys": { "description": "Contains the names of document attributes that are used to\ndetermine the target shard for documents. _(cluster only)_\n", "items": { "type": "string" }, "type": "array" }, "shardingStrategy": { "description": "The sharding strategy selected for the collection. _(cluster only)_\n", "enum": [ "community-compat", "enterprise-compat", "enterprise-smart-edge-compat", "hash", "enterprise-hash-smart-edge", "enterprise-hex-smart-vertex" ], "type": "string" }, "smartGraphAttribute": { "description": "The attribute that is used for sharding: nodes with the same value of\nthis attribute are placed in the same shard. All nodes are required to\nhave this attribute set and it has to be a string. Edges derive the\nattribute from their connected nodes. _(cluster only)_\n", "type": "string" }, "smartJoinAttribute": { "description": "Determines an attribute of the collection that must contain the shard key value\nof the referred-to SmartJoin collection. _(cluster only)_\n", "type": "string" }, "status": { "description": "The status of the collection (deprecated).\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "statusString": { "description": "The status of the collection as a descriptive string (deprecated).\n", "enum": [ "loaded", "deleted" ], "example": "loaded", "type": "string" }, "syncByRevision": { "description": "Whether the newer revision-based replication protocol is\nenabled for this collection. This is an internal property.\n", "type": "boolean" }, "type": { "description": "The type of the collection:\n - `0`: \"unknown\"\n - `2`: regular document collection\n - `3`: edge collection\n", "type": "integer" }, "waitForSync": { "description": "If `true`, creating, changing, or removing\ndocuments waits until the data has been synchronized to disk.\n", "type": "boolean" }, "writeConcern": { "description": "Determines how many copies of each shard are required to be\nin-sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\n\nIf `distributeShardsLike` is set when the collection is created,\nthe initial `writeConcern` defaults to that of the indicated\nprototype collection. Afterwards, `writeConcern` is independent\nfrom the prototype collection and can differ from it.\n\nFor SatelliteCollections, the `writeConcern` is automatically controlled to\nequal the number of DB-Servers and has a value of `0`.\nOtherwise, the default value is controlled by the current database's\ndefault `writeConcern`, which uses the `--cluster.write-concern`\nstartup option as default, which defaults to `1`. _(cluster only)_\n", "type": "integer" } }, "required": [ "error", "code", "name", "type", "status", "statusString", "isSystem", "id", "globallyUniqueId", "waitForSync", "keyOptions", "schema", "computedValues", "cacheEnabled", "syncByRevision" ], "type": "object" } } }, "description": "The collection has been created.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `name` or another required attribute is missing or an attribute\nhas an invalid value.\n" } }, "summary": "Create a collection", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}": { "delete": { "description": "Delete the collection identified by `collection-name` and all its documents.\n", "operationId": "deleteCollection", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection to drop.\n\n\u003e **WARNING:**\nAccessing collections by their numeric ID is deprecated from version 3.4.0 on.\nYou should reference them via their names instead.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } }, { "description": "Whether the collection to drop is a system collection. This parameter\nmust be set to `true` in order to drop a system collection.\n", "in": "query", "name": "isSystem", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "id": { "description": "The identifier of the dropped collection.\n", "type": "string" } }, "required": [ "error", "code", "id" ], "type": "object" } } }, "description": "Dropping the collection has been successful.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `collection-name` parameter is missing.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A collection called `collection-name` could not be found.\n" } }, "summary": "Drop a collection", "tags": [ "Collections" ] }, "get": { "description": "Returns the basic information about a specific collection.\n", "operationId": "getCollection", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n\n\u003e **WARNING:**\nAccessing collections by their numeric ID is deprecated from version 3.4.0 on.\nYou should reference them via their names instead.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "example": false, "type": "boolean" }, "name": { "description": "The name of the collection.\n", "example": "coll", "type": "string" }, "status": { "description": "The status of the collection.\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "type": { "description": "The type of the collection:\n- `0`: \"unknown\"\n- `2`: regular document collection\n- `3`: edge collection\n", "example": 2, "type": "integer" } }, "required": [ "error", "code", "id", "name", "status", "type", "isSystem", "globallyUniqueId" ], "type": "object" } } }, "description": "The basic information about a collection.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "example": 1203, "type": "integer" } }, "required": [ "code", "error", "errorMessage", "errorNum" ], "type": "object" } } }, "description": "The specified collection is unknown.\n" } }, "summary": "Get the collection information", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/checksum": { "get": { "description": "Calculates a checksum of the meta-data (keys and optionally revision ids) and\noptionally the document data in the collection.\n\nThe checksum can be used to compare if two collections on different ArangoDB\ninstances contain the same contents. The current revision of the collection is\nreturned too so one can make sure the checksums are calculated for the same\nstate of data.\n\nBy default, the checksum is only calculated on the `_key` system attribute\nof the documents contained in the collection. For edge collections, the system\nattributes `_from` and `_to` are also included in the calculation.\n\nBy setting the optional query parameter `withRevisions` to `true`, then revision\nIDs (`_rev` system attributes) are included in the checksumming.\n\nBy providing the optional query parameter `withData` with a value of `true`,\nthe user-defined document attributes are included in the calculation, too.\n\n\u003e **INFO:**\nIncluding user-defined attributes will make the checksumming slower.\n", "operationId": "getCollectionChecksum", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n\n\u003e **WARNING:**\nAccessing collections by their numeric ID is deprecated from version 3.4.0 on.\nYou should reference them via their names instead.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } }, { "description": "Whether to include document revision ids in the checksum calculation.\n", "in": "query", "name": "withRevisions", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to include document body data in the checksum calculation.\n", "in": "query", "name": "withData", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "checksum": { "description": "The calculated checksum as a number.\n" }, "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "example": false, "type": "boolean" }, "name": { "description": "The name of the collection.\n", "example": "coll", "type": "string" }, "revision": { "description": "The collection revision id as a string.\n" }, "status": { "description": "The status of the collection.\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "type": { "description": "The type of the collection:\n- `0`: \"unknown\"\n- `2`: regular document collection\n- `3`: edge collection\n", "example": 2, "type": "integer" } }, "required": [ "checksum", "revision", "error", "code", "id", "name", "status", "type", "isSystem", "globallyUniqueId" ], "type": "object" } } }, "description": "The basic information about the collection but additionally the\ncollection `checksum` and `revision`.\n" }, "400": { "description": "If the `collection-name` placeholder is missing, then a *HTTP 400* is\nreturned.\n" }, "404": { "description": "If the collection is unknown, then a *HTTP 404*\nis returned.\n" } }, "summary": "Get the collection checksum", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/compact": { "put": { "description": "Compacts the data of a collection in order to reclaim disk space.\nThe operation will compact the document and index data by rewriting the\nunderlying .sst files and only keeping the relevant entries.\n\nUnder normal circumstances, running a compact operation is not necessary, as\nthe collection data will eventually get compacted anyway. However, in some\nsituations, e.g. after running lots of update/replace or remove operations,\nthe disk data for a collection may contain a lot of outdated data for which the\nspace shall be reclaimed. In this case the compaction operation can be used.\n", "operationId": "compactCollection", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Name of the collection to compact\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "example": false, "type": "boolean" }, "name": { "description": "The name of the collection.\n", "example": "coll", "type": "string" }, "status": { "description": "The status of the collection.\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "type": { "description": "The type of the collection:\n- `0`: \"unknown\"\n- `2`: regular document collection\n- `3`: edge collection\n", "example": 2, "type": "integer" } }, "required": [ "error", "code", "name", "type", "isSystem", "status", "id", "globallyUniqueId" ], "type": "object" } } }, "description": "The compaction has been started successfully.\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "If the request was not authenticated as a user with sufficient rights.\n" } }, "summary": "Compact a collection", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/count": { "get": { "description": "Get the number of documents in a collection.\n", "operationId": "getCollectionCount", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n\n\u003e **WARNING:**\nAccessing collections by their numeric ID is deprecated from version 3.4.0 on.\nYou should reference them via their names instead.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cacheEnabled": { "description": "Whether the in-memory hash cache for documents is enabled for this\ncollection.\n", "type": "boolean" }, "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "computedValues": { "description": "A list of objects, each representing a computed value.\n", "items": { "properties": { "computeOn": { "description": "An array of strings that defines on which write operations the value is\ncomputed.\n", "example": [ "insert", "update", "replace" ], "items": { "enum": [ "insert", "update", "replace" ], "type": "string" }, "type": "array", "uniqueItems": true }, "expression": { "description": "An AQL `RETURN` operation with an expression that computes the desired value.\n", "type": "string" }, "failOnWarning": { "description": "Whether the write operation fails if the expression produces a warning.\n", "type": "boolean" }, "keepNull": { "description": "Whether the target attribute is set if the expression evaluates to `null`.\n", "type": "boolean" }, "name": { "description": "The name of the target attribute.\n", "type": "string" }, "overwrite": { "description": "Whether the computed value takes precedence over a user-provided or\nexisting attribute.\n", "type": "boolean" } }, "required": [ "name", "expression", "overwrite" ], "type": "object" }, "type": "array" }, "count": { "description": "The number of documents currently present in the collection.\n", "type": "integer" }, "distributeShardsLike": { "description": "The name of another collection. This collection uses the `replicationFactor`,\n`numberOfShards` and `shardingStrategy` properties of the other collection and\nthe shards of this collection are distributed in the same way as the shards of\nthe other collection.\n", "type": "string" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isDisjoint": { "description": "Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSmart": { "description": "Whether the collection is used in a SmartGraph or EnterpriseGraph.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "type": "boolean" }, "keyOptions": { "description": "An object which contains key generation options.\n", "properties": { "allowUserKeys": { "description": "If set to `true`, then you are allowed to supply\nown key values in the `_key` attribute of a document. If set to\n`false`, then the key generator is solely responsible for\ngenerating keys and an error is raised if you supply own key values in the\n`_key` attribute of documents.\n\n\u003e **WARNING:**\nYou should not use both user-specified and automatically generated document keys\nin the same collection in cluster deployments for collections with more than a\nsingle shard. Mixing the two can lead to conflicts because Coordinators that\nauto-generate keys in this case are not aware of all keys which are already used.\n", "type": "boolean" }, "increment": { "description": "The increment value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "lastValue": { "description": "The offset value of the `autoincrement` or `padded` key generator.\nThis is an internal property for restoring dumps properly.\n", "type": "integer" }, "offset": { "description": "The initial offset value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "type": { "description": "Specifies the type of the key generator.\n", "enum": [ "traditional", "autoincrement", "uuid", "padded" ], "type": "string" } }, "required": [ "type", "allowUserKeys" ], "type": "object" }, "name": { "description": "The name of this collection.\n", "type": "string" }, "numberOfShards": { "description": "The number of shards of the collection. _(cluster only)_\n", "type": "integer" }, "replicationFactor": { "description": "Contains how many copies of each shard are kept on different DB-Servers.\nIt is an integer number in the range of 1-10 or the string `\"satellite\"`\nfor SatelliteCollections. _(cluster only)_\n\nIf `distributeShardsLike` is set, the actual replication factor\nis that of the indicated prototype collection. Query the\nprototype collection to get the current `replicationFactor`\nfor this collection. The reported `replicationFactor` of\nthis collection is the value as of the time at which the\ncollection was created, but it may have been changed\nfor the prototype collection in the meantime.\n", "type": "integer" }, "schema": { "description": "The configuration of the collection-level schema validation for documents.\n", "properties": { "level": { "default": "strict", "description": "The level controls when the validation is triggered:\n- `\"none\"`: The rule is inactive and validation thus turned off.\n- `\"new\"`: Only newly inserted documents are validated.\n- `\"moderate\"`: New and modified documents must pass validation,\n except for modified documents where the OLD value did not pass\n validation already. This level is useful if you have documents\n which do not match your target structure, but you want to stop\n the insertion of more invalid documents and prohibit that valid\n documents are changed to invalid documents.\n- `\"strict\"`: All new and modified document must strictly pass\n validation. No exceptions are made.\n", "enum": [ "none", "new", "moderate", "strict" ], "type": "string" }, "message": { "description": "The error message to raise if the schema validation fails\nfor a document.\n", "type": "string" }, "rule": { "description": "A [JSON Schema](https://json-schema.org/specification-links#draft-4)\nobject (draft-4, without remote schemas).\n\nSee [Document Schema Validation](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/schema-validation/)\nfor details.\n", "type": "object" }, "type": { "const": "json", "description": "The schema validation type. Only JSON Schema is supported.\n", "type": "string" } }, "required": [ "rule", "level", "message", "type" ], "type": "object" }, "shardKeys": { "description": "Contains the names of document attributes that are used to\ndetermine the target shard for documents. _(cluster only)_\n", "items": { "type": "string" }, "type": "array" }, "shardingStrategy": { "description": "The sharding strategy selected for the collection. _(cluster only)_\n", "enum": [ "community-compat", "enterprise-compat", "enterprise-smart-edge-compat", "hash", "enterprise-hash-smart-edge", "enterprise-hex-smart-vertex" ], "type": "string" }, "smartGraphAttribute": { "description": "The attribute that is used for sharding: nodes with the same value of\nthis attribute are placed in the same shard. All nodes are required to\nhave this attribute set and it has to be a string. Edges derive the\nattribute from their connected nodes. _(cluster only)_\n", "type": "string" }, "smartJoinAttribute": { "description": "Determines an attribute of the collection that must contain the shard key value\nof the referred-to SmartJoin collection. _(cluster only)_\n", "type": "string" }, "status": { "description": "The status of the collection (deprecated).\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "statusString": { "description": "The status of the collection as a descriptive string (deprecated).\n", "enum": [ "loaded", "deleted" ], "example": "loaded", "type": "string" }, "syncByRevision": { "description": "Whether the newer revision-based replication protocol is\nenabled for this collection. This is an internal property.\n", "type": "boolean" }, "type": { "description": "The type of the collection:\n - `0`: \"unknown\"\n - `2`: regular document collection\n - `3`: edge collection\n", "type": "integer" }, "waitForSync": { "description": "If `true`, creating, changing, or removing\ndocuments waits until the data has been synchronized to disk.\n", "type": "boolean" }, "writeConcern": { "description": "Determines how many copies of each shard are required to be\nin-sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\n\nIf `distributeShardsLike` is set when the collection is created,\nthe initial `writeConcern` defaults to that of the indicated\nprototype collection. Afterwards, `writeConcern` is independent\nfrom the prototype collection and can differ from it.\n\nFor SatelliteCollections, the `writeConcern` is automatically controlled to\nequal the number of DB-Servers and has a value of `0`.\nOtherwise, the default value is controlled by the current database's\ndefault `writeConcern`, which uses the `--cluster.write-concern`\nstartup option as default, which defaults to `1`. _(cluster only)_\n", "type": "integer" } }, "required": [ "count", "error", "code", "name", "type", "status", "statusString", "isSystem", "id", "globallyUniqueId", "waitForSync", "keyOptions", "schema", "computedValues", "cacheEnabled", "syncByRevision" ], "type": "object" } } }, "description": "All properties of the collection but additionally the document `count`.\n" }, "400": { "description": "The `collection-name` parameter is missing.\n" }, "404": { "description": "The collection cannot be found.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" } }, "summary": "Get the document count of a collection", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/figures": { "get": { "description": "Get the number of documents and additional statistical information\nabout the collection.\n", "operationId": "getCollectionFigures", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n\n\u003e **WARNING:**\nAccessing collections by their numeric ID is deprecated from version 3.4.0 on.\nYou should reference them via their names instead.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } }, { "description": "Setting `details` to `true` will return extended storage engine-specific\ndetails to the figures. The details are intended for debugging ArangoDB itself\nand their format is subject to change. By default, `details` is set to `false`,\nso no details are returned and the behavior is identical to previous versions\nof ArangoDB.\nPlease note that requesting `details` may cause additional load and thus have\nan impact on performance.\n", "in": "query", "name": "details", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cacheEnabled": { "description": "Whether the in-memory hash cache for documents is enabled for this\ncollection.\n", "type": "boolean" }, "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "computedValues": { "description": "A list of objects, each representing a computed value.\n", "items": { "properties": { "computeOn": { "description": "An array of strings that defines on which write operations the value is\ncomputed.\n", "example": [ "insert", "update", "replace" ], "items": { "enum": [ "insert", "update", "replace" ], "type": "string" }, "type": "array", "uniqueItems": true }, "expression": { "description": "An AQL `RETURN` operation with an expression that computes the desired value.\n", "type": "string" }, "failOnWarning": { "description": "Whether the write operation fails if the expression produces a warning.\n", "type": "boolean" }, "keepNull": { "description": "Whether the target attribute is set if the expression evaluates to `null`.\n", "type": "boolean" }, "name": { "description": "The name of the target attribute.\n", "type": "string" }, "overwrite": { "description": "Whether the computed value takes precedence over a user-provided or\nexisting attribute.\n", "type": "boolean" } }, "required": [ "name", "expression", "overwrite" ], "type": "object" }, "type": "array" }, "count": { "description": "The number of documents currently present in the collection.\n", "type": "integer" }, "distributeShardsLike": { "description": "The name of another collection. This collection uses the `replicationFactor`,\n`numberOfShards` and `shardingStrategy` properties of the other collection and\nthe shards of this collection are distributed in the same way as the shards of\nthe other collection.\n", "type": "string" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "figures": { "description": "The metrics of the collection.\n", "properties": { "cacheInUse": { "description": "Whether the document cache is enabled for this collection.\n", "type": "boolean" }, "cacheLifeTimeHitRate": { "description": "The overall cache hit ratio in percent. In cluster deployments,\nit is the sum of percentages of all shards.\n\nThe attribute is only present if `cacheInUse` is `true`.\n", "type": "number" }, "cacheSize": { "description": "The total memory usage of the document cache in bytes.\n", "type": "integer" }, "cacheUsage": { "description": "The current data memory usage of the document cache in bytes.\n", "type": "integer" }, "cacheWindowedHitRate": { "description": "The cache hit ratio of the past several thousand find\noperations in percent. In cluster deployments,\nit is the sum of percentages of all shards.\n\nThe attribute is only present if `cacheInUse` is `true`.\n", "type": "number" }, "documentsSize": { "description": "The approximate on-disk size of the documents in bytes.\n", "type": "integer" }, "engine": { "description": "Extended, storage-engine specific figures.\nOnly included if the `details` query parameter is set to `true`.\n", "properties": { "documents": { "description": "The number of documents determined by iterating over all\nRocksDB keys in range of the column family and counting them.\n", "type": "integer" }, "indexes": { "description": "The detailed index metrics with the number of entries per index.\n", "items": { "properties": { "count": { "description": "The number of index entries.\n", "type": "integer" }, "id": { "description": "The identifier of the index.\n", "type": "integer" }, "type": { "description": "The index type.\nA `persistent` index is reported as `rocksdb-persistent`.\n", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "indexes": { "description": "The coarse index metrics.\n", "properties": { "count": { "description": "The total number of indexes defined for the collection, including the pre-defined\nindexes (e.g. primary index).\n", "type": "integer" }, "size": { "description": "The total memory allocated for indexes in bytes.\n", "type": "integer" } }, "required": [ "count", "size" ], "type": "object" } }, "required": [ "indexes" ], "type": "object" }, "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isDisjoint": { "description": "Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSmart": { "description": "Whether the collection is used in a SmartGraph or EnterpriseGraph.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "type": "boolean" }, "keyOptions": { "description": "An object which contains key generation options.\n", "properties": { "allowUserKeys": { "description": "If set to `true`, then you are allowed to supply\nown key values in the `_key` attribute of a document. If set to\n`false`, then the key generator is solely responsible for\ngenerating keys and an error is raised if you supply own key values in the\n`_key` attribute of documents.\n\n\u003e **WARNING:**\nYou should not use both user-specified and automatically generated document keys\nin the same collection in cluster deployments for collections with more than a\nsingle shard. Mixing the two can lead to conflicts because Coordinators that\nauto-generate keys in this case are not aware of all keys which are already used.\n", "type": "boolean" }, "increment": { "description": "The increment value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "lastValue": { "description": "The offset value of the `autoincrement` or `padded` key generator.\nThis is an internal property for restoring dumps properly.\n", "type": "integer" }, "offset": { "description": "The initial offset value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "type": { "description": "Specifies the type of the key generator.\n", "enum": [ "traditional", "autoincrement", "uuid", "padded" ], "type": "string" } }, "required": [ "type", "allowUserKeys" ], "type": "object" }, "name": { "description": "The name of this collection.\n", "type": "string" }, "numberOfShards": { "description": "The number of shards of the collection. _(cluster only)_\n", "type": "integer" }, "replicationFactor": { "description": "Contains how many copies of each shard are kept on different DB-Servers.\nIt is an integer number in the range of 1-10 or the string `\"satellite\"`\nfor SatelliteCollections. _(cluster only)_\n\nIf `distributeShardsLike` is set, the actual replication factor\nis that of the indicated prototype collection. Query the\nprototype collection to get the current `replicationFactor`\nfor this collection. The reported `replicationFactor` of\nthis collection is the value as of the time at which the\ncollection was created, but it may have been changed\nfor the prototype collection in the meantime.\n", "type": "integer" }, "schema": { "description": "The configuration of the collection-level schema validation for documents.\n", "properties": { "level": { "default": "strict", "description": "The level controls when the validation is triggered:\n- `\"none\"`: The rule is inactive and validation thus turned off.\n- `\"new\"`: Only newly inserted documents are validated.\n- `\"moderate\"`: New and modified documents must pass validation,\n except for modified documents where the OLD value did not pass\n validation already. This level is useful if you have documents\n which do not match your target structure, but you want to stop\n the insertion of more invalid documents and prohibit that valid\n documents are changed to invalid documents.\n- `\"strict\"`: All new and modified document must strictly pass\n validation. No exceptions are made.\n", "enum": [ "none", "new", "moderate", "strict" ], "type": "string" }, "message": { "description": "The error message to raise if the schema validation fails\nfor a document.\n", "type": "string" }, "rule": { "description": "A [JSON Schema](https://json-schema.org/specification-links#draft-4)\nobject (draft-4, without remote schemas).\n\nSee [Document Schema Validation](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/schema-validation/)\nfor details.\n", "type": "object" }, "type": { "const": "json", "description": "The schema validation type. Only JSON Schema is supported.\n", "type": "string" } }, "required": [ "rule", "level", "message", "type" ], "type": "object" }, "shardKeys": { "description": "Contains the names of document attributes that are used to\ndetermine the target shard for documents. _(cluster only)_\n", "items": { "type": "string" }, "type": "array" }, "shardingStrategy": { "description": "The sharding strategy selected for the collection. _(cluster only)_\n", "enum": [ "community-compat", "enterprise-compat", "enterprise-smart-edge-compat", "hash", "enterprise-hash-smart-edge", "enterprise-hex-smart-vertex" ], "type": "string" }, "smartGraphAttribute": { "description": "The attribute that is used for sharding: nodes with the same value of\nthis attribute are placed in the same shard. All nodes are required to\nhave this attribute set and it has to be a string. Edges derive the\nattribute from their connected nodes. _(cluster only)_\n", "type": "string" }, "smartJoinAttribute": { "description": "Determines an attribute of the collection that must contain the shard key value\nof the referred-to SmartJoin collection. _(cluster only)_\n", "type": "string" }, "status": { "description": "The status of the collection (deprecated).\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "statusString": { "description": "The status of the collection as a descriptive string (deprecated).\n", "enum": [ "loaded", "deleted" ], "example": "loaded", "type": "string" }, "syncByRevision": { "description": "Whether the newer revision-based replication protocol is\nenabled for this collection. This is an internal property.\n", "type": "boolean" }, "type": { "description": "The type of the collection:\n - `0`: \"unknown\"\n - `2`: regular document collection\n - `3`: edge collection\n", "type": "integer" }, "waitForSync": { "description": "If `true`, creating, changing, or removing\ndocuments waits until the data has been synchronized to disk.\n", "type": "boolean" }, "writeConcern": { "description": "Determines how many copies of each shard are required to be\nin-sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\n\nIf `distributeShardsLike` is set when the collection is created,\nthe initial `writeConcern` defaults to that of the indicated\nprototype collection. Afterwards, `writeConcern` is independent\nfrom the prototype collection and can differ from it.\n\nFor SatelliteCollections, the `writeConcern` is automatically controlled to\nequal the number of DB-Servers and has a value of `0`.\nOtherwise, the default value is controlled by the current database's\ndefault `writeConcern`, which uses the `--cluster.write-concern`\nstartup option as default, which defaults to `1`. _(cluster only)_\n", "type": "integer" } }, "required": [ "count", "figures", "error", "code", "name", "type", "status", "statusString", "isSystem", "id", "globallyUniqueId", "waitForSync", "keyOptions", "schema", "computedValues", "cacheEnabled", "syncByRevision" ], "type": "object" } } }, "description": "All properties of the collection but additionally the document `count`\nand collection `figures`.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `collection-name` parameter is missing.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A collection called `collection-name` could not be found.\n" } }, "summary": "Get the collection statistics", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/load": { "put": { "deprecated": true, "description": "\u003e **WARNING:**\nThe load function is deprecated from version 3.8.0 onwards and is a no-op\nfrom version 3.9.0 onwards. It should no longer be used and is removed\nin ArangoDB v4.0.\n\n\nSince ArangoDB version 3.9.0 this API does nothing. Previously, it used to\nload a collection into memory.\n", "operationId": "loadCollection", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n\n\u003e **WARNING:**\nAccessing collections by their numeric ID is deprecated from version 3.4.0 on.\nYou should reference them via their names instead.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "count": { "description": "The number of documents currently present in the collection.\n", "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "example": false, "type": "boolean" }, "name": { "description": "The name of the collection.\n", "example": "coll", "type": "string" }, "status": { "description": "The status of the collection.\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "type": { "description": "The type of the collection:\n- `0`: \"unknown\"\n- `2`: regular document collection\n- `3`: edge collection\n", "example": 2, "type": "integer" } }, "required": [ "error", "code", "name", "type", "isSystem", "status", "id", "globallyUniqueId" ], "type": "object" } } }, "description": "Returns the basic collection properties for compatibility reasons.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `collection-name` parameter or the `name` attribute is missing.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A collection called `collection-name` could not be found.\n" } }, "summary": "Load a collection", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/loadIndexesIntoMemory": { "put": { "description": "You can call this endpoint to try to cache this collection's index entries in\nthe main memory. Index lookups served from the memory cache can be much faster\nthan lookups not stored in the cache, resulting in a performance boost.\n\nThe endpoint iterates over suitable indexes of the collection and stores the\nindexed values (not the entire document data) in memory. This is implemented for\nedge indexes only.\n\nThe endpoint returns as soon as the index warmup has been scheduled. The index\nwarmup may still be ongoing in the background, even after the return value has\nalready been sent. As all suitable indexes are scanned, it may cause significant\nI/O activity and background load.\n\nThis feature honors memory limits. If the indexes you want to load are smaller\nthan your memory limit, this feature guarantees that most index values are\ncached. If the index is greater than your memory limit, this feature fills\nup values up to this limit. You cannot control which indexes of the collection\nshould have priority over others.\n\nIt is guaranteed that the in-memory cache data is consistent with the stored\nindex data at all times.\n", "operationId": "loadCollectionIndexes", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n\n\u003e **WARNING:**\nAccessing collections by their numeric ID is deprecated from version 3.4.0 on.\nYou should reference them via their names instead.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "The value `true`.\n", "example": true, "type": "boolean" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "The index loading has been scheduled for all suitable indexes.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `collection-name` parameter is missing.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A collection called `collection-name` could not be found.\n" } }, "summary": "Load collection indexes into memory", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/properties": { "get": { "description": "Returns all properties of the specified collection.\n", "operationId": "getCollectionProperties", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n\n\u003e **WARNING:**\nAccessing collections by their numeric ID is deprecated from version 3.4.0 on.\nYou should reference them via their names instead.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cacheEnabled": { "description": "Whether the in-memory hash cache for documents is enabled for this\ncollection.\n", "type": "boolean" }, "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "computedValues": { "description": "A list of objects, each representing a computed value.\n", "items": { "properties": { "computeOn": { "description": "An array of strings that defines on which write operations the value is\ncomputed.\n", "example": [ "insert", "update", "replace" ], "items": { "enum": [ "insert", "update", "replace" ], "type": "string" }, "type": "array", "uniqueItems": true }, "expression": { "description": "An AQL `RETURN` operation with an expression that computes the desired value.\n", "type": "string" }, "failOnWarning": { "description": "Whether the write operation fails if the expression produces a warning.\n", "type": "boolean" }, "keepNull": { "description": "Whether the target attribute is set if the expression evaluates to `null`.\n", "type": "boolean" }, "name": { "description": "The name of the target attribute.\n", "type": "string" }, "overwrite": { "description": "Whether the computed value takes precedence over a user-provided or\nexisting attribute.\n", "type": "boolean" } }, "required": [ "name", "expression", "overwrite" ], "type": "object" }, "type": "array" }, "distributeShardsLike": { "description": "The name of another collection. This collection uses the `replicationFactor`,\n`numberOfShards` and `shardingStrategy` properties of the other collection and\nthe shards of this collection are distributed in the same way as the shards of\nthe other collection.\n", "type": "string" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isDisjoint": { "description": "Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSmart": { "description": "Whether the collection is used in a SmartGraph or EnterpriseGraph.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "type": "boolean" }, "keyOptions": { "description": "An object which contains key generation options.\n", "properties": { "allowUserKeys": { "description": "If set to `true`, then you are allowed to supply\nown key values in the `_key` attribute of a document. If set to\n`false`, then the key generator is solely responsible for\ngenerating keys and an error is raised if you supply own key values in the\n`_key` attribute of documents.\n\n\u003e **WARNING:**\nYou should not use both user-specified and automatically generated document keys\nin the same collection in cluster deployments for collections with more than a\nsingle shard. Mixing the two can lead to conflicts because Coordinators that\nauto-generate keys in this case are not aware of all keys which are already used.\n", "type": "boolean" }, "increment": { "description": "The increment value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "lastValue": { "description": "The offset value of the `autoincrement` or `padded` key generator.\nThis is an internal property for restoring dumps properly.\n", "type": "integer" }, "offset": { "description": "The initial offset value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "type": { "description": "Specifies the type of the key generator.\n", "enum": [ "traditional", "autoincrement", "uuid", "padded" ], "type": "string" } }, "required": [ "type", "allowUserKeys" ], "type": "object" }, "name": { "description": "The name of this collection.\n", "type": "string" }, "numberOfShards": { "description": "The number of shards of the collection. _(cluster only)_\n", "type": "integer" }, "replicationFactor": { "description": "Contains how many copies of each shard are kept on different DB-Servers.\nIt is an integer number in the range of 1-10 or the string `\"satellite\"`\nfor SatelliteCollections. _(cluster only)_\n\nIf `distributeShardsLike` is set, the actual replication factor\nis that of the indicated prototype collection. Query the\nprototype collection to get the current `replicationFactor`\nfor this collection. The reported `replicationFactor` of\nthis collection is the value as of the time at which the\ncollection was created, but it may have been changed\nfor the prototype collection in the meantime.\n", "type": "integer" }, "schema": { "description": "The configuration of the collection-level schema validation for documents.\n", "properties": { "level": { "default": "strict", "description": "The level controls when the validation is triggered:\n- `\"none\"`: The rule is inactive and validation thus turned off.\n- `\"new\"`: Only newly inserted documents are validated.\n- `\"moderate\"`: New and modified documents must pass validation,\n except for modified documents where the OLD value did not pass\n validation already. This level is useful if you have documents\n which do not match your target structure, but you want to stop\n the insertion of more invalid documents and prohibit that valid\n documents are changed to invalid documents.\n- `\"strict\"`: All new and modified document must strictly pass\n validation. No exceptions are made.\n", "enum": [ "none", "new", "moderate", "strict" ], "type": "string" }, "message": { "description": "The error message to raise if the schema validation fails\nfor a document.\n", "type": "string" }, "rule": { "description": "A [JSON Schema](https://json-schema.org/specification-links#draft-4)\nobject (draft-4, without remote schemas).\n\nSee [Document Schema Validation](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/schema-validation/)\nfor details.\n", "type": "object" }, "type": { "const": "json", "description": "The schema validation type. Only JSON Schema is supported.\n", "type": "string" } }, "required": [ "rule", "level", "message", "type" ], "type": "object" }, "shardKeys": { "description": "Contains the names of document attributes that are used to\ndetermine the target shard for documents. _(cluster only)_\n", "items": { "type": "string" }, "type": "array" }, "shardingStrategy": { "description": "The sharding strategy selected for the collection. _(cluster only)_\n", "enum": [ "community-compat", "enterprise-compat", "enterprise-smart-edge-compat", "hash", "enterprise-hash-smart-edge", "enterprise-hex-smart-vertex" ], "type": "string" }, "smartGraphAttribute": { "description": "The attribute that is used for sharding: nodes with the same value of\nthis attribute are placed in the same shard. All nodes are required to\nhave this attribute set and it has to be a string. Edges derive the\nattribute from their connected nodes. _(cluster only)_\n", "type": "string" }, "smartJoinAttribute": { "description": "Determines an attribute of the collection that must contain the shard key value\nof the referred-to SmartJoin collection. _(cluster only)_\n", "type": "string" }, "status": { "description": "The status of the collection (deprecated).\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "statusString": { "description": "The status of the collection as a descriptive string (deprecated).\n", "enum": [ "loaded", "deleted" ], "example": "loaded", "type": "string" }, "syncByRevision": { "description": "Whether the newer revision-based replication protocol is\nenabled for this collection. This is an internal property.\n", "type": "boolean" }, "type": { "description": "The type of the collection:\n - `0`: \"unknown\"\n - `2`: regular document collection\n - `3`: edge collection\n", "type": "integer" }, "waitForSync": { "description": "If `true`, creating, changing, or removing\ndocuments waits until the data has been synchronized to disk.\n", "type": "boolean" }, "writeConcern": { "description": "Determines how many copies of each shard are required to be\nin-sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\n\nIf `distributeShardsLike` is set when the collection is created,\nthe initial `writeConcern` defaults to that of the indicated\nprototype collection. Afterwards, `writeConcern` is independent\nfrom the prototype collection and can differ from it.\n\nFor SatelliteCollections, the `writeConcern` is automatically controlled to\nequal the number of DB-Servers and has a value of `0`.\nOtherwise, the default value is controlled by the current database's\ndefault `writeConcern`, which uses the `--cluster.write-concern`\nstartup option as default, which defaults to `1`. _(cluster only)_\n", "type": "integer" } }, "required": [ "error", "code", "name", "type", "status", "statusString", "isSystem", "id", "globallyUniqueId", "waitForSync", "keyOptions", "schema", "computedValues", "cacheEnabled", "syncByRevision" ], "type": "object" } } }, "description": "All the collection properties.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `name` attribute is missing or has an invalid value.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A collection called `collection-name` could not be found.\n" } }, "summary": "Get the properties of a collection", "tags": [ "Collections" ] }, "put": { "description": "Changes the properties of a collection. Only the provided attributes are\nupdated. Collection properties **cannot be changed** once a collection is\ncreated except for the listed properties, as well as the collection name via\nthe rename endpoint (but not in clusters).\n", "operationId": "updateCollectionProperties", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n\n\u003e **WARNING:**\nAccessing collections by their numeric ID is deprecated from version 3.4.0 on.\nYou should reference them via their names instead.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cacheEnabled": { "description": "Whether the in-memory hash cache for documents should be enabled for this\ncollection. Can be controlled globally with the `--cache.size`\nstartup option. The cache can speed up repeated reads of the same documents via\ntheir document keys. If the same documents are not fetched often or are\nmodified frequently, then you may disable the cache to avoid the maintenance\ncosts.\n", "type": "boolean" }, "computedValues": { "description": "An optional list of objects, each representing a computed value.\n", "items": { "properties": { "computeOn": { "description": "An array of strings to define on which write operations the value shall be\ncomputed.\n", "example": [ "insert", "update", "replace" ], "items": { "enum": [ "insert", "update", "replace" ], "type": "string" }, "type": "array", "uniqueItems": true }, "expression": { "description": "An AQL `RETURN` operation with an expression that computes the desired value.\nSee [Computed Value Expressions](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/computed-values/#computed-value-expressions) for details.\n", "type": "string" }, "failOnWarning": { "default": false, "description": "Whether to let the write operation fail if the expression produces a warning.\n", "type": "boolean" }, "keepNull": { "default": true, "description": "Whether the target attribute shall be set if the expression evaluates to `null`.\nYou can set the option to `false` to not set (or unset) the target attribute if\nthe expression returns `null`.\n", "type": "boolean" }, "name": { "description": "The name of the target attribute. Can only be a top-level attribute, but you\nmay return a nested object. Cannot be `_key`, `_id`, `_rev`, `_from`, `_to`,\nor a shard key attribute.\n", "type": "string" }, "overwrite": { "description": "Whether the computed value shall take precedence over a user-provided or\nexisting attribute.\n", "type": "boolean" } }, "required": [ "name", "expression", "overwrite" ], "type": "object" }, "type": "array" }, "replicationFactor": { "description": "In a cluster, this attribute determines how many copies\nof each shard are kept on different DB-Servers. The value 1 means that only one\ncopy (no synchronous replication) is kept. A value of k means that k-1 replicas\nare kept. For SatelliteCollections, it needs to be the string `\"satellite\"`,\nwhich matches the replication factor to the number of DB-Servers.\n\nAny two copies reside on different DB-Servers. Replication between them is\nsynchronous, that is, every write operation to the \"leader\" copy will be replicated\nto all \"follower\" replicas, before the write operation is reported successful.\n\nIf a server fails, this is detected automatically and one of the servers holding\ncopies take over, usually without an error being reported.\n\nIf `distributeShardsLike` is set, the `replicationFactor`\nis that of the indicated prototype collection. You can only\nchange the `replicationFactor` of the prototype collection\nto change the `replicationFactor` for this collection (and for\nall other collections that follow this prototype collection).\n", "type": "integer" }, "schema": { "description": "The configuration of the collection-level schema validation for documents.\n", "properties": { "level": { "default": "strict", "description": "The level controls when the validation is triggered:\n- `\"none\"`: The rule is inactive and validation thus turned off.\n- `\"new\"`: Only newly inserted documents are validated.\n- `\"moderate\"`: New and modified documents must pass validation,\n except for modified documents where the OLD value did not pass\n validation already. This level is useful if you have documents\n which do not match your target structure, but you want to stop\n the insertion of more invalid documents and prohibit that valid\n documents are changed to invalid documents.\n- `\"strict\"`: All new and modified document must strictly pass\n validation. No exceptions are made.\n", "enum": [ "none", "new", "moderate", "strict" ], "type": "string" }, "message": { "description": "The error message to raise if the schema validation fails\nfor a document.\n", "type": "string" }, "rule": { "description": "A [JSON Schema](https://json-schema.org/specification-links#draft-4)\nobject (draft-4, without remote schemas).\n\nSee [Document Schema Validation](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/schema-validation/)\nfor details.\n", "type": "object" } }, "required": [ "rule" ], "type": "object" }, "waitForSync": { "description": "If set to `true`, the data is synchronized to disk before returning from a\ndocument create, update, replace or removal operation.\n", "type": "boolean" }, "writeConcern": { "description": "Determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\n\nIf `distributeShardsLike` is set,\nthe initial `writeConcern` defaults to that of the indicated\nprototype collection. Afterwards, `writeConcern` is independent\nfrom the prototype collection and can differ from it.\n\nFor SatelliteCollections, the `writeConcern` is automatically controlled to\nequal the number of DB-Servers and has a value of `0`.\nOtherwise, the default value is controlled by the current database's\ndefault `writeConcern`, which uses the `--cluster.write-concern`\nstartup option as default, which defaults to `1`. _(cluster only)_\n", "type": "integer" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cacheEnabled": { "description": "Whether the in-memory hash cache for documents is enabled for this\ncollection.\n", "type": "boolean" }, "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "computedValues": { "description": "A list of objects, each representing a computed value.\n", "items": { "properties": { "computeOn": { "description": "An array of strings that defines on which write operations the value is\ncomputed.\n", "example": [ "insert", "update", "replace" ], "items": { "enum": [ "insert", "update", "replace" ], "type": "string" }, "type": "array", "uniqueItems": true }, "expression": { "description": "An AQL `RETURN` operation with an expression that computes the desired value.\n", "type": "string" }, "failOnWarning": { "description": "Whether the write operation fails if the expression produces a warning.\n", "type": "boolean" }, "keepNull": { "description": "Whether the target attribute is set if the expression evaluates to `null`.\n", "type": "boolean" }, "name": { "description": "The name of the target attribute.\n", "type": "string" }, "overwrite": { "description": "Whether the computed value takes precedence over a user-provided or\nexisting attribute.\n", "type": "boolean" } }, "required": [ "name", "expression", "overwrite" ], "type": "object" }, "type": "array" }, "distributeShardsLike": { "description": "The name of another collection. This collection uses the `replicationFactor`,\n`numberOfShards` and `shardingStrategy` properties of the other collection and\nthe shards of this collection are distributed in the same way as the shards of\nthe other collection.\n", "type": "string" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isDisjoint": { "description": "Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSmart": { "description": "Whether the collection is used in a SmartGraph or EnterpriseGraph.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "type": "boolean" }, "keyOptions": { "description": "An object which contains key generation options.\n", "properties": { "allowUserKeys": { "description": "If set to `true`, then you are allowed to supply\nown key values in the `_key` attribute of a document. If set to\n`false`, then the key generator is solely responsible for\ngenerating keys and an error is raised if you supply own key values in the\n`_key` attribute of documents.\n\n\u003e **WARNING:**\nYou should not use both user-specified and automatically generated document keys\nin the same collection in cluster deployments for collections with more than a\nsingle shard. Mixing the two can lead to conflicts because Coordinators that\nauto-generate keys in this case are not aware of all keys which are already used.\n", "type": "boolean" }, "increment": { "description": "The increment value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "lastValue": { "description": "The offset value of the `autoincrement` or `padded` key generator.\nThis is an internal property for restoring dumps properly.\n", "type": "integer" }, "offset": { "description": "The initial offset value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "type": { "description": "Specifies the type of the key generator.\n", "enum": [ "traditional", "autoincrement", "uuid", "padded" ], "type": "string" } }, "required": [ "type", "allowUserKeys" ], "type": "object" }, "name": { "description": "The name of this collection.\n", "type": "string" }, "numberOfShards": { "description": "The number of shards of the collection. _(cluster only)_\n", "type": "integer" }, "replicationFactor": { "description": "Contains how many copies of each shard are kept on different DB-Servers.\nIt is an integer number in the range of 1-10 or the string `\"satellite\"`\nfor SatelliteCollections. _(cluster only)_\n\nIf `distributeShardsLike` is set, the actual replication factor\nis that of the indicated prototype collection. Query the\nprototype collection to get the current `replicationFactor`\nfor this collection. The reported `replicationFactor` of\nthis collection is the value as of the time at which the\ncollection was created, but it may have been changed\nfor the prototype collection in the meantime.\n", "type": "integer" }, "schema": { "description": "The configuration of the collection-level schema validation for documents.\n", "properties": { "level": { "default": "strict", "description": "The level controls when the validation is triggered:\n- `\"none\"`: The rule is inactive and validation thus turned off.\n- `\"new\"`: Only newly inserted documents are validated.\n- `\"moderate\"`: New and modified documents must pass validation,\n except for modified documents where the OLD value did not pass\n validation already. This level is useful if you have documents\n which do not match your target structure, but you want to stop\n the insertion of more invalid documents and prohibit that valid\n documents are changed to invalid documents.\n- `\"strict\"`: All new and modified document must strictly pass\n validation. No exceptions are made.\n", "enum": [ "none", "new", "moderate", "strict" ], "type": "string" }, "message": { "description": "The error message to raise if the schema validation fails\nfor a document.\n", "type": "string" }, "rule": { "description": "A [JSON Schema](https://json-schema.org/specification-links#draft-4)\nobject (draft-4, without remote schemas).\n\nSee [Document Schema Validation](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/schema-validation/)\nfor details.\n", "type": "object" }, "type": { "const": "json", "description": "The schema validation type. Only JSON Schema is supported.\n", "type": "string" } }, "required": [ "rule", "level", "message", "type" ], "type": "object" }, "shardKeys": { "description": "Contains the names of document attributes that are used to\ndetermine the target shard for documents. _(cluster only)_\n", "items": { "type": "string" }, "type": "array" }, "shardingStrategy": { "description": "The sharding strategy selected for the collection. _(cluster only)_\n", "enum": [ "community-compat", "enterprise-compat", "enterprise-smart-edge-compat", "hash", "enterprise-hash-smart-edge", "enterprise-hex-smart-vertex" ], "type": "string" }, "smartGraphAttribute": { "description": "The attribute that is used for sharding: nodes with the same value of\nthis attribute are placed in the same shard. All nodes are required to\nhave this attribute set and it has to be a string. Edges derive the\nattribute from their connected nodes. _(cluster only)_\n", "type": "string" }, "smartJoinAttribute": { "description": "Determines an attribute of the collection that must contain the shard key value\nof the referred-to SmartJoin collection. _(cluster only)_\n", "type": "string" }, "status": { "description": "The status of the collection (deprecated).\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "statusString": { "description": "The status of the collection as a descriptive string (deprecated).\n", "enum": [ "loaded", "deleted" ], "example": "loaded", "type": "string" }, "syncByRevision": { "description": "Whether the newer revision-based replication protocol is\nenabled for this collection. This is an internal property.\n", "type": "boolean" }, "type": { "description": "The type of the collection:\n - `0`: \"unknown\"\n - `2`: regular document collection\n - `3`: edge collection\n", "type": "integer" }, "waitForSync": { "description": "If `true`, creating, changing, or removing\ndocuments waits until the data has been synchronized to disk.\n", "type": "boolean" }, "writeConcern": { "description": "Determines how many copies of each shard are required to be\nin-sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\n\nIf `distributeShardsLike` is set when the collection is created,\nthe initial `writeConcern` defaults to that of the indicated\nprototype collection. Afterwards, `writeConcern` is independent\nfrom the prototype collection and can differ from it.\n\nFor SatelliteCollections, the `writeConcern` is automatically controlled to\nequal the number of DB-Servers and has a value of `0`.\nOtherwise, the default value is controlled by the current database's\ndefault `writeConcern`, which uses the `--cluster.write-concern`\nstartup option as default, which defaults to `1`. _(cluster only)_\n", "type": "integer" } }, "required": [ "error", "code", "name", "type", "status", "statusString", "isSystem", "id", "globallyUniqueId", "waitForSync", "keyOptions", "schema", "computedValues", "cacheEnabled", "syncByRevision" ], "type": "object" } } }, "description": "The collection has been updated successfully.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `collection-name` parameter is missing.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A collection called `collection-name` could not be found.\n" } }, "summary": "Change the properties of a collection", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/recalculateCount": { "put": { "description": "Recalculates the document count of a collection, if it ever becomes inconsistent.\n", "operationId": "recalculateCollectionCount", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "count": { "description": "The recalculated document count.\nThis attribute is not present when using a cluster.\n", "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "example": true, "type": "boolean" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "The document count has been recalculated successfully.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `collection-name` parameter is missing.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A collection called `collection-name` could not be found.\n" } }, "summary": "Recalculate the document count of a collection", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/rename": { "put": { "description": "Renames a collection.\n\n\u003e **INFO:**\nRenaming collections is not supported in cluster deployments.\n\n\nIf renaming the collection succeeds, then the collection is also renamed in\nall graph definitions inside the `_graphs` collection in the current database.\n", "operationId": "renameCollection", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection to rename.\n\n\u003e **WARNING:**\nAccessing collections by their numeric ID is deprecated from version 3.4.0 on.\nYou should reference them via their names instead.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "The new collection name.\n", "type": "string" } }, "required": [ "name" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cacheEnabled": { "description": "Whether the in-memory hash cache for documents is enabled for this\ncollection.\n", "type": "boolean" }, "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "computedValues": { "description": "A list of objects, each representing a computed value.\n", "items": { "properties": { "computeOn": { "description": "An array of strings that defines on which write operations the value is\ncomputed.\n", "example": [ "insert", "update", "replace" ], "items": { "enum": [ "insert", "update", "replace" ], "type": "string" }, "type": "array", "uniqueItems": true }, "expression": { "description": "An AQL `RETURN` operation with an expression that computes the desired value.\n", "type": "string" }, "failOnWarning": { "description": "Whether the write operation fails if the expression produces a warning.\n", "type": "boolean" }, "keepNull": { "description": "Whether the target attribute is set if the expression evaluates to `null`.\n", "type": "boolean" }, "name": { "description": "The name of the target attribute.\n", "type": "string" }, "overwrite": { "description": "Whether the computed value takes precedence over a user-provided or\nexisting attribute.\n", "type": "boolean" } }, "required": [ "name", "expression", "overwrite" ], "type": "object" }, "type": "array" }, "distributeShardsLike": { "description": "The name of another collection. This collection uses the `replicationFactor`,\n`numberOfShards` and `shardingStrategy` properties of the other collection and\nthe shards of this collection are distributed in the same way as the shards of\nthe other collection.\n", "type": "string" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isDisjoint": { "description": "Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSmart": { "description": "Whether the collection is used in a SmartGraph or EnterpriseGraph.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "example": false, "type": "boolean" }, "keyOptions": { "description": "An object which contains key generation options.\n", "properties": { "allowUserKeys": { "description": "If set to `true`, then you are allowed to supply\nown key values in the `_key` attribute of a document. If set to\n`false`, then the key generator is solely responsible for\ngenerating keys and an error is raised if you supply own key values in the\n`_key` attribute of documents.\n\n\u003e **WARNING:**\nYou should not use both user-specified and automatically generated document keys\nin the same collection in cluster deployments for collections with more than a\nsingle shard. Mixing the two can lead to conflicts because Coordinators that\nauto-generate keys in this case are not aware of all keys which are already used.\n", "type": "boolean" }, "increment": { "description": "The increment value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "lastValue": { "description": "The offset value of the `autoincrement` or `padded` key generator.\nThis is an internal property for restoring dumps properly.\n", "type": "integer" }, "offset": { "description": "The initial offset value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "type": { "description": "Specifies the type of the key generator.\n", "enum": [ "traditional", "autoincrement", "uuid", "padded" ], "type": "string" } }, "required": [ "type", "allowUserKeys" ], "type": "object" }, "name": { "description": "The name of this collection.\n", "example": "coll", "type": "string" }, "numberOfShards": { "description": "The number of shards of the collection. _(cluster only)_\n", "type": "integer" }, "replicationFactor": { "description": "Contains how many copies of each shard are kept on different DB-Servers.\nIt is an integer number in the range of 1-10 or the string `\"satellite\"`\nfor SatelliteCollections. _(cluster only)_\n\nIf `distributeShardsLike` is set, the actual replication factor\nis that of the indicated prototype collection. Query the\nprototype collection to get the current `replicationFactor`\nfor this collection. The reported `replicationFactor` of\nthis collection is the value as of the time at which the\ncollection was created, but it may have been changed\nfor the prototype collection in the meantime.\n", "type": "integer" }, "schema": { "description": "The configuration of the collection-level schema validation for documents.\n", "properties": { "level": { "default": "strict", "description": "The level controls when the validation is triggered:\n- `\"none\"`: The rule is inactive and validation thus turned off.\n- `\"new\"`: Only newly inserted documents are validated.\n- `\"moderate\"`: New and modified documents must pass validation,\n except for modified documents where the OLD value did not pass\n validation already. This level is useful if you have documents\n which do not match your target structure, but you want to stop\n the insertion of more invalid documents and prohibit that valid\n documents are changed to invalid documents.\n- `\"strict\"`: All new and modified document must strictly pass\n validation. No exceptions are made.\n", "enum": [ "none", "new", "moderate", "strict" ], "type": "string" }, "message": { "description": "The error message to raise if the schema validation fails\nfor a document.\n", "type": "string" }, "rule": { "description": "A [JSON Schema](https://json-schema.org/specification-links#draft-4)\nobject (draft-4, without remote schemas).\n\nSee [Document Schema Validation](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/schema-validation/)\nfor details.\n", "type": "object" }, "type": { "const": "json", "description": "The schema validation type. Only JSON Schema is supported.\n", "type": "string" } }, "required": [ "rule", "level", "message", "type" ], "type": "object" }, "shardKeys": { "description": "Contains the names of document attributes that are used to\ndetermine the target shard for documents. _(cluster only)_\n", "items": { "type": "string" }, "type": "array" }, "shardingStrategy": { "description": "The sharding strategy selected for the collection. _(cluster only)_\n", "enum": [ "community-compat", "enterprise-compat", "enterprise-smart-edge-compat", "hash", "enterprise-hash-smart-edge", "enterprise-hex-smart-vertex" ], "type": "string" }, "smartGraphAttribute": { "description": "The attribute that is used for sharding: nodes with the same value of\nthis attribute are placed in the same shard. All nodes are required to\nhave this attribute set and it has to be a string. Edges derive the\nattribute from their connected nodes. _(cluster only)_\n", "type": "string" }, "smartJoinAttribute": { "description": "Determines an attribute of the collection that must contain the shard key value\nof the referred-to SmartJoin collection. _(cluster only)_\n", "type": "string" }, "status": { "description": "The status of the collection (deprecated).\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "statusString": { "description": "The status of the collection as a descriptive string (deprecated).\n", "enum": [ "loaded", "deleted" ], "example": "loaded", "type": "string" }, "syncByRevision": { "description": "Whether the newer revision-based replication protocol is\nenabled for this collection. This is an internal property.\n", "type": "boolean" }, "type": { "description": "The type of the collection:\n- `0`: \"unknown\"\n- `2`: regular document collection\n- `3`: edge collection\n", "example": 2, "type": "integer" }, "waitForSync": { "description": "If `true`, creating, changing, or removing\ndocuments waits until the data has been synchronized to disk.\n", "type": "boolean" }, "writeConcern": { "description": "Determines how many copies of each shard are required to be\nin-sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\n\nIf `distributeShardsLike` is set when the collection is created,\nthe initial `writeConcern` defaults to that of the indicated\nprototype collection. Afterwards, `writeConcern` is independent\nfrom the prototype collection and can differ from it.\n\nFor SatelliteCollections, the `writeConcern` is automatically controlled to\nequal the number of DB-Servers and has a value of `0`.\nOtherwise, the default value is controlled by the current database's\ndefault `writeConcern`, which uses the `--cluster.write-concern`\nstartup option as default, which defaults to `1`. _(cluster only)_\n", "type": "integer" } }, "required": [ "error", "code", "name", "type", "status", "statusString", "isSystem", "id", "globallyUniqueId", "waitForSync", "keyOptions", "schema", "computedValues", "cacheEnabled", "syncByRevision" ], "type": "object" } } }, "description": "The collection has been renamed successfully.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `collection-name` parameter or the `name` attribute is missing.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A collection called `collection-name` could not be found.\n" } }, "summary": "Rename a collection", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/responsibleShard": { "put": { "description": "Returns the ID of the shard that is responsible for the given document\n(if the document exists) or that would be responsible if such document\nexisted.\n\nThe request must body must contain a JSON document with at least the\ncollection's shard key attributes set to some values.\n\nThe response is a JSON object with a `shardId` attribute, which will\ncontain the ID of the responsible shard.\n\n\u003e **INFO:**\nThis method is only available in cluster deployments on Coordinators.\n", "operationId": "getResponsibleShard", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The request body must be a JSON object with at least the shard key\nattributes set to some values, but it may also be a full document.\n", "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "shardId": { "description": "The ID of the responsible shard\n", "type": "string" } }, "required": [ "error", "code", "shardId" ], "type": "object" } } }, "description": "Returns the ID of the responsible shard.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `collection-name` parameter is missing or not all of the\ncollection's shard key attributes are present in the input document.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A collection called `collection-name` could not be found.\n" }, "501": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 501, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The method has been called on a single server.\n" } }, "summary": "Get the responsible shard for a document", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/revision": { "get": { "description": "The response contains the collection's latest used revision ID.\nThe revision ID is a server-generated string that clients can use to\ncheck whether data in a collection has changed since the last revision check.\n", "operationId": "getCollectionRevision", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n\n\u003e **WARNING:**\nAccessing collections by their numeric ID is deprecated from version 3.4.0 on.\nYou should reference them via their names instead.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cacheEnabled": { "description": "Whether the in-memory hash cache for documents is enabled for this\ncollection.\n", "type": "boolean" }, "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "computedValues": { "description": "A list of objects, each representing a computed value.\n", "items": { "properties": { "computeOn": { "description": "An array of strings that defines on which write operations the value is\ncomputed.\n", "example": [ "insert", "update", "replace" ], "items": { "enum": [ "insert", "update", "replace" ], "type": "string" }, "type": "array", "uniqueItems": true }, "expression": { "description": "An AQL `RETURN` operation with an expression that computes the desired value.\n", "type": "string" }, "failOnWarning": { "description": "Whether the write operation fails if the expression produces a warning.\n", "type": "boolean" }, "keepNull": { "description": "Whether the target attribute is set if the expression evaluates to `null`.\n", "type": "boolean" }, "name": { "description": "The name of the target attribute.\n", "type": "string" }, "overwrite": { "description": "Whether the computed value takes precedence over a user-provided or\nexisting attribute.\n", "type": "boolean" } }, "required": [ "name", "expression", "overwrite" ], "type": "object" }, "type": "array" }, "distributeShardsLike": { "description": "The name of another collection. This collection uses the `replicationFactor`,\n`numberOfShards` and `shardingStrategy` properties of the other collection and\nthe shards of this collection are distributed in the same way as the shards of\nthe other collection.\n", "type": "string" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isDisjoint": { "description": "Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSmart": { "description": "Whether the collection is used in a SmartGraph or EnterpriseGraph.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "type": "boolean" }, "keyOptions": { "description": "An object which contains key generation options.\n", "properties": { "allowUserKeys": { "description": "If set to `true`, then you are allowed to supply\nown key values in the `_key` attribute of a document. If set to\n`false`, then the key generator is solely responsible for\ngenerating keys and an error is raised if you supply own key values in the\n`_key` attribute of documents.\n\n\u003e **WARNING:**\nYou should not use both user-specified and automatically generated document keys\nin the same collection in cluster deployments for collections with more than a\nsingle shard. Mixing the two can lead to conflicts because Coordinators that\nauto-generate keys in this case are not aware of all keys which are already used.\n", "type": "boolean" }, "increment": { "description": "The increment value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "lastValue": { "description": "The offset value of the `autoincrement` or `padded` key generator.\nThis is an internal property for restoring dumps properly.\n", "type": "integer" }, "offset": { "description": "The initial offset value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "type": { "description": "Specifies the type of the key generator.\n", "enum": [ "traditional", "autoincrement", "uuid", "padded" ], "type": "string" } }, "required": [ "type", "allowUserKeys" ], "type": "object" }, "name": { "description": "The name of this collection.\n", "type": "string" }, "numberOfShards": { "description": "The number of shards of the collection. _(cluster only)_\n", "type": "integer" }, "replicationFactor": { "description": "Contains how many copies of each shard are kept on different DB-Servers.\nIt is an integer number in the range of 1-10 or the string `\"satellite\"`\nfor SatelliteCollections. _(cluster only)_\n\nIf `distributeShardsLike` is set, the actual replication factor\nis that of the indicated prototype collection. Query the\nprototype collection to get the current `replicationFactor`\nfor this collection. The reported `replicationFactor` of\nthis collection is the value as of the time at which the\ncollection was created, but it may have been changed\nfor the prototype collection in the meantime.\n", "type": "integer" }, "revision": { "description": "The collection revision ID as a string.\n", "type": "string" }, "schema": { "description": "The configuration of the collection-level schema validation for documents.\n", "properties": { "level": { "default": "strict", "description": "The level controls when the validation is triggered:\n- `\"none\"`: The rule is inactive and validation thus turned off.\n- `\"new\"`: Only newly inserted documents are validated.\n- `\"moderate\"`: New and modified documents must pass validation,\n except for modified documents where the OLD value did not pass\n validation already. This level is useful if you have documents\n which do not match your target structure, but you want to stop\n the insertion of more invalid documents and prohibit that valid\n documents are changed to invalid documents.\n- `\"strict\"`: All new and modified document must strictly pass\n validation. No exceptions are made.\n", "enum": [ "none", "new", "moderate", "strict" ], "type": "string" }, "message": { "description": "The error message to raise if the schema validation fails\nfor a document.\n", "type": "string" }, "rule": { "description": "A [JSON Schema](https://json-schema.org/specification-links#draft-4)\nobject (draft-4, without remote schemas).\n\nSee [Document Schema Validation](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/schema-validation/)\nfor details.\n", "type": "object" }, "type": { "const": "json", "description": "The schema validation type. Only JSON Schema is supported.\n", "type": "string" } }, "required": [ "rule", "level", "message", "type" ], "type": "object" }, "shardKeys": { "description": "Contains the names of document attributes that are used to\ndetermine the target shard for documents. _(cluster only)_\n", "items": { "type": "string" }, "type": "array" }, "shardingStrategy": { "description": "The sharding strategy selected for the collection. _(cluster only)_\n", "enum": [ "community-compat", "enterprise-compat", "enterprise-smart-edge-compat", "hash", "enterprise-hash-smart-edge", "enterprise-hex-smart-vertex" ], "type": "string" }, "smartGraphAttribute": { "description": "The attribute that is used for sharding: nodes with the same value of\nthis attribute are placed in the same shard. All nodes are required to\nhave this attribute set and it has to be a string. Edges derive the\nattribute from their connected nodes. _(cluster only)_\n", "type": "string" }, "smartJoinAttribute": { "description": "Determines an attribute of the collection that must contain the shard key value\nof the referred-to SmartJoin collection. _(cluster only)_\n", "type": "string" }, "status": { "description": "The status of the collection (deprecated).\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "statusString": { "description": "The status of the collection as a descriptive string (deprecated).\n", "enum": [ "loaded", "deleted" ], "example": "loaded", "type": "string" }, "syncByRevision": { "description": "Whether the newer revision-based replication protocol is\nenabled for this collection. This is an internal property.\n", "type": "boolean" }, "type": { "description": "The type of the collection:\n - `0`: \"unknown\"\n - `2`: regular document collection\n - `3`: edge collection\n", "type": "integer" }, "waitForSync": { "description": "If `true`, creating, changing, or removing\ndocuments waits until the data has been synchronized to disk.\n", "type": "boolean" }, "writeConcern": { "description": "Determines how many copies of each shard are required to be\nin-sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\n\nIf `distributeShardsLike` is set when the collection is created,\nthe initial `writeConcern` defaults to that of the indicated\nprototype collection. Afterwards, `writeConcern` is independent\nfrom the prototype collection and can differ from it.\n\nFor SatelliteCollections, the `writeConcern` is automatically controlled to\nequal the number of DB-Servers and has a value of `0`.\nOtherwise, the default value is controlled by the current database's\ndefault `writeConcern`, which uses the `--cluster.write-concern`\nstartup option as default, which defaults to `1`. _(cluster only)_\n", "type": "integer" } }, "required": [ "revision", "error", "code", "name", "type", "status", "statusString", "isSystem", "id", "globallyUniqueId", "waitForSync", "keyOptions", "schema", "computedValues", "cacheEnabled", "syncByRevision" ], "type": "object" } } }, "description": "All collection properties but additionally the `revision` of the collection.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `collection-name` parameter is missing.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A collection called `collection-name` could not be found.\n" } }, "summary": "Get the collection revision ID", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/shards": { "get": { "description": "The response contains a list of the collection's shard IDs.\n\nIf the `details` parameter is set to `true`, it returns an object instead\nof a list, with the shard IDs as object attribute keys, and an array with\nthe responsible servers for each shard mapped to them as attribute values.\nThe first element of each array is the leader shard.\n\n\u003e **INFO:**\nThis method is only available in cluster deployments on Coordinators.\n", "operationId": "getCollectionShards", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } }, { "description": "If set to true, the return value also contains the responsible servers for the collections' shards.\n", "in": "query", "name": "details", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cacheEnabled": { "description": "Whether the in-memory hash cache for documents is enabled for this\ncollection.\n", "type": "boolean" }, "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "computedValues": { "description": "A list of objects, each representing a computed value.\n", "items": { "properties": { "computeOn": { "description": "An array of strings that defines on which write operations the value is\ncomputed.\n", "example": [ "insert", "update", "replace" ], "items": { "enum": [ "insert", "update", "replace" ], "type": "string" }, "type": "array", "uniqueItems": true }, "expression": { "description": "An AQL `RETURN` operation with an expression that computes the desired value.\n", "type": "string" }, "failOnWarning": { "description": "Whether the write operation fails if the expression produces a warning.\n", "type": "boolean" }, "keepNull": { "description": "Whether the target attribute is set if the expression evaluates to `null`.\n", "type": "boolean" }, "name": { "description": "The name of the target attribute.\n", "type": "string" }, "overwrite": { "description": "Whether the computed value takes precedence over a user-provided or\nexisting attribute.\n", "type": "boolean" } }, "required": [ "name", "expression", "overwrite" ], "type": "object" }, "type": "array" }, "distributeShardsLike": { "description": "The name of another collection. This collection uses the `replicationFactor`,\n`numberOfShards` and `shardingStrategy` properties of the other collection and\nthe shards of this collection are distributed in the same way as the shards of\nthe other collection.\n", "type": "string" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isDisjoint": { "description": "Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSmart": { "description": "Whether the collection is used in a SmartGraph or EnterpriseGraph.\nThis is an internal property. _(cluster only)_\n", "type": "boolean" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "type": "boolean" }, "keyOptions": { "description": "An object which contains key generation options.\n", "properties": { "allowUserKeys": { "description": "If set to `true`, then you are allowed to supply\nown key values in the `_key` attribute of a document. If set to\n`false`, then the key generator is solely responsible for\ngenerating keys and an error is raised if you supply own key values in the\n`_key` attribute of documents.\n\n\u003e **WARNING:**\nYou should not use both user-specified and automatically generated document keys\nin the same collection in cluster deployments for collections with more than a\nsingle shard. Mixing the two can lead to conflicts because Coordinators that\nauto-generate keys in this case are not aware of all keys which are already used.\n", "type": "boolean" }, "increment": { "description": "The increment value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "lastValue": { "description": "The offset value of the `autoincrement` or `padded` key generator.\nThis is an internal property for restoring dumps properly.\n", "type": "integer" }, "offset": { "description": "The initial offset value for the `autoincrement` key generator.\nNot used by other key generator types.\n", "type": "integer" }, "type": { "description": "Specifies the type of the key generator.\n", "enum": [ "traditional", "autoincrement", "uuid", "padded" ], "type": "string" } }, "required": [ "type", "allowUserKeys" ], "type": "object" }, "name": { "description": "The name of this collection.\n", "type": "string" }, "numberOfShards": { "description": "The number of shards of the collection. _(cluster only)_\n", "type": "integer" }, "replicationFactor": { "description": "Contains how many copies of each shard are kept on different DB-Servers.\nIt is an integer number in the range of 1-10 or the string `\"satellite\"`\nfor SatelliteCollections. _(cluster only)_\n\nIf `distributeShardsLike` is set, the actual replication factor\nis that of the indicated prototype collection. Query the\nprototype collection to get the current `replicationFactor`\nfor this collection. The reported `replicationFactor` of\nthis collection is the value as of the time at which the\ncollection was created, but it may have been changed\nfor the prototype collection in the meantime.\n", "type": "integer" }, "schema": { "description": "The configuration of the collection-level schema validation for documents.\n", "properties": { "level": { "default": "strict", "description": "The level controls when the validation is triggered:\n- `\"none\"`: The rule is inactive and validation thus turned off.\n- `\"new\"`: Only newly inserted documents are validated.\n- `\"moderate\"`: New and modified documents must pass validation,\n except for modified documents where the OLD value did not pass\n validation already. This level is useful if you have documents\n which do not match your target structure, but you want to stop\n the insertion of more invalid documents and prohibit that valid\n documents are changed to invalid documents.\n- `\"strict\"`: All new and modified document must strictly pass\n validation. No exceptions are made.\n", "enum": [ "none", "new", "moderate", "strict" ], "type": "string" }, "message": { "description": "The error message to raise if the schema validation fails\nfor a document.\n", "type": "string" }, "rule": { "description": "A [JSON Schema](https://json-schema.org/specification-links#draft-4)\nobject (draft-4, without remote schemas).\n\nSee [Document Schema Validation](https://docs.arango.ai/arangodb/3.12/concepts/data-structure/documents/schema-validation/)\nfor details.\n", "type": "object" }, "type": { "const": "json", "description": "The schema validation type. Only JSON Schema is supported.\n", "type": "string" } }, "required": [ "rule", "level", "message", "type" ], "type": "object" }, "shardKeys": { "description": "Contains the names of document attributes that are used to\ndetermine the target shard for documents. _(cluster only)_\n", "items": { "type": "string" }, "type": "array" }, "shardingStrategy": { "description": "The sharding strategy selected for the collection. _(cluster only)_\n", "enum": [ "community-compat", "enterprise-compat", "enterprise-smart-edge-compat", "hash", "enterprise-hash-smart-edge", "enterprise-hex-smart-vertex" ], "type": "string" }, "shards": { "description": "The type and value depend on the setting of the `details` parameter:\n- `false`: An array of the collection shard IDs.\n- `true`: An object where the keys are shard IDs and the\n values are arrays with the responsible DB-Server names\n (shard leader first).\n" }, "smartGraphAttribute": { "description": "The attribute that is used for sharding: vertices with the same value of\nthis attribute are placed in the same shard. All vertices are required to\nhave this attribute set and it has to be a string. Edges derive the\nattribute from their connected vertices. _(cluster only)_\n", "type": "string" }, "smartJoinAttribute": { "description": "Determines an attribute of the collection that must contain the shard key value\nof the referred-to SmartJoin collection. _(cluster only)_\n", "type": "string" }, "status": { "description": "The status of the collection (deprecated).\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "statusString": { "description": "The status of the collection as a descriptive string (deprecated).\n", "enum": [ "loaded", "deleted" ], "example": "loaded", "type": "string" }, "syncByRevision": { "description": "Whether the newer revision-based replication protocol is\nenabled for this collection. This is an internal property.\n", "type": "boolean" }, "type": { "description": "The type of the collection:\n - `0`: \"unknown\"\n - `2`: regular document collection\n - `3`: edge collection\n", "type": "integer" }, "waitForSync": { "description": "If `true`, creating, changing, or removing\ndocuments waits until the data has been synchronized to disk.\n", "type": "boolean" }, "writeConcern": { "description": "Determines how many copies of each shard are required to be\nin-sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\n\nIf `distributeShardsLike` is set when the collection is created,\nthe initial `writeConcern` defaults to that of the indicated\nprototype collection. Afterwards, `writeConcern` is independent\nfrom the prototype collection and can differ from it.\n\nFor SatelliteCollections, the `writeConcern` is automatically controlled to\nequal the number of DB-Servers and has a value of `0`.\nOtherwise, the default value is controlled by the current database's\ndefault `writeConcern`, which uses the `--cluster.write-concern`\nstartup option as default, which defaults to `1`. _(cluster only)_\n", "type": "integer" } }, "required": [ "shards", "error", "code", "name", "type", "status", "statusString", "isSystem", "id", "globallyUniqueId", "waitForSync", "keyOptions", "schema", "computedValues", "cacheEnabled", "syncByRevision" ], "type": "object" } } }, "description": "All collection properties but additionally the `shards` of the collection.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `collection-name` parameter is missing.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A collection called `collection-name` could not be found.\n" }, "501": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 501, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The method has been called on a single server.\n" } }, "summary": "Get the shard IDs of a collection", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/truncate": { "put": { "description": "Removes all documents from the collection, but leaves the indexes intact.\n", "operationId": "truncateCollection", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n\n\u003e **WARNING:**\nAccessing collections by their numeric ID is deprecated from version 3.4.0 on.\nYou should reference them via their names instead.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } }, { "description": "If set to `true`, the data is synchronized to disk before returning from the\ntruncate operation.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If set to `true`, the storage engine is told to start a compaction\nin order to free up disk space. This can be resource intensive. If the only\nintention is to start over with an empty collection, specify `false`.\n", "in": "query", "name": "compact", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" } }, "required": [ "error", "code", "id" ], "type": "object" } } }, "description": "Truncating the collection was successful.\nReturns the basic information about the collection.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `collection-name` parameter is missing.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The collection cannot be found.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 410, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" } }, "summary": "Truncate a collection", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/collection/{collection-name}/unload": { "put": { "deprecated": true, "description": "\u003e **WARNING:**\nThe unload function is deprecated from version 3.8.0 onwards and is a no-op\nfrom version 3.9.0 onwards. It should no longer be used and is removed\nin ArangoDB v4.0.\n\n\nSince ArangoDB version 3.9.0 this API does nothing. Previously it used to\nunload a collection from memory, while preserving all documents.\n", "operationId": "unloadCollection", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection.\n\n\u003e **WARNING:**\nAccessing collections by their numeric ID is deprecated from version 3.4.0 on.\nYou should reference them via their names instead.\n", "in": "path", "name": "collection-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the collection. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the collection (deprecated).\n", "type": "string" }, "isSystem": { "description": "Whether the collection is a system collection. Collection names that starts with\nan underscore are usually system collections.\n", "example": false, "type": "boolean" }, "name": { "description": "The name of the collection.\n", "example": "coll", "type": "string" }, "status": { "description": "The status of the collection.\n- `3`: loaded\n- `5`: deleted\n\nEvery other status indicates a corrupted collection.\n", "example": 3, "type": "integer" }, "type": { "description": "The type of the collection:\n- `0`: \"unknown\"\n- `2`: regular document collection\n- `3`: edge collection\n", "example": 2, "type": "integer" } }, "required": [ "error", "code", "name", "type", "isSystem", "status", "id", "globallyUniqueId" ], "type": "object" } } }, "description": "Returns the basic collection properties for compatibility reasons.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `collection-name` parameter or the `name` attribute is missing.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A collection called `collection-name` could not be found.\n" } }, "summary": "Unload a collection", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/cursor": { "post": { "description": "Submits an AQL query for execution in the current database. The server returns\na result batch and may indicate that further batches need to be fetched using\na cursor identifier.\n\nThe query details include the query string plus optional query options and\nbind parameters. These values need to be passed in a JSON representation in\nthe body of the POST request.\n", "operationId": "createAqlQueryCursor", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Set this header to `true` to allow the Coordinator to ask any shard replica for\nthe data, not only the shard leader. This may result in \"dirty reads\".\n\nThe header is ignored if this operation is part of a Stream Transaction\n(`x-arango-trx-id` header). The header set when creating the transaction decides\nabout dirty reads for the entire transaction, not the individual read operations.\n", "in": "header", "name": "x-arango-allow-dirty-read", "required": false, "schema": { "type": "boolean" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "batchSize": { "default": 1000, "description": "The maximum number of result documents to be transferred from\nthe server to the client in one roundtrip. If this attribute is\nnot set, a server-controlled default value will be used. A `batchSize` value of\n`0` is disallowed.\n", "type": "integer" }, "bindVars": { "description": "An object with key/value pairs representing the bind parameters.\nFor a bind variable `@var` in the query, specify the value using an attribute\nwith the name `var`. For a collection bind variable `@@coll`, use `@coll` as the\nattribute name. For example: `\"bindVars\": { \"var\": 42, \"@coll\": \"products\" }`.\n", "type": "object" }, "count": { "default": false, "description": "Whether the number of documents in the result set should be returned in\nthe `count` attribute of the result.\nCalculating this count might have a performance impact for some queries\nin the future, so this option is turned off by default and `count`\nis only returned when requested.\n", "type": "boolean" }, "memoryLimit": { "description": "The maximum amount of memory (in bytes) that the query is allowed to\nuse. If set, then the query fails with error \"resource limit exceeded\" in\ncase it allocates too much memory. A value of `0` indicates that there is\nno memory limit, but the [`--query.global-memory-limit` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--queryglobal-memory-limit)\nmay still limit it.\n\nDefault: You can configure a default per-query memory limit with the\n[`--query.memory-limit` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querymemory-limit). You can only increase\nthis default memory limit if `--query.memory-limit-override`\nis enabled.\n", "type": "integer" }, "options": { "description": "key/value object with extra options for the query.\n", "properties": { "allowDirtyReads": { "default": false, "description": "If you set this option to `true` and execute the query against a cluster\ndeployment, then the Coordinator is allowed to read from any shard replica and\nnot only from the leader.\n\nYou may observe data inconsistencies (dirty reads) when reading from followers,\nnamely obsolete revisions of documents because changes have not yet been\nreplicated to the follower, as well as changes to documents before they are\nofficially committed on the leader.\n\nThe option is ignored if this operation is part of a Stream Transaction\n(`x-arango-trx-id` header). The `x-arango-allow-dirty-read` header set\nwhen creating the transaction decides about dirty reads for the entire\ntransaction, not the individual read operations.\n", "type": "boolean" }, "allowRetry": { "default": false, "description": "Set this option to `true` to make it possible to retry\nfetching the latest batch from a cursor.\n\nIf retrieving a result batch fails because of a connection issue, you can ask\nfor that batch again using the `POST /_api/cursor/\u003ccursor-id\u003e/\u003cbatch-id\u003e`\nendpoint. The first batch has an ID of `1` and the value is incremented by 1\nwith every batch. Every result response except the last one also includes a\n`nextBatchId` attribute, indicating the ID of the batch after the current.\nYou can remember and use this batch ID should retrieving the next batch fail.\n\nYou can only request the latest batch again (or the next batch).\nEarlier batches are not kept on the server-side.\nRequesting a batch again does not advance the cursor.\n\nYou can also call this endpoint with the next batch identifier, i.e. the value\nreturned in the `nextBatchId` attribute of a previous request. This advances the\ncursor and returns the results of the next batch. This is only supported if there\nare more results in the cursor (i.e. `hasMore` is `true` in the latest batch).\n\nFrom v3.11.1 onward, you may use the `POST /_api/cursor/\u003ccursor-id\u003e/\u003cbatch-id\u003e`\nendpoint even if the `allowRetry` attribute is `false` to fetch the next batch,\nbut you cannot request a batch again unless you set it to `true`.\n\nTo allow refetching of the very last batch of the query, the server cannot\nautomatically delete the cursor. After the first attempt of fetching the last\nbatch, the server would normally delete the cursor to free up resources. As you\nmight need to reattempt the fetch, it needs to keep the final batch when the\n`allowRetry` option is enabled. Once you successfully received the last batch,\nyou should call the `DELETE /_api/cursor/\u003ccursor-id\u003e` endpoint so that the\nserver doesn't unnecessarily keep the batch until the cursor times out\n(`ttl` query option).\n", "type": "boolean" }, "cache": { "description": "Whether the [AQL query results cache](https://docs.arango.ai/arangodb/3.12/aql/execution-and-performance/caching-query-results/)\nshall be used for adding as well as for retrieving results.\n\nIf the query cache mode is set to `demand` and you set the `cache` query option\nto `true` for a query, then its query result is cached if it's eligible for\ncaching. If the query cache mode is set to `on`, query results are automatically\ncached if they are eligible for caching unless you set the `cache` option to `false`.\n\nIf you set the `cache` option to `false`, then any query cache lookup is skipped\nfor the query. If you set it to `true`, the query cache is checked for a cached result\n**if** the query cache mode is either set to `on` or `demand`.\n\nDefault: Controlled by the [`--query.cache-mode` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querycache-mode).\n", "type": "boolean" }, "failOnWarning": { "description": "If set to `true`, the query throws an exception and aborts instead of producing\na warning. You should use this option during development to catch potential issues\nearly. When the attribute is set to `false`, warnings are not propagated to\nexceptions and are returned with the query result.\n\nDefault: Controlled by the [`--query.fail-on-warning` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--queryfail-on-warning),\nso you don't need to set it on a per-query basis.\n", "type": "boolean" }, "fillBlockCache": { "default": true, "description": "If set to `true`, then the query stores the data it\nreads via the RocksDB storage engine in the RocksDB block cache. This is usually\nthe desired behavior. The option can be set to `false` for queries that are\nknown to either read a lot of data which would thrash the block cache, or for queries\nthat read data which are known to be outside of the hot set. By setting the option\nto `false`, data read by the query does not make it into the RocksDB block cache if\nnot already in there, thus leaving more room for the actual hot set.\n", "type": "boolean" }, "fullCount": { "default": false, "description": "If set to `true` and the query contains a `LIMIT` clause, then the\nresult will have an `extra` attribute with the sub-attributes `stats`\nand `fullCount`, `{ ... , \"extra\": { \"stats\": { \"fullCount\": 123 } } }`.\nThe `fullCount` attribute will contain the number of documents in the result before the\nlast top-level LIMIT in the query was applied. It can be used to count the number of\ndocuments that match certain filter criteria, but only return a subset of them, in one go.\nIt is thus similar to MySQL's *SQL_CALC_FOUND_ROWS* hint. Note that setting the option\nwill disable a few LIMIT optimizations and may lead to more documents being processed,\nand thus make queries run longer. Note that the `fullCount` attribute may only\nbe present in the result if the query has a top-level LIMIT clause and the LIMIT\nclause is actually used in the query.\n", "type": "boolean" }, "intermediateCommitCount": { "description": "The maximum number of operations after which an intermediate commit is performed\nautomatically.\n\nDefault: Controlled by the [`--rocksdb.intermediate-commit-count` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--rocksdbintermediate-commit-count).\n", "type": "integer" }, "intermediateCommitSize": { "description": "The maximum total size of operations after which an intermediate commit is performed\nautomatically.\n\nDefault: Controlled by [`--rocksdb.intermediate-commit-size` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--rocksdbintermediate-commit-size).\n", "type": "integer" }, "maxDNFConditionMembers": { "description": "A threshold for the maximum number of `OR` sub-nodes in the internal\nrepresentation of an AQL `FILTER` condition.\n\nYon can use this option to limit the computation time and memory usage when\nconverting complex AQL `FILTER` conditions into the internal DNF\n(disjunctive normal form) format. `FILTER` conditions with a lot of logical\nbranches (`AND`, `OR`, `NOT`) can take a large amount of processing time and\nmemory. This query option limits the computation time and memory usage for\nsuch conditions.\n\nOnce the threshold value is reached during the DNF conversion of a `FILTER`\ncondition, the conversion is aborted, and the query continues with a simplified\ninternal representation of the condition, which **cannot be used for index lookups**.\n\nDefault: Controlled by the [`--query.max-dnf-condition-members` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querymax-dnf-condition-members)\nto set the threshold globally instead of per query.\n", "type": "integer" }, "maxNodesPerCallstack": { "description": "The number of execution nodes in the query plan after that stack splitting is\nperformed to avoid a potential stack overflow.\n\nThis option is only useful for testing and debugging and normally does not need\nany adjustment.\n\nDefault: Controlled by the [`--query.max-nodes-per-callstack` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querymax-nodes-per-callstack).\n", "type": "integer" }, "maxNumberOfPlans": { "description": "Limits the maximum number of plans that are created by the AQL query optimizer.\n\nDefault: Controlled by the [`--query.optimizer-max-plans` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--queryoptimizer-max-plans).\n", "type": "integer" }, "maxRuntime": { "description": "The query has to be executed within the given runtime or it is killed.\nThe value is specified in seconds. A value of `0.0` means no timeout.\n\nDefault: Controlled by the [`--query.max-runtime` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querymax-runtime).\n", "type": "number" }, "maxTransactionSize": { "description": "The transaction size limit in bytes.\n\nDefault: Controlled by the [`--rocksdb.max-transaction-size` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--rocksdbmax-transaction-size).\n", "type": "integer" }, "maxWarningCount": { "default": 10, "description": "Limits the number of warnings a query can return.\nYou can increased or decreased the number with this option.\n", "type": "integer" }, "optimizer": { "description": "Options related to the query optimizer.\n", "properties": { "rules": { "description": "A list of optimizer rules, telling the optimizer to\ninclude or exclude specific rules. See the\n[List of optimizer rules](https://docs.arango.ai/arangodb/3.12/aql/execution-and-performance/query-optimization/#list-of-optimizer-rules).\n\nTo disable a rule, prefix its name with `-`. To enable a rule,\nprefix it with `+`. There is also a pseudo-rule `all` that\nmatches all optimizer rules. `-all` disables all rules.\n", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "profile": { "default": 0, "description": "If set to `true` or `1`, then the additional query profiling information is returned\nin the `profile` sub-attribute of the `extra` return attribute, unless the query result\nis served from the query results cache. If set to `2`, the query includes execution stats\nper query plan node in `stats.nodes` sub-attribute of the `extra` return attribute.\nAdditionally, the query plan is returned in the `extra.plan` sub-attribute.\n", "type": "integer" }, "satelliteSyncWait": { "default": 60, "description": "How long a DB-Server has time (in seconds) to bring the SatelliteCollections\ninvolved in the query into sync. When the maximal time is reached, the query is stopped.\n", "type": "number" }, "skipInaccessibleCollections": { "default": false, "description": "Let AQL queries (especially graph traversals) treat collections to which a user\nhas no access rights for as if these collections are empty. Instead of returning a\nforbidden access error, your queries execute normally. This is intended to help\nwith certain use-cases: A graph contains several collections and different users\nexecute AQL queries on that graph. You can naturally limit the accessible\nresults by changing the access rights of users on collections.\n", "type": "boolean" }, "spillOverThresholdMemoryUsage": { "description": "This option allows queries to store intermediate and final results temporarily\non disk if the amount of memory used (in bytes) exceeds the specified value.\nThis is used for decreasing the memory usage during the query execution.\n\nThis option only has an effect on queries that use the `SORT` operation but\nwithout a `LIMIT`, and if you enable the spillover feature by setting a path\nfor the directory to store the temporary data in with the\n[`--temp.intermediate-results-path` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--tempintermediate-results-path).\n\nDefault: 128 MiB, respectively the value of the\n[`--temp.intermediate-results-spillover-threshold-memory-usage` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--tempintermediate-results-spillover-threshold-memory-usage).\n\n\u003e **INFO:**\nSpilling data from RAM onto disk is an experimental feature and is turned off\nby default. The query results are still built up entirely in RAM on Coordinators\nand single servers for non-streaming queries. To avoid the buildup of\nthe entire query result in RAM, use a streaming query (see the `stream` option).\n", "type": "integer" }, "spillOverThresholdNumRows": { "description": "This option allows queries to store intermediate and final results temporarily\non disk if the number of rows produced by the query exceeds the specified value.\nThis is used for decreasing the memory usage during the query execution. In a\nquery that iterates over a collection that contains documents, each row is a\ndocument, and in a query that iterates over temporary values\n(i.e. `FOR i IN 1..100`), each row is one of such temporary values.\n\nThis option only has an effect on queries that use the `SORT` operation but\nwithout a `LIMIT`, and if you enable the spillover feature by setting a path\nfor the directory to store the temporary data in with the\n[`--temp.intermediate-results-path` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--tempintermediate-results-path).\n\nDefault: 5 million rows, respectively the value of the\n[`--temp.intermediate-results-spillover-threshold-num-rows` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--tempintermediate-results-spillover-threshold-num-rows).\n\n\u003e **INFO:**\nSpilling data from RAM onto disk is an experimental feature and is turned off\nby default. The query results are still built up entirely in RAM on Coordinators\nand single servers for non-streaming queries. To avoid the buildup of\nthe entire query result in RAM, use a streaming query (see the `stream` option).\n", "type": "integer" }, "stream": { "default": false, "description": "Can be enabled to execute the query lazily. If set to `true`, then the query is\nexecuted as long as necessary to produce up to `batchSize` results. These\nresults are returned immediately and the query is suspended until the client\nasks for the next batch (if there are more results). Depending on the query\nthis can mean that the first results will be available much faster and that\nless memory is needed because the server only needs to store a subset of\nresults at a time. Read-only queries can benefit the most, unless `SORT`\nwithout index or `COLLECT` are involved that make it necessary to process all\ndocuments before a partial result can be returned. It is advisable to only use\nthis option for queries without exclusive locks.\n\nRemarks:\n- The query will hold resources until it ends (such as RocksDB snapshots, which\n prevents compaction to some degree). Writes will be in memory until the query\n is committed.\n- If existing documents are modified, then write locks are held on these\n documents and other queries trying to modify the same documents will fail\n because of this conflict.\n- A streaming query may fail late because of a conflict or for other reasons\n after some batches were already returned successfully, possibly rendering the\n results up to that point meaningless.\n- The query options `cache`, `count` and `fullCount` are not supported for\n streaming queries.\n- Query statistics, profiling data and warnings are delivered as part of the\n last batch.\n\nIf the `stream` option is `false`, then the complete result of the\nquery is calculated before any of it is returned to the client. The server\nstores the full result in memory (on the contacted Coordinator if in a cluster).\nAll other resources are freed immediately (locks, RocksDB snapshots). The query\nwill fail before it returns results in case of a conflict.\n", "type": "boolean" }, "usePlanCache": { "default": false, "description": "Set this option to `true` to utilize a cached query plan or add the execution plan\nof this query to the cache if it's not in the cache yet. Otherwise, the plan cache\nis bypassed (introduced in v3.12.4).\n\nQuery plan caching can reduce the total time for processing queries by avoiding\nto parse, plan, and optimize queries over and over again that effectively have\nthe same execution plan with at most some changes to bind parameter values.\n\nAn error is raised if a query doesn't meet the requirements for plan caching.\nSee [Cache eligibility](https://docs.arango.ai/arangodb/3.12/aql/execution-and-performance/caching-query-plans/#cache-eligibility)\nfor details.\n", "type": "boolean" } }, "type": "object" }, "query": { "description": "The AQL query string to execute.\n", "type": "string" }, "ttl": { "description": "The time-to-live for the cursor (in seconds). If the result set is small enough\n(less than or equal to `batchSize`) then results are returned right away.\nOtherwise they are stored in memory and will be accessible via the cursor with\nrespect to the `ttl`. The cursor will be removed on the server automatically\nafter the specified amount of time. This is useful to ensure garbage collection\nof cursors that are not fully fetched by clients.\n\nThe time-to-live is renewed upon every access to the cursor.\n\nDefault: Controlled by the [`--query.registry-ttl` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--queryregistry-ttl).\nIf not set, the defaults are 30 seconds for single servers and 600 seconds for\nCoordinators of a cluster deployment.\n", "type": "number" } }, "required": [ "query" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "cached": { "description": "A boolean flag indicating whether the query result was served\nfrom the query results cache or not. If the query result is served from the query\ncache, the `extra` attribute in the response does not contain the `stats`\nand `profile` sub-attributes.\n", "type": "boolean" }, "code": { "description": "The HTTP response status code.\n", "example": 201, "type": "integer" }, "count": { "description": "The total number of result documents available (only\navailable if the query was executed with the `count` attribute set).\n", "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "extra": { "description": "An optional JSON object with extra information about the query result.\n\nOnly delivered as part of the first batch, or the last batch in case of a cursor\nwith the `stream` option enabled.\n", "properties": { "plan": { "description": "The execution plan.\n", "properties": { "collections": { "description": "A list of the collections involved in the query. The list only includes the\ncollections that can statically be determined at query compile time.\n", "items": { "properties": { "name": { "description": "The collection name.\n", "type": "string" }, "type": { "description": "How the collection is used.\n", "enum": [ "read", "write", "exclusive" ], "type": "string" } }, "required": [ "name", "type" ], "type": "object" }, "type": "array" }, "estimatedCost": { "description": "The estimated cost of the query.\n", "type": "number" }, "estimatedNrItems": { "description": "The estimated number of results.\n", "type": "integer" }, "isModificationQuery": { "description": "Whether the query contains write operations.\n", "type": "boolean" }, "nodes": { "description": "A nested list of the execution plan nodes.\n", "items": { "type": "object" }, "type": "array" }, "rules": { "description": "A list with the names of the applied optimizer rules.\n", "items": { "type": "string" }, "type": "array" }, "variables": { "description": "All of the query variables, including user-created and internal ones.\n", "items": { "type": "object" }, "type": "array" } }, "required": [ "nodes", "rules", "collections", "variables", "estimatedCost", "estimatedNrItems", "isModificationQuery" ], "type": "object" }, "profile": { "description": "The duration of the different query execution phases in seconds.\n", "properties": { "executing": { "description": "", "type": "number" }, "finalizing": { "description": "", "type": "number" }, "initializing": { "description": "", "type": "number" }, "instantiating executors": { "description": "", "type": "number" }, "instantiating plan": { "description": "", "type": "number" }, "loading collections": { "description": "", "type": "number" }, "optimizing ast": { "description": "", "type": "number" }, "optimizing plan": { "description": "", "type": "number" }, "parsing": { "description": "", "type": "number" } }, "required": [ "initializing", "parsing", "optimizing ast", "loading collections", "instantiating plan", "optimizing plan", "instantiating executors", "executing", "finalizing" ], "type": "object" }, "stats": { "description": "An object with query statistics.\n", "properties": { "cacheHits": { "description": "The total number of index entries read from in-memory caches for indexes\nof type edge or persistent. This value is only non-zero when reading from indexes\nthat have an in-memory cache enabled, and when the query allows using the in-memory\ncache (i.e. using equality lookups on all index attributes).\n", "type": "integer" }, "cacheMisses": { "description": "The total number of cache read attempts for index entries that could not\nbe served from in-memory caches for indexes of type edge or persistent. This value\nis only non-zero when reading from indexes that have an in-memory cache enabled, the\nquery allows using the in-memory cache (i.e. using equality lookups on all index attributes)\nand the looked-up values are not present in the cache.\n", "type": "integer" }, "cursorsCreated": { "description": "The total number of cursor objects created during query execution. Cursor\nobjects are created for index lookups.\n", "type": "integer" }, "cursorsRearmed": { "description": "The total number of times an existing cursor object was repurposed.\nRepurposing an existing cursor object is normally more efficient compared to destroying an\nexisting cursor object and creating a new one from scratch.\n", "type": "integer" }, "documentLookups": { "description": "The number of real document lookups caused by late materialization\nas well as `IndexNode`s that had to load document attributes not covered\nby the index. This is how many documents had to be fetched from storage after\nan index scan that initially covered the attribute access for these documents.\n", "type": "integer" }, "executionTime": { "description": "The query execution time (wall-clock time) in seconds.\n", "type": "number" }, "filtered": { "description": "The total number of documents removed after executing a filter condition\nin a `FilterNode` or another node that post-filters data. Note that nodes of the\n`IndexNode` type can also filter documents by selecting only the required index range\nfrom a collection, and the `filtered` value only indicates how much filtering was done by a\npost filter in the `IndexNode` itself or following `FilterNode` nodes.\nNodes of the `EnumerateCollectionNode` and `TraversalNode` types can also apply\nfilter conditions and can report the number of filtered documents.\n", "type": "integer" }, "fullCount": { "description": "The total number of documents that matched the search condition if the query's\nfinal top-level `LIMIT` operation were not present.\nThis attribute may only be returned if the `fullCount` option was set when starting the\nquery and only contains a sensible value if the query contains a `LIMIT` operation on\nthe top level.\n", "type": "integer" }, "httpRequests": { "description": "The total number of cluster-internal HTTP requests performed.\n", "type": "integer" }, "intermediateCommits": { "description": "The number of intermediate commits performed by the query. This is only non-zero\nfor write queries, and only for queries that reached either the `intermediateCommitSize`\nor `intermediateCommitCount` thresholds. Note: in a cluster, intermediate commits can happen\non each participating DB-Server.\n", "type": "integer" }, "nodes": { "description": "When the query is executed with the `profile` option set to at least `2`,\nthen this attribute contains runtime statistics per query execution node.\nFor a human-readable output, you can execute\n`db._profileQuery(\u003cquery\u003e, \u003cbind-vars\u003e)` in arangosh.\n", "items": { "properties": { "calls": { "description": "The number of calls to this node.\n", "type": "integer" }, "id": { "description": "The execution node ID to correlate the statistics with the `plan` returned in\nthe `extra` attribute.\n", "type": "integer" }, "items": { "description": "The number of items returned by this node. Items are the temporary results\nreturned at this stage.\n", "type": "integer" }, "runtime": { "description": "The execution time of this node in seconds.\n", "type": "number" } }, "required": [ "id", "calls", "items", "runtime" ], "type": "object" }, "type": "array" }, "peakMemoryUsage": { "description": "The maximum memory usage of the query while it was running. In a cluster,\nthe memory accounting is done per shard, and the memory usage reported is the peak\nmemory usage value from the individual shards.\nNote that to keep things lightweight, the per-query memory usage is tracked on a relatively\nhigh level, not including any memory allocator overhead nor any memory used for temporary\nresults calculations (e.g. memory allocated/deallocated inside AQL expressions and function\ncalls).\n", "type": "integer" }, "scannedFull": { "description": "The total number of documents iterated over when scanning a collection\nwithout an index. Documents scanned by subqueries are included in the result, but\noperations triggered by built-in or user-defined AQL functions are not.\n", "type": "integer" }, "scannedIndex": { "description": "The total number of documents iterated over when scanning a collection using\nan index. Documents scanned by subqueries are included in the result, but operations\ntriggered by built-in or user-defined AQL functions are not.\n", "type": "integer" }, "searchParallelism": { "description": "The number of threads used by ArangoSearch for this\nquery (introduced in v3.12.9).\n", "type": "integer" }, "seeks": { "description": "The number of seek calls done by RocksDB iterators for merge joins\n(`JoinNode` in the execution plan).\n", "type": "integer" }, "writesExecuted": { "description": "The total number of data-modification operations successfully executed.\n", "type": "integer" }, "writesIgnored": { "description": "The total number of data-modification operations that were unsuccessful,\nbut have been ignored because of the `ignoreErrors` query option.\n", "type": "integer" } }, "required": [ "writesExecuted", "writesIgnored", "documentLookups", "seeks", "scannedFull", "scannedIndex", "searchParallelism", "cursorsCreated", "cursorsRearmed", "cacheHits", "cacheMisses", "filtered", "httpRequests", "executionTime", "peakMemoryUsage", "intermediateCommits" ], "type": "object" }, "warnings": { "description": "A list of query warnings.\n", "items": { "properties": { "code": { "description": "An error code.\n", "type": "integer" }, "message": { "description": "A description of the problem.\n", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "warnings", "stats" ], "type": "object" }, "hasMore": { "description": "A boolean indicator whether there are more results\navailable for the cursor on the server.\n\nNote that even if `hasMore` returns `true`, the next call might still return no\ndocuments. Once `hasMore` is `false`, the cursor is exhausted and the client\ncan stop asking for more results.\n", "type": "boolean" }, "id": { "description": "The ID of the cursor for fetching more result batches.\n", "type": "string" }, "nextBatchId": { "description": "Only set if the `allowRetry` query option is enabled in v3.11.0.\nFrom v3.11.1 onward, this attribute is always set, except in the last batch.\n\nThe ID of the batch after the current one. The first batch has an ID of `1` and\nthe value is incremented by 1 with every batch. You can remember and use this\nbatch ID should retrieving the next batch fail. Use the\n`POST /_api/cursor/\u003ccursor-id\u003e/\u003cbatch-id\u003e` endpoint to ask for the batch again.\nYou can also request the next batch.\n", "type": "string" }, "planCacheKey": { "description": "The key of the plan cache entry. This attribute is only\npresent if a cached query execution plan has been used.\n", "type": "string" }, "result": { "description": "An array of result documents for the current batch\n(might be empty if the query has no results).\n", "type": "array" } }, "required": [ "error", "code", "hasMore", "cached" ], "type": "object" } } }, "description": "is returned if the result set can be created by the server.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n\nIf the query specification is complete, the server will process the query. If an\nerror occurs during query processing, the server will respond with *HTTP 400*.\nAgain, the body of the response will contain details about the error.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The JSON representation is malformed, the query specification is\nmissing from the request, or the query is invalid.\n\nThe body of the response contains a JSON object with additional error\ndetails.\n" }, "404": { "description": "A non-existing collection is accessed in the query.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "405": { "description": "An unsupported HTTP method is used.\n" }, "410": { "description": "A server which processes the query or the leader of a shard which is used\nin the query stops responding, but the connection has not been closed.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "503": { "description": "A server which processes the query or the leader of a shard which is used\nin the query is down, either for going through a restart, a failure, or\nconnectivity issues.\n" } }, "summary": "Create a cursor", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/cursor/{cursor-identifier}": { "delete": { "description": "Deletes the cursor and frees the resources associated with it.\n\nThe cursor will automatically be destroyed on the server when the client has\nretrieved all documents from it. The client can also explicitly destroy the\ncursor at any earlier time using an HTTP DELETE request. The cursor identifier must\nbe included as part of the URL.\n\nNote: the server will also destroy abandoned cursors automatically after a\ncertain server-controlled timeout to avoid resource leakage.\n", "operationId": "deleteAqlQueryCursor", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The identifier of the cursor\n", "in": "path", "name": "cursor-identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "The server is aware of the cursor.\n" }, "404": { "description": "The server is not aware of the cursor. This is also\nreturned if a cursor is used after it has been destroyed.\n" } }, "summary": "Delete a cursor", "tags": [ "Queries" ] }, "post": { "description": "If the cursor is still alive, returns an object with the next query result batch.\n\nIf the cursor is not fully consumed, the time-to-live for the cursor\nis renewed by this API call.\n", "operationId": "getNextAqlQueryCursorBatch", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the cursor\n", "in": "path", "name": "cursor-identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cached": { "description": "A boolean flag indicating whether the query result was served\nfrom the query results cache or not. If the query result is served from the query\ncache, the `extra` attribute in the response does not contain the `stats`\nand `profile` sub-attributes.\n", "type": "boolean" }, "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "count": { "description": "The total number of result documents available (only\navailable if the query was executed with the `count` attribute set).\n", "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "extra": { "description": "An optional JSON object with extra information about the query result.\n\nOnly delivered as part of the first batch, or the last batch in case of a cursor\nwith the `stream` option enabled.\n", "properties": { "plan": { "description": "The execution plan.\n", "properties": { "collections": { "description": "A list of the collections involved in the query. The list only includes the\ncollections that can statically be determined at query compile time.\n", "items": { "properties": { "name": { "description": "The collection name.\n", "type": "string" }, "type": { "description": "How the collection is used.\n", "enum": [ "read", "write", "exclusive" ], "type": "string" } }, "required": [ "name", "type" ], "type": "object" }, "type": "array" }, "estimatedCost": { "description": "The estimated cost of the query.\n", "type": "number" }, "estimatedNrItems": { "description": "The estimated number of results.\n", "type": "integer" }, "isModificationQuery": { "description": "Whether the query contains write operations.\n", "type": "boolean" }, "nodes": { "description": "A nested list of the execution plan nodes.\n", "items": { "type": "object" }, "type": "array" }, "rules": { "description": "A list with the names of the applied optimizer rules.\n", "items": { "type": "string" }, "type": "array" }, "variables": { "description": "All of the query variables, including user-created and internal ones.\n", "items": { "type": "object" }, "type": "array" } }, "required": [ "nodes", "rules", "collections", "variables", "estimatedCost", "estimatedNrItems", "isModificationQuery" ], "type": "object" }, "profile": { "description": "The duration of the different query execution phases in seconds.\n", "properties": { "executing": { "description": "", "type": "number" }, "finalizing": { "description": "", "type": "number" }, "initializing": { "description": "", "type": "number" }, "instantiating executors": { "description": "", "type": "number" }, "instantiating plan": { "description": "", "type": "number" }, "loading collections": { "description": "", "type": "number" }, "optimizing ast": { "description": "", "type": "number" }, "optimizing plan": { "description": "", "type": "number" }, "parsing": { "description": "", "type": "number" } }, "required": [ "initializing", "parsing", "optimizing ast", "loading collections", "instantiating plan", "optimizing plan", "instantiating executors", "executing", "finalizing" ], "type": "object" }, "stats": { "description": "An object with query statistics.\n", "properties": { "cacheHits": { "description": "The total number of index entries read from in-memory caches for indexes\nof type edge or persistent. This value is only non-zero when reading from indexes\nthat have an in-memory cache enabled, and when the query allows using the in-memory\ncache (i.e. using equality lookups on all index attributes).\n", "type": "integer" }, "cacheMisses": { "description": "The total number of cache read attempts for index entries that could not\nbe served from in-memory caches for indexes of type edge or persistent. This value\nis only non-zero when reading from indexes that have an in-memory cache enabled, the\nquery allows using the in-memory cache (i.e. using equality lookups on all index attributes)\nand the looked-up values are not present in the cache.\n", "type": "integer" }, "cursorsCreated": { "description": "The total number of cursor objects created during query execution. Cursor\nobjects are created for index lookups.\n", "type": "integer" }, "cursorsRearmed": { "description": "The total number of times an existing cursor object was repurposed.\nRepurposing an existing cursor object is normally more efficient compared to destroying an\nexisting cursor object and creating a new one from scratch.\n", "type": "integer" }, "documentLookups": { "description": "The number of real document lookups caused by late materialization\nas well as `IndexNode`s that had to load document attributes not covered\nby the index. This is how many documents had to be fetched from storage after\nan index scan that initially covered the attribute access for these documents.\n", "type": "integer" }, "executionTime": { "description": "The query execution time (wall-clock time) in seconds.\n", "type": "number" }, "filtered": { "description": "The total number of documents removed after executing a filter condition\nin a `FilterNode` or another node that post-filters data. Note that nodes of the\n`IndexNode` type can also filter documents by selecting only the required index range\nfrom a collection, and the `filtered` value only indicates how much filtering was done by a\npost filter in the `IndexNode` itself or following `FilterNode` nodes.\nNodes of the `EnumerateCollectionNode` and `TraversalNode` types can also apply\nfilter conditions and can report the number of filtered documents.\n", "type": "integer" }, "fullCount": { "description": "The total number of documents that matched the search condition if the query's\nfinal top-level `LIMIT` operation were not present.\nThis attribute may only be returned if the `fullCount` option was set when starting the\nquery and only contains a sensible value if the query contains a `LIMIT` operation on\nthe top level.\n", "type": "integer" }, "httpRequests": { "description": "The total number of cluster-internal HTTP requests performed.\n", "type": "integer" }, "intermediateCommits": { "description": "The number of intermediate commits performed by the query. This is only non-zero\nfor write queries, and only for queries that reached either the `intermediateCommitSize`\nor `intermediateCommitCount` thresholds. Note: in a cluster, intermediate commits can happen\non each participating DB-Server.\n", "type": "integer" }, "nodes": { "description": "When the query is executed with the `profile` option set to at least `2`,\nthen this attribute contains runtime statistics per query execution node.\nFor a human-readable output, you can execute\n`db._profileQuery(\u003cquery\u003e, \u003cbind-vars\u003e)` in arangosh.\n", "items": { "properties": { "calls": { "description": "The number of calls to this node.\n", "type": "integer" }, "id": { "description": "The execution node ID to correlate the statistics with the `plan` returned in\nthe `extra` attribute.\n", "type": "integer" }, "items": { "description": "The number of items returned by this node. Items are the temporary results\nreturned at this stage.\n", "type": "integer" }, "runtime": { "description": "The execution time of this node in seconds.\n", "type": "number" } }, "required": [ "id", "calls", "items", "runtime" ], "type": "object" }, "type": "array" }, "peakMemoryUsage": { "description": "The maximum memory usage of the query while it was running. In a cluster,\nthe memory accounting is done per shard, and the memory usage reported is the peak\nmemory usage value from the individual shards.\nNote that to keep things lightweight, the per-query memory usage is tracked on a relatively\nhigh level, not including any memory allocator overhead nor any memory used for temporary\nresults calculations (e.g. memory allocated/deallocated inside AQL expressions and function\ncalls).\n", "type": "integer" }, "scannedFull": { "description": "The total number of documents iterated over when scanning a collection\nwithout an index. Documents scanned by subqueries are included in the result, but\noperations triggered by built-in or user-defined AQL functions are not.\n", "type": "integer" }, "scannedIndex": { "description": "The total number of documents iterated over when scanning a collection using\nan index. Documents scanned by subqueries are included in the result, but operations\ntriggered by built-in or user-defined AQL functions are not.\n", "type": "integer" }, "searchParallelism": { "description": "The number of threads used by ArangoSearch for this\nquery (introduced in v3.12.9).\n", "type": "integer" }, "seeks": { "description": "The number of seek calls done by RocksDB iterators for merge joins\n(`JoinNode` in the execution plan).\n", "type": "integer" }, "writesExecuted": { "description": "The total number of data-modification operations successfully executed.\n", "type": "integer" }, "writesIgnored": { "description": "The total number of data-modification operations that were unsuccessful,\nbut have been ignored because of the `ignoreErrors` query option.\n", "type": "integer" } }, "required": [ "writesExecuted", "writesIgnored", "documentLookups", "seeks", "scannedFull", "scannedIndex", "searchParallelism", "cursorsCreated", "cursorsRearmed", "cacheHits", "cacheMisses", "filtered", "httpRequests", "executionTime", "peakMemoryUsage", "intermediateCommits" ], "type": "object" }, "warnings": { "description": "A list of query warnings.\n", "items": { "properties": { "code": { "description": "An error code.\n", "type": "integer" }, "message": { "description": "A description of the problem.\n", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "warnings", "stats" ], "type": "object" }, "hasMore": { "description": "A boolean indicator whether there are more results\navailable for the cursor on the server.\n\nNote that even if `hasMore` returns `true`, the next call might still return no\ndocuments. Once `hasMore` is `false`, the cursor is exhausted and the client\ncan stop asking for more results.\n", "type": "boolean" }, "id": { "description": "The ID of the cursor for fetching more result batches.\n", "type": "string" }, "nextBatchId": { "description": "Only set if the `allowRetry` query option is enabled in v3.11.0.\nFrom v3.11.1 onward, this attribute is always set, except in the last batch.\n\nThe ID of the batch after the current one. The first batch has an ID of `1` and\nthe value is incremented by 1 with every batch. You can remember and use this\nbatch ID should retrieving the next batch fail. Use the\n`POST /_api/cursor/\u003ccursor-id\u003e/\u003cbatch-id\u003e` endpoint to ask for the batch again.\nYou can also request the next batch.\n", "type": "string" }, "planCacheKey": { "description": "The key of the plan cache entry. This attribute is only\npresent if a cached query execution plan has been used.\n", "type": "string" }, "result": { "description": "An array of result documents for the current batch\n(might be empty if the query has no results).\n", "type": "array" } }, "required": [ "error", "code", "hasMore", "cached" ], "type": "object" } } }, "description": "Successfully fetched the batch.\n" }, "400": { "description": "The cursor identifier is missing.\n" }, "404": { "description": "A cursor with the specified identifier cannot found.\n" }, "410": { "description": "A server which processes the query or the leader of a shard which is\nused in the query stops responding, but the connection has not been closed.\n" }, "503": { "description": "A server which processes the query or the leader of a shard which is used\nin the query is down, either for going through a restart, a failure,\nor connectivity issues.\n" } }, "summary": "Read the next batch from a cursor", "tags": [ "Queries" ] }, "put": { "deprecated": true, "description": "\u003e **WARNING:**\nThis endpoint is deprecated in favor its functionally equivalent POST counterpart.\n\n\nIf the cursor is still alive, returns an object with the following\nattributes:\n\n- `id`: a `cursor-identifier`\n- `result`: a list of documents for the current batch\n- `hasMore`: `false` if this was the last batch\n- `count`: if present the total number of elements\n- `code`: an HTTP status code\n- `error`: a boolean flag to indicate whether an error occurred\n- `errorNum`: a server error number (if `error` is `true`)\n- `errorMessage`: a descriptive error message (if `error` is `true`)\n- `extra`: an object with additional information about the query result, with\n the nested objects `stats` and `warnings`. Only delivered as part of the last\n batch in case of a cursor with the `stream` option enabled.\n\nNote that even if `hasMore` returns `true`, the next call might\nstill return no documents. If, however, `hasMore` is `false`, then\nthe cursor is exhausted. Once the `hasMore` attribute has a value of\n`false`, the client can stop.\n\nIf the cursor is not fully consumed, the time-to-live for the cursor\nis renewed by this API call.\n", "operationId": "getNextAqlQueryCursorBatchPut", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the cursor\n", "in": "path", "name": "cursor-identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully fetched the batch.\n" }, "400": { "description": "The cursor identifier is missing.\n" }, "404": { "description": "A cursor with the specified identifier cannot be found.\n" }, "410": { "description": "A server which processes the query or the leader of a shard which is\nused in the query stops responding, but the connection has not been closed.\n" }, "503": { "description": "A server which processes the query or the leader of a shard which is used\nin the query is down, either for going through a restart, a failure,\nor connectivity issues.\n" } }, "summary": "Read the next batch from a cursor (deprecated)", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/cursor/{cursor-identifier}/{batch-identifier}": { "post": { "description": "You can use this endpoint to retry fetching the latest batch from a cursor.\nThe endpoint requires the `allowRetry` query option to be enabled for the cursor.\n\nCalling this endpoint with the last returned batch identifier returns the\nquery results for that same batch again. This does not advance the cursor.\nClient applications can use this to re-transfer a batch once more in case of\ntransfer errors.\n\nYou can also call this endpoint with the next batch identifier, i.e. the value\nreturned in the `nextBatchId` attribute of a previous request. This advances the\ncursor and returns the results of the next batch.\n\nFrom v3.11.1 onward, you may use this endpoint even if the `allowRetry`\nattribute is `false` to fetch the next batch, but you cannot request a batch\nagain unless you set it to `true`.\n\nNote that it is only supported to query the last returned batch identifier or\nthe directly following batch identifier. The latter is only supported if there\nare more results in the cursor (i.e. `hasMore` is `true` in the latest batch).\n\nNote that when the last batch has been consumed successfully by a client\napplication, it should explicitly delete the cursor to inform the server that it\nsuccessfully received and processed the batch so that the server can free up\nresources.\n\nThe time-to-live for the cursor is renewed by this API call.\n", "operationId": "getPreviousAqlQueryCursorBatch", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the cursor.\n", "in": "path", "name": "cursor-identifier", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the batch. The first batch has an ID of `1` and the value is\nincremented by 1 with every batch. You can only request the latest batch again\n(or the next batch). Earlier batches are not kept on the server-side.\n", "in": "path", "name": "batch-identifier", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cached": { "description": "A boolean flag indicating whether the query result was served\nfrom the query results cache or not. If the query result is served from the query\ncache, the `extra` attribute in the response does not contain the `stats`\nand `profile` sub-attributes.\n", "type": "boolean" }, "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "count": { "description": "The total number of result documents available (only\navailable if the query was executed with the `count` attribute set).\n", "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "extra": { "description": "An optional JSON object with extra information about the query result.\n\nOnly delivered as part of the first batch, or the last batch in case of a cursor\nwith the `stream` option enabled.\n", "properties": { "plan": { "description": "The execution plan.\n", "properties": { "collections": { "description": "A list of the collections involved in the query. The list only includes the\ncollections that can statically be determined at query compile time.\n", "items": { "properties": { "name": { "description": "The collection name.\n", "type": "string" }, "type": { "description": "How the collection is used.\n", "enum": [ "read", "write", "exclusive" ], "type": "string" } }, "required": [ "name", "type" ], "type": "object" }, "type": "array" }, "estimatedCost": { "description": "The estimated cost of the query.\n", "type": "number" }, "estimatedNrItems": { "description": "The estimated number of results.\n", "type": "integer" }, "isModificationQuery": { "description": "Whether the query contains write operations.\n", "type": "boolean" }, "nodes": { "description": "A nested list of the execution plan nodes.\n", "items": { "type": "object" }, "type": "array" }, "rules": { "description": "A list with the names of the applied optimizer rules.\n", "items": { "type": "string" }, "type": "array" }, "variables": { "description": "All of the query variables, including user-created and internal ones.\n", "items": { "type": "object" }, "type": "array" } }, "required": [ "nodes", "rules", "collections", "variables", "estimatedCost", "estimatedNrItems", "isModificationQuery" ], "type": "object" }, "profile": { "description": "The duration of the different query execution phases in seconds.\n", "properties": { "executing": { "description": "", "type": "number" }, "finalizing": { "description": "", "type": "number" }, "initializing": { "description": "", "type": "number" }, "instantiating executors": { "description": "", "type": "number" }, "instantiating plan": { "description": "", "type": "number" }, "loading collections": { "description": "", "type": "number" }, "optimizing ast": { "description": "", "type": "number" }, "optimizing plan": { "description": "", "type": "number" }, "parsing": { "description": "", "type": "number" } }, "required": [ "initializing", "parsing", "optimizing ast", "loading collections", "instantiating plan", "optimizing plan", "instantiating executors", "executing", "finalizing" ], "type": "object" }, "stats": { "description": "An object with query statistics.\n", "properties": { "cacheHits": { "description": "The total number of index entries read from in-memory caches for indexes\nof type edge or persistent. This value is only non-zero when reading from indexes\nthat have an in-memory cache enabled, and when the query allows using the in-memory\ncache (i.e. using equality lookups on all index attributes).\n", "type": "integer" }, "cacheMisses": { "description": "The total number of cache read attempts for index entries that could not\nbe served from in-memory caches for indexes of type edge or persistent. This value\nis only non-zero when reading from indexes that have an in-memory cache enabled, the\nquery allows using the in-memory cache (i.e. using equality lookups on all index attributes)\nand the looked-up values are not present in the cache.\n", "type": "integer" }, "cursorsCreated": { "description": "The total number of cursor objects created during query execution. Cursor\nobjects are created for index lookups.\n", "type": "integer" }, "cursorsRearmed": { "description": "The total number of times an existing cursor object was repurposed.\nRepurposing an existing cursor object is normally more efficient compared to destroying an\nexisting cursor object and creating a new one from scratch.\n", "type": "integer" }, "documentLookups": { "description": "The number of real document lookups caused by late materialization\nas well as `IndexNode`s that had to load document attributes not covered\nby the index. This is how many documents had to be fetched from storage after\nan index scan that initially covered the attribute access for these documents.\n", "type": "integer" }, "executionTime": { "description": "The query execution time (wall-clock time) in seconds.\n", "type": "number" }, "filtered": { "description": "The total number of documents removed after executing a filter condition\nin a `FilterNode` or another node that post-filters data. Note that nodes of the\n`IndexNode` type can also filter documents by selecting only the required index range\nfrom a collection, and the `filtered` value only indicates how much filtering was done by a\npost filter in the `IndexNode` itself or following `FilterNode` nodes.\nNodes of the `EnumerateCollectionNode` and `TraversalNode` types can also apply\nfilter conditions and can report the number of filtered documents.\n", "type": "integer" }, "fullCount": { "description": "The total number of documents that matched the search condition if the query's\nfinal top-level `LIMIT` operation were not present.\nThis attribute may only be returned if the `fullCount` option was set when starting the\nquery and only contains a sensible value if the query contains a `LIMIT` operation on\nthe top level.\n", "type": "integer" }, "httpRequests": { "description": "The total number of cluster-internal HTTP requests performed.\n", "type": "integer" }, "intermediateCommits": { "description": "The number of intermediate commits performed by the query. This is only non-zero\nfor write queries, and only for queries that reached either the `intermediateCommitSize`\nor `intermediateCommitCount` thresholds. Note: in a cluster, intermediate commits can happen\non each participating DB-Server.\n", "type": "integer" }, "nodes": { "description": "When the query is executed with the `profile` option set to at least `2`,\nthen this attribute contains runtime statistics per query execution node.\nFor a human-readable output, you can execute\n`db._profileQuery(\u003cquery\u003e, \u003cbind-vars\u003e)` in arangosh.\n", "items": { "properties": { "calls": { "description": "The number of calls to this node.\n", "type": "integer" }, "id": { "description": "The execution node ID to correlate the statistics with the `plan` returned in\nthe `extra` attribute.\n", "type": "integer" }, "items": { "description": "The number of items returned by this node. Items are the temporary results\nreturned at this stage.\n", "type": "integer" }, "runtime": { "description": "The execution time of this node in seconds.\n", "type": "number" } }, "required": [ "id", "calls", "items", "runtime" ], "type": "object" }, "type": "array" }, "peakMemoryUsage": { "description": "The maximum memory usage of the query while it was running. In a cluster,\nthe memory accounting is done per shard, and the memory usage reported is the peak\nmemory usage value from the individual shards.\nNote that to keep things lightweight, the per-query memory usage is tracked on a relatively\nhigh level, not including any memory allocator overhead nor any memory used for temporary\nresults calculations (e.g. memory allocated/deallocated inside AQL expressions and function\ncalls).\n", "type": "integer" }, "scannedFull": { "description": "The total number of documents iterated over when scanning a collection\nwithout an index. Documents scanned by subqueries are included in the result, but\noperations triggered by built-in or user-defined AQL functions are not.\n", "type": "integer" }, "scannedIndex": { "description": "The total number of documents iterated over when scanning a collection using\nan index. Documents scanned by subqueries are included in the result, but operations\ntriggered by built-in or user-defined AQL functions are not.\n", "type": "integer" }, "searchParallelism": { "description": "The number of threads used by ArangoSearch for this\nquery (introduced in v3.12.9).\n", "type": "integer" }, "seeks": { "description": "The number of seek calls done by RocksDB iterators for merge joins\n(`JoinNode` in the execution plan).\n", "type": "integer" }, "writesExecuted": { "description": "The total number of data-modification operations successfully executed.\n", "type": "integer" }, "writesIgnored": { "description": "The total number of data-modification operations that were unsuccessful,\nbut have been ignored because of the `ignoreErrors` query option.\n", "type": "integer" } }, "required": [ "writesExecuted", "writesIgnored", "documentLookups", "seeks", "scannedFull", "scannedIndex", "searchParallelism", "cursorsCreated", "cursorsRearmed", "cacheHits", "cacheMisses", "filtered", "httpRequests", "executionTime", "peakMemoryUsage", "intermediateCommits" ], "type": "object" }, "warnings": { "description": "A list of query warnings.\n", "items": { "properties": { "code": { "description": "An error code.\n", "type": "integer" }, "message": { "description": "A description of the problem.\n", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "type": "array" } }, "required": [ "warnings", "stats" ], "type": "object" }, "hasMore": { "description": "A boolean indicator whether there are more results\navailable for the cursor on the server.\n\nNote that even if `hasMore` returns `true`, the next call might still return no\ndocuments. Once `hasMore` is `false`, the cursor is exhausted and the client\ncan stop asking for more results.\n", "type": "boolean" }, "id": { "description": "The ID of the cursor for fetching more result batches.\n", "type": "string" }, "nextBatchId": { "description": "Only set if the `allowRetry` query option is enabled in v3.11.0.\nFrom v3.11.1 onward, this attribute is always set, except in the last batch.\n\nThe ID of the batch after the current one. The first batch has an ID of `1` and\nthe value is incremented by 1 with every batch. You can remember and use this\nbatch ID should retrieving the next batch fail. Use the\n`POST /_api/cursor/\u003ccursor-id\u003e/\u003cbatch-id\u003e` endpoint to ask for the batch again.\nYou can also request the next batch.\n", "type": "string" }, "planCacheKey": { "description": "The key of the plan cache entry. This attribute is only\npresent if a cached query execution plan has been used.\n", "type": "string" }, "result": { "description": "An array of result documents for the current batch\n(might be empty if the query has no results).\n", "type": "array" } }, "required": [ "error", "code", "hasMore", "cached" ], "type": "object" } } }, "description": "The server responds with *HTTP 200* in case of success.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The cursor and the batch identifier are missing.\n" }, "404": { "description": "A cursor with the specified identifier cannot be found, or the requested\nbatch isn't available.\n" }, "410": { "description": "The server responds with *HTTP 410* if a server which processes the query\nor is the leader for a shard which is used in the query stops responding, but\nthe connection has not been closed.\n" }, "503": { "description": "The server responds with *HTTP 503* if a server which processes the query\nor is the leader for a shard which is used in the query is down, either for\ngoing through a restart, a failure or connectivity issues.\n" } }, "summary": "Read a batch from the cursor again", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/database/current": { "get": { "description": "Retrieves the properties of the current database\n\nThe response is a JSON object with the following attributes:\n\n- `name`: the name of the current database\n- `id`: the id of the current database\n- `path`: the filesystem path of the current database\n- `isSystem`: whether or not the current database is the `_system` database\n- `sharding`: the default sharding method for collections created in this database\n- `replicationFactor`: the default replication factor for collections in this database\n- `writeConcern`: the default write concern for collections in this database\n", "operationId": "getCurrentDatabase", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the information was retrieved successfully.\n" }, "400": { "description": "is returned if the request is invalid.\n" }, "404": { "description": "is returned if the database could not be found.\n" } }, "summary": "Get information about the current database", "tags": [ "Databases" ] } }, "/_db/{database-name}/_api/database/user": { "get": { "description": "Retrieves the list of all databases the current user can access without\nspecifying a different username or password.\n", "operationId": "listUserAccessibleDatabases", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the list of database was compiled successfully.\n" }, "400": { "description": "is returned if the request is invalid.\n" } }, "summary": "List the accessible databases", "tags": [ "Databases" ] } }, "/_db/{database-name}/_api/document/{collection}": { "delete": { "description": "The body of the request is an array consisting of selectors for\ndocuments. A selector can either be a string with a key or a string\nwith a document identifier or an object with a `_key` attribute. This\nAPI call removes all specified documents from `collection`.\nIf the `ignoreRevs` query parameter is `false` and the\nselector is an object and has a `_rev` attribute, it is a\nprecondition that the actual revision of the removed document in the\ncollection is the specified one.\n\nThe body of the response is an array of the same length as the input\narray. For each input selector, the output contains a JSON object\nwith the information about the outcome of the operation. If no error\noccurred, then such an object has the following attributes:\n- `_id`, containing the document identifier with the format `\u003ccollection-name\u003e/\u003cdocument-key\u003e`.\n- `_key`, containing the document key that uniquely identifies a document within the collection.\n- `_rev`, containing the document revision.\nIn case of an error, the object has the `error` attribute set to `true`\nand `errorCode` set to the error code.\n\nIf the `waitForSync` parameter is not specified or set to `false`,\nthen the collection's default `waitForSync` behavior is applied.\nThe `waitForSync` query parameter cannot be used to disable\nsynchronization for collections that have a default `waitForSync`\nvalue of `true`.\n\nIf the query parameter `returnOld` is `true`, then\nthe complete previous revision of the document\nis returned under the `old` attribute in the result.\n\nNote that if any precondition is violated or an error occurred with\nsome of the documents, the return code is still 200 or 202, but the\n`X-Arango-Error-Codes` HTTP header is set. It contains a map of the\nerror codes and how often each kind of error occurred. For example,\n`1200:17,1205:10` means that in 17 cases the error 1200 (\"revision conflict\")\nhas happened, and in 10 cases the error 1205 (\"illegal document handle\").\n", "operationId": "deleteDocuments", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Collection from which documents are removed.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "Wait until deletion operation has been synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If set to `true`, an empty object is returned as response if all document operations\nsucceed. No meta-data is returned for the deleted documents. If at least one of\nthe operations raises an error, an array with the error object(s) is returned.\n\nYou can use this option to save network traffic but you cannot map any errors\nto the inputs of your request.\n", "in": "query", "name": "silent", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If set to `true`, ignore any `_rev` attribute included in the request. No\nrevision check is performed. If set to `false`, then revisions are checked.\n", "in": "query", "name": "ignoreRevs", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Whether to delete existing entries from in-memory index caches and refill them\nif document removals affect the edge index or cache-enabled persistent indexes.\n", "in": "query", "name": "refillIndexCaches", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "An array of document selectors. A selector can be a string\n(document key or identifier) or an object that has to contain a\n`_key` attribute with the document key.\n", "type": "array" } } } }, "responses": { "200": { "description": "The individual operations have been processed and `waitForSync` was `true`.\n" }, "202": { "description": "The individual operations have been processed and `waitForSync` was `false`.\n" }, "403": { "description": "If the error code is `1004`, the specified write concern for the\ncollection cannot be fulfilled. This can happen if less than the number of\nspecified replicas for a shard are currently in-sync with the leader. For example,\nif the write concern is `2` and the replication factor is `3`, then the\nwrite concern is not fulfilled if two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" }, "404": { "description": "The collection cannot be found.\nThe response body contains an error document in this case.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "503": { "description": "The system is temporarily not available. This can be a system\noverload or temporary failure. In this case it makes sense to retry the request\nlater.\n\nIf the error code is `1429`, then the write concern for the collection cannot be\nfulfilled. This can happen if less than the number of specified replicas for\na shard are currently in-sync with the leader. For example, if the write concern\nis `2` and the replication factor is `3`, then the write concern is not fulfilled\nif two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" } }, "summary": "Remove multiple documents", "tags": [ "Documents" ] }, "patch": { "description": "Partially updates documents, the documents to update are specified\nby the `_key` attributes in the body objects. The body of the\nrequest must contain a JSON array of document updates with the\nattributes to patch (the patch documents). All attributes from the\npatch documents are added to the existing documents if they do\nnot yet exist, and overwritten in the existing documents if they do\nexist there.\n\nThe values of the `_key`, `_id`, and `_rev` system attributes as well as\nattributes used as sharding keys cannot be changed.\n\nSetting an attribute value to `null` in the patch documents causes a\nvalue of `null` to be saved for the attribute by default.\n\nIf `ignoreRevs` is `false` and there is a `_rev` attribute in a\ndocument in the body and its value does not match the revision of\nthe corresponding document in the database, the precondition is\nviolated.\n\nCluster only: The patch document _may_ contain\nvalues for the collection's pre-defined shard keys. Values for the shard keys\nare treated as hints to improve performance. Should the shard keys\nvalues be incorrect ArangoDB may answer with a *not found* error\n\nOptionally, the query parameter `waitForSync` can be used to force\nsynchronization of the document replacement operation to disk even in case\nthat the `waitForSync` flag had been disabled for the entire collection.\nThus, the `waitForSync` query parameter can be used to force synchronization\nof just specific operations. To use this, set the `waitForSync` parameter\nto `true`. If the `waitForSync` parameter is not specified or set to\n`false`, then the collection's default `waitForSync` behavior is\napplied. The `waitForSync` query parameter cannot be used to disable\nsynchronization for collections that have a default `waitForSync` value\nof `true`.\n\nThe body of the response contains a JSON array of the same length\nas the input array with the information about the identifier and the\nrevision of the updated documents. Each element has the following\nattributes:\n- `_id`, containing the document identifier with the format `\u003ccollection-name\u003e/\u003cdocument-key\u003e`.\n- `_key`, containing the document key that uniquely identifies a document within the collection.\n- `_rev`, containing the new document revision.\n\nIn case of an error or violated precondition, an error\nobject with the attribute `error` set to `true` and the attribute\n`errorCode` set to the error code is built.\n\nIf the query parameter `returnOld` is `true`, then, for each\ngenerated document, the complete previous revision of the document\nis returned under the `old` attribute in the result.\n\nIf the query parameter `returnNew` is `true`, then, for each\ngenerated document, the complete new document is returned under\nthe `new` attribute in the result.\n\nNote that if any precondition is violated or an error occurred with\nsome of the documents, the return code is still 201 or 202, but the\n`X-Arango-Error-Codes` HTTP header is set. It contains a map of the\nerror codes and how often each kind of error occurred. For example,\n`1200:17,1205:10` means that in 17 cases the error 1200 (\"revision conflict\")\nhas happened, and in 10 cases the error 1205 (\"illegal document handle\").\n", "operationId": "updateDocuments", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Name of the `collection` in which the documents are to be updated.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "If the intention is to delete existing attributes with the patch\ncommand, set the `keepNull` query parameter to `false`. This modifies the\nbehavior of the patch command to remove top-level attributes and sub-attributes\nfrom the existing document that are contained in the patch document with an\nattribute value of `null` (but not attributes of objects that are nested inside\nof arrays).\n", "in": "query", "name": "keepNull", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Controls whether objects (not arrays) are merged if present in\nboth the existing and the patch document. If set to `false`, the\nvalue in the patch document overwrites the existing document's\nvalue. If set to `true`, objects are merged.\n", "in": "query", "name": "mergeObjects", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Wait until the new documents have been synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "If set to `true`, the `_rev` attributes in\nthe given documents are ignored. If this is set to `false`, then\nany `_rev` attribute given in a body document is taken as a\nprecondition. The document is only updated if the current revision\nis the one specified.\n", "in": "query", "name": "ignoreRevs", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to additionally include the complete new document under the\n`new` attribute in the result.\n", "in": "query", "name": "returnNew", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If set to `true`, an empty object is returned as response if all document operations\nsucceed. No meta-data is returned for the updated documents. If at least one\noperation raises an error, an array with the error object(s) is returned.\n\nYou can use this option to save network traffic but you cannot map any errors\nto the inputs of your request.\n", "in": "query", "name": "silent", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to update existing entries in in-memory index caches if document updates\naffect the edge index or cache-enabled persistent indexes.\n", "in": "query", "name": "refillIndexCaches", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "You can use the `versionAttribute` option for external versioning support.\nIf set, the attribute with the name specified by the option is looked up in the\nstored document and the attribute value is compared numerically to the value of\nthe versioning attribute in the supplied document that is supposed to update it.\n\nIf the version number in the new document is higher (rounded down to a whole number)\nthan in the document that already exists in the database, then the update\noperation is performed normally. This is also the case if the new versioning\nattribute has a non-numeric value, if it is a negative number, or if the\nattribute doesn't exist in the supplied or stored document.\n\nIf the version number in the new document is lower or equal to what exists in\nthe database, the operation is not performed and the existing document thus not\nchanged. No error is returned in this case.\n\nThe attribute can only be a top-level attribute.\n\nYou can check if `_oldRev` and `_rev` are different to determine if the\ndocument has been changed.\n", "in": "query", "name": "versionAttribute", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "An array of partial documents representing the desired updates.\nEach element has to contain a `_key` attribute. The existing\ndocuments with matching document keys are updated.\n", "items": { "type": "object" }, "type": "array" } } } }, "responses": { "201": { "description": "The individual operations have been processed and `waitForSync` was `true`.\n" }, "202": { "description": "The individual operations have been processed and `waitForSync` was `false`.\n" }, "400": { "description": "The request body does not contain a valid JSON representation\nof an array of documents.\n" }, "403": { "description": "If the error code is `1004`, the specified write concern for the\ncollection cannot be fulfilled. This can happen if less than the number of\nspecified replicas for a shard are currently in-sync with the leader. For example,\nif the write concern is `2` and the replication factor is `3`, then the\nwrite concern is not fulfilled if two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" }, "404": { "description": "The collection cannot be found.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "503": { "description": "The system is temporarily not available. This can be a system\noverload or temporary failure. In this case it makes sense to retry the request\nlater.\n\nIf the error code is `1429`, then the write concern for the collection cannot be\nfulfilled. This can happen if less than the number of specified replicas for\na shard are currently in-sync with the leader. For example, if the write concern\nis `2` and the replication factor is `3`, then the write concern is not fulfilled\nif two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" } }, "summary": "Update multiple documents", "tags": [ "Documents" ] }, "post": { "description": "Creates a new document from the document given in the body, unless there\nis already a document with the `_key` given. If no `_key` is given, a\nnew unique `_key` is generated automatically. The `_id` is automatically\nset in both cases, derived from the collection name and `_key`.\n\n\u003e **INFO:**\nAn `_id` or `_rev` attribute specified in the body is ignored.\n\n\nIf the document was created successfully, then the `Location` header\ncontains the path to the newly created document. The `ETag` header field\ncontains the revision of the document. Both are only set in the single\ndocument case.\n\nUnless `silent` is set to `true`, the body of the response contains a\nJSON object with the following attributes:\n- `_id`, containing the document identifier with the format `\u003ccollection-name\u003e/\u003cdocument-key\u003e`.\n- `_key`, containing the document key that uniquely identifies a document within the collection.\n- `_rev`, containing the document revision.\n\nIf the collection parameter `waitForSync` is `false`, then the call\nreturns as soon as the document has been accepted. It does not wait\nuntil the documents have been synced to disk.\n\nOptionally, the query parameter `waitForSync` can be used to force\nsynchronization of the document creation operation to disk even in\ncase that the `waitForSync` flag had been disabled for the entire\ncollection. Thus, the `waitForSync` query parameter can be used to\nforce synchronization of just this specific operations. To use this,\nset the `waitForSync` parameter to `true`. If the `waitForSync`\nparameter is not specified or set to `false`, then the collection's\ndefault `waitForSync` behavior is applied. The `waitForSync` query\nparameter cannot be used to disable synchronization for collections\nthat have a default `waitForSync` value of `true`.\n\nIf the query parameter `returnNew` is `true`, then, for each\ngenerated document, the complete new document is returned under\nthe `new` attribute in the result.\n", "operationId": "createDocument", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Name of the `collection` in which the document is to be created.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "Wait until document has been synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Whether to additionally include the complete new document under the\n`new` attribute in the result.\n", "in": "query", "name": "returnNew", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result. Only available if the `overwriteMode`\nparameter is set to `\"update\"` or `\"replace\"`, or if `overwrite` is set to `true`.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If set to `true`, an empty object is returned as response if the document operation\nsucceeds. No meta-data is returned for the created document. If the\noperation raises an error, an error object is returned.\n\nYou can use this option to save network traffic.\n", "in": "query", "name": "silent", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If set to `true`, the insert becomes a replace-insert. If a document with the\nsame `_key` already exists, the new document is not rejected with unique\nconstraint violation error but replaces the old document. Note that operations\nwith `overwrite` parameter require a `_key` attribute in the request payload,\ntherefore they can only be performed on collections sharded by `_key`.\n", "in": "query", "name": "overwrite", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "This option supersedes `overwrite` and offers the following modes:\n- `\"ignore\"`: if a document with the specified `_key` value exists already,\n nothing is done and no write operation is carried out. The\n insert operation returns success in this case. This mode does not\n support returning the old document version using `RETURN OLD`. When using\n `RETURN NEW`, `null` is returned in case the document already existed.\n- `\"replace\"`: if a document with the specified `_key` value exists already,\n it is overwritten with the specified document value. This mode is\n also used when no overwrite mode is specified but the `overwrite`\n flag is set to `true`.\n- `\"update\"`: if a document with the specified `_key` value exists already,\n it is patched (partially updated) with the specified document value.\n The overwrite mode can be further controlled via the `keepNull` and\n `mergeObjects` parameters.\n- `\"conflict\"`: if a document with the specified `_key` value exists already,\n return a unique constraint violation error so that the insert operation\n fails. This is also the default behavior in case the overwrite mode is\n not set, and the `overwrite` flag is `false` or not set either.\n", "in": "query", "name": "overwriteMode", "required": false, "schema": { "default": "conflict", "enum": [ "ignore", "replace", "update", "conflict" ], "type": "string" } }, { "description": "If the intention is to delete existing attributes with the update-insert\ncommand, set the `keepNull` query parameter to `false`. This modifies the\nbehavior of the patch command to remove top-level attributes and sub-attributes\nfrom the existing document that are contained in the patch document with an\nattribute value of `null` (but not attributes of objects that are nested inside\nof arrays). This option controls the update-insert behavior only.\n", "in": "query", "name": "keepNull", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Controls whether objects (not arrays) are merged if present in both, the\nexisting and the update-insert document. If set to `false`, the value in the\npatch document overwrites the existing document's value. If set to `true`,\nobjects are merged.\nThis option controls the update-insert behavior only.\n", "in": "query", "name": "mergeObjects", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Whether to add new entries to in-memory index caches if document insertions\naffect the edge index or cache-enabled persistent indexes.\n", "in": "query", "name": "refillIndexCaches", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Only applicable if `overwrite` is set to `true` or `overwriteMode`\nis set to `update` or `replace`.\n\nYou can use the `versionAttribute` option for external versioning support.\nIf set, the attribute with the name specified by the option is looked up in the\nstored document and the attribute value is compared numerically to the value of\nthe versioning attribute in the supplied document that is supposed to update/replace it.\n\nIf the version number in the new document is higher (rounded down to a whole number)\nthan in the document that already exists in the database, then the update/replace\noperation is performed normally. This is also the case if the new versioning\nattribute has a non-numeric value, if it is a negative number, or if the\nattribute doesn't exist in the supplied or stored document.\n\nIf the version number in the new document is lower or equal to what exists in\nthe database, the operation is not performed and the existing document thus not\nchanged. No error is returned in this case.\n\nThe attribute can only be a top-level attribute.\n\nYou can check if `_oldRev` (if present) and `_rev` are different to determine if the\ndocument has been changed.\n", "in": "query", "name": "versionAttribute", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "A JSON representation of a single document.\n", "type": "object" } } } }, "responses": { "201": { "description": "The document has been created successfully and\n`waitForSync` was `true`.\n" }, "202": { "description": "The document has been created successfully and\n`waitForSync` was `false`.\n" }, "400": { "description": "The request body does not contain a valid JSON representation\nof a document. The response body contains\nan error document in this case.\n" }, "403": { "description": "If the error code is `1004`, the specified write concern for the\ncollection cannot be fulfilled. This can happen if less than the number of\nspecified replicas for a shard are currently in-sync with the leader. For example,\nif the write concern is `2` and the replication factor is `3`, then the\nwrite concern is not fulfilled if two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" }, "404": { "description": "The collection cannot be found.\nThe response body contains an error document in this case.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "409": { "description": "There are two possible reasons for this error in the single document case:\n\n- A document with the same qualifiers in an indexed attribute conflicts with an\n already existing document and thus violates the unique constraint.\n The response body contains an error document with the `errorNum` set to\n `1210` (`ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED`) in this case.\n- Locking the document key or some unique index entry failed to due to another\n concurrent operation that operates on the same document. This is also referred\n to as a _write-write conflict_. The response body contains an error document\n with the `errorNum` set to `1200` (`ERROR_ARANGO_CONFLICT`) in this case.\n" }, "410": { "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "503": { "description": "The system is temporarily not available. This can be a system\noverload or temporary failure. In this case it makes sense to retry the request\nlater.\n\nIf the error code is `1429`, then the write concern for the collection cannot be\nfulfilled. This can happen if less than the number of specified replicas for\na shard are currently in-sync with the leader. For example, if the write concern\nis `2` and the replication factor is `3`, then the write concern is not fulfilled\nif two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" } }, "summary": "Create a document", "tags": [ "Documents" ] }, "put": { "description": "Replaces multiple documents in the specified collection with the\nones in the body, the replaced documents are specified by the `_key`\nattributes in the body documents.\n\nThe values of the `_key`, `_id`, and `_rev` system attributes as well as\nattributes used as sharding keys cannot be changed.\n\nIf `ignoreRevs` is `false` and there is a `_rev` attribute in a\ndocument in the body and its value does not match the revision of\nthe corresponding document in the database, the precondition is\nviolated.\n\nCluster only: The replace documents _may_ contain\nvalues for the collection's pre-defined shard keys. Values for the shard keys\nare treated as hints to improve performance. Should the shard keys\nvalues be incorrect ArangoDB may answer with a `not found` error.\n\nOptionally, the query parameter `waitForSync` can be used to force\nsynchronization of the document replacement operation to disk even in case\nthat the `waitForSync` flag had been disabled for the entire collection.\nThus, the `waitForSync` query parameter can be used to force synchronization\nof just specific operations. To use this, set the `waitForSync` parameter\nto `true`. If the `waitForSync` parameter is not specified or set to\n`false`, then the collection's default `waitForSync` behavior is\napplied. The `waitForSync` query parameter cannot be used to disable\nsynchronization for collections that have a default `waitForSync` value\nof `true`.\n\nThe body of the response contains a JSON array of the same length\nas the input array with the information about the identifier and the\nrevision of the replaced documents. In each element has the following\nattributes:\n- `_id`, containing the document identifier with the format `\u003ccollection-name\u003e/\u003cdocument-key\u003e`.\n- `_key`, containing the document key that uniquely identifies a document within the collection.\n- `_rev`, containing the new document revision.\n\nIn case of an error or violated precondition, an error\nobject with the attribute `error` set to `true` and the attribute\n`errorCode` set to the error code is built.\n\nIf the query parameter `returnOld` is `true`, then, for each\ngenerated document, the complete previous revision of the document\nis returned under the `old` attribute in the result.\n\nIf the query parameter `returnNew` is `true`, then, for each\ngenerated document, the complete new document is returned under\nthe `new` attribute in the result.\n\nNote that if any precondition is violated or an error occurred with\nsome of the documents, the return code is still 201 or 202, but the\n`X-Arango-Error-Codes` HTTP header is set. It contains a map of the\nerror codes and how often each kind of error occurred. For example,\n`1200:17,1205:10` means that in 17 cases the error 1200 (\"revision conflict\")\nhas happened, and in 10 cases the error 1205 (\"illegal document handle\").\n", "operationId": "replaceDocuments", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "This URL parameter is the name of the collection in which the\ndocuments are replaced.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "Wait until the new documents have been synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "If set to `true`, the `_rev` attributes in\nthe given documents are ignored. If this is set to `false`, then\nany `_rev` attribute given in a body document is taken as a\nprecondition. The document is only replaced if the current revision\nis the one specified.\n", "in": "query", "name": "ignoreRevs", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to additionally include the complete new document under the\n`new` attribute in the result.\n", "in": "query", "name": "returnNew", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If set to `true`, an empty object is returned as response if all document operations\nsucceed. No meta-data is returned for the replaced documents. If at least one\noperation raises an error, an array with the error object(s) is returned.\n\nYou can use this option to save network traffic but you cannot map any errors\nto the inputs of your request.\n", "in": "query", "name": "silent", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to update existing entries in in-memory index caches if documents\nreplacements affect the edge index or cache-enabled persistent indexes.\n", "in": "query", "name": "refillIndexCaches", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "You can use the `versionAttribute` option for external versioning support.\nIf set, the attribute with the name specified by the option is looked up in the\nstored document and the attribute value is compared numerically to the value of\nthe versioning attribute in the supplied document that is supposed to replace it.\n\nIf the version number in the new document is higher (rounded down to a whole number)\nthan in the document that already exists in the database, then the replace\noperation is performed normally. This is also the case if the new versioning\nattribute has a non-numeric value, if it is a negative number, or if the\nattribute doesn't exist in the supplied or stored document.\n\nIf the version number in the new document is lower or equal to what exists in\nthe database, the operation is not performed and the existing document thus not\nchanged. No error is returned in this case.\n\nThe attribute can only be a top-level attribute.\n\nYou can check if `_oldRev` and `_rev` are different to determine if the\ndocument has been changed.\n", "in": "query", "name": "versionAttribute", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "An array of documents. Each element has to contain a `_key` attribute.\nThe existing documents with matching document keys are replaced.\n", "items": { "type": "object" }, "type": "array" } } } }, "responses": { "201": { "description": "The individual operations have been processed and `waitForSync` was `true`.\n" }, "202": { "description": "The individual operations have been processed and `waitForSync` was `false`.\n" }, "400": { "description": "The request body does not contain a valid JSON representation\nof an array of documents.\n" }, "403": { "description": "If the error code is `1004`, the specified write concern for the\ncollection cannot be fulfilled. This can happen if less than the number of\nspecified replicas for a shard are currently in-sync with the leader. For example,\nif the write concern is `2` and the replication factor is `3`, then the\nwrite concern is not fulfilled if two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" }, "404": { "description": "The collection cannot be found.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "503": { "description": "The system is temporarily not available. This can be a system\noverload or temporary failure. In this case it makes sense to retry the request\nlater.\n\nIf the error code is `1429`, then the write concern for the collection cannot be\nfulfilled. This can happen if less than the number of specified replicas for\na shard are currently in-sync with the leader. For example, if the write concern\nis `2` and the replication factor is `3`, then the write concern is not fulfilled\nif two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" } }, "summary": "Replace multiple documents", "tags": [ "Documents" ] } }, "/_db/{database-name}/_api/document/{collection}#get": { "put": { "description": "\u003e **WARNING:**\nThe endpoint for getting multiple documents is the same as for replacing\nmultiple documents but with an additional query parameter:\n`PUT /_api/document/{collection}?onlyget=true`. This is because a lot of\nsoftware does not support payload bodies in `GET` requests.\n\n\nReturns the documents identified by their `_key` attribute.\nThe body of the request _must_ contain a JSON array of either\nstrings (the `_key` values to look up) or search documents.\n\nA search document _must_ contain at least a value for the `_key` field.\nA value for `_rev` _may_ be specified to verify whether the document\nhas the same revision value, unless _ignoreRevs_ is set to false.\n\nCluster only: The search document _may_ contain\nvalues for the collection's pre-defined shard keys. Values for the shard keys\nare treated as hints to improve performance. Should the shard keys\nvalues be incorrect ArangoDB may answer with a *not found* error.\n\nThe returned array of documents contain three special attributes: \n- `_id`, containing the document identifier with the format `\u003ccollection-name\u003e/\u003cdocument-key\u003e`.\n- `_key`, containing the document key that uniquely identifies a document within the collection.\n- `_rev`, containing the document revision.\n", "operationId": "getDocuments", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Name of the `collection` from which the documents are to be read.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "This parameter is required to be `true`, otherwise a replace\noperation is executed!\n", "example": true, "in": "query", "name": "onlyget", "required": true, "schema": { "type": "boolean" } }, { "description": "If set to `false` and a `_rev` attribute is included in the request,\nthen the document is only returned if it has the same revision.\nOtherwise, a precondition failed error is returned for the document.\n", "in": "query", "name": "ignoreRevs", "required": false, "schema": { "default": true, "type": "string" } }, { "description": "Set this header to `true` to allow the Coordinator to ask any shard replica for\nthe data, not only the shard leader. This may result in \"dirty reads\".\n\nThe header is ignored if this operation is part of a Stream Transaction\n(`x-arango-trx-id` header). The header set when creating the transaction decides\nabout dirty reads for the entire transaction, not the individual read operations.\n", "in": "header", "name": "x-arango-allow-dirty-read", "required": false, "schema": { "type": "boolean" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "An array of documents to retrieve.\n", "type": "array" } } } }, "responses": { "200": { "description": "No error occurred for the overall operation.\n" }, "400": { "description": "The request body does not contain a valid JSON representation\nof an array of documents.\n" }, "404": { "description": "The collection cannot be found.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" } }, "summary": "Get multiple documents", "tags": [ "Documents" ] } }, "/_db/{database-name}/_api/document/{collection}#multiple": { "post": { "description": "Creates new documents from the documents given in the body, unless there\nis already a document with the `_key` given. If no `_key` is given, a new\nunique `_key` is generated automatically. The `_id` is automatically\nset in both cases, derived from the collection name and `_key`.\n\nThe result body contains a JSON array of the\nsame length as the input array, and each entry contains the result\nof the operation for the corresponding input. In case of an error\nthe entry is a document with attributes `error` set to `true` and\nerrorCode set to the error code that has happened.\n\n\u003e **INFO:**\nAny `_id` or `_rev` attribute specified in the body is ignored.\n\n\nUnless `silent` is set to `true`, the body of the response contains an\narray of JSON objects with the following attributes:\n- `_id`, containing the document identifier with the format `\u003ccollection-name\u003e/\u003cdocument-key\u003e`.\n- `_key`, containing the document key that uniquely identifies a document within the collection.\n- `_rev`, containing the document revision.\n\nIf the collection parameter `waitForSync` is `false`, then the call\nreturns as soon as the documents have been accepted. It does not wait\nuntil the documents have been synced to disk.\n\nOptionally, the query parameter `waitForSync` can be used to force\nsynchronization of the document creation operation to disk even in\ncase that the `waitForSync` flag had been disabled for the entire\ncollection. Thus, the `waitForSync` query parameter can be used to\nforce synchronization of just this specific operations. To use this,\nset the `waitForSync` parameter to `true`. If the `waitForSync`\nparameter is not specified or set to `false`, then the collection's\ndefault `waitForSync` behavior is applied. The `waitForSync` query\nparameter cannot be used to disable synchronization for collections\nthat have a default `waitForSync` value of `true`.\n\nIf the query parameter `returnNew` is `true`, then, for each\ngenerated document, the complete new document is returned under\nthe `new` attribute in the result.\n\nShould an error have occurred with some of the documents,\nthe `X-Arango-Error-Codes` HTTP header is set. It contains a map of the\nerror codes and how often each kind of error occurred. For example,\n`1200:17,1205:10` means that in 17 cases the error 1200 (\"revision conflict\")\nhas happened, and in 10 cases the error 1205 (\"illegal document handle\").\n", "operationId": "createDocuments", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Name of the `collection` in which the documents are to be created.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "Wait until document has been synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Whether to additionally include the complete new document under the\n`new` attribute in the result.\n", "in": "query", "name": "returnNew", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result. Only available if the `overwriteMode`\nparameter is set to `\"update\"` or `\"replace\"`, or if `overwrite` is set to `true`.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If set to `true`, an empty object is returned as response if all document operations\nsucceed. No meta-data is returned for the created documents. If any of the\noperations raises an error, an array with the error object(s) is returned.\n\nYou can use this option to save network traffic but you cannot map any errors\nto the inputs of your request.\n", "in": "query", "name": "silent", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If set to `true`, the insert becomes a replace-insert. If a document with the\nsame `_key` already exists, the new document is not rejected with a unique\nconstraint violation error but replaces the old document. Note that operations\nwith `overwrite` parameter require a `_key` attribute in the request payload,\ntherefore they can only be performed on collections sharded by `_key`.\n", "in": "query", "name": "overwrite", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "This option supersedes `overwrite` and offers the following modes:\n- `\"ignore\"`: if a document with the specified `_key` value exists already,\n nothing is done and no write operation is carried out. The\n insert operation returns success in this case. This mode does not\n support returning the old document version using `RETURN OLD`. When using\n `RETURN NEW`, `null` is returned in case the document already existed.\n- `\"replace\"`: if a document with the specified `_key` value exists already,\n it is overwritten with the specified document value. This mode is\n also used when no overwrite mode is specified but the `overwrite`\n flag is set to `true`.\n- `\"update\"`: if a document with the specified `_key` value exists already,\n it is patched (partially updated) with the specified document value.\n The overwrite mode can be further controlled via the `keepNull` and\n `mergeObjects` parameters.\n- `\"conflict\"`: if a document with the specified `_key` value exists already,\n return a unique constraint violation error so that the insert operation\n fails. This is also the default behavior in case the overwrite mode is\n not set, and the `overwrite` flag is `false` or not set either.\n", "in": "query", "name": "overwriteMode", "required": false, "schema": { "default": "conflict", "enum": [ "ignore", "replace", "update", "conflict" ], "type": "string" } }, { "description": "If the intention is to delete existing attributes with the update-insert\ncommand, set the `keepNull` query parameter to `false`. This modifies the\nbehavior of the patch command to remove top-level attributes and sub-attributes\nfrom the existing document that are contained in the patch document with an\nattribute value of `null` (but not attributes of objects that are nested inside\nof arrays). This option controls the update-insert behavior only.\n", "in": "query", "name": "keepNull", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Controls whether objects (not arrays) are merged if present in both, the\nexisting and the update-insert document. If set to `false`, the value in the\npatch document overwrites the existing document's value. If set to `true`,\nobjects are merged.\nThis option controls the update-insert behavior only.\n", "in": "query", "name": "mergeObjects", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Whether to add new entries to in-memory index caches if document insertions\naffect the edge index or cache-enabled persistent indexes.\n", "in": "query", "name": "refillIndexCaches", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Only applicable if `overwrite` is set to `true` or `overwriteMode`\nis set to `update` or `replace`.\n\nYou can use the `versionAttribute` option for external versioning support.\nIf set, the attribute with the name specified by the option is looked up in the\nstored document and the attribute value is compared numerically to the value of\nthe versioning attribute in the supplied document that is supposed to update/replace it.\n\nIf the version number in the new document is higher (rounded down to a whole number)\nthan in the document that already exists in the database, then the update/replace\noperation is performed normally. This is also the case if the new versioning\nattribute has a non-numeric value, if it is a negative number, or if the\nattribute doesn't exist in the supplied or stored document.\n\nIf the version number in the new document is lower or equal to what exists in\nthe database, the operation is not performed and the existing document thus not\nchanged. No error is returned in this case.\n\nThe attribute can only be a top-level attribute.\n\nYou can check if `_oldRev` (if present) and `_rev` are different to determine if the\ndocument has been changed.\n", "in": "query", "name": "versionAttribute", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "An array of documents to create.\n", "items": { "type": "object" }, "type": "array" } } } }, "responses": { "201": { "description": "The individual operations have been processed and `waitForSync` was `true`.\n" }, "202": { "description": "The individual operations have been processed and `waitForSync` was `false`.\n" }, "400": { "description": "The request body does not contain a valid JSON representation\nof an array of documents.\n" }, "403": { "description": "If the error code is `1004`, the specified write concern for the\ncollection cannot be fulfilled. This can happen if less than the number of\nspecified replicas for a shard are currently in-sync with the leader. For example,\nif the write concern is `2` and the replication factor is `3`, then the\nwrite concern is not fulfilled if two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" }, "404": { "description": "The document or collection cannot be found.\nThe response body contains an error document in this case.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "503": { "description": "The system is temporarily not available. This can be a system\noverload or temporary failure. In this case it makes sense to retry the request\nlater.\n\nIf the error code is `1429`, then the write concern for the collection cannot be\nfulfilled. This can happen if less than the number of specified replicas for\na shard are currently in-sync with the leader. For example, if the write concern\nis `2` and the replication factor is `3`, then the write concern is not fulfilled\nif two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" } }, "summary": "Create multiple documents", "tags": [ "Documents" ] } }, "/_db/{database-name}/_api/document/{collection}/{key}": { "delete": { "description": "Unless `silent` is set to `true`, the body of the response contains a\nJSON object with the following attributes:\n- `_id`, containing the document identifier with the format `\u003ccollection-name\u003e/\u003cdocument-key\u003e`.\n- `_key`, containing the document key that uniquely identifies a document within the collection.\n- `_rev`, containing the document revision.\n\nIf the `waitForSync` parameter is not specified or set to `false`,\nthen the collection's default `waitForSync` behavior is applied.\nThe `waitForSync` query parameter cannot be used to disable\nsynchronization for collections that have a default `waitForSync`\nvalue of `true`.\n\nIf the query parameter `returnOld` is `true`, then\nthe complete previous revision of the document\nis returned under the `old` attribute in the result.\n", "operationId": "deleteDocument", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Name of the `collection` in which the document is to be deleted.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The document key.\n", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "Wait until deletion operation has been synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If set to `true`, an empty object is returned as response if the document operation\nsucceeds. No meta-data is returned for the deleted document. If the\noperation raises an error, an error object is returned.\n\nYou can use this option to save network traffic.\n", "in": "query", "name": "silent", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to delete existing entries from in-memory index caches and refill them\nif document removals affect the edge index or cache-enabled persistent indexes.\n", "in": "query", "name": "refillIndexCaches", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "You can conditionally remove a document based on a target revision id by\nusing the `If-Match` HTTP header.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The document has been removed successfully and\n`waitForSync` was `true`.\n" }, "202": { "description": "The document has been removed successfully and\n`waitForSync` was `false`.\n" }, "403": { "description": "If the error code is `1004`, the specified write concern for the\ncollection cannot be fulfilled. This can happen if less than the number of\nspecified replicas for a shard are currently in-sync with the leader. For example,\nif the write concern is `2` and the replication factor is `3`, then the\nwrite concern is not fulfilled if two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" }, "404": { "description": "The document or collection cannot be found.\nThe response body contains an error document in this case.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "409": { "description": "Locking the document key failed due to another\nconcurrent operation that operates on the same document.\nThis is also referred to as a _write-write conflict_.\nThe response body contains an error document with the\n`errorNum` set to `1200` (`ERROR_ARANGO_CONFLICT`) in this case.\n" }, "410": { "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "412": { "description": "An `If-Match` header is specified and the found\ndocument has a different version. The response includes the found\ndocument's current revision in the `_rev` attribute. Additionally, the\nattributes `_id` and `_key` are returned.\n" }, "503": { "description": "The system is temporarily not available. This can be a system\noverload or temporary failure. In this case it makes sense to retry the request\nlater.\n\nIf the error code is `1429`, then the write concern for the collection cannot be\nfulfilled. This can happen if less than the number of specified replicas for\na shard are currently in-sync with the leader. For example, if the write concern\nis `2` and the replication factor is `3`, then the write concern is not fulfilled\nif two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" } }, "summary": "Remove a document", "tags": [ "Documents" ] }, "get": { "description": "Returns the document identified by the collection name and document key.\nThe returned document contains three special attributes:\n- `_id`, containing the document identifier with the format `\u003ccollection-name\u003e/\u003cdocument-key\u003e`.\n- `_key`, containing the document key that uniquely identifies a document within the collection.\n- `_rev`, containing the document revision.\n", "operationId": "getDocument", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Name of the collection from which the document is to be read.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The document key.\n", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "If the `If-None-Match` header is given, then it must contain exactly one\nETag. The document is returned, if it has a different revision than the\ngiven ETag. Otherwise an *HTTP 304* is returned.\n", "in": "header", "name": "If-None-Match", "required": false, "schema": { "type": "string" } }, { "description": "If the `If-Match` header is given, then it must contain exactly one\nETag. The document is returned, if it has the same revision as the\ngiven ETag. Otherwise a *HTTP 412* is returned.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "Set this header to `true` to allow the Coordinator to ask any shard replica for\nthe data, not only the shard leader. This may result in \"dirty reads\".\n\nThe header is ignored if this operation is part of a Stream Transaction\n(`x-arango-trx-id` header). The header set when creating the transaction decides\nabout dirty reads for the entire transaction, not the individual read operations.\n", "in": "header", "name": "x-arango-allow-dirty-read", "required": false, "schema": { "type": "boolean" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The document has been found.\n" }, "304": { "description": "The `If-None-Match` header is specified and the document\nhas the same revision.\n" }, "404": { "description": "The document or collection cannot be found.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "412": { "description": "An `If-Match` header is specified and the found\ndocument has a different revision. The response includes the found\ndocument's current revision in the `_rev` attribute. Additionally, the\n`_id` and `_key` attributes are returned.\n" } }, "summary": "Get a document", "tags": [ "Documents" ] }, "head": { "description": "Like `GET`, but only returns the header fields and not the body. You\ncan use this call to get the current revision of a document or check if\nthe document was deleted.\n", "operationId": "getDocumentHeader", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Name of the `collection` from which the document is to be read.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The document key.\n", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "If the `If-None-Match` header is given, then it must contain exactly one\nETag. If the current document revision is not equal to the specified ETag,\nan *HTTP 200* response is returned. If the current document revision is\nidentical to the specified ETag, then an *HTTP 304* is returned.\n", "in": "header", "name": "If-None-Match", "required": false, "schema": { "type": "string" } }, { "description": "If the `If-Match` header is given, then it must contain exactly one\nETag. The document is returned, if it has the same revision as the\ngiven ETag. Otherwise a *HTTP 412* is returned.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "Set this header to `true` to allow the Coordinator to ask any shard replica for\nthe data, not only the shard leader. This may result in \"dirty reads\".\n\nThe header is ignored if this operation is part of a Stream Transaction\n(`x-arango-trx-id` header). The header set when creating the transaction decides\nabout dirty reads for the entire transaction, not the individual read operations.\n", "in": "header", "name": "x-arango-allow-dirty-read", "required": false, "schema": { "type": "boolean" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The document has been found.\n" }, "304": { "description": "An `If-None-Match` header is specified and the document has\nthe same version.\n" }, "404": { "description": "The document or collection cannot be found.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "412": { "description": "An `If-Match` header is given and the found\ndocument has a different version. The response includes the found\ndocument's current revision in the `ETag` header.\n" } }, "summary": "Get a document header", "tags": [ "Documents" ] }, "patch": { "description": "Partially updates the document identified by the *document ID*.\nThe body of the request must contain a JSON document with the\nattributes to patch (the patch document). All attributes from the\npatch document are added to the existing document if they do not\nyet exist, and overwritten in the existing document if they do exist\nthere.\n\nThe values of the `_key`, `_id`, and `_rev` system attributes as well as\nattributes used as sharding keys cannot be changed.\n\nSetting an attribute value to `null` in the patch document causes a\nvalue of `null` to be saved for the attribute by default.\n\nIf the `If-Match` header is specified and the revision of the\ndocument in the database is unequal to the given revision, the\nprecondition is violated.\n\nIf `If-Match` is not given and `ignoreRevs` is `false` and there\nis a `_rev` attribute in the body and its value does not match\nthe revision of the document in the database, the precondition is\nviolated.\n\nIf a precondition is violated, an *HTTP 412* is returned.\n\nIf the document exists and can be updated, then an *HTTP 201* or\nan *HTTP 202* is returned (depending on `waitForSync`, see below),\nthe `ETag` header field contains the new revision of the document\n(in double quotes) and the `Location` header contains a complete URL\nunder which the document can be queried.\n\nCluster only: The patch document _may_ contain\nvalues for the collection's pre-defined shard keys. Values for the shard keys\nare treated as hints to improve performance. Should the shard keys\nvalues be incorrect ArangoDB may answer with a `not found` error\n\nOptionally, the query parameter `waitForSync` can be used to force\nsynchronization of the updated document operation to disk even in case\nthat the `waitForSync` flag had been disabled for the entire collection.\nThus, the `waitForSync` query parameter can be used to force synchronization\nof just specific operations. To use this, set the `waitForSync` parameter\nto `true`. If the `waitForSync` parameter is not specified or set to\n`false`, then the collection's default `waitForSync` behavior is\napplied. The `waitForSync` query parameter cannot be used to disable\nsynchronization for collections that have a default `waitForSync` value\nof `true`.\n\nUnless `silent` is set to `true`, the body of the response contains a\nJSON object with the following attributes:\n- `_id`, containing the document identifier with the format `\u003ccollection-name\u003e/\u003cdocument-key\u003e`.\n- `_key`, containing the document key that uniquely identifies a document within the collection.\n- `_rev`, containing the new document revision.\n\nIf the query parameter `returnOld` is `true`, then\nthe complete previous revision of the document\nis returned under the `old` attribute in the result.\n\nIf the query parameter `returnNew` is `true`, then\nthe complete new document is returned under\nthe `new` attribute in the result.\n\nIf the document does not exist, then a *HTTP 404* is returned and the\nbody of the response contains an error document.\n", "operationId": "updateDocument", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Name of the `collection` in which the document is to be updated.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The document key.\n", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "If the intention is to delete existing attributes with the patch\ncommand, set the `keepNull` query parameter to `false`. This modifies the\nbehavior of the patch command to remove top-level attributes and sub-attributes\nfrom the existing document that are contained in the patch document with an\nattribute value of `null` (but not attributes of objects that are nested inside\nof arrays).\n", "in": "query", "name": "keepNull", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Controls whether objects (not arrays) are merged if present in\nboth the existing and the patch document. If set to `false`, the\nvalue in the patch document overwrites the existing document's\nvalue. If set to `true`, objects are merged.\n", "in": "query", "name": "mergeObjects", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Wait until document has been synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "If set to `true`, the `_rev` attributes in\nthe given document is ignored. If this is set to `false`, then\nthe `_rev` attribute given in the body document is taken as a\nprecondition. The document is only updated if the current revision\nis the one specified.\n", "in": "query", "name": "ignoreRevs", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to additionally include the complete new document under the\n`new` attribute in the result.\n", "in": "query", "name": "returnNew", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If set to `true`, an empty object is returned as response if the document operation\nsucceeds. No meta-data is returned for the updated document. If the\noperation raises an error, an error object is returned.\n\nYou can use this option to save network traffic.\n", "in": "query", "name": "silent", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to update existing entries in in-memory index caches if document updates\naffect the edge index or cache-enabled persistent indexes.\n", "in": "query", "name": "refillIndexCaches", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "You can use the `versionAttribute` option for external versioning support.\nIf set, the attribute with the name specified by the option is looked up in the\nstored document and the attribute value is compared numerically to the value of\nthe versioning attribute in the supplied document that is supposed to update it.\n\nIf the version number in the new document is higher (rounded down to a whole number)\nthan in the document that already exists in the database, then the update\noperation is performed normally. This is also the case if the new versioning\nattribute has a non-numeric value, if it is a negative number, or if the\nattribute doesn't exist in the supplied or stored document.\n\nIf the version number in the new document is lower or equal to what exists in\nthe database, the operation is not performed and the existing document thus not\nchanged. No error is returned in this case.\n\nThe attribute can only be a top-level attribute.\n\nYou can check if `_oldRev` and `_rev` are different to determine if the\ndocument has been changed.\n", "in": "query", "name": "versionAttribute", "required": false, "schema": { "type": "string" } }, { "description": "You can conditionally update a document based on a target revision id by\nusing the `If-Match` HTTP header.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "A JSON representation of a (partial) document.\n", "type": "object" } } } }, "responses": { "201": { "description": "The document has been updated successfully and\n`waitForSync` was `true`.\n" }, "202": { "description": "The document has been updated successfully and\n`waitForSync` was `false`.\n" }, "400": { "description": "The request body does not contain a valid JSON representation\nof a document. The response body contains\nan error document in this case.\n" }, "403": { "description": "If the error code is `1004`, the specified write concern for the\ncollection cannot be fulfilled. This can happen if less than the number of\nspecified replicas for a shard are currently in-sync with the leader. For example,\nif the write concern is `2` and the replication factor is `3`, then the\nwrite concern is not fulfilled if two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" }, "404": { "description": "The document or collection cannot be found.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "409": { "description": "There are two possible reasons for this error:\n\n- The update causes a unique constraint violation in a secondary index.\n The response body contains an error document with the `errorNum` set to\n `1210` (`ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED`) in this case.\n- Locking the document key or some unique index entry failed due to another\n concurrent operation that operates on the same document. This is also referred\n to as a _write-write conflict_. The response body contains an error document\n with the `errorNum` set to `1200` (`ERROR_ARANGO_CONFLICT`) in this case.\n" }, "410": { "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "412": { "description": "The precondition was violated. The response also contains\nthe found documents' current revisions in the `_rev` attributes.\nAdditionally, the attributes `_id` and `_key` are returned.\n" }, "503": { "description": "The system is temporarily not available. This can be a system\noverload or temporary failure. In this case it makes sense to retry the request\nlater.\n\nIf the error code is `1429`, then the write concern for the collection cannot be\nfulfilled. This can happen if less than the number of specified replicas for\na shard are currently in-sync with the leader. For example, if the write concern\nis `2` and the replication factor is `3`, then the write concern is not fulfilled\nif two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" } }, "summary": "Update a document", "tags": [ "Documents" ] }, "put": { "description": "Replaces the specified document with the one in the body, provided there is\nsuch a document and no precondition is violated.\n\nThe values of the `_key`, `_id`, and `_rev` system attributes as well as\nattributes used as sharding keys cannot be changed.\n\nIf the `If-Match` header is specified and the revision of the\ndocument in the database is unequal to the given revision, the\nprecondition is violated.\n\nIf `If-Match` is not given and `ignoreRevs` is `false` and there\nis a `_rev` attribute in the body and its value does not match\nthe revision of the document in the database, the precondition is\nviolated.\n\nIf a precondition is violated, an *HTTP 412* is returned.\n\nIf the document exists and can be updated, then an *HTTP 201* or\nan *HTTP 202* is returned (depending on `waitForSync`, see below),\nthe `ETag` header field contains the new revision of the document\nand the `Location` header contains a complete URL under which the\ndocument can be queried.\n\nCluster only: The replace documents _may_ contain\nvalues for the collection's pre-defined shard keys. Values for the shard keys\nare treated as hints to improve performance. Should the shard keys\nvalues be incorrect ArangoDB may answer with a *not found* error.\n\nOptionally, the query parameter `waitForSync` can be used to force\nsynchronization of the document replacement operation to disk even in case\nthat the `waitForSync` flag had been disabled for the entire collection.\nThus, the `waitForSync` query parameter can be used to force synchronization\nof just specific operations. To use this, set the `waitForSync` parameter\nto `true`. If the `waitForSync` parameter is not specified or set to\n`false`, then the collection's default `waitForSync` behavior is\napplied. The `waitForSync` query parameter cannot be used to disable\nsynchronization for collections that have a default `waitForSync` value\nof `true`.\n\nUnless `silent` is set to `true`, the body of the response contains a\nJSON object with the following attributes:\n- `_id`, containing the document identifier with the format `\u003ccollection-name\u003e/\u003cdocument-key\u003e`.\n- `_key`, containing the document key that uniquely identifies a document within the collection.\n- `_rev`, containing the new document revision.\n\nIf the query parameter `returnOld` is `true`, then\nthe complete previous revision of the document\nis returned under the `old` attribute in the result.\n\nIf the query parameter `returnNew` is `true`, then\nthe complete new document is returned under\nthe `new` attribute in the result.\n\nIf the document does not exist, then a *HTTP 404* is returned and the\nbody of the response contains an error document.\n", "operationId": "replaceDocument", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Name of the `collection` in which the document is to be replaced.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The document key.\n", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } }, { "description": "Wait until document has been synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "If set to `true`, the `_rev` attributes in\nthe given document is ignored. If this is set to `false`, then\nthe `_rev` attribute given in the body document is taken as a\nprecondition. The document is only replaced if the current revision\nis the one specified.\n", "in": "query", "name": "ignoreRevs", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to additionally include the complete new document under the\n`new` attribute in the result.\n", "in": "query", "name": "returnNew", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If set to `true`, an empty object is returned as response if the document operation\nsucceeds. No meta-data is returned for the replaced document. If the\noperation raises an error, an error object is returned.\n\nYou can use this option to save network traffic.\n", "in": "query", "name": "silent", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to update existing entries in in-memory index caches if documents\nreplacements affect the edge index or cache-enabled persistent indexes.\n", "in": "query", "name": "refillIndexCaches", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "You can use the `versionAttribute` option for external versioning support.\nIf set, the attribute with the name specified by the option is looked up in the\nstored document and the attribute value is compared numerically to the value of\nthe versioning attribute in the supplied document that is supposed to replace it.\n\nIf the version number in the new document is higher (rounded down to a whole number)\nthan in the document that already exists in the database, then the replace\noperation is performed normally. This is also the case if the new versioning\nattribute has a non-numeric value, if it is a negative number, or if the\nattribute doesn't exist in the supplied or stored document.\n\nIf the version number in the new document is lower or equal to what exists in\nthe database, the operation is not performed and the existing document thus not\nchanged. No error is returned in this case.\n\nThe attribute can only be a top-level attribute.\n\nYou can check if `_oldRev` and `_rev` are different to determine if the\ndocument has been changed.\n", "in": "query", "name": "versionAttribute", "required": false, "schema": { "type": "string" } }, { "description": "You can conditionally replace a document based on a target revision id by\nusing the `If-Match` HTTP header.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "A JSON representation of a single document.\n", "type": "object" } } } }, "responses": { "201": { "description": "The document has been replaced successfully and\n`waitForSync` was `true`.\n" }, "202": { "description": "The document has been replaced successfully and\n`waitForSync` was `false`.\n" }, "400": { "description": "The request body does not contain a valid JSON representation\nof a document. The response body contains\nan error document in this case.\n" }, "403": { "description": "If the error code is `1004`, the specified write concern for the\ncollection cannot be fulfilled. This can happen if less than the number of\nspecified replicas for a shard are currently in-sync with the leader. For example,\nif the write concern is `2` and the replication factor is `3`, then the\nwrite concern is not fulfilled if two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" }, "404": { "description": "The collection or the document was not found.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "409": { "description": "There are two possible reasons for this error:\n\n- The replace operation causes a unique constraint violation in a secondary\n index. The response body contains an error document with the `errorNum` set to\n `1210` (`ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED`) in this case.\n- Locking the document key or some unique index entry failed due to another\n concurrent operation that operates on the same document. This is also referred\n to as a _write-write conflict_. The response body contains an error document\n with the `errorNum` set to `1200` (`ERROR_ARANGO_CONFLICT`) in this case.\n" }, "410": { "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "412": { "description": "The precondition is violated. The response includes\nthe found documents' current revisions in the `_rev` attributes.\nAdditionally, the attributes `_id` and `_key` are returned.\n" }, "503": { "description": "The system is temporarily not available. This can be a system\noverload or temporary failure. In this case it makes sense to retry the request\nlater.\n\nIf the error code is `1429`, then the write concern for the collection cannot be\nfulfilled. This can happen if less than the number of specified replicas for\na shard are currently in-sync with the leader. For example, if the write concern\nis `2` and the replication factor is `3`, then the write concern is not fulfilled\nif two replicas are not in-sync.\n\nNote that the HTTP status code is configurable via the\n`--cluster.failed-write-concern-status-code` startup option. It defaults to `403`\nbut can be changed to `503` to signal client applications that it is a\ntemporary error.\n" } }, "summary": "Replace a document", "tags": [ "Documents" ] } }, "/_db/{database-name}/_api/edges/{collection}": { "get": { "description": "Returns an array of edges starting or ending in the node identified by\n`vertex`.\n", "operationId": "getVertexEdges", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the edge collection you want to retrieve edges from.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The document identifier of the start node.\n", "in": "query", "name": "vertex", "required": true, "schema": { "type": "string" } }, { "description": "- `\"in\"`: Return edges that reference the `vertex` in the `_to` attribute.\n- `\"out\"`: Return edges that reference the `vertex` in the `_from` attribute.\n- `\"any\"`: Return edges that reference the `vertex` in the `_from` or `_to` attribute.\n", "in": "query", "name": "direction", "required": false, "schema": { "default": "any", "enum": [ "any", "in", "out" ], "type": "string" } }, { "description": "Set this header to `true` to allow the Coordinator to ask any shard replica for\nthe data, not only the shard leader. This may result in \"dirty reads\".\n", "in": "header", "name": "x-arango-allow-dirty-read", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "is returned if the edge collection was found and edges were retrieved.\n" }, "400": { "description": "is returned if the request contains invalid parameters.\n" }, "404": { "description": "is returned if the edge collection was not found.\n" } }, "summary": "Get inbound and outbound edges", "tags": [ "Graphs" ] } }, "/_db/{database-name}/_api/engine": { "get": { "description": "Returns the storage engine the server is configured to use.\n", "operationId": "getEngine", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "Always `rocksdb`.\n", "type": "string" } }, "required": [ "name" ], "type": "object" } } }, "description": "Successfully retrieved storage engine name.\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Missing read access to the given database.\n" } }, "summary": "Get the storage engine type", "tags": [ "Administration" ] } }, "/_db/{database-name}/_api/engine/stats": { "get": { "description": "Returns detailed statistics related to the RocksDB storage engine activity,\nincluding figures about data size, cache usage, individual column families, etc.\n", "operationId": "getEngineStats", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database. If the `--server.harden` startup option is enabled,\nadministrate access to the `_system` database is required.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "A plethora of information about RocksDB.\n", "type": "object" } } }, "description": "Successfully retrieved the storage engine statistics.\n" }, "401": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 401, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The user account you authenticated with lacks read access to the\nspecified database, the credentials are wrong, or the user account\nis inactive.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `--server.harden` startup option is enabled but the user account\nyou authenticated with lacks write access to the `_system` database.\n" } }, "summary": "Get the storage engine statistics", "tags": [ "Administration" ] } }, "/_db/{database-name}/_api/explain": { "post": { "description": "To explain how an AQL query would be executed on the server, the query string\ncan be sent to the server via an HTTP POST request. The server will then validate\nthe query and create an execution plan for it. The execution plan will be\nreturned, but the query will not be executed.\n\nThe execution plan that is returned by the server can be used to estimate the\nprobable performance of the query. Though the actual performance will depend\non many different factors, the execution plan normally can provide some rough\nestimates on the amount of work the server needs to do in order to actually run\nthe query.\n\nBy default, the explain operation will return the optimal plan as chosen by\nthe query optimizer The optimal plan is the plan with the lowest total estimated\ncost. The plan will be returned in the attribute `plan` of the response object.\nIf the option `allPlans` is specified in the request, the result will contain\nall plans created by the optimizer. The plans will then be returned in the\nattribute `plans`.\n\nThe result will also contain an attribute `warnings`, which is an array of\nwarnings that occurred during optimization or execution plan creation. Additionally,\na `stats` attribute is contained in the result with some optimizer statistics.\nIf `allPlans` is set to `false`, the result will contain an attribute `cacheable`\nthat states whether the query results can be cached on the server if the query\nresult cache were used. The `cacheable` attribute is not present when `allPlans`\nis set to `true`.\n\nEach plan in the result is a JSON object with the following attributes:\n- `nodes`: the array of execution nodes of the plan.\n\n- `estimatedCost`: the total estimated cost for the plan. If there are multiple\n plans, the optimizer will choose the plan with the lowest total cost.\n\n- `collections`: an array of collections used in the query\n\n- `rules`: an array of rules the optimizer applied.\n\n- `variables`: array of variables used in the query (note: this may contain\n internal variables created by the optimizer)\n", "operationId": "explainAqlQuery", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "bindVars": { "description": "An object with key/value pairs representing the bind parameters.\nFor a bind variable `@var` in the query, specify the value using an attribute\nwith the name `var`. For a collection bind variable `@@coll`, use `@coll` as the\nattribute name. For example: `\"bindVars\": { \"var\": 42, \"@coll\": \"products\" }`.\n", "type": "object" }, "options": { "description": "Options for the query\n", "properties": { "allPlans": { "default": false, "description": "If set to `true`, all possible execution plans are returned.\nThe default is `false`, meaning only the optimal plan is returned.\n", "type": "boolean" }, "failOnWarning": { "description": "If set to `true`, the query throws an exception and aborts instead of producing\na warning. You should use this option during development to catch potential issues\nearly. When the attribute is set to `false`, warnings are not propagated to\nexceptions and are returned with the query result.\n\nDefault: Controlled by the [`--query.fail-on-warning` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--queryfail-on-warning),\nso you don't need to set it on a per-query basis.\n", "type": "boolean" }, "fullCount": { "default": false, "description": "Whether to calculate the total number of documents matching the\nfilter conditions as if the query's final top-level `LIMIT` operation\nwere not applied. This option generally leads to different\nexecution plans.\n", "type": "boolean" }, "maxNodesPerCallstack": { "description": "The number of execution nodes in the query plan after that stack splitting is\nperformed to avoid a potential stack overflow.\n\nThis option is only useful for testing and debugging and normally does not need\nany adjustment.\n\nDefault: Controlled by the [`--query.max-nodes-per-callstack` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querymax-nodes-per-callstack).\n", "type": "integer" }, "maxNumberOfPlans": { "description": "The maximum number of plans that the optimizer is allowed to\ngenerate. Setting this attribute to a low value allows you to put a\ncap on the amount of work the optimizer does.\n\nDefault: Controlled by the [`--query.optimizer-max-plans` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--queryoptimizer-max-plans).\n", "type": "integer" }, "maxWarningCount": { "default": 10, "description": "Limits the number of warnings a query can return.\nYou can increased or decreased the number with this option.\n", "type": "integer" }, "optimizer": { "description": "Options related to the query optimizer.\n", "properties": { "rules": { "description": "A list of optimizer rules, telling the optimizer to\ninclude or exclude specific rules. See the\n[List of optimizer rules](https://docs.arango.ai/arangodb/3.12/aql/execution-and-performance/query-optimization/#list-of-optimizer-rules).\n\nTo disable a rule, prefix its name with `-`. To enable a rule,\nprefix it with `+`. There is also a pseudo-rule `all` that\nmatches all optimizer rules. `-all` disables all rules.\n", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "profile": { "default": 0, "description": "Whether to include additional query profiling information.\nIf set to `2`, the response includes the time it took to process\neach optimizer rule under `stats.rules`.\n", "type": "integer" }, "usePlanCache": { "default": false, "description": "Set this option to `true` to utilize a cached query plan or add the execution plan\nof this query to the cache if it's not in the cache yet. Otherwise, the plan cache\nis bypassed (introduced in v3.12.4).\n\nQuery plan caching can reduce the total time for processing queries by avoiding\nto parse, plan, and optimize queries over and over again that effectively have\nthe same execution plan with at most some changes to bind parameter values.\n\nAn error is raised if a query doesn't meet the requirements for plan caching.\nSee [Cache eligibility](https://docs.arango.ai/arangodb/3.12/aql/execution-and-performance/caching-query-plans/#cache-eligibility)\nfor details.\n", "type": "boolean" } }, "type": "object" }, "query": { "description": "the query which you want explained; If the query references any bind variables,\nthese must also be passed in the attribute `bindVars`. Additional\noptions for the query can be passed in the `options` attribute.\n", "type": "string" } }, "required": [ "query" ], "type": "object" } } } }, "responses": { "200": { "description": "If the query is valid, the server will respond with *HTTP 200* and\nreturn the optimal execution plan in the `plan` attribute of the response.\nIf option `allPlans` was set in the request, an array of plans will be returned\nin the `allPlans` attribute instead.\n" }, "400": { "description": "The request is malformed or the query contains a parse error.\nThe body of the response contains the error details embedded in a JSON object.\nOmitting bind variables if the query references any also results\nan error.\n" }, "404": { "description": "A non-existing collection is accessed in the query.\n" } }, "summary": "Explain an AQL query", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/foxx": { "get": { "deprecated": true, "description": "Fetches a list of services installed in the current database.\n\nReturns a list of objects with the following attributes:\n\n- `mount`: the mount path of the service\n- `development`: `true` if the service is running in development mode\n- `legacy`: `true` if the service is running in 2.8 legacy compatibility mode\n- `provides`: the service manifest's `provides` value or an empty object\n\nAdditionally the object may contain the following attributes if they have been set on the manifest:\n\n- `name`: a string identifying the service type\n- `version`: a semver-compatible version string\n", "operationId": "listFoxxServices", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Whether or not system services should be excluded from the result.\n", "in": "query", "name": "excludeSystem", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "List the installed services", "tags": [ "Foxx" ] }, "post": { "deprecated": true, "description": "Installs the given new service at the given mount path.\n\nThe request body can be any of the following formats:\n\n- `application/zip`: a raw zip bundle containing a service\n- `application/javascript`: a standalone JavaScript file\n- `application/json`: a service definition as JSON\n- `multipart/form-data`: a service definition as a multipart form\n\nA service definition is an object or form with the following properties or fields:\n\n- `configuration`: a JSON object describing configuration values\n- `dependencies`: a JSON object describing dependency settings\n- `source`: a fully qualified URL or an absolute path on the server's file system\n\nWhen using multipart data, the `source` field can also alternatively be a file field\ncontaining either a zip bundle or a standalone JavaScript file.\n\nWhen using a standalone JavaScript file the given file will be executed\nto define our service's HTTP endpoints. It is the same which would be defined\nin the field `main` of the service manifest.\n\nIf `source` is a URL, the URL must be reachable from the server.\nIf `source` is a file system path, the path will be resolved on the server.\nIn either case the path or URL is expected to resolve to a zip bundle,\nJavaScript file or (in case of a file system path) directory.\n\nNote that when using file system paths in a cluster with multiple Coordinators\nthe file system path must resolve to equivalent files on every Coordinator.\n", "operationId": "createFoxxService", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path the service should be installed at.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } }, { "description": "Set to `true` to enable development mode.\n", "in": "query", "name": "development", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Set to `false` to not run the service's setup script.\n", "in": "query", "name": "setup", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Set to `true` to install the service in 2.8 legacy compatibility mode.\n", "in": "query", "name": "legacy", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "201": { "description": "Returned if the request was successful.\n" } }, "summary": "Install a new service", "tags": [ "Foxx" ] } }, "/_db/{database-name}/_api/foxx/commit": { "post": { "deprecated": true, "description": "Commits the local service state of the Coordinator to the database.\n\nThis can be used to resolve service conflicts between Coordinators that cannot be fixed automatically due to missing data.\n", "operationId": "commitFoxxServiceState", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Overwrite existing service files in database even if they already exist.\n", "in": "query", "name": "replace", "required": false, "schema": { "type": "boolean" } } ], "responses": { "204": { "description": "Returned if the request was successful.\n" } }, "summary": "Commit the local service state", "tags": [ "Foxx" ] } }, "/_db/{database-name}/_api/foxx/configuration": { "get": { "deprecated": true, "description": "Fetches the current configuration for the service at the given mount path.\n\nReturns an object mapping the configuration option names to their definitions\nincluding a human-friendly `title` and the `current` value (if any).\n", "operationId": "getFoxxConfiguration", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "Get the configuration options", "tags": [ "Foxx" ] }, "patch": { "deprecated": true, "description": "Replaces the given service's configuration partially.\n\nReturns an object mapping all configuration option names to their new values.\n", "operationId": "updateFoxxConfiguration", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "A JSON object, mapping configuration option names to their new values.\nAny omitted options will be ignored.\n", "type": "object" } } } }, "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "Update the configuration options", "tags": [ "Foxx" ] }, "put": { "deprecated": true, "description": "Replaces the given service's configuration completely.\n\nReturns an object mapping all configuration option names to their new values.\n", "operationId": "replaceFoxxConfiguration", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "A JSON object, mapping configuration option names to their new values.\nAny omitted options will be reset to their default values or marked as unconfigured.\n", "type": "object" } } } }, "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "Replace the configuration options", "tags": [ "Foxx" ] } }, "/_db/{database-name}/_api/foxx/dependencies": { "get": { "deprecated": true, "description": "Fetches the current dependencies for service at the given mount path.\n\nReturns an object mapping the dependency names to their definitions\nincluding a human-friendly `title` and the `current` mount path (if any).\n", "operationId": "getFoxxDependencies", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "Get the dependency options", "tags": [ "Foxx" ] }, "patch": { "deprecated": true, "description": "Replaces the given service's dependencies.\n\nReturns an object mapping all dependency names to their new mount paths.\n", "operationId": "updateFoxxDependencies", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "options": { "description": "A JSON object mapping dependency names to their new mount paths.\nAny omitted dependencies will be ignored.\n", "type": "object" } }, "required": [ "options" ], "type": "object" } } } }, "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "Update the dependency options", "tags": [ "Foxx" ] }, "put": { "deprecated": true, "description": "Replaces the given service's dependencies completely.\n\nReturns an object mapping all dependency names to their new mount paths.\n", "operationId": "replaceFoxxDependencies", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "options": { "description": "A JSON object mapping dependency names to their new mount paths.\nAny omitted dependencies will be disabled.\n", "type": "object" } }, "required": [ "options" ], "type": "object" } } } }, "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "Replace the dependency options", "tags": [ "Foxx" ] } }, "/_db/{database-name}/_api/foxx/development": { "delete": { "deprecated": true, "description": "Puts the service at the given mount path into production mode.\n\nWhen running ArangoDB in a cluster with multiple Coordinators this will\nreplace the service on all other Coordinators with the version on this\nCoordinator.\n", "operationId": "disableFoxxDevelopmentMode", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "Disable the development mode", "tags": [ "Foxx" ] }, "post": { "deprecated": true, "description": "Puts the service into development mode.\n\nWhile the service is running in development mode the service will be reloaded\nfrom the filesystem and its setup script (if any) will be re-executed every\ntime the service handles a request.\n\nWhen running ArangoDB in a cluster with multiple Coordinators note that changes\nto the filesystem on one Coordinator will not be reflected across the other\nCoordinators. This means you should treat your Coordinators as inconsistent\nas long as any service is running in development mode.\n", "operationId": "enableFoxxDevelopmentMode", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "Enable the development mode", "tags": [ "Foxx" ] } }, "/_db/{database-name}/_api/foxx/download": { "post": { "deprecated": true, "description": "Downloads a zip bundle of the service directory.\n\nWhen development mode is enabled, this always creates a new bundle.\n\nOtherwise the bundle will represent the version of a service that\nis installed on that ArangoDB instance.\n", "operationId": "downloadFoxxService", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the request was successful.\n" }, "400": { "description": "Returned if the mount path is unknown.\n" } }, "summary": "Download a service bundle", "tags": [ "Foxx" ] } }, "/_db/{database-name}/_api/foxx/readme": { "get": { "deprecated": true, "description": "Fetches the service's README or README.md file's contents if any.\n", "operationId": "getFoxxReadme", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the request was successful.\n" }, "204": { "description": "Returned if no README file was found.\n" } }, "summary": "Get the service README", "tags": [ "Foxx" ] } }, "/_db/{database-name}/_api/foxx/scripts": { "get": { "deprecated": true, "description": "Fetches a list of the scripts defined by the service.\n\nReturns an object mapping the raw script names to human-friendly names.\n", "operationId": "listFoxxScripts", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "List the service scripts", "tags": [ "Foxx" ] } }, "/_db/{database-name}/_api/foxx/scripts/{name}": { "post": { "deprecated": true, "description": "Runs the given script for the service at the given mount path.\n\nReturns the exports of the script, if any.\n", "operationId": "runFoxxScript", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Name of the script to run.\n", "in": "path", "name": "name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "An arbitrary JSON value that will be parsed and passed to the\nscript as its first argument.\n" } } } }, "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "Run a service script", "tags": [ "Foxx" ] } }, "/_db/{database-name}/_api/foxx/service": { "delete": { "deprecated": true, "description": "Removes the service at the given mount path from the database and file system.\n\nReturns an empty response on success.\n", "operationId": "deleteFoxxService", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } }, { "description": "Set to `false` to not run the service's teardown script.\n", "in": "query", "name": "teardown", "required": false, "schema": { "default": true, "type": "boolean" } } ], "responses": { "204": { "description": "Returned if the request was successful.\n" } }, "summary": "Uninstall a service", "tags": [ "Foxx" ] }, "get": { "deprecated": true, "description": "Fetches detailed information for the service at the given mount path.\n\nReturns an object with the following attributes:\n\n- `mount`: the mount path of the service\n- `path`: the local file system path of the service\n- `development`: `true` if the service is running in development mode\n- `legacy`: `true` if the service is running in 2.8 legacy compatibility mode\n- `manifest`: the normalized JSON manifest of the service\n\nAdditionally the object may contain the following attributes if they have been set on the manifest:\n\n- `name`: a string identifying the service type\n- `version`: a semver-compatible version string\n", "operationId": "getFoxxServiceDescription", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the request was successful.\n" }, "400": { "description": "Returned if the mount path is unknown.\n" } }, "summary": "Get the service description", "tags": [ "Foxx" ] }, "patch": { "deprecated": true, "description": "Installs the given new service on top of the service currently installed at the given mount path.\nThis is only recommended for switching between different versions of the same service.\n\nUnlike replacing a service, upgrading a service retains the old service's configuration\nand dependencies (if any) and should therefore only be used to migrate an existing service\nto a newer or equivalent service.\n\nThe request body can be any of the following formats:\n\n- `application/zip`: a raw zip bundle containing a service\n- `application/javascript`: a standalone JavaScript file\n- `application/json`: a service definition as JSON\n- `multipart/form-data`: a service definition as a multipart form\n\nA service definition is an object or form with the following properties or fields:\n\n- `configuration`: a JSON object describing configuration values\n- `dependencies`: a JSON object describing dependency settings\n- `source`: a fully qualified URL or an absolute path on the server's file system\n\nWhen using multipart data, the `source` field can also alternatively be a file field\ncontaining either a zip bundle or a standalone JavaScript file.\n\nWhen using a standalone JavaScript file the given file will be executed\nto define our service's HTTP endpoints. It is the same which would be defined\nin the field `main` of the service manifest.\n\nIf `source` is a URL, the URL must be reachable from the server.\nIf `source` is a file system path, the path will be resolved on the server.\nIn either case the path or URL is expected to resolve to a zip bundle,\nJavaScript file or (in case of a file system path) directory.\n\nNote that when using file system paths in a cluster with multiple Coordinators\nthe file system path must resolve to equivalent files on every Coordinator.\n", "operationId": "upgradeFoxxService", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } }, { "description": "Set to `true` to run the old service's teardown script.\n", "in": "query", "name": "teardown", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Set to `false` to not run the new service's setup script.\n", "in": "query", "name": "setup", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Set to `true` to install the new service in 2.8 legacy compatibility mode.\n", "in": "query", "name": "legacy", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Set to `true` to force service install even if no service is installed under given mount.\n", "in": "query", "name": "force", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "Upgrade a service", "tags": [ "Foxx" ] }, "put": { "deprecated": true, "description": "Removes the service at the given mount path from the database and file system.\nThen installs the given new service at the same mount path.\n\nThis is a slightly safer equivalent to performing an uninstall of the old service\nfollowed by installing the new service. The new service's main and script files\n(if any) will be checked for basic syntax errors before the old service is removed.\n\nThe request body can be any of the following formats:\n\n- `application/zip`: a raw zip bundle containing a service\n- `application/javascript`: a standalone JavaScript file\n- `application/json`: a service definition as JSON\n- `multipart/form-data`: a service definition as a multipart form\n\nA service definition is an object or form with the following properties or fields:\n\n- `configuration`: a JSON object describing configuration values\n- `dependencies`: a JSON object describing dependency settings\n- `source`: a fully qualified URL or an absolute path on the server's file system\n\nWhen using multipart data, the `source` field can also alternatively be a file field\ncontaining either a zip bundle or a standalone JavaScript file.\n\nWhen using a standalone JavaScript file the given file will be executed\nto define our service's HTTP endpoints. It is the same which would be defined\nin the field `main` of the service manifest.\n\nIf `source` is a URL, the URL must be reachable from the server.\nIf `source` is a file system path, the path will be resolved on the server.\nIn either case the path or URL is expected to resolve to a zip bundle,\nJavaScript file or (in case of a file system path) directory.\n\nNote that when using file system paths in a cluster with multiple Coordinators\nthe file system path must resolve to equivalent files on every Coordinator.\n", "operationId": "replaceFoxxService", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } }, { "description": "Set to `false` to not run the old service's teardown script.\n", "in": "query", "name": "teardown", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Set to `false` to not run the new service's setup script.\n", "in": "query", "name": "setup", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Set to `true` to install the new service in 2.8 legacy compatibility mode.\n", "in": "query", "name": "legacy", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Set to `true` to force service install even if no service is installed under given mount.\n", "in": "query", "name": "force", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "Replace a service", "tags": [ "Foxx" ] } }, "/_db/{database-name}/_api/foxx/swagger": { "get": { "deprecated": true, "description": "Fetches the Swagger API description for the service at the given mount path.\n\nThe response body will be an OpenAPI 2.0 compatible JSON description of the service API.\n", "operationId": "getFoxxSwaggerDescription", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "Get the Swagger description", "tags": [ "Foxx" ] } }, "/_db/{database-name}/_api/foxx/tests": { "post": { "deprecated": true, "description": "Runs the tests for the service at the given mount path and returns the results.\n\nSupported test reporters are:\n\n- `default`: a simple list of test cases\n- `suite`: an object of test cases nested in suites\n- `stream`: a raw stream of test results\n- `xunit`: an XUnit/JUnit compatible structure\n- `tap`: a raw TAP compatible stream\n\nThe `Accept` request header can be used to further control the response format:\n\nWhen using the `stream` reporter `application/x-ldjson` will result\nin the response body being formatted as a newline-delimited JSON stream.\n\nWhen using the `tap` reporter `text/plain` or `text/*` will result\nin the response body being formatted as a plain text TAP report.\n\nWhen using the `xunit` reporter `application/xml` or `text/xml` will result\nin the response body being formatted as XML instead of JSONML.\n\nOtherwise the response body will be formatted as non-prettyprinted JSON.\n", "operationId": "runFoxxTests", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Mount path of the installed service.\n", "in": "query", "name": "mount", "required": true, "schema": { "type": "string" } }, { "description": "Test reporter to use.\n", "in": "query", "name": "reporter", "required": false, "schema": { "type": "string" } }, { "description": "Use the matching format for the reporter, regardless of the `Accept` header.\n", "in": "query", "name": "idiomatic", "required": false, "schema": { "type": "boolean" } }, { "description": "Only run tests where the full name (including full test suites and test case)\nmatches this string.\n", "in": "query", "name": "filter", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the request was successful.\n" } }, "summary": "Run the service tests", "tags": [ "Foxx" ] } }, "/_db/{database-name}/_api/gharial": { "get": { "description": "Lists all graphs stored in this database.\n", "operationId": "listGraphs", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graphs": { "description": "A list of all named graphs.\n", "items": { "properties": { "graph": { "description": "The properties of the named graph.\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n\nDefault: The `replicationFactor` defined by the database.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "type": "object" }, "type": "array" } }, "required": [ "error", "code", "graphs" ], "type": "object" } } }, "description": "Is returned if the module is available and the graphs can be listed.\n" } }, "summary": "List all graphs", "tags": [ "Graphs" ] }, "post": { "description": "The creation of a graph requires the name of the graph and a\ndefinition of its edges.\n", "operationId": "createGraph", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Define if the request should wait until everything is synced to disk.\nChanges the success HTTP response status code.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "A list of node collection names.\nEdges you later insert into `collection` can only reference nodes\nfrom these collections in their `_from` attribute (if you use the\ninterface for named graphs).\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "A list of node collection names.\nEdges you later insert into `collection` can only reference nodes\nfrom these collections in their `_to` attribute (if you use the\ninterface for named graphs).\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "default": false, "description": "Whether to create a Disjoint SmartGraph instead of a regular SmartGraph.\n", "type": "boolean" }, "isSmart": { "default": false, "description": "Define if the created graph should be smart.\n- Setting `options.smartGraphAttribute` creates a SmartGraph (`isSmart` is automatically `true`).\n- Setting `isSmart` to `true` but no `options.smartGraphAttribute` creates an EnterpriseGraph.\n", "type": "boolean" }, "name": { "description": "Name of the graph.\n", "type": "string" }, "options": { "description": "Options for creating collections within this graph.\nIt can contain the following attributes:\n", "properties": { "numberOfShards": { "default": 1, "description": "The number of shards that is used for every collection within this graph.\nCannot be modified later.\n", "type": "integer" }, "replicationFactor": { "description": "The replication factor used when initially creating collections for this graph.\nCan be set to `\"satellite\"` to create a SatelliteGraph, which then ignores\n`numberOfShards`, `minReplicationFactor`, and `writeConcern`.\n\nDefault: The `replicationFactor` defined by the database.\n", "type": "integer" }, "satellites": { "description": "An array of collection names that is used to create SatelliteCollections\nfor a (Disjoint) SmartGraph using SatelliteCollections.\nEach array element must be a string and a valid collection name.\nThe collection type cannot be modified later.\n", "items": { "type": "string" }, "type": "array" }, "smartGraphAttribute": { "description": "Setting this option creates a SmartGraph.\n\nThe attribute name that is used to smartly shard the nodes of a graph.\nEvery node in this SmartGraph has to have this attribute.\nCannot be modified later.\n", "type": "string" }, "writeConcern": { "description": "Write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "type": "object" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "name" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 201, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graph": { "description": "The information about the newly created graph.\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "required": [ "error", "code", "graph" ], "type": "object" } } }, "description": "Is returned if the graph can be created and `waitForSync` is enabled\nfor the `_graphs` collection, or given in the request.\nThe response body contains the graph configuration that has been stored.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graph": { "description": "The information about the newly created graph.\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "required": [ "error", "code", "graph" ], "type": "object" } } }, "description": "Is returned if the graph can be created and `waitForSync` is disabled\nfor the `_graphs` collection and not given in the request.\nThe response body contains the graph configuration that has been stored.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if the request is in a wrong format.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to create a graph, you need to have at least the following privileges:\n- `Administrate` access on the database.\n- `Read Only` access on every collection used within this graph.\n" }, "409": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 409, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if there is a conflict storing the graph. This can occur\neither if a graph with this name already exists, or if there is an\nedge definition with the same edge collection but different `from`\nand `to` node collections in any other graph.\n" } }, "summary": "Create a graph", "tags": [ "Graphs" ] } }, "/_db/{database-name}/_api/gharial/{graph}": { "delete": { "description": "Drops an existing graph object by name.\nOptionally all collections not used by other graphs\ncan be dropped as well.\n", "operationId": "deleteGraph", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "Drop the collections of this graph as well. Collections are only\ndropped if they are not used in other graphs.\n", "in": "query", "name": "dropCollections", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "removed": { "description": "Always `true`.\n", "example": true, "type": "boolean" } }, "required": [ "error", "code", "removed" ], "type": "object" } } }, "description": "Is returned if the graph can be dropped.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to drop a graph, you need to have at least the following privileges:\n- `Administrate` access on the database.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if no graph with this name can be found.\n" } }, "summary": "Drop a graph", "tags": [ "Graphs" ] }, "get": { "description": "Selects information for a given graph.\nReturns the edge definitions as well as the orphan collections,\nor returns an error if the graph does not exist.\n", "operationId": "getGraph", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graph": { "description": "The information about the newly created graph\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "required": [ "error", "code", "graph" ], "type": "object" } } }, "description": "Returns the graph if it can be found.\nThe result has the following format:\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if no graph with this name can be found.\n" } }, "summary": "Get a graph", "tags": [ "Graphs" ] } }, "/_db/{database-name}/_api/gharial/{graph}/edge": { "get": { "description": "Lists all edge collections within this graph.\n", "operationId": "listEdgeCollections", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "collections": { "description": "A list of all edge collections used in the edge definitions\nof this graph.\n", "items": { "type": "string" }, "type": "array" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" } }, "required": [ "error", "code", "collections" ], "type": "object" } } }, "description": "Is returned if the edge definitions can be listed.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if no graph with this name can be found.\n" } }, "summary": "List edge collections", "tags": [ "Graphs" ] }, "post": { "description": "Adds an additional edge definition to the graph.\n\nThis edge definition has to contain a `collection` and an array of\neach `from` and `to` node collections. An edge definition can only\nbe added if this definition is either not used in any other graph, or\nit is used with exactly the same definition. For example, it is not\npossible to store a definition \"e\" from \"v1\" to \"v2\" in one graph, and\n\"e\" from \"v2\" to \"v1\" in another graph, but both can have \"e\" from\n\"v1\" to \"v2\".\n\nAdditionally, collection creation options can be set.\n", "operationId": "createEdgeDefinition", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "collection": { "description": "The name of the edge collection to be used.\n", "type": "string" }, "from": { "description": "One or many node collections that can contain source nodes.\n", "items": { "type": "string" }, "type": "array" }, "options": { "description": "A JSON object to set options for creating collections within this\nedge definition.\n", "properties": { "satellites": { "description": "An array of collection names that is used to create SatelliteCollections\nfor a (Disjoint) SmartGraph using SatelliteCollections.\nEach array element must be a string and a valid collection name.\nThe collection type cannot be modified later.\n", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "to": { "description": "One or many node collections that can contain target nodes.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 201, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graph": { "description": "The information about the modified graph.\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "required": [ "error", "code", "graph" ], "type": "object" } } }, "description": "Returned if the definition can be added successfully and\n`waitForSync` is enabled for the `_graphs` collection.\nThe response body contains the graph configuration that has been stored.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graph": { "description": "The information about the modified graph.\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "required": [ "error", "code", "graph" ], "type": "object" } } }, "description": "Returned if the definition can be added successfully and\n`waitForSync` is disabled for the `_graphs` collection.\nThe response body contains the graph configuration that has been stored.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if the edge definition can not be added.\nThis can be because it is ill-formed, or if there is an\nedge definition with the same edge collection but different `from`\nand `to` node collections in any other graph.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to modify a graph, you need to have at least the following privileges:\n- `Administrate` access on the database.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if no graph with this name can be found.\n" } }, "summary": "Add an edge definition", "tags": [ "Graphs" ] } }, "/_db/{database-name}/_api/gharial/{graph}/edge/{collection}": { "delete": { "description": "Remove one edge definition from the graph. This only removes the\nedge collection from the graph definition. The node collections of the\nedge definition become orphan collections but otherwise remain untouched\nand can still be used in your queries.\n", "operationId": "deleteEdgeDefinition", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "The name of the edge collection used in the edge definition.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "Define if the request should wait until synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Drop the edge collection in addition to removing it from the graph.\nThe collection is only dropped if it is not used in other graphs.\n", "in": "query", "name": "dropCollections", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 201, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graph": { "description": "The information about the modified graph.\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "required": [ "error", "code", "graph" ], "type": "object" } } }, "description": "Returned if the edge definition can be removed from the graph\nand `waitForSync` is `true`.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graph": { "description": "The information about the modified graph.\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "required": [ "error", "code", "graph" ], "type": "object" } } }, "description": "Returned if the edge definition can be removed from the graph and\n`waitForSync` is `false`.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to drop a node, you need to have at least the following privileges:\n- `Administrate` access on the database.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if no graph with this name can be found,\nor if no edge definition with this name is found in the graph.\n" } }, "summary": "Remove an edge definition", "tags": [ "Graphs" ] }, "post": { "description": "Creates a new edge in the specified collection.\nWithin the body the edge has to contain a `_from` and `_to` value referencing to valid nodes in the graph.\nFurthermore, the edge has to be valid according to the edge definitions.\n", "operationId": "createEdge", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "The name of the edge collection the edge belongs to.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "Define if the request should wait until synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Whether to additionally include the complete new document under the\n`new` attribute in the result.\n", "in": "query", "name": "returnNew", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The body has to be a JSON object you want to store as an edge document.\n", "properties": { "_from": { "description": "The source node of this edge. Has to be valid within\nthe used edge definition.\n", "type": "string" }, "_to": { "description": "The target node of this edge. Has to be valid within\nthe used edge definition.\n", "type": "string" } }, "required": [ "_from", "_to" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 201, "type": "integer" }, "edge": { "description": "The internal attributes for the edge.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "new": { "description": "The complete newly written edge document.\nIncludes all written attributes in the request body\nand all internal attributes generated by ArangoDB.\nOnly present if `returnNew` is `true`.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" } }, "required": [ "error", "code", "edge" ], "type": "object" } } }, "description": "Returned if the edge can be created and `waitForSync` is `true`.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "edge": { "description": "The internal attributes for the edge.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "new": { "description": "The complete newly written edge document.\nIncludes all written attributes in the request body\nand all internal attributes generated by ArangoDB.\nOnly present if `returnNew` is `true`.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" } }, "required": [ "error", "code", "edge" ], "type": "object" } } }, "description": "Returned if the request was successful but `waitForSync` is `false`.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if the input document is invalid.\nThis can for instance be the case if the `_from` or `_to` attribute is missing\nor malformed.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to insert edges into the graph, you need to have at least the following privileges:\n- `Read Only` access on the database.\n- `Write` access on the given collection.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned in any of the following cases:\n- The graph cannot be found.\n- The edge collection is not part of the graph.\n- The node collection referenced in the `_from` or `_to` attribute is not part of the graph.\n- The node collection is part of the graph, but does not exist.\n- `_from` or `_to` node does not exist.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 410, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" } }, "summary": "Create an edge", "tags": [ "Graphs" ] }, "put": { "description": "Change the node collections of one specific edge definition.\nThis modifies all occurrences of this definition in all graphs known to your database.\n", "operationId": "replaceEdgeDefinition", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "The name of the edge collection used in the edge definition.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "Define if the request should wait until synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Drop the edge collection in addition to removing it from the graph.\nThe collection is only dropped if it is not used in other graphs.\n", "in": "query", "name": "dropCollections", "required": false, "schema": { "default": false, "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "collection": { "description": "The name of the edge collection to modify.\n", "type": "string" }, "from": { "description": "One or many node collections that can contain source nodes.\n", "items": { "type": "string" }, "type": "array" }, "options": { "description": "A JSON object to set options for modifying collections within this\nedge definition.\n", "properties": { "satellites": { "description": "An array of collection names that is used to create SatelliteCollections\nfor a (Disjoint) SmartGraph using SatelliteCollections.\nEach array element must be a string and a valid collection name.\nThe collection type cannot be modified later.\n", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "to": { "description": "One or many node collections that can contain target nodes.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 201, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graph": { "description": "The information about the modified graph.\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "required": [ "error", "code", "graph" ], "type": "object" } } }, "description": "Returned if the request was successful and `waitForSync` is `true`.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graph": { "description": "The information about the modified graph.\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "required": [ "error", "code", "graph" ], "type": "object" } } }, "description": "Returned if the request was successful but `waitForSync` is `false`.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if the new edge definition is ill-formed and cannot be used.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to drop a node, you need to have at least the following privileges:\n- `Administrate` access on the database.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if no graph with this name can be found, or if no edge definition\nwith this name is found in the graph.\n" } }, "summary": "Replace an edge definition", "tags": [ "Graphs" ] } }, "/_db/{database-name}/_api/gharial/{graph}/edge/{collection}/{edge}": { "delete": { "description": "Removes an edge from an edge collection of the named graph. Any other edges\nthat directly reference this edge like a node are removed, too.\n", "operationId": "deleteEdge", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "The name of the edge collection the edge belongs to.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The `_key` attribute of the edge.\n", "in": "path", "name": "edge", "required": true, "schema": { "type": "string" } }, { "description": "Define if the request should wait until synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If you provide an `If-Match` header, it must contain exactly one ETag.\nThe document is deleted if it has the same revision as the given ETag.\nOtherwise, an error with HTTP status code 412 is returned.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "old": { "description": "The complete deleted edge document.\nIncludes all attributes stored before this operation.\nOnly present if `returnOld` is `true`.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" }, "removed": { "description": "Is set to true if the remove was successful.\n", "type": "boolean" } }, "required": [ "error", "code", "removed" ], "type": "object" } } }, "description": "Returned if the edge can be removed.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "old": { "description": "The complete deleted edge document.\nIncludes all attributes stored before this operation.\nOnly present if `returnOld` is `true`.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" }, "removed": { "description": "Is set to true if the remove was successful.\n", "type": "boolean" } }, "required": [ "error", "code", "removed" ], "type": "object" } } }, "description": "Returned if the request was successful but `waitForSync` is `false`.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to delete nodes in the graph, you need to have at least the following privileges:\n- `Read Only` access on the database.\n- `Write` access on the given collection.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned in the following cases:\n- The graph cannot be found.\n- The collection is not part of the graph.\n- The edge to remove does not exist.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 410, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "412": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 412, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `If-Match` header has been specified but the stored document's\nrevision is different.\n" } }, "summary": "Remove an edge", "tags": [ "Graphs" ] }, "get": { "description": "Gets an edge from the given collection.\n", "operationId": "getEdge", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "The name of the edge collection the edge belongs to.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The `_key` attribute of the edge.\n", "in": "path", "name": "edge", "required": true, "schema": { "type": "string" } }, { "description": "If you provide an `If-Match` header, it must contain exactly one ETag.\nThe document is returned if it has the same revision as the given ETag.\nOtherwise, an error with HTTP status code 412 is returned.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "If you provide an `If-None-Match` header, it must contain exactly one ETag.\nThe document is returned if it has a different revision as the given ETag.\nOtherwise, an error with HTTP status code 304 is returned.\n", "in": "header", "name": "If-None-Match", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "edge": { "description": "The complete edge.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" } }, "required": [ "error", "code", "edge" ], "type": "object" } } }, "description": "Returned if the edge can be found.\n" }, "304": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 304, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `If-None-Match` header has been specified and the currently\nstored edge still has this revision value. There was no update since\nthe last time the edge was fetched by the caller.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to update nodes in the graph, you need to have at least the following privileges:\n- `Read Only` access on the database.\n- `Read Only` access on the given collection.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned in the following cases:\n- The graph cannot be found.\n- The collection is not part of the graph.\n- The edge does not exist.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 410, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "412": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 412, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `If-Match` header has been specified but the stored document's\nrevision is different.\n" } }, "summary": "Get an edge", "tags": [ "Graphs" ] }, "patch": { "description": "Partially modify the data of the specific edge in the collection.\n", "operationId": "updateEdge", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "The name of the edge collection the edge belongs to.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The `_key` attribute of the node.\n", "in": "path", "name": "edge", "required": true, "schema": { "type": "string" } }, { "description": "Define if the request should wait until synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Define if values set to `null` should be stored.\nBy default (`true`), the given documents attribute(s) are set to `null`.\nIf this parameter is set to `false`, top-level attribute and sub-attributes with\na `null` value in the request are removed from the document (but not attributes\nof objects that are nested inside of arrays).\n", "in": "query", "name": "keepNull", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to additionally include the complete new document under the\n`new` attribute in the result.\n", "in": "query", "name": "returnNew", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If you provide an `If-Match` header, it must contain exactly one ETag.\nThe document is updated if it has the same revision as the given ETag.\nOtherwise, an error with HTTP status code 412 is returned.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The body has to be a JSON object containing exactly the attributes\nthat should be overwritten. All other attributes remain unchanged.\n", "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "edge": { "description": "The internal attributes for the edge.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "new": { "description": "The complete newly written edge document.\nIncludes all written attributes in the request body\nand all internal attributes generated by ArangoDB.\nOnly present if `returnNew` is `true`.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" }, "old": { "description": "The complete overwritten edge document.\nIncludes all attributes stored before this operation.\nOnly present if `returnOld` is `true`.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" } }, "required": [ "error", "code", "edge" ], "type": "object" } } }, "description": "Returned if the edge can be updated, and `waitForSync` is `false`.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "edge": { "description": "The internal attributes for the edge.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "new": { "description": "The complete newly written edge document.\nIncludes all written attributes in the request body\nand all internal attributes generated by ArangoDB.\nOnly present if `returnNew` is `true`.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" }, "old": { "description": "The complete overwritten edge document.\nIncludes all attributes stored before this operation.\nOnly present if `returnOld` is `true`.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" } }, "required": [ "error", "code", "edge" ], "type": "object" } } }, "description": "Returned if the request was successful but `waitForSync` is `false`.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to update edges in the graph, you need to have at least the following privileges:\n- `Read Only` access on the database.\n- `Write` access on the given collection.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned in the following cases:\n- The graph cannot be found.\n- The collection is not part of the graph.\n- The edge to update does not exist.\n- Either `_from` or `_to` node does not exist (if updated).\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 410, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "412": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 412, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `If-Match` header has been specified but the stored document's\nrevision is different.\n" } }, "summary": "Update an edge", "tags": [ "Graphs" ] }, "put": { "description": "Replaces the data of an edge in the collection.\n", "operationId": "replaceEdge", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "The name of the edge collection the edge belongs to.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The `_key` attribute of the node.\n", "in": "path", "name": "edge", "required": true, "schema": { "type": "string" } }, { "description": "Define if the request should wait until synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Define if values set to `null` should be stored.\nBy default (`true`), the given documents attribute(s) are set to `null`.\nIf this parameter is set to `false`, top-level attribute and sub-attributes with\na `null` value in the request are removed from the document (but not attributes\nof objects that are nested inside of arrays).\n", "in": "query", "name": "keepNull", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to additionally include the complete new document under the\n`new` attribute in the result.\n", "in": "query", "name": "returnNew", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If you provide an `If-Match` header, it must contain exactly one ETag.\nThe document is replaced if it has the same revision as the given ETag.\nOtherwise, an error with HTTP status code 412 is returned.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The body has to be a JSON object you want to replace an existing\nedge document with.\n", "properties": { "_from": { "description": "The source node of this edge. Has to be valid within\nthe used edge definition.\n", "type": "string" }, "_to": { "description": "The target node of this edge. Has to be valid within\nthe used edge definition.\n", "type": "string" } }, "required": [ "_from", "_to" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 201, "type": "integer" }, "edge": { "description": "The internal attributes for the edge\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "new": { "description": "The complete newly written edge document.\nIncludes all written attributes in the request body\nand all internal attributes generated by ArangoDB.\nOnly present if `returnNew` is `true`.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" }, "old": { "description": "The complete overwritten edge document.\nIncludes all attributes stored before this operation.\nOnly present if `returnOld` is `true`.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" } }, "required": [ "error", "code", "edge" ], "type": "object" } } }, "description": "Returned if the request was successful but `waitForSync` is `true`.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "edge": { "description": "The internal attributes for the edge\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "new": { "description": "The complete newly written edge document.\nIncludes all written attributes in the request body\nand all internal attributes generated by ArangoDB.\nOnly present if `returnNew` is `true`.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" }, "old": { "description": "The complete overwritten edge document.\nIncludes all attributes stored before this operation.\nOnly present if `returnOld` is `true`.\n", "properties": { "_from": { "description": "The _from value of the stored data.\n", "type": "string" }, "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" }, "_to": { "description": "The _to value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev", "_from", "_to" ], "type": "object" } }, "required": [ "error", "code", "edge" ], "type": "object" } } }, "description": "Returned if the request was successful but `waitForSync` is `false`.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to replace edges in the graph, you need to have at least the following privileges:\n- `Read Only` access on the database.\n- `Write` access on the given collection.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned in the following cases:\n- The graph cannot be found.\n- The collection is not part of the graph.\n- The edge to replace does not exist.\n- Either `_from` or `_to` node does not exist.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 410, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "412": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 412, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `If-Match` header has been specified but the stored document's\nrevision is different.\n" } }, "summary": "Replace an edge", "tags": [ "Graphs" ] } }, "/_db/{database-name}/_api/gharial/{graph}/vertex": { "get": { "description": "Lists all node collections within this graph, including orphan collections.\n", "operationId": "listVertexCollections", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "collections": { "description": "The list of all node collections within this graph.\nIncludes the node collections used in edge definitions\nas well as orphan collections.\n", "items": { "type": "string" }, "type": "array" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" } }, "required": [ "error", "code", "collections" ], "type": "object" } } }, "description": "Is returned if the collections can be listed.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if no graph with this name can be found.\n" } }, "summary": "List node collections", "tags": [ "Graphs" ] }, "post": { "description": "Adds a node collection to the set of orphan collections of the graph.\nIf the collection does not exist, it is created.\n", "operationId": "addVertexCollection", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "collection": { "description": "The name of the node collection to add to the graph definition.\n", "type": "string" }, "options": { "description": "A JSON object to set options for creating node collections.\n", "properties": { "satellites": { "description": "An array of collection names that is used to create SatelliteCollections\nfor a (Disjoint) SmartGraph using SatelliteCollections.\nEach array element must be a string and a valid collection name.\nThe collection type cannot be modified later.\n", "items": { "type": "string" }, "type": "array" } }, "type": "object" } }, "required": [ "collection" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 201, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graph": { "description": "The information about the modified graph.\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "required": [ "error", "code", "graph" ], "type": "object" } } }, "description": "Is returned if the collection can be created and `waitForSync` is enabled\nfor the `_graphs` collection, or given in the request.\nThe response body contains the graph configuration that has been stored.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graph": { "description": "The information about the newly created graph\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "required": [ "error", "code", "graph" ], "type": "object" } } }, "description": "Is returned if the collection can be created and `waitForSync` is disabled\nfor the `_graphs` collection, or given in the request.\nThe response body contains the graph configuration that has been stored.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if the request is in an invalid format.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to modify a graph, you need to have at least the following privileges:\n- `Administrate` access on the database.\n- `Read Only` access on every collection used within this graph.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if no graph with this name can be found.\n" } }, "summary": "Add a node collection", "tags": [ "Graphs" ] } }, "/_db/{database-name}/_api/gharial/{graph}/vertex/{collection}": { "delete": { "description": "Removes a node collection from the list of the graph's\norphan collections. It can optionally delete the collection if it is\nnot used in any other graph.\n\nYou cannot remove node collections that are used in one of the\nedge definitions of the graph. You need to modify or remove the\nedge definition first in order to fully remove a node collection from\nthe graph.\n", "operationId": "deleteVertexCollection", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "The name of the node collection.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "Drop the collection in addition to removing it from the graph.\nThe collection is only dropped if it is not used in other graphs.\n", "in": "query", "name": "dropCollection", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graph": { "description": "The information about the newly created graph\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "required": [ "error", "code", "graph" ], "type": "object" } } }, "description": "Returned if the node collection was removed from the graph successfully\nand `waitForSync` is `true`.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "graph": { "description": "The information about the newly created graph\n", "properties": { "_id": { "description": "The internal id value of this graph.\n", "type": "string" }, "_rev": { "description": "The revision of this graph. Can be used to make sure to not override\nconcurrent modifications to this graph.\n", "type": "string" }, "edgeDefinitions": { "description": "An array of definitions for the relations of the graph.\nEach has the following type:\n", "items": { "properties": { "collection": { "description": "Name of the edge collection, where the edges are stored in.\n", "type": "string" }, "from": { "description": "List of node collection names.\nEdges in collection can only be inserted if their _from is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" }, "to": { "description": "List of node collection names.\n\nEdges in collection can only be inserted if their _to is in any of the collections here.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "collection", "from", "to" ], "type": "object" }, "type": "array" }, "isDisjoint": { "description": "Whether the graph is a Disjoint SmartGraph.\n", "type": "boolean" }, "isSatellite": { "description": "Whether the graph is a SatelliteGraph.\n", "type": "boolean" }, "isSmart": { "description": "Whether the graph is a SmartGraph (`smartGraphAttribute` is set)\nor EnterpriseGraph (`isSmart` is `true` but `smartGraphAttribute` is not set).\n", "type": "boolean" }, "name": { "description": "The name of the graph.\n", "type": "string" }, "numberOfShards": { "description": "Number of shards created for every new collection in the graph.\n", "type": "integer" }, "orphanCollections": { "description": "An array of additional node collections.\nDocuments in these collections do not have edges within this graph.\n", "items": { "type": "string" }, "type": "array" }, "replicationFactor": { "description": "The replication factor used for every new collection in the graph.\nFor SatelliteGraphs, it is the string `\"satellite\"`.\n", "type": "integer" }, "smartGraphAttribute": { "description": "Name of the sharding attribute in the SmartGraph case.\n", "type": "string" }, "writeConcern": { "description": "The default write concern for new collections in the graph.\nIt determines how many copies of each shard are required to be\nin sync on the different DB-Servers. If there are less than these many copies\nin the cluster, a shard refuses to write. Writes to shards with enough\nup-to-date copies succeed at the same time, however. The value of\n`writeConcern` cannot be greater than `replicationFactor`.\nFor SatelliteGraphs, the `writeConcern` is automatically controlled to equal the\nnumber of DB-Servers and the attribute is not available. _(cluster only)_\n", "type": "integer" } }, "required": [ "name", "edgeDefinitions", "orphanCollections", "numberOfShards", "_id", "_rev", "replicationFactor", "isSmart", "isDisjoint", "isSatellite" ], "type": "object" } }, "required": [ "error", "code", "graph" ], "type": "object" } } }, "description": "Returned if the request was successful but `waitForSync` is `false`.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if the node collection is still used in an edge definition.\nIn this case it cannot be removed from the graph yet, it has to be\nremoved from the edge definition first.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to drop a node, you need to have at least the following privileges:\n- `Administrate` access on the database.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if no graph with this name can be found.\n" } }, "summary": "Remove a node collection", "tags": [ "Graphs" ] }, "post": { "description": "Adds a node to the given collection.\n", "operationId": "createVertex", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "The name of the node collection the node should be inserted into.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "Define if the request should wait until synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Whether to additionally include the complete new document under the\n`new` attribute in the result.\n", "in": "query", "name": "returnNew", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The body has to be a JSON object you want to store as a node document.\n", "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 201, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "new": { "description": "The complete newly written node document.\nIncludes all written attributes in the request body\nand all internal attributes generated by ArangoDB.\nOnly present if `returnNew` is `true`.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" }, "vertex": { "description": "The internal attributes for the node.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" } }, "required": [ "error", "code", "vertex" ], "type": "object" } } }, "description": "Returned if the node can be added and `waitForSync` is `true`.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "new": { "description": "The complete newly written node document.\nIncludes all written attributes in the request body\nand all internal attributes generated by ArangoDB.\nOnly present if `returnNew` is `true`.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" }, "vertex": { "description": "The internal attributes generated while storing the node.\nDoes not include any attribute given in request body.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" } }, "required": [ "error", "code", "vertex" ], "type": "object" } } }, "description": "Returned if the request was successful but `waitForSync` is `false`.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to insert nodes into the graph, you need to have at least the following privileges:\n- `Read Only` access on the database.\n- `Write` access on the given collection.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The graph cannot be found or the collection is not part of the graph.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 410, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" } }, "summary": "Create a node", "tags": [ "Graphs" ] } }, "/_db/{database-name}/_api/gharial/{graph}/vertex/{collection}/{vertex}": { "delete": { "description": "Removes a node from a collection of the named graph. Additionally removes all\nincoming and outgoing edges of the node.\n", "operationId": "deleteVertex", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "The name of the node collection the node belongs to.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The `_key` attribute of the node.\n", "in": "path", "name": "vertex", "required": true, "schema": { "type": "string" } }, { "description": "Define if the request should wait until synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If you provide an `If-Match` header, it must contain exactly one ETag.\nThe document is deleted if it has the same revision as the given ETag.\nOtherwise, an error with HTTP status code 412 is returned.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "old": { "description": "The complete deleted node document.\nIncludes all attributes stored before this operation.\nOnly present if `returnOld` is `true`.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" }, "removed": { "description": "Is set to true if the remove was successful.\n", "type": "boolean" } }, "required": [ "error", "code", "removed" ], "type": "object" } } }, "description": "Returned if the node can be removed.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "old": { "description": "The complete deleted node document.\nIncludes all attributes stored before this operation.\nOnly present if `returnOld` is `true`.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" }, "removed": { "description": "Is set to true if the remove was successful.\n", "type": "boolean" } }, "required": [ "error", "code", "removed" ], "type": "object" } } }, "description": "Returned if the request was successful but `waitForSync` is `false`.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to delete nodes in the graph, you need to have at least the following privileges:\n- `Read Only` access on the database.\n- `Write` access on the given collection.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned in the following cases:\n- The graph cannot be found.\n- The collection is not part of the graph.\n- The node to remove does not exist.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 410, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "412": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 412, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `If-Match` header has been specified but the stored document's\nrevision is different.\n" } }, "summary": "Remove a node", "tags": [ "Graphs" ] }, "get": { "description": "Gets a node from the given collection.\n", "operationId": "getVertex", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "The name of the node collection the node belongs to.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The `_key` attribute of the node.\n", "in": "path", "name": "vertex", "required": true, "schema": { "type": "string" } }, { "description": "If you provide an `If-Match` header, it must contain exactly one ETag.\nThe document is returned if it has the same revision as the given ETag.\nOtherwise, an error with HTTP status code 412 is returned.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "If you provide an `If-None-Match` header, it must contain exactly one ETag.\nThe document is returned if it has a different revision as the given ETag.\nOtherwise, an error with HTTP status code 304 is returned.\n", "in": "header", "name": "If-None-Match", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "vertex": { "description": "The complete node.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" } }, "required": [ "error", "code", "vertex" ], "type": "object" } } }, "description": "Returned if the node can be found.\n" }, "304": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 304, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `If-None-Match` header has been specified and the currently\nstored node still has this revision value. There was no update since\nthe last time the node was fetched by the caller.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to update nodes in the graph, you need to have at least the following privileges:\n- `Read Only` access on the database.\n- `Read Only` access on the given collection.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned in the following cases:\n- The graph cannot be found.\n- The collection is not part of the graph.\n- The node does not exist.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 410, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "412": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 412, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `If-Match` header has been specified but the stored document's\nrevision is different.\n" } }, "summary": "Get a node", "tags": [ "Graphs" ] }, "patch": { "description": "Updates the data of the specific node in the collection.\n", "operationId": "updateVertex", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "The name of the node collection the node belongs to.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The `_key` attribute of the node.\n", "in": "path", "name": "vertex", "required": true, "schema": { "type": "string" } }, { "description": "Define if the request should wait until synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Define if values set to `null` should be stored.\nBy default (`true`), the given documents attribute(s) are set to `null`.\nIf this parameter is set to `false`, top-level attribute and sub-attributes with\na `null` value in the request are removed from the document (but not attributes\nof objects that are nested inside of arrays).\n", "in": "query", "name": "keepNull", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to additionally include the complete new document under the\n`new` attribute in the result.\n", "in": "query", "name": "returnNew", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If you provide an `If-Match` header, it must contain exactly one ETag.\nThe document is updated if it has the same revision as the given ETag.\nOtherwise, an error with HTTP status code 412 is returned.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The body has to be a JSON object containing exactly the attributes\nthat should be overwritten. All other attributes remain unchanged.\n", "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "new": { "description": "The complete newly written node document.\nIncludes all written attributes in the request body\nand all internal attributes generated by ArangoDB.\nOnly present if `returnNew` is `true`.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" }, "old": { "description": "The complete overwritten node document.\nIncludes all attributes stored before this operation.\nOnly present if `returnOld` is `true`.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" }, "vertex": { "description": "The internal attributes for the node.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" } }, "required": [ "error", "code", "vertex" ], "type": "object" } } }, "description": "Returned if the node can be updated, and `waitForSync` is `true`.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "new": { "description": "The complete newly written node document.\nIncludes all written attributes in the request body\nand all internal attributes generated by ArangoDB.\nOnly present if `returnNew` is `true`.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" }, "old": { "description": "The complete overwritten node document.\nIncludes all attributes stored before this operation.\nOnly present if `returnOld` is `true`.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" }, "vertex": { "description": "The internal attributes for the node.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" } }, "required": [ "error", "code", "vertex" ], "type": "object" } } }, "description": "Returned if the request was successful, and `waitForSync` is `false`.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to update nodes in the graph, you need to have at least the following privileges:\n- `Read Only` access on the database.\n- `Write` access on the given collection.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned in the following cases:\n- The graph cannot be found.\n- The collection is not part of the graph.\n- The node to update does not exist.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 410, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "412": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 412, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `If-Match` header has been specified but the stored document's\nrevision is different.\n" } }, "summary": "Update a node", "tags": [ "Graphs" ] }, "put": { "description": "Replaces the data of a node in the collection.\n", "operationId": "replaceVertex", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the graph.\n", "in": "path", "name": "graph", "required": true, "schema": { "type": "string" } }, { "description": "The name of the node collection the node belongs to.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The `_key` attribute of the node.\n", "in": "path", "name": "vertex", "required": true, "schema": { "type": "string" } }, { "description": "Define if the request should wait until synced to disk.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "type": "boolean" } }, { "description": "Define if values set to `null` should be stored.\nBy default (`true`), the given documents attribute(s) are set to `null`.\nIf this parameter is set to `false`, top-level attribute and sub-attributes with\na `null` value in the request are removed from the document (but not attributes\nof objects that are nested inside of arrays).\n", "in": "query", "name": "keepNull", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Whether to additionally include the complete previous document under the\n`old` attribute in the result.\n", "in": "query", "name": "returnOld", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to additionally include the complete new document under the\n`new` attribute in the result.\n", "in": "query", "name": "returnNew", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If you provide an `If-Match` header, it must contain exactly one ETag.\nThe document is replaced if it has the same revision as the given ETag.\nOtherwise, an error with HTTP status code 412 is returned.\n", "in": "header", "name": "If-Match", "required": false, "schema": { "type": "string" } }, { "description": "To make this operation a part of a Stream Transaction, set this header to the\ntransaction ID returned by the `POST /_api/transaction/begin` call.\n", "in": "header", "name": "x-arango-trx-id", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The body has to be a JSON object you want to replace the existing\nnode document with.\n", "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "new": { "description": "The complete newly written node document.\nIncludes all written attributes in the request body\nand all internal attributes generated by ArangoDB.\nOnly present if `returnNew` is `true`.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" }, "old": { "description": "The complete overwritten node document.\nIncludes all attributes stored before this operation.\nOnly present if `returnOld` is `true`.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" }, "vertex": { "description": "The internal attributes for the node.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" } }, "required": [ "error", "code", "vertex" ], "type": "object" } } }, "description": "Returned if the node can be replaced, and `waitForSync` is `true`.\n" }, "202": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 202, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "new": { "description": "The complete newly written node document.\nIncludes all written attributes in the request body\nand all internal attributes generated by ArangoDB.\nOnly present if `returnNew` is `true`.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" }, "old": { "description": "The complete overwritten node document.\nIncludes all attributes stored before this operation.\nOnly present if `returnOld` is `true`.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" }, "vertex": { "description": "The internal attributes for the node.\n", "properties": { "_id": { "description": "The _id value of the stored data.\n", "type": "string" }, "_key": { "description": "The _key value of the stored data.\n", "type": "string" }, "_rev": { "description": "The _rev value of the stored data.\n", "type": "string" } }, "required": [ "_id", "_key", "_rev" ], "type": "object" } }, "required": [ "error", "code", "vertex" ], "type": "object" } } }, "description": "Returned if the node can be replaced, and `waitForSync` is `false`.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned if your user has insufficient rights.\nIn order to replace nodes in the graph, you need to have at least the following privileges:\n- `Read Only` access on the database.\n- `Write` access on the given collection.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned in the following cases:\n- The graph cannot be found.\n- The collection is not part of the graph.\n- The node to replace does not exist.\n\nThis error also occurs if you try to run this operation as part of a\nStream Transaction but the transaction ID specified in the\n`x-arango-trx-id` header is unknown to the server.\n" }, "410": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 410, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "This error occurs if you try to run this operation as part of a\nStream Transaction that has just been canceled or timed out.\n" }, "412": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 412, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `If-Match` header has been specified but the stored document's\nrevision is different.\n" } }, "summary": "Replace a node", "tags": [ "Graphs" ] } }, "/_db/{database-name}/_api/import": { "post": { "description": "Load JSON data and store it as documents into the specified collection.\n\nIf you import documents into edge collections, all documents require a `_from`\nand a `_to` attribute.\n", "operationId": "importData", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the target collection. The collection needs to exist already.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "Determines how the body of the request is interpreted.\n\n- `documents`: JSON Lines (JSONL) format. Each line is expected to be one\n JSON object.\n\n Example:\n\n ```json\n {\"_key\":\"john\",\"name\":\"John Smith\",\"age\":35}\n {\"_key\":\"katie\",\"name\":\"Katie Foster\",\"age\":28}\n ```\n\n- `array` (or `list`): JSON format. The request body is expected to be a\n JSON array of objects. This format requires ArangoDB to parse the complete\n array and keep it in memory for the duration of the import. This is more\n resource-intensive than the line-wise JSONL processing.\n\n Any whitespace outside of strings is ignored, which means the JSON data can be\n a single line or be formatted as multiple lines.\n\n Example:\n\n ```json\n [\n {\"_key\":\"john\",\"name\":\"John Smith\",\"age\":35},\n {\"_key\":\"katie\",\"name\":\"Katie Foster\",\"age\":28}\n ]\n ```\n\n- `auto`: automatically determines the type (either `documents` or `array`).\n\n- Omit the `type` parameter entirely (or set it to an empty string)\n to import JSON arrays of tabular data, similar to CSV.\n\n The first line is an array of strings that defines the attribute keys. The\n subsequent lines are arrays with the attribute values. The keys and values\n are matched by the order of the array elements.\n\n Example:\n\n ```json\n [\"_key\",\"name\",\"age\"]\n [\"john\",\"John Smith\",35]\n [\"katie\",\"Katie Foster\",28]\n ```\n", "in": "query", "name": "type", "required": false, "schema": { "default": "", "enum": [ "", "documents", "array", "auto" ], "type": "string" } }, { "description": "When importing JSON arrays of tabular data (`type` parameter is omitted),\nthe first line of the request body defines the attribute keys and the\nsubsequent lines the attribute values for each document. Subsequent lines\nwith a different number of elements than the first line are not imported\nby default.\n\n```js\n[\"attr1\", \"attr2\"]\n[1, 2] // matching number of elements\n[1] // misses 2nd element\n[1, 2, 3] // excess 3rd element\n```\n\nYou can enable this option to import them anyway. For the missing elements,\nthe document attributes are omitted. Excess elements are ignored.\n", "in": "query", "name": "ignoreMissing", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "The collection name prefix to prepend to all values in the `_from`\nattribute that only specify a document key.\n", "in": "query", "name": "fromPrefix", "required": false, "schema": { "type": "string" } }, { "description": "The collection name prefix to prepend to all values in the `_to`\nattribute that only specify a document key.\n", "in": "query", "name": "toPrefix", "required": false, "schema": { "type": "string" } }, { "description": "Force the `fromPrefix` and `toPrefix`, possibly replacing existing\ncollection name prefixes.\n", "in": "query", "name": "overwriteCollectionPrefix", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If enabled, then all data in the collection is removed prior to the\nimport. Any existing index definitions are preserved.\n", "in": "query", "name": "overwrite", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Wait until documents have been synced to disk before returning.\n", "in": "query", "name": "waitForSync", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Controls what action is carried out in case of a unique key constraint\nviolation.\n\n- `error`: this will not import the current document because of the unique\n key constraint violation. This is the default setting.\n- `update`: this will update an existing document in the database with the\n data specified in the request. Attributes of the existing document that\n are not present in the request will be preserved.\n- `replace`: this will replace an existing document in the database with the\n data specified in the request.\n- `ignore`: this will not update an existing document and simply ignore the\n error caused by a unique key constraint violation.\n\nNote that `update`, `replace` and `ignore` will only work when the\nimport document in the request contains the `_key` attribute. `update` and\n`replace` may also fail because of secondary unique key constraint violations.\n", "in": "query", "name": "onDuplicate", "required": false, "schema": { "default": "error", "enum": [ "error", "update", "replace", "ignore" ], "type": "string" } }, { "description": "If set to `true`, the whole import fails if any error occurs. Otherwise, the\nimport continues even if some documents are invalid and cannot be imported,\nskipping the problematic documents.\n", "in": "query", "name": "complete", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "If set to `true`, the result includes a `details` attribute with information\nabout documents that could not be imported.\n", "in": "query", "name": "details", "required": false, "schema": { "default": false, "type": "boolean" } } ], "requestBody": { "content": { "text/plain; charset=utf-8": { "schema": { "description": "The request body can have different JSON formats depending on\nthe `type` parameter:\n- One JSON object per line (JSONL)\n- A JSON array of objects\n- One JSON array per line (CSV-like)\n" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "created": { "description": "The number of imported documents.\n", "type": "integer" }, "details": { "description": "An array with the error messages caused by documents that could not be imported.\nOnly present if `details` is set to `true`.\n", "items": { "type": "string" }, "type": "array" }, "empty": { "description": "The number of empty lines found in the input. Only greater than zero for the\ntypes `documents` and `auto`.\n", "type": "integer" }, "errors": { "description": "The number of documents that were not imported due to errors.\n", "type": "integer" }, "ignored": { "description": "The number of failed but ignored insert operations. Only greater than zero if\n`onDuplicate` is set to `ignore`.\n", "type": "integer" }, "updated": { "description": "The number of updated/replaced documents. Only greater than zero if `onDuplicate`\nis set to either `update` or `replace`.\n", "type": "integer" } }, "required": [ "created", "errors", "empty", "updated", "ignored" ], "type": "object" } } }, "description": "is returned if all documents could be imported successfully.\n\nThe response is a JSON object with the following attributes:\n" }, "400": { "description": "The `type` contains an invalid value, no `collection` is\nspecified, the documents are incorrectly encoded, or the request\nis malformed.\n" }, "404": { "description": "The `collection` parameter or the `_from` or `_to` attributes of an\nimported edge refer to an unknown collection.\n" }, "409": { "description": "The `complete` option is enabled and the import triggers a\nunique key violation.\n" }, "500": { "description": "The `complete` option is enabled and the input is invalid,\nor the server cannot auto-generate a document key (out of keys error)\nfor a document with no user-defined key.\n" } }, "summary": "Import JSON data as documents", "tags": [ "Import" ] } }, "/_db/{database-name}/_api/index": { "get": { "description": "Returns an object with an `indexes` attribute containing an array of all\nindex descriptions for the given collection. The same information is also\navailable in the `identifiers` attribute as an object with the index identifiers\nas object keys.\n", "operationId": "listIndexes", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The collection name.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "Whether to include figures and estimates in the result.\n", "in": "query", "name": "withStats", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Whether to include hidden indexes in the result. Internal indexes\n(such as `arangosearch`) and ones that are currently built in the\nbackground are hidden.\n", "in": "query", "name": "withHidden", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "returns a JSON object containing a list of indexes on that collection.\n" } }, "summary": "List all indexes of a collection", "tags": [ "Indexes" ] }, "post": { "description": "Creates a new index in the collection `collection`. Expects\nan object containing the index details.\n\nThe type of the index to be created must specified in the **type**\nattribute of the index details. Depending on the index type, additional\nother attributes may need to specified in the request in order to create\nthe index.\n\nIndexes require the to be indexed attribute(s) in the **fields** attribute\nof the index details. Depending on the index type, a single attribute or\nmultiple attributes can be indexed. In the latter case, an array of\nstrings is expected.\n\nThe `.` character denotes sub-attributes in attribute paths. Attributes with\nliteral `.` in their name cannot be indexed. Attributes with the name `_id`\ncannot be indexed either, neither as a top-level attribute nor as a sub-attribute.\n\nOptionally, an index name may be specified as a string in the **name** attribute.\nIndex names have the same restrictions as collection names. If no value is\nspecified, one will be auto-generated.\n\nPersistent indexes (including vertex-centric indexes) can be created as unique\nor non-unique variants. Uniqueness can be controlled by specifying the\n**unique** option for the index definition. Setting it to `true` creates a\nunique index. Setting it to `false` or omitting the `unique` attribute creates a\nnon-unique index.\n\n\u003e **INFO:**\nUnique indexes on non-shard keys are not supported in cluster deployments.\n\n\nPersistent indexes can optionally be created in a sparse\nvariant. A sparse index will be created if the **sparse** attribute in\nthe index details is set to `true`. Sparse indexes do not index documents\nfor which any of the index attributes is either not set or is `null`.\n\nThe optional **deduplicate** attribute is supported by persistent array indexes.\nIt controls whether inserting duplicate index values\nfrom the same document into a unique array index will lead to a unique constraint\nerror or not. The default value is `true`, so only a single instance of each\nnon-unique index value will be inserted into the index per document. Trying to\ninsert a value into the index that already exists in the index always fails,\nregardless of the value of this attribute.\n\nThe optional **estimates** attribute is supported by `persistent`, `mdi`, and\n`mdi-prefixed` indexes. This attribute controls whether index selectivity estimates are\nmaintained for the index. Not maintaining index selectivity estimates can have\na slightly positive impact on write performance.\nThe downside of turning off index selectivity estimates will be that\nthe query optimizer will not be able to determine the usefulness of different\ncompeting indexes in AQL queries when there are multiple candidate indexes to\nchoose from.\nThe `estimates` attribute is optional and defaults to `true` if not set. It will\nhave no effect on indexes other than persistent indexes.\n\nThe optional attribute **cacheEnabled** is supported by indexes of type\n`persistent`. This attribute controls whether an extra in-memory hash cache is\ncreated for the index. The hash cache can be used to speed up index lookups.\nThe cache can only be used for queries that look up all index attributes via\nan equality lookup (`==`). The hash cache cannot be used for range scans,\npartial lookups or sorting.\nThe cache will be populated lazily upon reading data from the index. Writing data\ninto the collection or updating existing data will invalidate entries in the\ncache. The cache may have a negative effect on performance in case index values\nare updated more often than they are read.\nThe maximum size of cache entries that can be stored is currently 4 MB, i.e.\nthe cumulated size of all index entries for any index lookup value must be\nless than 4 MB. This limitation is there to avoid storing the index entries\nof \"super nodes\" in the cache.\n`cacheEnabled` defaults to `false` and should only be used for indexes that\nare known to benefit from an extra layer of caching.\n\nThe optional attribute **inBackground** can be set to `true` to keep the\ncollection/shards available for write operations by not using an exclusive\nwrite lock for the duration of the index creation.\n", "operationId": "createIndex", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The collection name.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The options for the index. The available attributes depend on the index type.\n", "type": "object" } } } }, "responses": { "200": { "description": "If the index already exists, then an *HTTP 200* is returned.\n" }, "201": { "description": "If the index does not already exist and could be created, then an *HTTP 201*\nis returned.\n" }, "400": { "description": "If an invalid index description is posted or attributes are used that the\ntarget index will not support, then an *HTTP 400* is returned.\n" }, "404": { "description": "If `collection` is unknown, then an *HTTP 404* is returned.\n" } }, "summary": "Create an index", "tags": [ "Indexes" ] } }, "/_db/{database-name}/_api/index#fulltext": { "post": { "deprecated": true, "description": "\u003e **WARNING:**\nThe fulltext index type is deprecated from version 3.10 onwards.\n\n\nCreates a fulltext index for the collection `collection-name`, if\nit does not already exist. The call expects an object containing the index\ndetails.\n", "operationId": "createIndexFulltext", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The collection name.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "fields": { "description": "A list with exactly one attribute path.\n", "items": { "type": "string" }, "maxItems": 1, "minItems": 1, "type": "array" }, "inBackground": { "default": false, "description": "Set this option to `true` to keep the collection/shards available for\nwrite operations by not using an exclusive write lock for the duration\nof the index creation.\n", "type": "boolean" }, "minLength": { "default": 2, "description": "Minimum character length of words to index. The default is\nlow, thus it is recommended to set this value explicitly\nwhen creating the index.\n", "type": "integer" }, "name": { "description": "An easy-to-remember name for the index to look it up or refer to it in index hints.\nIndex names are subject to the same character restrictions as collection names.\nIf omitted, a name is auto-generated so that it is unique with respect to the\ncollection, e.g. `idx_832910498`.\n", "type": "string" }, "type": { "description": "Needs to be set to `\"fulltext\"`.\n", "example": "fulltext", "type": "string" } }, "required": [ "type", "fields", "minLength" ], "type": "object" } } } }, "responses": { "200": { "description": "The index exists already.\n" }, "201": { "description": "The index is created as there is no such existing index.\n" }, "404": { "description": "The collection is unknown.\n" } }, "summary": "Create a full-text index", "tags": [ "Indexes" ] } }, "/_db/{database-name}/_api/index#geo": { "post": { "description": "Creates a geo-spatial index in the collection `collection`, if\nit does not already exist.\n\nGeo indexes are always sparse, meaning that documents that do not contain\nthe index attributes or have non-numeric values in the index attributes\nwill not be indexed.\n", "operationId": "createIndexGeo", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The collection name.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "fields": { "description": "An array with one or two attribute paths.\n\nIf it is an array with one attribute path `location`, then a geo-spatial\nindex on all documents is created using `location` as path to the\ncoordinates. The value of the attribute must be an array with at least two\ndouble values. The array must contain the latitude (first value) and the\nlongitude (second value). All documents, which do not have the attribute\npath or with value that are not suitable, are ignored.\n\nIf it is an array with two attribute paths `latitude` and `longitude`,\nthen a geo-spatial index on all documents is created using `latitude`\nand `longitude` as paths the latitude and the longitude. The values of\nthe `latitude` and `longitude` attributes must each be a number (double).\nAll documents which do not have the attribute paths or which have\nvalues that are not suitable are ignored.\n", "items": { "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array", "uniqueItems": true }, "geoJson": { "default": false, "description": "If you create a geo-spatial index over a single attribute and `geoJson`\nis `true`, then the coordinate order within the attribute's array is\nlongitude followed by latitude. This corresponds to the format described in\n\u003chttp://geojson.org/geojson-spec.html#positions\u003e\n", "type": "boolean" }, "inBackground": { "default": false, "description": "Set this option to `true` to keep the collection/shards available for\nwrite operations by not using an exclusive write lock for the duration\nof the index creation.\n", "type": "boolean" }, "legacyPolygons": { "description": "If `geoJson` is set to `true`, then this option controls how GeoJSON Polygons\nare interpreted.\n\n- If `legacyPolygons` is `true`, the smaller of the two regions defined by a\n linear ring is interpreted as the interior of the ring and a ring can at most\n enclose half the Earth's surface.\n- If `legacyPolygons` is `false`, the area to the left of the boundary ring's\n path is considered to be the interior and a ring can enclose the entire\n surface of the Earth.\n\nThe default is `true` for geo indexes that were created in versions before 3.10,\nand `false` for geo indexes created in 3.10 or later.\n", "type": "boolean" }, "name": { "description": "An easy-to-remember name for the index to look it up or refer to it in index hints.\nIndex names are subject to the same character restrictions as collection names.\nIf omitted, a name is auto-generated so that it is unique with respect to the\ncollection, e.g. `idx_832910498`.\n", "type": "string" }, "type": { "description": "Needs to be set to `\"geo\"`.\n", "example": "geo", "type": "string" } }, "required": [ "type", "fields" ], "type": "object" } } } }, "responses": { "200": { "description": "The index exists already.\n" }, "201": { "description": "The index is created as there is no such existing index.\n" }, "404": { "description": "The collection is unknown.\n" } }, "summary": "Create a geo-spatial index", "tags": [ "Indexes" ] } }, "/_db/{database-name}/_api/index#inverted": { "post": { "description": "Creates an inverted index for the collection `collection-name`, if\nit does not already exist. The call expects an object containing the index\ndetails.\n", "operationId": "createIndexInverted", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The collection name.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "analyzer": { "default": "identity", "description": "The name of an Analyzer to use by default. This Analyzer is applied to the\nvalues of the indexed fields for which you don't define Analyzers explicitly.\n", "type": "string" }, "cache": { "default": false, "description": "Enable this option to always cache the field normalization values in memory\nfor all fields by default. This can improve the performance of scoring and\nranking queries. Otherwise, these values are memory-mapped and it is up to the\noperating system to load them from disk into memory and to evict them from memory.\n\nNormalization values are computed for fields which are processed with Analyzers\nthat have the `\"norm\"` feature enabled. These values are used to score fairer if\nthe same tokens occur repeatedly, to emphasize these documents less.\n\nYou can also enable this option to always cache auxiliary data used for querying\nfields that are indexed with Geo Analyzers in memory for all fields by default.\nThis can improve the performance of geo-spatial queries.\n\nSee the `--arangosearch.columns-cache-limit` startup option to control the\nmemory consumption of this cache. You can reduce the memory usage of the column\ncache in cluster deployments by only using the cache for leader shards, see the\n`--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6).\n", "type": "boolean" }, "cleanupIntervalStep": { "default": 2, "description": "Wait at least this many commits between removing unused files in the\nArangoSearch data directory (set to `0` to disable).\nFor the case where the consolidation policies merge segments often (i.e. a lot\nof commit+consolidate), a lower value causes a lot of disk space to be\nwasted.\nFor the case where the consolidation policies rarely merge segments (i.e. few\ninserts/deletes), a higher value impacts performance without any added\nbenefits.\n\n_Background:_\n With every \"commit\" or \"consolidate\" operation, a new state of the\n inverted index' internal data structures is created on disk.\n Old states/snapshots are released once there are no longer any users\n remaining.\n However, the files for the released states/snapshots are left on disk, and\n only removed by \"cleanup\" operation.\n", "type": "integer" }, "commitIntervalMsec": { "default": 1000, "description": "Wait at least this many milliseconds between committing inverted index data store\nchanges and making documents visible to queries (set to `0` to disable).\nFor the case where there are a lot of inserts/updates, a higher value causes the\nindex not to account for them and memory usage continues to grow until the commit.\nA lower value impacts performance, including the case where there are no or only a\nfew inserts/updates because of synchronous locking, and it wastes disk space for\neach commit call.\n\n_Background:_\n For data retrieval, ArangoSearch follows the concept of\n \"eventually-consistent\", i.e. eventually all the data in ArangoDB will be\n matched by corresponding query expressions.\n The concept of ArangoSearch \"commit\" operations is introduced to\n control the upper-bound on the time until document addition/removals are\n actually reflected by corresponding query expressions.\n Once a \"commit\" operation is complete, all documents added/removed prior to\n the start of the \"commit\" operation will be reflected by queries invoked in\n subsequent ArangoDB transactions, in-progress ArangoDB transactions will\n still continue to return a repeatable-read state.\n", "type": "integer" }, "consolidationIntervalMsec": { "default": 5000, "description": "Wait at least this many milliseconds between applying `consolidationPolicy` to\nconsolidate the inverted index data store and possibly release space on the filesystem\n(set to `0` to disable).\nFor the case where there are a lot of data modification operations, a higher\nvalue could potentially have the data store consume more space and file handles.\nFor the case where there are a few data modification operations, a lower value\nimpacts performance due to no segment candidates being available for\nconsolidation.\n\n_Background:_\n For data modification, ArangoSearch follows the concept of a\n \"versioned data store\". Thus old versions of data may be removed once there\n are no longer any users of the old data. The frequency of the cleanup and\n compaction operations are governed by `consolidationIntervalMsec` and the\n candidates for compaction are selected via `consolidationPolicy`.\n", "type": "integer" }, "consolidationPolicy": { "description": "The consolidation policy to apply for selecting which segments should be merged.\n\n_Background:_\n With each ArangoDB transaction that inserts documents, one or more\n ArangoSearch-internal segments get created.\n Similarly, for removed documents, the segments that contain such documents\n have these documents marked as 'deleted'.\n Over time, this approach causes a lot of small and sparse segments to be\n created.\n A \"consolidation\" operation selects one or more segments and copies all of\n their valid documents into a single new segment, thereby allowing the\n search algorithm to perform more optimally and for extra file handles to be\n released once old segments are no longer used.\n", "properties": { "maxSkewThreshold": { "default": 0.4, "description": "This option is available from v3.12.7 onward:\n\nThe skew describes how much segment files vary in file size. It is a number\nbetween `0.0` and `1.0` and is calculated by dividing the largest file size\nof a set of segment files by the total size. For example, the skew of a\n200 MiB, 300 MiB, and 500 MiB segment file is `0.5` (`500 / 1000`).\n\nA large `maxSkewThreshold` value allows merging large segment files with\nsmaller ones, consolidation occurs more frequently, and there are fewer\nsegment files on disk at all times. While this may potentially improve the\nread performance and use fewer file descriptors, frequent consolidations\ncause a higher write load and thus a higher write amplification.\n\nOn the other hand, a small threshold value triggers the consolidation only\nwhen there are a large number of segment files that don't vary in size a lot.\nConsolidation occurs less frequently, reducing the write amplification, but\nit can result in a greater number of segment files on disk.\n\nMultiple combinations of candidate segments are checked and the one with\nthe lowest skew value is selected for consolidation. The selection process\npicks the greatest number of segments that together have the lowest skew value\nwhile ensuring that the size of the new consolidated segment remains under\nthe configured `segmentsBytesMax`.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minDeletionRatio": { "default": 0.5, "description": "This option is available from v3.12.7 onward:\n\nThe `minDeletionRatio` represents the minimum required deletion ratio\nin one or more segments to perform a cleanup of those segments.\nIt is a number between `0.0` and `1.0`.\n\nThe deletion ratio is the percentage of deleted documents across one or\nmore segment files and is calculated by dividing the number of deleted\ndocuments by the total number of documents in a segment or a group of\nsegments. For example, if there is a segment with 1000 documents of which\n300 are deleted and another segment with 1000 documents of which 700 are\ndeleted, the deletion ratio is `0.5` (50%, calculated as `1000 / 2000`).\n\nThe `minDeletionRatio` threshold must be carefully selected. A smaller\nvalue leads to earlier cleanup of deleted documents from segments and\nthus reclamation of disk space but it generates a higher write load.\nA very large value lowers the write amplification but at the same time\nthe system can be left with a large number of segment files with a high\npercentage of deleted documents that occupy disk space unnecessarily.\n\nDuring cleanup, the segment files are first arranged in decreasing\norder of their individual deletion ratios. Then the largest subset of\nsegments whose collective deletion ratio is greater than or equal to\n`minDeletionRatio` is picked.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minScore": { "default": 0, "description": "This option is only available up to v3.12.6:\n\nFilter out consolidation candidates with a score less than this.\n", "type": "integer" }, "segmentsBytesFloor": { "default": 25165824, "description": "This option is only available up to v3.12.6:\n\nDefines the value (in bytes) to treat all smaller segments as equal for\nconsolidation selection.\n", "type": "integer" }, "segmentsBytesMax": { "default": 8589934592, "description": "The maximum allowed size of all consolidated segments in bytes.\n", "type": "integer" }, "segmentsMax": { "default": 200, "description": "This option is only available up to v3.12.6:\n\nThe maximum number of segments that are evaluated as candidates for\nconsolidation.\n", "type": "integer" }, "segmentsMin": { "default": 50, "description": "This option is only available up to v3.12.6:\n\nThe minimum number of segments that are evaluated as candidates for\nconsolidation.\n", "type": "integer" }, "type": { "default": "tier", "description": "The segment candidates for the \"consolidation\" operation are selected based\nupon several possible configurable formulas as defined by their types.\nThe supported types are:\n\n- `\"tier\"`: consolidate based on segment byte size skew and live\n document count as dictated by the customization attributes.\n", "type": "string" } }, "type": "object" }, "features": { "description": "A list of Analyzer features. You can set this option to overwrite what features\nare enabled for the default `analyzer`.\n\nDefault: the features as defined by the Analyzer itself.\n", "items": { "enum": [ "frequency", "norm", "position", "offset" ], "type": "string" }, "type": "array", "uniqueItems": true }, "fields": { "description": "An array of attribute paths. You can use strings to index the fields with the\ndefault options, or objects to specify options for the fields (with the\nattribute path in the `name` property), or a mix of both.\n", "items": { "properties": { "analyzer": { "description": "The name of an Analyzer to use for this field.\n\nDefault: the value defined by the top-level `analyzer` option.\n", "type": "string" }, "cache": { "description": "Enable this option to always cache the field normalization values in memory\nfor this specific field. This can improve the performance of scoring and\nranking queries. Otherwise, these values are memory-mapped and it is up to the\noperating system to load them from disk into memory and to evict them from memory.\n\nNormalization values are computed for fields which are processed with Analyzers\nthat have the `\"norm\"` feature enabled. These values are used to score fairer if\nthe same tokens occur repeatedly, to emphasize these documents less.\n\nYou can also enable this option to always cache auxiliary data used for querying\nfields that are indexed with Geo Analyzers in memory for this specific field.\nThis can improve the performance of geo-spatial queries.\n\nDefault: the value defined by the top-level `cache` option.\n\nSee the `--arangosearch.columns-cache-limit` startup option to control the\nmemory consumption of this cache. You can reduce the memory usage of the column\ncache in cluster deployments by only using the cache for leader shards, see the\n`--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6).\n", "type": "boolean" }, "features": { "description": "A list of Analyzer features to use for this field. You can set this option to\noverwrite what features are enabled for the `analyzer`.\n\nDefault: the features as defined by the Analyzer itself, or inherited from the\ntop-level `features` option if the `analyzer` option adjacent to this option is\nnot set.\n", "items": { "enum": [ "frequency", "norm", "position", "offset" ], "type": "string" }, "type": "array", "uniqueItems": true }, "includeAllFields": { "description": "This option only applies if you use the inverted index in a `search-alias` Views.\n\nIf set to `true`, then all sub-attributes of this field are indexed, excluding\nany sub-attributes that are configured separately by other elements in the\n`fields` array (and their sub-attributes). The `analyzer` and `features`\nproperties apply to the sub-attributes.\n\nIf set to `false`, then sub-attributes are ignored.\n\nDefault: the value defined by the top-level `includeAllFields` option.\n", "type": "boolean" }, "name": { "description": "An attribute path. The `.` character denotes sub-attributes.\nYou can expand one array attribute with `[*]`.\n", "type": "string" }, "nested": { "description": "Index the specified sub-objects that are stored in an array. Other than with the\n`fields` property, the values get indexed in a way that lets you query for\nco-occurring values. For example, you can search the sub-objects and all the\nconditions need to be met by a single sub-object instead of across all of them.\n", "items": { "properties": { "analyzer": { "description": "The name of an Analyzer to use for this field.\nDefault: the value defined by the parent field, or the top-level `analyzer` option.\n", "type": "string" }, "cache": { "description": "Enable this option to always cache the field normalization values in memory\nfor this specific nested field. This can improve the performance of scoring and\nranking queries. Otherwise, these values are memory-mapped and it is up to the\noperating system to load them from disk into memory and to evict them from memory.\n\nNormalization values are computed for fields which are processed with Analyzers\nthat have the `\"norm\"` feature enabled. These values are used to score fairer if\nthe same tokens occur repeatedly, to emphasize these documents less.\n\nYou can also enable this option to always cache auxiliary data used for querying\nfields that are indexed with Geo Analyzers in memory for this specific nested field.\nThis can improve the performance of geo-spatial queries.\n\nDefault: the value defined by the top-level `cache` option.\n\nSee the `--arangosearch.columns-cache-limit` startup option to control the\nmemory consumption of this cache. You can reduce the memory usage of the column\ncache in cluster deployments by only using the cache for leader shards, see the\n`--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6).\n", "type": "boolean" }, "features": { "description": "A list of Analyzer features to use for this field. You can set this option to\noverwrite what features are enabled for the `analyzer`.\n\nDefault: the features as defined by the Analyzer itself, or inherited from the\nparent field's or top-level `features` option if no `analyzer` option is set\nat a deeper level, closer to this option.\n", "items": { "enum": [ "frequency", "norm", "position", "offset" ], "type": "string" }, "type": "array", "uniqueItems": true }, "name": { "description": "An attribute path. The `.` character denotes sub-attributes.\n", "type": "string" }, "nested": { "description": "You can recursively index sub-objects. See the above description of the\n`nested` option.\n", "items": { "type": "object" }, "type": "array" }, "searchField": { "description": "This option only applies if you use the inverted index in a `search-alias` Views.\n\nYou can set the option to `true` to get the same behavior as with `arangosearch`\nViews regarding the indexing of array values for this field. If enabled, both,\narray and primitive values (strings, numbers, etc.) are accepted. Every element\nof an array is indexed according to the `trackListPositions` option.\n\nIf set to `false`, it depends on the attribute path. If it explicitly expands an\narray (`[*]`), then the elements are indexed separately. Otherwise, the array is\nindexed as a whole, but only `geopoint` and `aql` Analyzers accept array inputs.\nYou cannot use an array expansion if `searchField` is enabled.\n\nDefault: the value defined by the top-level `searchField` option.\n", "type": "boolean" } }, "required": [ "name" ], "type": "object" }, "type": "array" }, "searchField": { "description": "This option only applies if you use the inverted index in a `search-alias` Views.\n\nYou can set the option to `true` to get the same behavior as with `arangosearch`\nViews regarding the indexing of array values for this field. If enabled, both,\narray and primitive values (strings, numbers, etc.) are accepted. Every element\nof an array is indexed according to the `trackListPositions` option.\n\nIf set to `false`, it depends on the attribute path. If it explicitly expands an\narray (`[*]`), then the elements are indexed separately. Otherwise, the array is\nindexed as a whole, but only `geopoint` and `aql` Analyzers accept array inputs.\nYou cannot use an array expansion if `searchField` is enabled.\n\nDefault: the value defined by the top-level `searchField` option.\n", "type": "boolean" }, "trackListPositions": { "description": "This option only applies if you use the inverted index in a `search-alias` Views,\nand `searchField` needs to be `true`.\n\nIf set to `true`, then track the value position in arrays for array values.\nFor example, when querying a document like `{ attr: [ \"valueX\", \"valueY\", \"valueZ\" ] }`,\nyou need to specify the array element, e.g. `doc.attr[1] == \"valueY\"`.\n\nIf set to `false`, all values in an array are treated as equal alternatives.\nYou don't specify an array element in queries, e.g. `doc.attr == \"valueY\"`, and\nall elements are searched for a match.\n\nDefault: the value defined by the top-level `trackListPositions` option.\n", "type": "boolean" } }, "required": [ "name" ], "type": "object" }, "minItems": 1, "type": "array", "uniqueItems": true }, "inBackground": { "default": false, "description": "Set this option to `true` to keep the collection/shards available for\nwrite operations by not using an exclusive write lock for the duration\nof the index creation.\n", "type": "boolean" }, "includeAllFields": { "default": false, "description": "This option only applies if you use the inverted index in a `search-alias` Views.\n\nIf set to `true`, then all document attributes are indexed, excluding any\nsub-attributes that are configured in the `fields` array (and their sub-attributes).\nThe `analyzer` and `features` properties apply to the sub-attributes.\n\n\u003e **WARNING:**\nUsing `includeAllFields` for a lot of attributes in combination\nwith complex Analyzers may significantly slow down the indexing process.\n", "type": "boolean" }, "name": { "description": "An easy-to-remember name for the index to look it up or refer to it in index hints.\nIndex names are subject to the same character restrictions as collection names.\nIf omitted, a name is auto-generated so that it is unique with respect to the\ncollection, e.g. `idx_832910498`.\n", "type": "string" }, "optimizeTopK": { "default": [], "description": "This option only applies if you use the inverted index in a `search-alias` Views.\n\nAn array of strings defining sort expressions that you want to optimize.\nThis is also known as _WAND optimization_ (introduced in v3.12.0).\n\nIf you query a View with the `SEARCH` operation in combination with a\n`SORT` and `LIMIT` operation, search results can be retrieved faster if the\n`SORT` expression matches one of the optimized expressions.\n\nOnly sorting by highest rank is supported, that is, sorting by the result\nof a scoring function in descending order (`DESC`). Use `@doc` in the expression\nwhere you would normally pass the document variable emitted by the `SEARCH`\noperation to the scoring function.\n\nYou can define up to 64 expressions per View.\n\nExample: `[\"BM25(@doc) DESC\", \"TFIDF(@doc, true) DESC\"]`\n", "items": { "type": "string" }, "type": "array" }, "parallelism": { "default": 2, "description": "The number of threads to use for indexing the fields.\n", "type": "integer" }, "primaryKeyCache": { "default": false, "description": "Enable this option to always cache the primary key column in memory. This can\nimprove the performance of queries that return many documents. Otherwise, these\nvalues are memory-mapped and it is up to the operating system to load them from\ndisk into memory and to evict them from memory.\n\nSee the `--arangosearch.columns-cache-limit` startup option to control the\nmemory consumption of this cache. You can reduce the memory usage of the column\ncache in cluster deployments by only using the cache for leader shards, see the\n`--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6).\n", "type": "boolean" }, "primarySort": { "description": "You can define a primary sort order to enable an AQL optimization. If a query\niterates over all documents of a collection, wants to sort them by attribute values,\nand the (left-most) fields to sort by, as well as their sorting direction, match\nwith the `primarySort` definition, then the `SORT` operation is optimized away.\n", "properties": { "cache": { "default": false, "description": "Enable this option to always cache the primary sort columns in memory. This can\nimprove the performance of queries that utilize the primary sort order.\nOtherwise, these values are memory-mapped and it is up to the operating system\nto load them from disk into memory and to evict them from memory.\n\nSee the `--arangosearch.columns-cache-limit` startup option to control the\nmemory consumption of this cache. You can reduce the memory usage of the column\ncache in cluster deployments by only using the cache for leader shards, see the\n`--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6).\n", "type": "boolean" }, "compression": { "default": "lz4", "description": "Defines how to compress the primary sort data.\n- `\"lz4\"`: use LZ4 fast compression.\n- `\"none\"`: disable compression to trade space for speed.\n", "enum": [ "lz4", "none" ], "type": "string" }, "fields": { "description": "An array of the fields to sort the index by and the direction to sort each field in.\n", "items": { "properties": { "direction": { "description": "The sorting direction.\n- `\"asc` for ascending\n- `\"desc\"` for descending\n", "enum": [ "asc", "desc" ], "type": "string" }, "field": { "description": "An attribute path. The `.` character denotes sub-attributes.\n", "type": "string" } }, "required": [ "field", "direction" ], "type": "object" }, "type": "array" } }, "required": [ "fields" ], "type": "object" }, "searchField": { "default": false, "description": "This option only applies if you use the inverted index in a `search-alias` Views.\n\nYou can set the option to `true` to get the same behavior as with `arangosearch`\nViews regarding the indexing of array values as the default. If enabled, both,\narray and primitive values (strings, numbers, etc.) are accepted. Every element\nof an array is indexed according to the `trackListPositions` option.\n\nIf set to `false`, it depends on the attribute path. If it explicitly expands an\narray (`[*]`), then the elements are indexed separately. Otherwise, the array is\nindexed as a whole, but only `geopoint` and `aql` Analyzers accept array inputs.\nYou cannot use an array expansion if `searchField` is enabled.\n", "type": "boolean" }, "storedValues": { "description": "The optional `storedValues` attribute can contain an array of objects with paths\nto additional attributes to store in the index. These additional attributes\ncannot be used for index lookups or for sorting, but they can be used for\nprojections. This allows an index to fully cover more queries and avoid extra\ndocument lookups.\n\nYou may use the following shorthand notations on index creation instead of\nan array of objects. The default compression and cache settings are used in\nthis case:\n\n- An array of strings, like `[\"attr1\", \"attr2\"]`, to place each attribute into\n a separate column of the index (introduced in v3.10.3).\n\n- An array of arrays of strings, like `[[\"attr1\", \"attr2\"]]`, to place the\n attributes into a single column of the index, or `[[\"attr1\"], [\"attr2\"]]`\n to place each attribute into a separate column. You can also mix it with the\n full form:\n\n ```json\n [\n [\"attr1\"],\n [\"attr2\", \"attr3\"],\n { \"fields\": [\"attr4\", \"attr5\"], \"cache\": true }\n ]\n ```\n", "items": { "properties": { "cache": { "default": false, "description": "Enable this option to always cache stored values in memory. This can improve the\nquery performance if stored values are involved. Otherwise, these values are\nmemory-mapped and it is up to the operating system to load them from disk into\nmemory and to evict them from memory.\n\nSee the `--arangosearch.columns-cache-limit` startup option to control the\nmemory consumption of this cache. You can reduce the memory usage of the column\ncache in cluster deployments by only using the cache for leader shards, see the\n`--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6).\n", "type": "boolean" }, "compression": { "default": "lz4", "description": "Defines how to compress the attribute values.\n- `\"lz4\"`: use LZ4 fast compression.\n- `\"none\"`: disable compression to trade space for speed.\n", "enum": [ "lz4", "none" ], "type": "string" }, "fields": { "description": "A list of attribute paths. The `.` character denotes sub-attributes.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "fields" ], "type": "object" }, "type": "array" }, "trackListPositions": { "default": false, "description": "This option only applies if you use the inverted index in a `search-alias` Views,\nand `searchField` needs to be `true`.\n\nIf set to `true`, then track the value position in arrays for array values.\nFor example, when querying a document like `{ attr: [ \"valueX\", \"valueY\", \"valueZ\" ] }`,\nyou need to specify the array element, e.g. `doc.attr[1] == \"valueY\"`.\n\nIf set to `false`, all values in an array are treated as equal alternatives.\nYou don't specify an array element in queries, e.g. `doc.attr == \"valueY\"`, and\nall elements are searched for a match.\n", "type": "boolean" }, "type": { "description": "Needs to be set to `\"inverted\"`.\n", "example": "inverted", "type": "string" }, "writebufferActive": { "default": 0, "description": "Maximum number of concurrent active writers (segments) that perform a\ntransaction. Other writers (segments) wait till current active writers\n(segments) finish (set to `0` to disable).\n", "type": "integer" }, "writebufferIdle": { "default": 64, "description": "Maximum number of writers (segments) cached in the pool\n(set to `0` to disable).\n", "type": "integer" }, "writebufferSizeMax": { "default": 33554432, "description": "Maximum memory byte size per writer (segment) before a writer (segment) flush\nis triggered. `0` value turns off this limit for any writer (buffer) and data\nis flushed periodically based on the value defined for the flush thread\n(ArangoDB server startup option). `0` value should be used carefully due to\nhigh potential memory consumption (set to `0 `to disable).\n", "type": "integer" } }, "required": [ "type", "fields" ], "type": "object" } } } }, "responses": { "200": { "description": "The index exists already.\n" }, "201": { "description": "The index is created as there is no such existing index.\n" }, "404": { "description": "The collection is unknown.\n" } }, "summary": "Create an inverted index", "tags": [ "Indexes" ] } }, "/_db/{database-name}/_api/index#mdi": { "post": { "description": "Creates a multi-dimensional index for the collection `collection-name`, if\nit does not already exist.\n", "operationId": "createIndexMdi", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The collection name.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "estimates": { "default": true, "description": "This attribute controls whether index selectivity estimates are maintained for the\nindex. Not maintaining index selectivity estimates can have a slightly positive\nimpact on write performance.\n\nThe downside of turning off index selectivity estimates is that\nthe query optimizer is not able to determine the usefulness of different\ncompeting indexes in AQL queries when there are multiple candidate indexes to\nchoose from.\n\nThe `estimates` attribute is optional and defaults to `true` if not set.\nIt has no effect on indexes other than `persistent`, `mdi`, and `mdi-prefixed`.\nIt cannot be disabled for non-unique `mdi` indexes because they have a fixed\nselectivity estimate of `1`.\n", "type": "boolean" }, "fieldValueTypes": { "description": "Needs to be set to `\"double\"`. Currently only doubles are supported as values.\n", "type": "string" }, "fields": { "description": "An array of attribute names used for each dimension. Array expansions are not allowed.\n", "items": { "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "inBackground": { "default": false, "description": "Set this option to `true` to keep the collection/shards available for\nwrite operations by not using an exclusive write lock for the duration\nof the index creation.\n", "type": "boolean" }, "name": { "description": "An easy-to-remember name for the index to look it up or refer to it in index hints.\nIndex names are subject to the same character restrictions as collection names.\nIf omitted, a name is auto-generated so that it is unique with respect to the\ncollection, e.g. `idx_832910498`.\n", "type": "string" }, "prefixFields": { "description": "Requires `type` to be `\"mdi-prefixed\"`, and `prefixFields` needs to be set in this case.\n\nAn array of attribute names used as search prefix. Array expansions are not allowed.\n", "items": { "type": "string" }, "type": "array", "uniqueItems": true }, "sparse": { "default": false, "description": "Whether to create a sparse index that excludes documents with\nat least one of the attributes for indexing missing or set to\n`null`. These attributes are defined by `fields` and (for\n`mdi-prefixed` indexes) by `prefixFields`.\n", "type": "boolean" }, "storedValues": { "description": "The optional `storedValues` attribute can contain an array of paths to additional\nattributes to store in the index. These additional attributes cannot be used for\nindex lookups or for sorting, but they can be used for projections. This allows an\nindex to fully cover more queries and avoid extra document lookups.\n\nYou can have the same attributes in `storedValues` and `fields` as the attributes\nin `fields` cannot be used for projections, but you can also store additional\nattributes that are not listed in `fields`.\nAttributes in `storedValues` cannot overlap with the attributes specified in\n`prefixFields`. There is no reason to store them in the index because you need\nto specify them in queries in order to use `mdi-prefixed` indexes.\n\nYou cannot create multiple multi-dimensional indexes with the same `sparse`,\n`unique`, `fields` and (for `mdi-prefixed` indexes) `prefixFields` attributes\nbut different `storedValues` settings. That means the value of `storedValues` is\nnot considered by index creation calls when checking if an index is already\npresent or needs to be created.\n\nIn unique indexes, only the index attributes in `fields` and (for `mdi-prefixed`\nindexes) `prefixFields` are checked for uniqueness. The index attributes in\n`storedValues` are not checked for their uniqueness.\n\nNon-existing attributes are stored as `null` values inside `storedValues`.\n\nThe maximum number of attributes in `storedValues` is 32.\n", "items": { "type": "string" }, "type": "array", "uniqueItems": true }, "type": { "description": "Needs to be set to `\"mdi\"` or `\"mdi-prefixed\"`.\n", "example": "mdi", "type": "string" }, "unique": { "default": false, "description": "if `true`, then create a unique index.\n", "type": "boolean" } }, "required": [ "type", "fields", "fieldValueTypes" ], "type": "object" } } } }, "responses": { "200": { "description": "The index exists already.\n" }, "201": { "description": "The index is created as there is no such existing index.\n" }, "400": { "description": "The index definition is invalid.\n" }, "404": { "description": "The collection is unknown.\n" } }, "summary": "Create a multi-dimensional index", "tags": [ "Indexes" ] } }, "/_db/{database-name}/_api/index#persistent": { "post": { "description": "Creates a persistent index for the collection `collection-name`, if\nit does not already exist.\n\nIn a sparse index all documents will be excluded from the index that do not\ncontain at least one of the specified index attributes (i.e. `fields`) or that\nhave a value of `null` in any of the specified index attributes. Such documents\nwill not be indexed, and not be taken into account for uniqueness checks if\nthe `unique` flag is set.\n\nIn a non-sparse index, these documents will be indexed (for non-present\nindexed attributes, a value of `null` will be used) and will be taken into\naccount for uniqueness checks if the `unique` flag is set.\n\n\u003e **INFO:**\nUnique indexes on non-shard keys are not supported in cluster deployments.\n", "operationId": "createIndexPersistent", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The collection name.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cacheEnabled": { "default": false, "description": "This attribute controls whether an extra in-memory hash cache is\ncreated for the index. The hash cache can be used to speed up index lookups.\nThe cache can only be used for queries that look up all index attributes via\nan equality lookup (`==`). The hash cache cannot be used for range scans,\npartial lookups or sorting.\n\nThe cache will be populated lazily upon reading data from the index. Writing data\ninto the collection or updating existing data will invalidate entries in the\ncache. The cache may have a negative effect on performance in case index values\nare updated more often than they are read.\n\nThe maximum size of cache entries that can be stored is currently 4 MB, i.e.\nthe cumulated size of all index entries for any index lookup value must be\nless than 4 MB. This limitation is there to avoid storing the index entries\nof \"super nodes\" in the cache.\n\n`cacheEnabled` defaults to `false` and should only be used for indexes that\nare known to benefit from an extra layer of caching.\n", "type": "boolean" }, "deduplicate": { "default": true, "description": "The attribute controls whether inserting duplicate index values\nfrom the same document into a unique array index lead to a unique constraint\nerror or not. Only a single instance of each non-unique index value\nis inserted into the index per document by default. Trying to\ninsert a value into the index that already exists in the index always fails,\nregardless of the value of this attribute.\n", "type": "boolean" }, "estimates": { "default": true, "description": "This attribute controls whether index selectivity estimates are maintained for the\nindex. Not maintaining index selectivity estimates can have a slightly positive\nimpact on write performance.\n\nThe downside of turning off index selectivity estimates is that\nthe query optimizer is not able to determine the usefulness of different\ncompeting indexes in AQL queries when there are multiple candidate indexes to\nchoose from.\n\nThe option has no effect on indexes other than `persistent`, `mdi`, and `mdi-prefixed`.\n", "type": "boolean" }, "fields": { "description": "An array of attribute paths.\n\nThe `.` character denotes sub-attributes in attribute paths. Attributes with\nliteral `.` in their name cannot be indexed. Attributes with the name `_id`\ncannot be indexed either, neither as a top-level attribute nor as a sub-attribute.\n\nYou can expand one array attribute with `[*]`.\n", "items": { "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "inBackground": { "default": false, "description": "Set this option to `true` to keep the collection/shards available for\nwrite operations by not using an exclusive write lock for the duration\nof the index creation.\n", "type": "boolean" }, "name": { "description": "An easy-to-remember name for the index to look it up or refer to it in index hints.\nIndex names are subject to the same character restrictions as collection names.\nIf omitted, a name is auto-generated so that it is unique with respect to the\ncollection, e.g. `idx_832910498`.\n", "type": "string" }, "sparse": { "default": false, "description": "Whether to create a sparse index that excludes documents with\nat least one of the attributes for indexing missing or set to\n`null`. These attributes are defined by `fields`.\n", "type": "boolean" }, "storedValues": { "description": "The optional `storedValues` attribute can contain an array of paths to additional\nattributes to store in the index. These additional attributes cannot be used for\nindex lookups or for sorting, but they can be used for projections. This allows an\nindex to fully cover more queries and avoid extra document lookups.\nThe maximum number of attributes in `storedValues` is 32.\n\nIt is not possible to create multiple indexes with the same `fields` attributes\nand uniqueness but different `storedValues` attributes. That means the value of\n`storedValues` is not considered by index creation calls when checking if an\nindex is already present or needs to be created.\n\nIn unique indexes, only the attributes in `fields` are checked for uniqueness,\nbut the attributes in `storedValues` are not checked for their uniqueness.\nNon-existing attributes are stored as `null` values inside `storedValues`.\n", "items": { "type": "string" }, "type": "array" }, "type": { "description": "Needs to be set to `\"persistent\"`.\n", "example": "persistent", "type": "string" }, "unique": { "default": false, "description": "Whether to create the index with a uniqueness constraint.\nIn unique indexes, only the attributes in `fields` are checked for uniqueness,\nbut the attributes in `storedValues` are not checked for their uniqueness.\n", "type": "boolean" } }, "required": [ "type", "fields" ], "type": "object" } } } }, "responses": { "200": { "description": "The index exists already.\n" }, "201": { "description": "The index is created as there is no such existing index.\n" }, "400": { "description": "You try to create a unique persistent index but there are already\ndocuments in the collection that violate the uniqueness requirement.\n" }, "404": { "description": "The collection is unknown.\n" } }, "summary": "Create a persistent index", "tags": [ "Indexes" ] } }, "/_db/{database-name}/_api/index#ttl": { "post": { "description": "Creates a time-to-live (TTL) index for the collection `collection-name` if it\ndoes not already exist.\n", "operationId": "createIndexTtl", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The collection name.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "expireAfter": { "description": "The time interval (in seconds) from the point in time stored in the `fields`\nattribute after which the documents count as expired. Can be set to `0` to let\ndocuments expire as soon as the server time passes the point in time stored in\nthe document attribute, or to a higher number to delay the expiration.\n", "type": "number" }, "fields": { "description": "A list with exactly one attribute path.\n", "items": { "type": "string" }, "maxItems": 1, "minItems": 1, "type": "array" }, "inBackground": { "default": false, "description": "Set this option to `true` to keep the collection/shards available for\nwrite operations by not using an exclusive write lock for the duration\nof the index creation.\n", "type": "boolean" }, "name": { "description": "An easy-to-remember name for the index to look it up or refer to it in index hints.\nIndex names are subject to the same character restrictions as collection names.\nIf omitted, a name is auto-generated so that it is unique with respect to the\ncollection, e.g. `idx_832910498`.\n", "type": "string" }, "type": { "description": "Needs to be set to `\"ttl\"`.\n", "type": "string" } }, "required": [ "type", "fields", "expireAfter" ], "type": "object" } } } }, "responses": { "200": { "description": "The index exists already.\n" }, "201": { "description": "The index is created as there is no such existing index.\n" }, "400": { "description": "There is already a TTL index for the collection but there can only be one.\n" }, "404": { "description": "The collection is unknown.\n" } }, "summary": "Create a TTL index", "tags": [ "Indexes" ] } }, "/_db/{database-name}/_api/index#vector": { "post": { "description": "Creates a vector index for the collection `collection-name`, if\nit does not already exist.\n", "operationId": "createIndexVector", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The collection name.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "fields": { "description": "A list with exactly one attribute path to specify\nwhere the vector embedding is stored in each document.\n\nIf you want to index another vector embedding attribute, you need to create a\nseparate vector index.\n\nUp to ArangoDB v3.12.8, the vector data needs to be populated before creating\nthe index. From v3.12.9 onward, you can create the vector index first and then\npopulate the collection with vector data. However, it is still recommended to\nload the data first and then create the index to ensure that all documents\nparticipate in the training process as the training is only executed once.\nThe training is triggered automatically if the vector index hasn't been\ntrained yet and the number of documents to index exceeds the threshold of\n`nLists` documents. If `sparse` is set to `true`, documents without the\nvector embedding field are not counted toward this threshold.\nCheck the `trainingState` to see if the index is\n`\"ready\"` and `errorMessage` for the reason if it's not.\n", "items": { "type": "string" }, "maxItems": 1, "minItems": 1, "type": "array" }, "inBackground": { "default": false, "description": "Set this option to `true` to keep the collection/shards available for\nwrite operations by not using an exclusive write lock for the duration\nof the index creation.\n\nIf the option is disabled, the call returns only after the index is\nready (but timeouts may occur), or if an error is encountered.\n", "type": "boolean" }, "name": { "description": "A user-defined name for the index for easier\nidentification. If not specified, a name is automatically generated.\n", "type": "string" }, "parallelism": { "default": 2, "description": "The number of threads to use for indexing.\n", "type": "integer" }, "params": { "description": "The parameters as used by the Faiss library.\n", "properties": { "defaultNProbe": { "default": 1, "description": "How many neighboring centroids to\nconsider for the search results by default. The larger the number, the slower\nthe search but the better the search results. The default is `1`. You should\ngenerally use a higher value here or per query via the `nProbe` option of\nthe vector similarity functions.\n", "type": "integer" }, "dimension": { "description": "The vector dimension. The attribute to index needs to\nhave this many elements in the array that stores the vector embedding.\n", "type": "integer" }, "factory": { "description": "You can specify an index factory string that is\nforwarded to the underlying Faiss library, allowing you to combine different\nadvanced options. Examples:\n- `\"IVF100_HNSW10,Flat\"`\n- `\"IVF100,SQ4\"`\n- `\"IVF10_HNSW5,Flat\"`\n- `\"IVF100_HNSW5,PQ256x16\"`\n\nThe base index must be an inverted file (IVF) to work with ArangoDB.\nIf you don't specify an index factory, the value is equivalent to\n`IVF\u003cnLists\u003e,Flat`. For more information on how to create these custom\nindexes, see the [Faiss Wiki](https://github.com/facebookresearch/faiss/wiki/The-index-factory).\n", "type": "string" }, "metric": { "description": "The measure for calculating the vector similarity:\n- `\"cosine\"`: Angular similarity. Vectors are automatically\n normalized before insertion and search.\n- `\"innerProduct\"` (introduced in v3.12.6):\n Similarity in terms of angle and magnitude.\n Vectors are not normalized, making it faster than `cosine`.\n- `\"l2\":` Euclidean distance.\n", "enum": [ "cosine", "innerProduct", "l2" ] }, "nLists": { "description": "The number of Voronoi cells to partition the vector space\ninto, respectively the number of centroids in the index. What value to choose\ndepends on the data distribution and chosen metric. According to\n[The Faiss library paper](https://arxiv.org/abs/2401.08281), it should scale\nsublinearly with the document count. The recommendation for ArangoDB is to use\napproximately `15 * sqrt(N)` where `N` is the number of documents in the collection,\nrespectively the number of documents in the shard for cluster deployments.\nA bigger value produces more correct results but increases the training time\nand thus how long it takes to build the index. It cannot be bigger than the\nnumber of documents.\n", "type": "integer" }, "numberOfDocsPerCentroid": { "default": 100, "description": "How many vectors per centroid to include in the random sample used for\ntraining. It must be `1` or greater.\n\nUp to v3.12.9, this is not configurable and a fixed value of `256` per\ncentroid is used instead.\n\nThe training does not use the full dataset but a sample bounded to\n`nLists` × `numberOfDocsPerCentroid` vectors. A larger value can improve the\ntraining quality but increases the memory and time required for training.\nSee [Resource usage during index creation](https://docs.arango.ai/arangodb/3.12/indexes-and-search/indexing/working-with-indexes/vector-indexes/#resource-usage-during-index-creation)\nfor details.\n", "minimum": 1, "type": "integer" }, "trainingIterations": { "default": 25, "description": "The number of iterations in the\ntraining process. The default is `25`. Smaller values lead to a faster index\ncreation but may yield worse search results.\n", "type": "integer" } }, "required": [ "metric", "dimension", "nLists" ], "type": "object" }, "sparse": { "default": false, "description": "Whether to create a sparse index that excludes documents with\nthe attribute for indexing missing or set to `null`. This\nattribute is defined by `fields`.\n", "type": "boolean" }, "storedValues": { "description": "Store additional attributes in the index (introduced in v3.12.7).\nUnlike with other index types, this is not for covering projections\nwith the index but for adding attributes that you filter on.\nThis lets you make the lookup in the vector index more efficient\nbecause it avoids materializing documents twice, once for the\nfiltering and once for the matches.\n\nThe maximum number of attributes that you can use in `storedValues` is 32.\n", "items": { "description": "A list of attribute paths. The `.` character denotes sub-attributes.\ntype: string\n", "type": "string" }, "type": "array", "uniqueItems": true }, "type": { "description": "The index type. Needs to be `\"vector\"`.\n", "example": "vector", "type": "string" } }, "required": [ "type", "fields", "params" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "errorMessage": { "description": "An optional message with details about the\ntraining state, for example, `\"not enough training data for vector index\"`.\nOnly present if there is a problem with the index.\n", "type": "string" }, "fields": { "description": "The list with exactly one attribute path the index is created on.\n", "items": { "type": "string" }, "maxItems": 1, "minItems": 1, "type": "array" }, "id": { "description": "The identifier of the index in the format `\u003ccollection-name\u003e/\u003cindex-identifier\u003e`.\n", "example": "products/68", "type": "string" }, "isNewlyCreated": { "description": "Whether the index was newly created (`true`) or already existed (`false`).\n", "example": false, "type": "boolean" }, "name": { "description": "The user-defined name of the index or an auto-generated name.\n", "type": "string" }, "params": { "description": "The parameters of the vector index.\n", "properties": { "defaultNProbe": { "description": "The default number of neighboring centroids to consider\nin search queries.\n", "type": "integer" }, "dimension": { "description": "The vector dimension.\n", "type": "integer" }, "factory": { "description": "The Faiss index factory string, if one was specified\nduring index creation.\n", "type": "string" }, "metric": { "description": "The distance metric used for similarity calculations.\n", "enum": [ "cosine", "innerProduct", "l2" ], "type": "string" }, "nLists": { "description": "The number of Voronoi cells.\n", "type": "integer" }, "numberOfDocsPerCentroid": { "description": "How many vectors per centroid are included in the random\nsample used for training (introduced in v3.12.10).\n", "type": "integer" }, "trainingIterations": { "description": "The number of iterations used in the training process.\n", "type": "integer" } }, "required": [ "metric", "dimension", "nLists", "trainingIterations", "defaultNProbe", "numberOfDocsPerCentroid" ], "type": "object" }, "sparse": { "description": "Whether the index is a sparse index that excludes documents\nwith the indexed attribute missing or set to `null`.\n", "type": "boolean" }, "storedValues": { "description": "The list of additionally stored attribute paths. Only\npresent if `storedValues` was specified during index creation.\n", "items": { "type": "string" }, "type": "array" }, "trainingState": { "description": "The current training state of the vector index:\n- `\"unusable\"`: The index is not yet trained or cannot be\n trained, for example, because of insufficient training data.\n- `\"training\"`: The index is currently being trained.\n- `\"ingesting\"`: The index has been trained and data is being\n ingested.\n- `\"ready\"`: The index is fully trained and ready for queries.\n", "enum": [ "unusable", "training", "ingesting", "ready" ], "type": "string" }, "type": { "description": "The index type (`\"vector\"`).\n", "example": "vector", "type": "string" }, "unique": { "description": "Whether the index is a unique index. Always `false` for vector indexes.\n", "example": false, "type": "boolean" } }, "required": [ "code", "error", "id", "isNewlyCreated", "type", "name", "fields", "params", "sparse", "unique", "trainingState" ], "type": "object" } } }, "description": "The index already exists. The `isNewlyCreated` field is `false`.\n" }, "201": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 201, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "errorMessage": { "description": "An optional message with details about the\ntraining state, for example, `\"not enough training data for vector index\"`.\nOnly present if there is a problem with the index.\n", "type": "string" }, "fields": { "description": "The list with exactly one attribute path the index is created on.\n", "items": { "type": "string" }, "maxItems": 1, "minItems": 1, "type": "array" }, "id": { "description": "The identifier of the index in the format `\u003ccollection-name\u003e/\u003cindex-identifier\u003e`.\n", "example": "products/68", "type": "string" }, "isNewlyCreated": { "description": "Whether the index was newly created (`true`) or already existed (`false`).\n", "example": true, "type": "boolean" }, "name": { "description": "The user-defined name of the index or an auto-generated name.\n", "type": "string" }, "params": { "description": "The parameters of the vector index.\n", "properties": { "defaultNProbe": { "description": "The default number of neighboring centroids to consider\nin search queries.\n", "type": "integer" }, "dimension": { "description": "The vector dimension.\n", "type": "integer" }, "factory": { "description": "The Faiss index factory string, if one was specified\nduring index creation.\n", "type": "string" }, "metric": { "description": "The distance metric used for similarity calculations.\n", "enum": [ "cosine", "innerProduct", "l2" ], "type": "string" }, "nLists": { "description": "The number of Voronoi cells.\n", "type": "integer" }, "numberOfDocsPerCentroid": { "description": "How many vectors per centroid are included in the random\nsample used for training (introduced in v3.12.10).\n", "type": "integer" }, "trainingIterations": { "description": "The number of iterations used in the training process.\n", "type": "integer" } }, "required": [ "metric", "dimension", "nLists", "trainingIterations", "defaultNProbe", "numberOfDocsPerCentroid" ], "type": "object" }, "sparse": { "description": "Whether the index is a sparse index that excludes documents\nwith the indexed attribute missing or set to `null`.\n", "type": "boolean" }, "storedValues": { "description": "The list of additionally stored attribute paths. Only\npresent if `storedValues` was specified during index creation.\n", "items": { "type": "string" }, "type": "array" }, "trainingState": { "description": "The current training state of the vector index:\n- `\"unusable\"`: The index is not yet trained or cannot be\n trained, for example, because of insufficient training data.\n- `\"training\"`: The index is currently being trained.\n- `\"ingesting\"`: The index has been trained and data is being\n ingested.\n- `\"ready\"`: The index is fully trained and ready for queries.\n", "enum": [ "unusable", "training", "ingesting", "ready" ], "type": "string" }, "type": { "description": "The index type (`\"vector\"`).\n", "example": "vector", "type": "string" }, "unique": { "description": "Whether the index is a unique index. Always `false` for vector indexes.\n", "example": false, "type": "boolean" } }, "required": [ "code", "error", "id", "isNewlyCreated", "type", "name", "fields", "params", "sparse", "unique", "trainingState" ], "type": "object" } } }, "description": "The index is newly created. The `isNewlyCreated` field is `true`.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "code", "error", "errorMessage", "errorNum" ], "type": "object" } } }, "description": "The request body or its content is invalid, for example,\nbecause of a missing or malformed `params` attribute,\nor the vector index feature is not enabled. You need to run ArangoDB\nwith the `--vector-index` startup option.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "code", "error", "errorMessage", "errorNum" ], "type": "object" } } }, "description": "The collection is unknown.\n" } }, "summary": "Create a vector index", "tags": [ "Indexes" ] } }, "/_db/{database-name}/_api/index/{index-id}": { "delete": { "description": "Deletes an index with `index-id`.\n", "operationId": "deleteIndex", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The index id.\n", "in": "path", "name": "index-id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "If the index could be deleted, then an *HTTP 200* is\nreturned.\n" }, "404": { "description": "If the `index-id` is unknown, then an *HTTP 404* is returned.\n" } }, "summary": "Delete an index", "tags": [ "Indexes" ] }, "get": { "description": "The result is an object describing the index. It has at least the following\nattributes:\n\n- `id`: the identifier of the index\n\n- `type`: the index type\n\nAll other attributes are type-dependent. For example, some indexes provide\n`unique` or `sparse` flags, whereas others don't. Some indexes also provide\na selectivity estimate in the `selectivityEstimate` attribute of the result.\n", "operationId": "getIndex", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The index identifier.\n", "in": "path", "name": "index-id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "If the index exists, then a *HTTP 200* is returned.\n" }, "404": { "description": "If the index does not exist, then a *HTTP 404*\nis returned.\n" } }, "summary": "Get an index", "tags": [ "Indexes" ] } }, "/_db/{database-name}/_api/job/{job-id}": { "delete": { "description": "Deletes either all job results, expired job results, or the result of a\nspecific job.\nClients can use this method to perform an eventual garbage collection of job\nresults.\n", "operationId": "deleteJob", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the job to delete. The ID can be:\n- `all`: Deletes all jobs results. Currently executing or queued async\n jobs are not stopped by this call.\n- `expired`: Deletes expired results. To determine the expiration status of a\n result, pass the stamp query parameter. stamp needs to be a Unix timestamp,\n and all async job results created before this time are deleted.\n- **A numeric job ID**: In this case, the call removes the result of the\n specified async job. If the job is currently executing or queued, it is\n not aborted.\n", "in": "path", "name": "job-id", "required": true, "schema": { "type": "string" } }, { "description": "A Unix timestamp specifying the expiration threshold for when the `job-id` is\nset to `expired`.\n", "in": "query", "name": "stamp", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "result": { "description": "Always `true`.\n", "example": true, "type": "boolean" } }, "required": [ "result" ], "type": "object" } } }, "description": "The result of a specific job has been deleted successfully.\nThis code is also returned if the deletion of `all` or `expired`\njobs has been requested, including if no results were deleted.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "code", "error", "errorMessage", "errorNum" ], "type": "object" } } }, "description": "The `job-id` is missing in the request or has an invalid value.\nIn this case, no `x-arango-async-id` HTTP header is returned.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "code", "error", "errorMessage", "errorNum" ], "type": "object" } } }, "description": "The job cannot be found or has already been deleted, or the result\nhas already been fetched. In this case, no `x-arango-async-id`\nHTTP header is returned.\n" } }, "summary": "Delete async job results", "tags": [ "Jobs" ] }, "get": { "description": "This endpoint returns either of the following, depending on the specified value\nfor the `job-id` parameter:\n\n- The IDs of async jobs with a specific status\n- The processing status of a specific async job\n", "operationId": "getJob", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "If you provide a value of `pending` or `done`, then the endpoint returns an\narray of strings with the job IDs of ongoing or completed async jobs.\n\nIf you provide a numeric job ID, then the endpoint returns the status of the\nspecific async job in the form of an HTTP reply without payload. Check the\nHTTP status code of the response for the job status.\n", "in": "path", "name": "job-id", "required": true, "schema": { "type": "string" } }, { "description": "The maximum number of job IDs to return per call. If not specified, a\nserver-defined maximum value is used. Only applicable if you specify `pending`\nor `done` as `job-id` to list jobs.\n", "in": "query", "name": "count", "required": false, "schema": { "default": 100, "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "A list of job IDs. The list can be empty.\n", "items": { "type": "string" }, "type": "array" } } }, "description": "The job has finished and you can fetch the result (the response has\nno body in this case), or your request for the list of `pending` or\n`done` jobs has been successful.\n" }, "204": { "description": "The job is still in the queue of pending (or not yet finished) jobs.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "code", "error", "errorMessage", "errorNum" ], "type": "object" } } }, "description": "The `job-id` is missing in the request or has an invalid value.\nIn this case, no `x-arango-async-id` HTTP header is returned.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "code", "error", "errorMessage", "errorNum" ], "type": "object" } } }, "description": "The job cannot be found or has already been deleted, or the result\nhas already been fetched. In this case, no `x-arango-async-id`\nHTTP header is returned.\n" } }, "summary": "List async jobs by status or get the status of specific job", "tags": [ "Jobs" ] }, "put": { "description": "Returns the result of an async job identified by `job-id` if it's ready.\n\nIf the async job result is available on the server, the endpoint returns\nthe original operation's result headers and body, plus the additional\n`x-arango-async-job-id` HTTP header. The result and job are then removed\nwhich means that you can retrieve the result exactly once.\n\nIf the result is not available yet or if the job is not known (anymore),\nthe additional header is not present and you can tell the status from\nthe HTTP status code.\n", "operationId": "getJobResult", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The async job id.\n", "in": "path", "name": "job-id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The job is still in the queue of pending (or not yet finished) jobs.\nIn this case, no `x-arango-async-id` HTTP header is returned.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "code", "error", "errorMessage", "errorNum" ], "type": "object" } } }, "description": "The `job-id` is missing in the request or has an invalid value.\nIn this case, no `x-arango-async-id` HTTP header is returned.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "code", "error", "errorMessage", "errorNum" ], "type": "object" } } }, "description": "The job cannot be found or has already been deleted, or the result\nhas already been fetched. In this case, no `x-arango-async-id`\nHTTP header is returned.\n" }, "default": { "description": "If the job has finished, you get the result with the headers of the\noriginal operation with an additional `x-arango-async-id` HTTP header.\nThe HTTP status code is also that of the operation that executed\nasynchronously, which can be a success or error code depending on\nthe outcome of the operation.\n" } }, "summary": "Get the results of an async job", "tags": [ "Jobs" ] } }, "/_db/{database-name}/_api/job/{job-id}/cancel": { "put": { "description": "Cancels the currently running job identified by `job-id`. Note that it still\nmight take some time to actually cancel the running async job.\n", "operationId": "cancelJob", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The async job id.\n", "in": "path", "name": "job-id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "result": { "description": "Always `true`.\n", "example": true, "type": "boolean" } }, "required": [ "result" ], "type": "object" } } }, "description": "The job cancellation has been initiated.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "code", "error", "errorMessage", "errorNum" ], "type": "object" } } }, "description": "The `job-id` is missing in the request or has an invalid value.\nIn this case, no `x-arango-async-id` HTTP header is returned.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "code", "error", "errorMessage", "errorNum" ], "type": "object" } } }, "description": "The job cannot be found or has already been deleted, or the result\nhas already been fetched. In this case, no `x-arango-async-id`\nHTTP header is returned.\n" } }, "summary": "Cancel an async job", "tags": [ "Jobs" ] } }, "/_db/{database-name}/_api/key-generators": { "get": { "description": "Returns the available key generators for collections.\n", "operationId": "getKeyGenerators", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "keyGenerators": { "description": "The available document key generators.\n", "example": [ "traditional", "autoincrement", "uuid", "padded" ], "items": { "enum": [ "traditional", "autoincrement", "uuid", "padded" ], "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "keyGenerators" ], "type": "object" } } }, "description": "An object that contains a list of the available generators for document keys.\n" } }, "summary": "Get the available key generators", "tags": [ "Collections" ] } }, "/_db/{database-name}/_api/query": { "post": { "description": "This endpoint is for query validation only. To actually query the database,\nsee `/api/cursor`.\n", "operationId": "parseAqlQuery", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "query": { "description": "To validate a query string without executing it, the query string can be\npassed to the server via an HTTP POST request.\n", "type": "string" } }, "required": [ "query" ], "type": "object" } } } }, "responses": { "200": { "description": "If the query is valid, the server will respond with *HTTP 200* and\nreturn the names of the bind parameters it found in the query (if any) in\nthe `bindVars` attribute of the response. It will also return an array\nof the collections used in the query in the `collections` attribute.\nIf a query can be parsed successfully, the `ast` attribute of the returned\nJSON will contain the abstract syntax tree representation of the query.\nThe format of the `ast` is subject to change in future versions of\nArangoDB, but it can be used to inspect how ArangoDB interprets a given\nquery. Note that the abstract syntax tree will be returned without any\noptimizations applied to it.\n" }, "400": { "description": "The request is malformed or the query contains a parse error.\nThe body of the response contains the error details embedded in a JSON object.\n" } }, "summary": "Parse an AQL query", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/query-cache": { "delete": { "description": "Clears all results stored in the AQL query results cache for the current database.\n", "operationId": "deleteAqlQueryCache", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" } }, "required": [ "error", "code" ], "type": "object" } } }, "description": "The results cache has been cleared.\n" }, "400": { "description": "The request is malformed.\n" } }, "summary": "Clear the AQL query results cache", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/query-cache/entries": { "get": { "description": "Returns an array containing the AQL query results currently stored in the query results\ncache of the selected database.\n", "operationId": "listQueryCacheResults", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The entries of the query results cache.\n", "items": { "description": "The properties of a cache entry.\n", "properties": { "bindVars": { "description": "The bind parameters. This attribute is omitted if the\n[`--query.tracking-with-bindvars` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querytracking-with-bindvars) is set\nto `false`.\n", "type": "object" }, "dataSources": { "description": "The collections and Views involved in the query.\n", "items": { "type": "string" }, "type": "array" }, "hash": { "description": "The hash value calculated from the query string,\ncertain query options, and the bind variables.\n", "type": "string" }, "hits": { "description": "How many times the result has been served from the cache so far.\n", "type": "integer" }, "query": { "description": "The query string.\n", "type": "string" }, "results": { "description": "The number of documents/rows in the query result.\n", "type": "integer" }, "runTime": { "description": "The total duration of the query in seconds.\n", "type": "number" }, "size": { "description": "The size of the query result and bind parameters (in bytes).\n", "type": "integer" }, "started": { "description": "The date and time at which the query result has been added\nto the cache (in ISO 8601 format).\n", "format": "date-time", "type": "string" } }, "required": [ "hash", "query", "size", "results", "hits", "runTime", "started", "dataSources" ], "type": "object" }, "type": "array" } } }, "description": "The list of cached query results.\n" }, "400": { "description": "The request is malformed.\n" } }, "summary": "List the entries of the AQL query results cache", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/query-cache/properties": { "get": { "description": "Returns the global AQL query results cache configuration.\n", "operationId": "getQueryCacheProperties", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The result cache configuration.\n", "properties": { "includeSystem": { "description": "Whether results of queries that involve system collections\nare stored in the query results cache.\n", "type": "boolean" }, "maxEntrySize": { "description": "The maximum individual result size of queries that are\nstored per database-specific cache (in bytes).\n" }, "maxResults": { "description": "The maximum number of query results that are stored per\ndatabase-specific cache.\n", "type": "integer" }, "maxResultsSize": { "description": "The maximum cumulated size of query results that are\nstored per database-specific cache (in bytes).\n", "type": "integer" }, "mode": { "description": "The mode the AQL query results cache operates in.\n", "enum": [ "off", "on", "demand" ], "type": "string" } }, "type": "object" } } }, "description": "The result cache configuration is returned successfully.\n" }, "400": { "description": "The request is malformed.\n" } }, "summary": "Get the AQL query results cache configuration", "tags": [ "Queries" ] }, "put": { "description": "Adjusts the global properties for the AQL query results cache.\n\nChanging the properties may invalidate all results currently in the cache.\n", "operationId": "setQueryCacheProperties", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The result cache configuration settings to change.\n", "properties": { "includeSystem": { "description": "Whether to store results of queries that involve\nsystem collections in the cache.\n\nDefault: Controlled by the [`--query.cache-include-system-collections` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querycache-include-system-collections).\n", "type": "boolean" }, "maxEntrySize": { "description": "The maximum individual size of query results that are stored\nper database-specific cache (in bytes).\n\nDefault: Controlled by the [`--query.cache-entry-max-size` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querycache-entry-max-size).\n", "type": "integer" }, "maxResults": { "description": "The maximum number of query results that are stored per\ndatabase-specific cache.\n\nDefault: Controlled by the [`--query.cache-entries` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querycache-entries).\n", "type": "integer" }, "maxResultsSize": { "description": "The maximum cumulated size of query results that are stored\nper database-specific cache (in bytes).\n\nDefault: Controlled by the [`--query.cache-entries-max-size` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querycache-entries-max-size).\n", "type": "integer" }, "mode": { "description": "The mode the AQL query cache shall operate in.\n\nDefault: Controlled by the [`--query.cache-mode` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querycache-mode).\n", "enum": [ "off", "on", "demand" ], "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "The result cache configuration.\n", "properties": { "includeSystem": { "description": "Whether results of queries that involve system collections\nare stored in the query results cache.\n", "type": "boolean" }, "maxEntrySize": { "description": "The maximum individual result size of queries that are\nstored per database-specific cache (in bytes).\n" }, "maxResults": { "description": "The maximum number of query results that are stored per\ndatabase-specific cache.\n", "type": "integer" }, "maxResultsSize": { "description": "The maximum cumulated size of query results that are\nstored per database-specific cache (in bytes).\n", "type": "integer" }, "mode": { "description": "The mode the AQL query results cache operates in.\n", "enum": [ "off", "on", "demand" ], "type": "string" } }, "type": "object" } } }, "description": "The result cache configuration has been changed successfully.\n" }, "400": { "description": "The request is malformed.\n" } }, "summary": "Set the AQL query results cache configuration", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/query-plan-cache": { "delete": { "description": "Clears all execution plans stored in the AQL query plan cache for the\ncurrent database.\n\nThis requires write privileges for the current database.\n", "operationId": "deleteAqlQueryPlanCache", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" } }, "required": [ "error", "code" ], "type": "object" } } }, "description": "The query plan cache has been cleared for the current database.\n" } }, "summary": "Clear the AQL query plan cache", "tags": [ "Queries" ] }, "get": { "description": "Returns an array containing information about each AQL execution plan\ncurrently stored in the cache of the selected database.\n\nThis requires read privileges for the current database. In addition, only those\nquery plans are returned for which the current user has at least read permissions\non all collections and Views included in the query.\n", "operationId": "listQueryCachePlans", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The entries of the query plan cache.\n", "items": { "description": "The properties of a cache entry.\n", "properties": { "bindVars": { "description": "A subset of the original bind parameters with only the\ncollection bind parameters (e.g. `@@coll`). They need to\nhave the same names and values for utilizing a cached plan.\n", "type": "object" }, "created": { "description": "The date and time at which the query plan has been added\nto the cache (in ISO 8601 format).\n", "format": "date-time", "type": "string" }, "dataSources": { "description": "The collections and Views involved in the query.\n", "items": { "type": "string" }, "type": "array" }, "fullCount": { "description": "The value of the `fullCount` query option in the\noriginal query. This option generally leads to different\nexecution plans.\n", "type": "boolean" }, "hash": { "description": "The plan cache key.\n", "type": "string" }, "hits": { "description": "How many times the cached plan has been utilized so far.\n", "type": "integer" }, "memoryUsage": { "description": "How much memory the plan cache entry takes up for the\nexecution plan, query string, and so on (in bytes).\n", "type": "integer" }, "query": { "description": "The query string.\n", "type": "string" }, "queryHash": { "description": "The hash value of the query string.\n", "type": "integer" } }, "required": [ "hash", "query", "queryHash", "bindVars", "fullCount", "dataSources", "created", "hits", "memoryUsage" ], "type": "object" }, "type": "array" } } }, "description": "The list of cached query plans.\n" } }, "summary": "List the entries of the AQL query plan cache", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/query/current": { "get": { "description": "Returns a list of the AQL queries that currently run in the specified\ndatabase.\n\nQuery tracking needs to be enabled by the\n[`--query.tracking` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querytracking)\nor at runtime with the `enabled` query tracking property of the\n`PUT /_db/{database-name}/_api/query/properties` endpoint.\nIf query tracking is disabled for the current database,\nan **empty list** is returned.\n", "operationId": "listAqlQueries", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "If set to `true`, will return the currently running queries in all databases,\nnot just the selected one.\nUsing the parameter is only allowed in the `_system` database and with superuser\nprivileges.\n", "in": "query", "name": "all", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "properties": { "bindVars": { "description": "The bind parameter values used by the query.\n\nWhether the actual bind variables or an empty object is\nreturned is controlled by the\n[`--query.tracking-with-bindvars` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querytracking-with-bindvars)\nor the `trackBindVars` query tracking property that you can\nchange via the `PUT /_db/{database-name}/_api/query/properties`\nendpoint at runtime.\n", "type": "object" }, "dataSources": { "description": "The collections and Views involved in the query.\n\nOnly present if the\n[`--query.tracking-with-datasources` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querytracking-with-datasources)\nis enabled.\n", "items": { "type": "string" }, "type": "array" }, "database": { "description": "The name of the database the query runs in.\n", "type": "string" }, "id": { "description": "The query identifier.\n", "type": "string" }, "modificationQuery": { "description": "Whether the query writes data (`true`) or only reads (`false`).\n", "type": "boolean" }, "peakMemoryUsage": { "description": "The query's peak memory usage in bytes (in increments of 32KB),\nup to the point the query list was requested.\n", "type": "integer" }, "query": { "description": "The query string (potentially truncated).\n\nThe cutoff is controlled by the\n[`--query.max-artifact-log-length` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querymax-artifact-log-length)\nor the `maxQueryStringLength` query tracking property\nthat you can change via the\n`PUT /_db/{database-name}/_api/query/properties` endpoint\nat runtime.\n\nWhether the actual query string is tracked or only a\nvalue of `\"\u003chidden\u003e\"` is returned depends on the\n[`--query.tracking-with-querystring` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querytracking-with-querystring).\n", "type": "string" }, "runTime": { "description": "The query duration up to the point the query list was\nrequested (in seconds).\n", "type": "number" }, "started": { "description": "The date and time when the query was started (in ISO 8601 format).\n", "format": "date-time", "type": "string" }, "state": { "description": "The query's current execution state.\n", "enum": [ "initializing", "parsing", "optimizing ast", "loading collections", "instantiating plan", "optimizing plan", "instantiating executors", "executing", "finalizing", "finished", "killed", "invalid" ], "type": "string" }, "stream": { "description": "Whether the query uses a streaming cursor.\n", "type": "boolean" }, "user": { "description": "The name of the user that started the query.\n", "type": "string" }, "warnings": { "description": "The number of query warnings that occurred.\n\nValues other than `0` may not be observable because this information\ntypically becomes available when the query finishes, at which point\nit is no longer listed as a running query. However, non-zero values can be\nobserved when enabling `stream` and there is more than one batch of\nresults.\n", "type": "integer" } }, "required": [ "id", "database", "user", "query", "bindVars", "started", "runTime", "peakMemoryUsage", "state", "stream", "modificationQuery", "warnings" ], "type": "object" }, "type": "array" } } }, "description": "The list of currently running AQL queries for the specified database.\nEmpty if query tracking is disabled.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The request is malformed.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned when the `all` parameter is used but the request was made\nin a database other than `_system`, or by a user without superuser\nprivileges.\n" } }, "summary": "List the running AQL queries", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/query/properties": { "get": { "description": "Returns the current query tracking properties of the specified database.\n", "operationId": "getAqlQueryTrackingProperties", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "enabled": { "description": "Whether query tracking is enabled for the specified\ndatabase. If set to `false`, neither the currently\nrunning queries nor slow queries are tracked.\n", "type": "boolean" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "maxQueryStringLength": { "description": "Maximum query string length kept in the list of queries\n(in bytes).\n\nQuery strings can have arbitrary lengths, and you can use\nthis property to save memory in case very long query strings\nare used.\n", "type": "integer" }, "maxSlowQueries": { "description": "The maximum number of slow queries kept in the list.\nIf the list of slow queries is full, the oldest entry\nis discarded when additional slow queries occur.\n", "type": "integer" }, "slowQueryThreshold": { "description": "Threshold in seconds for treating a regular query as slow\n(the `stream` option is `false` for the query).\n", "type": "number" }, "slowStreamingQueryThreshold": { "description": "Threshold in seconds for treating a streaming query as slow\n(the `stream` option is `true` for the query).\n", "type": "number" }, "trackBindVars": { "description": "Whether bind variables used in queries are tracked.\n", "type": "boolean" }, "trackSlowQueries": { "description": "Whether slow queries are tracked. The `enabled` property\nmust be set to `true` as well in order to track slow queries.\n\nQueries are added to the list of slow queries after\nfinishing and if their runtime exceeded the value set in\n`slowQueryThreshold`.\n", "type": "boolean" } }, "required": [ "error", "code", "enabled", "trackSlowQueries", "trackBindVars", "maxSlowQueries", "slowQueryThreshold", "slowStreamingQueryThreshold", "maxQueryStringLength" ], "type": "object" } } }, "description": "The query tracking properties were retrieved successfully.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The request is malformed.\n" } }, "summary": "Get the AQL query tracking configuration", "tags": [ "Queries" ] }, "put": { "description": "Modify one or more query tracking properties at runtime for the\nspecified database.\n", "operationId": "updateAqlQueryTrackingProperties", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "enabled": { "description": "Whether to track queries for the specified database.\nIf set to `false`, neither the currently\nrunning queries nor slow queries are tracked.\n\nDefault: Controlled by the [`--query.tracking` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querytracking).\n", "type": "boolean" }, "maxQueryStringLength": { "default": 4096, "description": "The maximum query string length to keep in the list of queries.\n\nQuery strings can have arbitrary lengths, and you can use\nthis property to save memory in case very long query strings\nare used.\n\nYou can disable the tracking of query strings by default\nwith the [`--query.tracking-with-querystring` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querytracking-with-querystring).\n", "type": "integer" }, "maxSlowQueries": { "default": 64, "description": "The maximum number of slow queries to keep in the list\nof slow queries. If the list of slow queries is full, the oldest entry\nis discarded when additional slow queries occur.\n", "type": "integer" }, "slowQueryThreshold": { "description": "Threshold in seconds for treating a regular query as slow\n(the `stream` option is `false` for the query).\n\nDefault: Controlled by the [`--query.slow-threshold` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--queryslow-threshold).\n", "type": "number" }, "slowStreamingQueryThreshold": { "description": "Threshold in seconds for treating a streaming query as slow\n(the `stream` option is `true` for the query).\n\nDefault: Controlled by the [`--query.slow-streaming-threshold` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--queryslow-streaming-threshold).\n", "type": "number" }, "trackBindVars": { "description": "Whether to track bind variables used in queries.\n\nDefault: Controlled by the [`--query.tracking-with-bindvars` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querytracking-with-bindvars).\n", "type": "boolean" }, "trackSlowQueries": { "description": "Whether to track slow queries. The `enabled` property\nmust be set to `true` as well in order to track slow queries.\n\nQueries are added to the list of slow queries after\nfinishing and if their runtime exceeded the value set in\n`slowQueryThreshold`.\n\nDefault: Controlled by the [`--query.tracking-slow-queries` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querytracking-slow-queries).\n", "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "enabled": { "description": "Whether query tracking is enabled for the specified\ndatabase. If set to `false`, neither the currently\nrunning queries nor slow queries are tracked.\n", "type": "boolean" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "maxQueryStringLength": { "description": "Maximum query string length kept in the list of queries\n(in bytes).\n\nQuery strings can have arbitrary lengths, and you can use\nthis property to save memory in case very long query strings\nare used.\n", "type": "integer" }, "maxSlowQueries": { "description": "The maximum number of slow queries kept in the list.\nIf the list of slow queries is full, the oldest entry\nis discarded when additional slow queries occur.\n", "type": "integer" }, "slowQueryThreshold": { "description": "Threshold in seconds for treating a regular query as slow\n(the `stream` option is `false` for the query).\n", "type": "number" }, "slowStreamingQueryThreshold": { "description": "Threshold in seconds for treating a streaming query as slow\n(the `stream` option is `true` for the query).\n", "type": "number" }, "trackBindVars": { "description": "Whether bind variables used in queries are tracked.\n", "type": "boolean" }, "trackSlowQueries": { "description": "Whether slow queries are tracked. The `enabled` property\nmust be set to `true` as well in order to track slow queries.\n\nQueries are added to the list of slow queries after\nfinishing and if their runtime exceeded the value set in\n`slowQueryThreshold`.\n", "type": "boolean" } }, "required": [ "error", "code", "enabled", "trackSlowQueries", "trackBindVars", "maxSlowQueries", "slowQueryThreshold", "slowStreamingQueryThreshold", "maxQueryStringLength" ], "type": "object" } } }, "description": "The properties were changed successfully. The response body contains\nthe current set of query tracking properties.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The request is malformed.\n" } }, "summary": "Update the AQL query tracking configuration", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/query/rules": { "get": { "description": "A list of all optimizer rules and their properties.\n", "operationId": "getAqlQueryOptimizerRules", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "An array of objects. Each object describes an AQL optimizer rule.\n", "items": { "properties": { "flags": { "description": "An object with the properties of the rule.\n", "properties": { "canBeDisabled": { "description": "Whether users are allowed to disable this rule. A few rules are mandatory.\n", "type": "boolean" }, "canCreateAdditionalPlans": { "description": "Whether this rule may create additional query execution plans.\n", "type": "boolean" }, "clusterOnly": { "description": "Whether the rule is applicable in the cluster deployment mode only.\n", "type": "boolean" }, "disabledByDefault": { "description": "Whether the optimizer considers this rule by default.\n", "type": "boolean" }, "enterpriseOnly": { "description": "Whether the rule is implemented in the non-public enterprise code.\n", "type": "boolean" }, "hidden": { "description": "Whether the rule is displayed to users. Internal rules are hidden.\n", "type": "boolean" } }, "required": [ "hidden", "clusterOnly", "canBeDisabled", "canCreateAdditionalPlans", "disabledByDefault", "enterpriseOnly" ], "type": "object" }, "name": { "description": "The name of the optimizer rule as seen in query explain outputs.\n", "type": "string" } }, "required": [ "name", "flags" ], "type": "object" }, "type": "array" } } }, "description": "is returned if the list of optimizer rules can be retrieved successfully.\n" } }, "summary": "List all AQL optimizer rules", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/query/slow": { "delete": { "description": "Clears the list of slow AQL queries for the current database.\n", "operationId": "clearSlowAqlQueryList", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "If set to `true`, clears the slow query history in all databases, not just\nthe specified one.\nUsing the parameter is only allowed in the `_system` database and with superuser\nprivileges.\n", "in": "query", "name": "all", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" } }, "required": [ "error", "code" ], "type": "object" } } }, "description": "The list of slow queries was cleared successfully.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The request is malformed.\n" } }, "summary": "Clear the list of slow AQL queries", "tags": [ "Queries" ] }, "get": { "description": "Returns a list of the recently finished AQL queries that exceeded the\nslow query threshold in the specified database.\n\nSlow query tracking needs to be enabled by the\n[`--query.tracking-slow-queries` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querytracking-slow-queries)\nor at runtime with the `trackSlowQueries` query tracking property of the\n`PUT /_db/{database-name}/_api/query/properties` endpoint.\nIf slow query tracking is disabled for the current database,\nan **empty list** is returned.\n\nThe maximum amount of queries in the list can be controlled by setting\nthe `maxSlowQueries` query tracking property via the\n`PUT /_db/{database-name}/_api/query/properties` endpoint at runtime.\n\nThe threshold for treating a query as *slow* can be adjusted separate\nfor queries with the `stream` option on or off by setting the\n[`--query.slow-threshold`](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--queryslow-threshold)\nand [`--query.slow-streaming-threshold`](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--queryslow-streaming-threshold)\nstartup options or at runtime with the `slowQueryThreshold` and\n`slowStreamingQueryThreshold` query tracking properties of the\n`PUT /_db/{database-name}/_api/query/properties` endpoint.\n", "operationId": "listSlowAqlQueries", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "If set to `true`, returns the slow queries from all databases, not just\nthe specified one.\nUsing the parameter is only allowed in the `_system` database and with superuser\nprivileges.\n", "in": "query", "name": "all", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "properties": { "bindVars": { "description": "The bind parameter values used by the query.\n\nWhether the actual bind variables or an empty object is\nreturned is controlled by the\n[`--query.tracking-with-bindvars` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querytracking-with-bindvars)\nor the `trackBindVars` query tracking property that you can\nchange via the `PUT /_db/{database-name}/_api/query/properties`\nendpoint at runtime.\n", "type": "object" }, "dataSources": { "description": "The collections and Views involved in the query.\n\nOnly present if the\n[`--query.tracking-with-datasources` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querytracking-with-datasources)\nis enabled.\n", "items": { "type": "string" }, "type": "array" }, "database": { "description": "The name of the database the query ran in.\n", "type": "string" }, "exitCode": { "description": "An error code (`errorNum`) that indicates why the query\nfailed, or `0` on success. See the\n[error codes](https://docs.arango.ai/arangodb/3.12/develop/error-codes/) documentation.\n", "type": "integer" }, "id": { "description": "The internal identifier of the query.\n", "type": "string" }, "modificationQuery": { "description": "Whether the query created, updated, replaced, or deleted\nany documents (`true`) or only read data (`false`).\n", "type": "boolean" }, "peakMemoryUsage": { "description": "The query's peak memory usage in bytes (in increments of 32KB).\n", "type": "integer" }, "query": { "description": "The query string (potentially truncated).\n\nThe cutoff is controlled by the\n[`--query.max-artifact-log-length` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querymax-artifact-log-length)\nor the `maxQueryStringLength` query tracking property\nthat you can change via the\n`PUT /_db/{database-name}/_api/query/properties` endpoint\nat runtime.\n\nWhether the actual query string is tracked or only a\nvalue of `\"\u003chidden\u003e\"` is returned depends on the\n[`--query.tracking-with-querystring` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--querytracking-with-querystring).\n", "type": "string" }, "runTime": { "description": "The total query duration (in seconds).\n", "type": "number" }, "started": { "description": "The date and time when the query was started (ISO 8601).\n", "format": "date-time", "type": "string" }, "state": { "description": "The query's last execution state.\n", "enum": [ "finished", "killed", "invalid" ], "type": "string" }, "stream": { "description": "Whether the query used a streaming cursor (`stream` query option).\n", "type": "boolean" }, "user": { "description": "The name of the user who started the query.\n", "type": "string" }, "warnings": { "description": "The number of query warnings that occurred.\n", "type": "integer" } }, "required": [ "id", "database", "user", "query", "bindVars", "started", "runTime", "peakMemoryUsage", "state", "stream", "modificationQuery", "warnings", "exitCode" ], "type": "object" }, "type": "array" } } }, "description": "The list of recently finished AQL queries that exceeded the slow\nquery threshold. Empty if query tracking or slow query tracking is\ndisabled.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The request is malformed.\n" }, "403": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 403, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "Returned when the `all` parameter is used but the request was made\nin a database other than `_system`, or by a user without superuser\nprivileges.\n" } }, "summary": "List the slow AQL queries", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/query/{query-id}": { "delete": { "description": "Kills a running query in the currently selected database. The query will be\nterminated at the next cancellation point.\n", "operationId": "deleteAqlQuery", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The identifier of the query.\n", "in": "path", "name": "query-id", "required": true, "schema": { "type": "string" } }, { "description": "If set to `true`, attempt to kill the specified query in all databases,\nnot just the selected one.\nUsing the parameter is only allowed in the `_system` database and with superuser\nprivileges.\n", "in": "query", "name": "all", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "The query was still running when the kill request was executed and\nthe query's kill flag has been set.\n" }, "400": { "description": "The request is malformed.\n" }, "403": { "description": "In case the `all` parameter is used but the request was made in a\ndifferent database than `_system`, or by a non-privileged user.\n" }, "404": { "description": "A query with the specified identifier cannot be found.\n" } }, "summary": "Kill a running AQL query", "tags": [ "Queries" ] } }, "/_db/{database-name}/_api/replication/applier-config": { "get": { "description": "Returns the configuration of the replication applier.\n\nThe body of the response is a JSON object with the configuration. The\nfollowing attributes may be present in the configuration:\n\n- `endpoint`: the logger server to connect to (e.g. \"tcp://192.168.173.13:8529\").\n\n- `database`: the name of the database to connect to (e.g. \"_system\").\n\n- `username`: an optional ArangoDB username to use when connecting to the endpoint.\n\n- `password`: the password to use when connecting to the endpoint.\n\n- `maxConnectRetries`: the maximum number of connection attempts the applier\n will make in a row. If the applier cannot establish a connection to the\n endpoint in this number of attempts, it will stop itself.\n\n- `connectTimeout`: the timeout (in seconds) when attempting to connect to the\n endpoint. This value is used for each connection attempt.\n\n- `requestTimeout`: the timeout (in seconds) for individual requests to the endpoint.\n\n- `chunkSize`: the requested maximum size for log transfer packets that\n is used when the endpoint is contacted.\n\n- `autoStart`: whether or not to auto-start the replication applier on\n (next and following) server starts\n\n- `adaptivePolling`: whether or not the replication applier will use\n adaptive polling.\n\n- `includeSystem`: whether or not system collection operations will be applied\n\n- `autoResync`: whether or not the follower should perform a full automatic\n resynchronization with the leader in case the leader cannot serve log data\n requested by the follower, or when the replication is started and no tick\n value\n can be found.\n\n- `autoResyncRetries`: number of resynchronization retries that will be performed\n in a row when automatic resynchronization is enabled and kicks in. Setting this\n to `0` will effectively disable `autoResync`. Setting it to some other value\n will limit the number of retries that are performed. This helps preventing endless\n retries in case resynchronizations always fail.\n\n- `initialSyncMaxWaitTime`: the maximum wait time (in seconds) that the initial\n synchronization will wait for a response from the leader when fetching initial\n collection data.\n This wait time can be used to control after what time the initial synchronization\n will give up waiting for a response and fail. This value is relevant even\n for continuous replication when `autoResync` is set to `true` because this\n may re-start the initial synchronization when the leader cannot provide\n log data the follower requires.\n This value will be ignored if set to `0`.\n\n- `connectionRetryWaitTime`: the time (in seconds) that the applier will\n intentionally idle before it retries connecting to the leader in case of\n connection problems.\n This value will be ignored if set to `0`.\n\n- `idleMinWaitTime`: the minimum wait time (in seconds) that the applier will\n intentionally idle before fetching more log data from the leader in case\n the leader has already sent all its log data. This wait time can be used\n to control the frequency with which the replication applier sends HTTP log\n fetch requests to the leader in case there is no write activity on the leader.\n This value will be ignored if set to `0`.\n\n- `idleMaxWaitTime`: the maximum wait time (in seconds) that the applier will\n intentionally idle before fetching more log data from the leader in case the\n leader has already sent all its log data and there have been previous log\n fetch attempts that resulted in no more log data. This wait time can be used\n to control the maximum frequency with which the replication applier sends HTTP\n log fetch requests to the leader in case there is no write activity on the\n leader for longer periods. This configuration value will only be used if the\n option `adaptivePolling` is set to `true`.\n This value will be ignored if set to `0`.\n\n- `requireFromPresent`: if set to `true`, then the replication applier will check\n at start whether the start tick from which it starts or resumes replication is\n still present on the leader. If not, then there would be data loss. If\n `requireFromPresent` is `true`, the replication applier will abort with an\n appropriate error message. If set to `false`, then the replication applier will\n still start, and ignore the data loss.\n\n- `verbose`: if set to `true`, then a log line will be emitted for all operations\n performed by the replication applier. This should be used for debugging\n replication\n problems only.\n\n- `restrictType`: the configuration for `restrictCollections`\n\n- `restrictCollections`: the optional array of collections to include or exclude,\n based on the setting of `restrictType`\n", "operationId": "getReplicationApplierConfig", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "If set to `true`, returns the configuration of the global replication applier for all\ndatabases. If set to `false`, returns the configuration of the replication applier in the\nselected database.\n", "in": "query", "name": "global", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" } }, "summary": "Get the replication applier configuration", "tags": [ "Replication" ] }, "put": { "description": "Sets the configuration of the replication applier. The configuration can\nonly be changed while the applier is not running. The updated configuration\nwill be saved immediately but only become active with the next start of the\napplier.\n\nIn case of success, the body of the response is a JSON object with the updated\nconfiguration.\n", "operationId": "updateReplicationApplierConfig", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "If set to `true`, adjusts the configuration of the global replication applier for all\ndatabases. If set to `false`, adjusts the configuration of the replication applier in the\nselected database.\n", "in": "query", "name": "global", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "adaptivePolling": { "description": "if set to `true`, the replication applier will fall\nto sleep for an increasingly long period in case the logger server at the\nendpoint does not have any more replication events to apply. Using\nadaptive polling is thus useful to reduce the amount of work for both the\napplier and the logger server for cases when there are only infrequent\nchanges. The downside is that when using adaptive polling, it might take\nlonger for the replication applier to detect that there are new replication\nevents on the logger server.\n\nSetting `adaptivePolling` to false will make the replication applier\ncontact the logger server in a constant interval, regardless of whether\nthe logger server provides updates frequently or seldom.\n", "type": "boolean" }, "autoResync": { "description": "whether or not the follower should perform a full automatic resynchronization\nwith the leader in case the leader cannot serve log data requested by the\nfollower, or when the replication is started and no tick value can be found.\n", "type": "boolean" }, "autoResyncRetries": { "description": "number of resynchronization retries that will be performed in a row when\nautomatic resynchronization is enabled and kicks in. Setting this to `0`\nwill\neffectively disable `autoResync`. Setting it to some other value will limit\nthe number of retries that are performed. This helps preventing endless\nretries\nin case resynchronizations always fail.\n", "type": "integer" }, "autoStart": { "description": "whether or not to auto-start the replication applier on\n(next and following) server starts\n", "type": "boolean" }, "chunkSize": { "description": "the requested maximum size for log transfer packets that\nis used when the endpoint is contacted.\n", "type": "integer" }, "connectTimeout": { "description": "the timeout (in seconds) when attempting to connect to the\nendpoint. This value is used for each connection attempt.\n", "type": "integer" }, "connectionRetryWaitTime": { "description": "the time (in seconds) that the applier will intentionally idle before\nit retries connecting to the leader in case of connection problems.\nThis value will be ignored if set to `0`.\n", "type": "integer" }, "database": { "description": "the name of the database on the endpoint. If not specified, defaults to the current local database name.\n", "type": "string" }, "endpoint": { "description": "the logger server to connect to (e.g. \"tcp://192.168.173.13:8529\"). The endpoint must be specified.\n", "type": "string" }, "idleMaxWaitTime": { "description": "the maximum wait time (in seconds) that the applier will intentionally idle\nbefore fetching more log data from the leader in case the leader has\nalready sent all its log data and there have been previous log fetch attempts\nthat resulted in no more log data. This wait time can be used to control the\nmaximum frequency with which the replication applier sends HTTP log fetch\nrequests to the leader in case there is no write activity on the leader for\nlonger periods. This configuration value will only be used if the option\n`adaptivePolling` is set to `true`.\nThis value will be ignored if set to `0`.\n", "type": "integer" }, "idleMinWaitTime": { "description": "the minimum wait time (in seconds) that the applier will intentionally idle\nbefore fetching more log data from the leader in case the leader has\nalready sent all its log data. This wait time can be used to control the\nfrequency with which the replication applier sends HTTP log fetch requests\nto the leader in case there is no write activity on the leader.\nThis value will be ignored if set to `0`.\n", "type": "integer" }, "includeSystem": { "description": "whether or not system collection operations will be applied\n", "type": "boolean" }, "initialSyncMaxWaitTime": { "description": "the maximum wait time (in seconds) that the initial synchronization will\nwait for a response from the leader when fetching initial collection data.\nThis wait time can be used to control after what time the initial\nsynchronization\nwill give up waiting for a response and fail. This value is relevant even\nfor continuous replication when `autoResync` is set to `true` because this\nmay re-start the initial synchronization when the leader cannot provide\nlog data the follower requires.\nThis value will be ignored if set to `0`.\n", "type": "integer" }, "maxConnectRetries": { "description": "the maximum number of connection attempts the applier\nwill make in a row. If the applier cannot establish a connection to the\nendpoint in this number of attempts, it will stop itself.\n", "type": "integer" }, "password": { "description": "the password to use when connecting to the endpoint.\n", "type": "string" }, "requestTimeout": { "description": "the timeout (in seconds) for individual requests to the endpoint.\n", "type": "integer" }, "requireFromPresent": { "description": "if set to `true`, then the replication applier will check\nat start whether the start tick from which it starts or resumes replication is\nstill present on the leader. If not, then there would be data loss. If\n`requireFromPresent` is `true`, the replication applier will abort with an\nappropriate error message. If set to `false`, then the replication applier will\nstill start, and ignore the data loss.\n", "type": "boolean" }, "restrictCollections": { "description": "the array of collections to include or exclude,\nbased on the setting of `restrictType`\n", "items": { "type": "string" }, "type": "array" }, "restrictType": { "description": "the configuration for `restrictCollections`; Has to be either `include` or `exclude`\n", "type": "string" }, "username": { "description": "an optional ArangoDB username to use when connecting to the endpoint.\n", "type": "string" }, "verbose": { "description": "if set to `true`, then a log line will be emitted for all operations\nperformed by the replication applier. This should be used for debugging replication\nproblems only.\n", "type": "boolean" } }, "required": [ "endpoint", "database", "password", "maxConnectRetries", "connectTimeout", "requestTimeout", "chunkSize", "autoStart", "adaptivePolling", "includeSystem", "requireFromPresent", "verbose", "restrictType" ], "type": "object" } } } }, "responses": { "200": { "description": "is returned if the request was executed successfully.\n" }, "400": { "description": "is returned if the configuration is incomplete or malformed, or if the\nreplication applier is currently running.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" } }, "summary": "Update the replication applier configuration", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/applier-start": { "put": { "description": "Starts the replication applier. This will return immediately if the\nreplication applier is already running.\n\nIf the replication applier is not already running, the applier configuration\nwill be checked, and if it is complete, the applier will be started in a\nbackground thread. This means that even if the applier will encounter any\nerrors while running, they will not be reported in the response to this\nmethod.\n\nTo detect replication applier errors after the applier was started, use the\n`/_api/replication/applier-state` API instead.\n", "operationId": "startReplicationApplier", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "If set to `true`, starts the global replication applier for all\ndatabases. If set to `false`, starts the replication applier in the\nselected database.\n", "in": "query", "name": "global", "required": false, "schema": { "type": "boolean" } }, { "description": "The remote `lastLogTick` value from which to start applying. If not specified,\nthe last saved tick from the previous applier run is used. If there is no\nprevious applier state saved, the applier will start at the beginning of the\nlogger server's log.\n", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully.\n" }, "400": { "description": "is returned if the replication applier is not fully configured or the\nconfiguration is invalid.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" } }, "summary": "Start the replication applier", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/applier-state": { "get": { "description": "Returns the state of the replication applier, regardless of whether the\napplier is currently running or not.\n\nThe response is a JSON object with the following attributes:\n\n- `state`: a JSON object with the following sub-attributes:\n\n - `running`: whether or not the applier is active and running\n\n - `lastAppliedContinuousTick`: the last tick value from the continuous\n replication log the applier has applied.\n\n - `lastProcessedContinuousTick`: the last tick value from the continuous\n replication log the applier has processed.\n\n Regularly, the last applied and last processed tick values should be\n identical. For transactional operations, the replication applier will first\n process incoming log events before applying them, so the processed tick\n value might be higher than the applied tick value. This will be the case\n until the applier encounters the *transaction commit* log event for the\n transaction.\n\n - `lastAvailableContinuousTick`: the last tick value the remote server can\n provide, for all databases.\n\n - `ticksBehind`: this attribute will be present only if the applier is currently\n running. It will provide the number of log ticks between what the applier\n has applied/seen and the last log tick value provided by the remote server.\n If this value is zero, then both servers are in sync. If this is non-zero,\n then the remote server has additional data that the applier has not yet\n fetched and processed, or the remote server may have more data that is not\n applicable to the applier.\n\n Client applications can use it to determine approximately how far the applier\n is behind the remote server, and can periodically check if the value is\n increasing (applier is falling behind) or decreasing (applier is catching up).\n\n Please note that as the remote server will only keep one last log tick value\n for all of its databases, but replication may be restricted to just certain\n databases on the applier, this value is more meaningful when the global applier\n is used.\n Additionally, the last log tick provided by the remote server may increase\n due to writes into system collections that are not replicated due to replication\n configuration. So the reported value may exaggerate the reality a bit for\n some scenarios.\n\n - `time`: the time on the applier server.\n\n - `totalRequests`: the total number of requests the applier has made to the\n endpoint.\n\n - `totalFailedConnects`: the total number of failed connection attempts the\n applier has made.\n\n - `totalEvents`: the total number of log events the applier has processed.\n\n - `totalOperationsExcluded`: the total number of log events excluded because\n of `restrictCollections`.\n\n - `progress`: a JSON object with details about the replication applier progress.\n It contains the following sub-attributes if there is progress to report:\n\n - `message`: a textual description of the progress\n\n - `time`: the date and time the progress was logged\n\n - `failedConnects`: the current number of failed connection attempts\n\n - `lastError`: a JSON object with details about the last error that happened on\n the applier. It contains the following sub-attributes if there was an error:\n\n - `errorNum`: a numerical error code\n\n - `errorMessage`: a textual error description\n\n - `time`: the date and time the error occurred\n\n In case no error has occurred, `lastError` will be empty.\n\n- `server`: a JSON object with the following sub-attributes:\n\n - `version`: the applier server's version\n\n - `serverId`: the applier server's id\n\n- `endpoint`: the endpoint the applier is connected to (if applier is\n active) or will connect to (if applier is currently inactive)\n\n- `database`: the name of the database the applier is connected to (if applier is\n active) or will connect to (if applier is currently inactive)\n\nPlease note that all \"tick\" values returned do not have a specific unit. Tick\nvalues are only meaningful when compared to each other. Higher tick values mean\n\"later in time\" than lower tick values.\n", "operationId": "getReplicationApplierState", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "If set to `true`, returns the state of the global replication applier for all\ndatabases. If set to `false`, returns the state of the replication applier in the\nselected database.\n", "in": "query", "name": "global", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" } }, "summary": "Get the replication applier state", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/applier-stop": { "put": { "description": "Stops the replication applier. This will return immediately if the\nreplication applier is not running.\n", "operationId": "stopReplicationApplier", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "If set to `true`, stops the global replication applier for all\ndatabases. If set to `false`, stops the replication applier in the\nselected database.\n", "in": "query", "name": "global", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" } }, "summary": "Stop the replication applier", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/batch": { "post": { "description": "\u003e **INFO:**\nThis is an internally used endpoint.\n\n\nCreates a new dump batch and returns the batch's id.\n\nThe response is a JSON object with the following attributes:\n\n- `id`: the id of the batch\n- `lastTick`: snapshot tick value using when creating the batch\n- `state`: additional leader state information (only present if the\n `state` URL parameter was set to `true` in the request)\n\n\u003e **INFO:**\nOn a Coordinator, this request must have a `DBserver`\nquery parameter which must be an ID of a DB-Server.\nThe very same request is forwarded synchronously to that DB-Server.\nIt is an error if this attribute is not bound in the Coordinator case.\n", "operationId": "createReplicationBatch", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Setting `state` to `true` makes the response also contain\na `state` attribute with information about the leader state.\nThis is used only internally during the replication process\nand should not be used by client applications.\n", "in": "query", "name": "state", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ttl": { "description": "The time-to-live for the new batch (in seconds).\n", "type": "number" } }, "required": [ "ttl" ], "type": "object" } } } }, "responses": { "200": { "description": "is returned if the batch was created successfully.\n" }, "400": { "description": "is returned if the TTL value is invalid or if the `DBserver` attribute\nis not specified or illegal on a Coordinator.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" } }, "summary": "Create a new dump batch", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/batch/{id}": { "delete": { "description": "\u003e **INFO:**\nThis is an internally used endpoint.\n\n\nDeletes the existing dump batch, allowing compaction and cleanup to resume.\n\n\u003e **INFO:**\nOn a Coordinator, this request must have a `DBserver`\nquery parameter which must be an ID of a DB-Server.\nThe very same request is forwarded synchronously to that DB-Server.\nIt is an error if this attribute is not bound in the Coordinator case.\n", "operationId": "deleteReplicationBatch", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The id of the batch.\n", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "is returned if the batch was deleted successfully.\n" }, "400": { "description": "is returned if the batch was not found.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" } }, "summary": "Delete an existing dump batch", "tags": [ "Replication" ] }, "put": { "description": "\u003e **INFO:**\nThis is an internally used endpoint.\n\n\nExtends the time-to-live (TTL) of an existing dump batch, using the batch's ID and\nthe provided TTL value.\n\nIf the batch's TTL can be extended successfully, the response is empty.\n\n\u003e **INFO:**\nOn a Coordinator, this request must have a `DBserver`\nquery parameter which must be an ID of a DB-Server.\nThe very same request is forwarded synchronously to that DB-Server.\nIt is an error if this attribute is not bound in the Coordinator case.\n", "operationId": "extendReplicationBatch", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The id of the batch.\n", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "ttl": { "description": "The time-to-live for the new batch (in seconds)\n", "type": "number" } }, "required": [ "ttl" ], "type": "object" } } } }, "responses": { "204": { "description": "is returned if the batch's ttl was extended successfully.\n" }, "400": { "description": "is returned if the ttl value is invalid or the batch was not found.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" } }, "summary": "Extend the TTL of a dump batch", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/clusterInventory": { "get": { "description": "Returns the array of collections and indexes available on the cluster.\n\nThe response will be an array of JSON objects, one for each collection.\nEach collection contains exactly two keys, `parameters` and `indexes`.\nThis information comes from `Plan/Collections/{DB-Name}/*` in the Agency,\njust that the `indexes` attribute there is relocated to adjust it to\nthe data format of arangodump.\n", "operationId": "getReplicationClusterInventory", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Include system collections in the result.\n", "in": "query", "name": "includeSystem", "required": false, "schema": { "default": true, "type": "boolean" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" } }, "summary": "Get the cluster collections and indexes", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/dump": { "get": { "description": "Returns the data from a collection for the requested range.\n\nThe `chunkSize` query parameter can be used to control the size of the result.\nIt must be specified in bytes. The `chunkSize` value will only be honored\napproximately. Otherwise a too low `chunkSize` value could cause the server\nto not be able to put just one entry into the result and return it.\nTherefore, the `chunkSize` value will only be consulted after an entry has\nbeen written into the result. If the result size is then greater than\n`chunkSize`, the server will respond with as many entries as there are\nin the response already. If the result size is still less than `chunkSize`,\nthe server will try to return more data if there's more data left to return.\n\nIf `chunkSize` is not specified, some server-side default value will be used.\n\nThe `Content-Type` of the result is `application/x-arango-dump`. This is an\neasy-to-process format, with all entries going onto separate lines in the\nresponse body.\n\nEach line itself is a JSON object, with at least the following attributes:\n\n- `tick`: the operation's tick attribute\n\n- `key`: the key of the document/edge or the key used in the deletion operation\n\n- `rev`: the revision id of the document/edge or the deletion operation\n\n- `data`: the actual document/edge data for types 2300 and 2301. The full\n document/edge data will be returned even for updates.\n\n- `type`: the type of entry. Possible values for `type` are:\n\n - 2300: document insertion/update\n\n - 2301: edge insertion/update\n\n - 2302: document/edge deletion\n\n\u003e **INFO:**\nThere will be no distinction between inserts and updates when calling this method.\n", "operationId": "getReplicationDump", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name or id of the collection to dump.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "Approximate maximum size of the returned result.\n", "in": "query", "name": "chunkSize", "required": false, "schema": { "type": "number" } }, { "description": "The id of the snapshot to use\n", "in": "query", "name": "batchId", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully and data was returned. The header\n`x-arango-replication-lastincluded` is set to the tick of the last document returned.\n" }, "204": { "description": "is returned if the request was executed successfully, but there was no content available.\nThe header `x-arango-replication-lastincluded` is `0` in this case.\n" }, "404": { "description": "is returned when the collection could not be found.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" } }, "summary": "Get a replication dump", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/inventory": { "get": { "description": "Returns the array of collections and their indexes, and the array of Views available. These\narrays can be used by replication clients to initiate an initial synchronization with the\nserver.\nThe response will contain all collections, their indexes and views in the requested database\nif `global` is not set, and all collections, indexes and views in all databases if `global`\nis set.\nIn case `global` is not set, it is possible to restrict the response to a single collection\nby setting the `collection` parameter. In this case the response will contain only information\nabout the requested collection in the `collections` array, and no information about views\n(i.e. the `views` response attribute will be an empty array).\n\nThe response will contain a JSON object with the `collections`, `views`, `state` and\n`tick` attributes.\n\n`collections` is an array of collections with the following sub-attributes:\n\n- `parameters`: the collection properties\n\n- `indexes`: an array of the indexes of the collection. Primary indexes and edge indexes\n are not included in this array.\n\nThe `state` attribute contains the current state of the replication logger. It\ncontains the following sub-attributes:\n\n- `running`: whether or not the replication logger is currently active. Note:\n since ArangoDB 2.2, the value will always be `true`\n\n- `lastLogTick`: the value of the last tick the replication logger has written\n\n- `time`: the current time on the server\n\n`views` is an array of available views.\n\nReplication clients should note the `lastLogTick` value returned. They can then\nfetch collections' data using the dump method up to the value of lastLogTick, and\nquery the continuous replication log for log events after this tick value.\n\nTo create a full copy of the collections on the server, a replication client\ncan execute these steps:\n\n- call the `/inventory` API method. This returns the `lastLogTick` value and the\n array of collections and indexes from the server.\n\n- for each collection returned by `/inventory`, create the collection locally and\n call `/dump` to stream the collection data to the client, up to the value of\n `lastLogTick`.\n After that, the client can create the indexes on the collections as they were\n reported by `/inventory`.\n\nIf the clients wants to continuously stream replication log events from the logger\nserver, the following additional steps need to be carried out:\n\n- the client should call `/_api/wal/tail` initially to fetch the first batch of\n replication events that were logged after the client's call to `/inventory`.\n\n The call to `/_api/wal/tail` should use a `from` parameter with the value of the\n `lastLogTick` as reported by `/inventory`. The call to `/_api/wal/tail` will\n return the `x-arango-replication-lastincluded` header which will contain the\n last tick value included in the response.\n\n- the client can then continuously call `/_api/wal/tail` to incrementally fetch new\n replication events that occurred after the last transfer.\n\n Calls should use a `from` parameter with the value of the `x-arango-replication-lastincluded`\n header of the previous response. If there are no more replication events, the\n response will be empty and clients can go to sleep for a while and try again\n later.\n\n\u003e **INFO:**\nOn a Coordinator, this request must have a `DBserver`\nquery parameter which must be an ID of a DB-Server.\nThe very same request is forwarded synchronously to that DB-Server.\nIt is an error if this attribute is not bound in the Coordinator case.\n\n\n\u003e **INFO:**\nUsing the `global` parameter the top-level object contains a key `databases`\nunder which each key represents a database name, and the value conforms to the above description.\n", "operationId": "getReplicationInventory", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Include system collections in the result.\n", "in": "query", "name": "includeSystem", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "Include all databases in the response. Only works in the context of\nthe `_system` database.\n", "in": "query", "name": "global", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "A valid batchId is required for this API call\n", "in": "query", "name": "batchId", "required": true, "schema": { "type": "number" } }, { "description": "If this parameter is set, the response will be restricted to a single collection (the one\nspecified), and no views will be returned. This can be used as an optimization to reduce\nthe size of the response.\n", "in": "query", "name": "collection", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" } }, "summary": "Get a replication inventory", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/logger-first-tick": { "get": { "deprecated": true, "description": "\u003e **WARNING:**\nThis endpoint is deprecated and removed in ArangoDB v4.0.\n\n\nReturns the first available tick value that can be served from the server's\nreplication log. This method can be called by replication clients after to\ndetermine if certain data (identified by a tick value) is still available\nfor replication.\n\nThe result is a JSON object containing the attribute `firstTick`. This\nattribute contains the minimum tick value available in the server's\nreplication\nlog.\n\n\u003e **INFO:**\nThis method is not supported on a Coordinator in a cluster deployment.\n", "operationId": "getReplicationLoggerFirstTick", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" }, "501": { "description": "is returned when this operation is called on a Coordinator in a cluster deployment.\n" } }, "summary": "Get the first available replication tick value", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/logger-follow": { "get": { "deprecated": true, "description": "\u003e **WARNING:**\nThis route should no longer be used.\nIt is considered as deprecated from version 3.4.0 on. Client applications\nshould use the REST API endpoint `/_api/wal/tail` instead.\n\n\nReturns data from the server's replication log. This method can be called\nby replication clients after an initial synchronization of data. The method\nwill return all \"recent\" log entries from the logger server, and the clients\ncan replay and apply these entries locally so they get to the same data\nstate as the logger server.\n\nClients can call this method repeatedly to incrementally fetch all changes\nfrom the logger server. In this case, they should provide the `from` value so\nthey will only get returned the log events since their last fetch.\n\nWhen the `from` query parameter is not used, the logger server will return log\nentries starting at the beginning of its replication log. When the `from`\nparameter is used, the logger server will only return log entries which have\nhigher tick values than the specified `from` value (note: the log entry with a\ntick value equal to `from` will be excluded). Use the `from` value when\nincrementally fetching log data.\n\nThe `to` query parameter can be used to optionally restrict the upper bound of\nthe result to a certain tick value. If used, the result will contain only log events\nwith tick values up to (including) `to`. In incremental fetching, there is no\nneed to use the `to` parameter. It only makes sense in special situations,\nwhen only parts of the change log are required.\n\nThe `chunkSize` query parameter can be used to control the size of the result.\nIt must be specified in bytes. The `chunkSize` value will only be honored\napproximately. Otherwise a too low `chunkSize` value could cause the server\nto not be able to put just one log entry into the result and return it.\nTherefore, the `chunkSize` value will only be consulted after a log entry has\nbeen written into the result. If the result size is then greater than\n`chunkSize`, the server will respond with as many log entries as there are\nin the response already. If the result size is still less than `chunkSize`,\nthe server will try to return more data if there's more data left to return.\n\nIf `chunkSize` is not specified, some server-side default value will be used.\n\nThe `Content-Type` of the result is `application/x-arango-dump`. This is an\neasy-to-process format, with all log events going onto separate lines in the\nresponse body. Each log event itself is a JSON object, with at least the\nfollowing attributes:\n\n- `tick`: the log event tick value\n\n- `type`: the log event type\n\nIndividual log events will also have additional attributes, depending on the\nevent type. A few common attributes which are used for multiple events types\nare:\n\n- `cid`: id of the collection the event was for\n\n- `tid`: id of the transaction the event was contained in\n\n- `key`: document key\n\n- `rev`: document revision id\n\n- `data`: the original document data\n\nThe response will also contain the following HTTP headers:\n\n- `x-arango-replication-active`: whether or not the logger is active. Clients\n can use this flag as an indication for their polling frequency. If the\n logger is not active and there are no more replication events available, it\n might be sensible for a client to abort, or to go to sleep for a long time\n and try again later to check whether the logger has been activated.\n\n- `x-arango-replication-lastincluded`: the tick value of the last included\n value in the result. In incremental log fetching, this value can be used\n as the `from` value for the following request. **Note** that if the result is\n empty, the value will be `0`. This value should not be used as `from` value\n by clients in the next request (otherwise the server would return the log\n events from the start of the log again).\n\n- `x-arango-replication-lasttick`: the last tick value the logger server has\n logged (not necessarily included in the result). By comparing the last\n tick and last included tick values, clients have an approximate indication of\n how many events there are still left to fetch.\n\n- `x-arango-replication-checkmore`: whether or not there already exists more\n log data which the client could fetch immediately. If there is more log data\n available, the client could call `logger-follow` again with an adjusted `from`\n value to fetch remaining log entries until there are no more.\n\n If there isn't any more log data to fetch, the client might decide to go\n to sleep for a while before calling the logger again.\n\n\u003e **INFO:**\nThis method is not supported on a Coordinator in a cluster deployment.\n", "operationId": "getReplicationLoggerFollow", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Exclusive lower bound tick value for results.\n", "in": "query", "name": "from", "required": false, "schema": { "type": "number" } }, { "description": "Inclusive upper bound tick value for results.\n", "in": "query", "name": "to", "required": false, "schema": { "type": "number" } }, { "description": "Approximate maximum size of the returned result.\n", "in": "query", "name": "chunkSize", "required": false, "schema": { "type": "number" } }, { "description": "Include system collections in the result.\n", "in": "query", "name": "includeSystem", "required": false, "schema": { "default": true, "type": "boolean" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully, and there are log\nevents available for the requested range. The response body will not be empty\nin this case.\n" }, "204": { "description": "is returned if the request was executed successfully, but there are no log\nevents available for the requested range. The response body will be empty\nin this case.\n" }, "400": { "description": "is returned if either the `from` or `to` values are invalid.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" }, "501": { "description": "is returned when this operation is called on a Coordinator in a cluster deployment.\n" } }, "summary": "Get replication log entries (deprecated)", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/logger-state": { "get": { "description": "Returns the current state of the server's replication logger. The state will\ninclude information about whether the logger is running and about the last\nlogged tick value. This tick value is important for incremental fetching of\ndata.\n\nThe body of the response contains a JSON object with the following\nattributes:\n\n- `state`: the current logger state as a JSON object with the following\n sub-attributes:\n\n - `running`: whether or not the logger is running\n\n - `lastLogTick`: the tick value of the latest tick the logger has logged.\n This value can be used for incremental fetching of log data.\n\n - `totalEvents`: total number of events logged since the server was started.\n The value is not reset between multiple stops and re-starts of the logger.\n\n - `time`: the current date and time on the logger server\n\n- `server`: a JSON object with the following sub-attributes:\n\n - `version`: the logger server's version\n\n - `serverId`: the logger server's id\n\n- `clients`: returns the last fetch status by replication clients connected to\n the logger. Each client is returned as a JSON object with the following attributes:\n\n - `syncerId`: id of the client syncer\n\n - `serverId`: server id of client\n\n - `lastServedTick`: last tick value served to this client via the WAL tailing API\n\n - `time`: date and time when this client last called the WAL tailing API\n", "operationId": "getReplicationLoggerState", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the logger state could be determined successfully.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if the logger state could not be determined.\n" } }, "summary": "Get the replication logger state", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/logger-tick-ranges": { "get": { "deprecated": true, "description": "\u003e **WARNING:**\nThis endpoint is deprecated and removed in ArangoDB v4.0.\n\n\nReturns the currently available ranges of tick values for all currently\navailable WAL logfiles. The tick values can be used to determine if certain\ndata (identified by tick value) are still available for replication.\n\nThe body of the response contains a JSON array. Each array member is an\nobject\nthat describes a single logfile. Each object has the following attributes:\n\n- `datafile`: name of the logfile\n\n- `status`: status of the datafile, in textual form (e.g. \"sealed\", \"open\")\n\n- `tickMin`: minimum tick value contained in logfile\n\n- `tickMax`: maximum tick value contained in logfile\n", "operationId": "getReplicationLoggerTickRanges", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the tick ranges could be determined successfully.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if the logger state could not be determined.\n" }, "501": { "description": "is returned when this operation is called on a Coordinator in a cluster deployment.\n" } }, "summary": "Get the tick ranges available in the WAL logfiles", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/make-follower": { "put": { "description": "\u003e **WARNING:**\nCalling this endpoint will synchronize data from the collections found on the\nremote leader to the local ArangoDB database. All data in the local collections\nwill be purged and replaced with data from the leader. Use with caution!\n\n\n\u003e **INFO:**\nThis command may take a long time to complete and return. This is because it\nwill first do a full data synchronization with the leader, which will take time\nroughly proportional to the amount of data.\n\n\nChanges the role to a follower and starts a full data synchronization from a\nremote endpoint into the local ArangoDB database and afterwards starts the\ncontinuous replication.\n\nThe operation works on a per-database level.\n\nAll local database data will be removed prior to the synchronization.\n\nIn case of success, the body of the response is a JSON object with the following\nattributes:\n\n- `state`: a JSON object with the following sub-attributes:\n\n - `running`: whether or not the applier is active and running\n\n - `lastAppliedContinuousTick`: the last tick value from the continuous\n replication log the applier has applied.\n\n - `lastProcessedContinuousTick`: the last tick value from the continuous\n replication log the applier has processed.\n\n Regularly, the last applied and last processed tick values should be\n identical. For transactional operations, the replication applier will first\n process incoming log events before applying them, so the processed tick\n value might be higher than the applied tick value. This will be the case\n until the applier encounters the *transaction commit* log event for the\n transaction.\n\n - `lastAvailableContinuousTick`: the last tick value the remote server can\n provide.\n\n - `ticksBehind`: this attribute will be present only if the applier is currently\n running. It will provide the number of log ticks between what the applier\n has applied/seen and the last log tick value provided by the remote server.\n If this value is zero, then both servers are in sync. If this is non-zero,\n then the remote server has additional data that the applier has not yet\n fetched and processed, or the remote server may have more data that is not\n applicable to the applier.\n\n Client applications can use it to determine approximately how far the applier\n is behind the remote server, and can periodically check if the value is\n increasing (applier is falling behind) or decreasing (applier is catching up).\n\n Please note that as the remote server will only keep one last log tick value\n for all of its databases, but replication may be restricted to just certain\n databases on the applier, this value is more meaningful when the global applier\n is used.\n Additionally, the last log tick provided by the remote server may increase\n due to writes into system collections that are not replicated due to replication\n configuration. So the reported value may exaggerate the reality a bit for\n some scenarios.\n\n - `time`: the time on the applier server.\n\n - `totalRequests`: the total number of requests the applier has made to the\n endpoint.\n\n - `totalFailedConnects`: the total number of failed connection attempts the\n applier has made.\n\n - `totalEvents`: the total number of log events the applier has processed.\n\n - `totalOperationsExcluded`: the total number of log events excluded because\n of `restrictCollections`.\n\n - `progress`: a JSON object with details about the replication applier progress.\n It contains the following sub-attributes if there is progress to report:\n\n - `message`: a textual description of the progress\n\n - `time`: the date and time the progress was logged\n\n - `failedConnects`: the current number of failed connection attempts\n\n - `lastError`: a JSON object with details about the last error that happened on\n the applier. It contains the following sub-attributes if there was an error:\n\n - `errorNum`: a numerical error code\n\n - `errorMessage`: a textual error description\n\n - `time`: the date and time the error occurred\n\n In case no error has occurred, `lastError` will be empty.\n\n- `server`: a JSON object with the following sub-attributes:\n\n - `version`: the applier server's version\n\n - `serverId`: the applier server's id\n\n- `endpoint`: the endpoint the applier is connected to (if applier is\n active) or will connect to (if applier is currently inactive)\n\n- `database`: the name of the database the applier is connected to (if applier is\n active) or will connect to (if applier is currently inactive)\n\nPlease note that all \"tick\" values returned do not have a specific unit. Tick\nvalues are only meaningful when compared to each other. Higher tick values mean\n\"later in time\" than lower tick values.\n\n\u003e **INFO:**\nThis endpoint is not supported on a Coordinator in a cluster deployment.\n", "operationId": "makeReplicationFollower", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "adaptivePolling": { "description": "whether or not the replication applier will use adaptive polling.\n", "type": "boolean" }, "autoResync": { "description": "whether or not the follower should perform an automatic resynchronization with\nthe leader in case the leader cannot serve log data requested by the follower,\nor when the replication is started and no tick value can be found.\n", "type": "boolean" }, "autoResyncRetries": { "description": "number of resynchronization retries that will be performed in a row when\nautomatic resynchronization is enabled and kicks in. Setting this to `0` will\neffectively disable `autoResync`. Setting it to some other value will limit\nthe number of retries that are performed. This helps preventing endless retries\nin case resynchronizations always fail.\n", "type": "integer" }, "chunkSize": { "description": "the requested maximum size for log transfer packets that\nis used when the endpoint is contacted.\n", "type": "integer" }, "connectTimeout": { "description": "the timeout (in seconds) when attempting to connect to the\nendpoint. This value is used for each connection attempt.\n", "type": "integer" }, "connectionRetryWaitTime": { "description": "the time (in seconds) that the applier will intentionally idle before\nit retries connecting to the leader in case of connection problems.\nThis value will be ignored if set to `0`.\n", "type": "integer" }, "database": { "description": "the database name on the leader (if not specified, defaults to the\nname of the local current database).\n", "type": "string" }, "endpoint": { "description": "the leader endpoint to connect to (e.g. \"tcp://192.168.173.13:8529\").\n", "type": "string" }, "idleMaxWaitTime": { "description": "the maximum wait time (in seconds) that the applier will intentionally idle\nbefore fetching more log data from the leader in case the leader has\nalready sent all its log data and there have been previous log fetch attempts\nthat resulted in no more log data. This wait time can be used to control the\nmaximum frequency with which the replication applier sends HTTP log fetch\nrequests to the leader in case there is no write activity on the leader for\nlonger periods. This configuration value will only be used if the option\n`adaptivePolling` is set to `true`.\nThis value will be ignored if set to `0`.\n", "type": "integer" }, "idleMinWaitTime": { "description": "the minimum wait time (in seconds) that the applier will intentionally idle\nbefore fetching more log data from the leader in case the leader has\nalready sent all its log data. This wait time can be used to control the\nfrequency with which the replication applier sends HTTP log fetch requests\nto the leader in case there is no write activity on the leader.\nThis value will be ignored if set to `0`.\n", "type": "integer" }, "includeSystem": { "description": "whether or not system collection operations will be applied\n", "type": "boolean" }, "initialSyncMaxWaitTime": { "description": "the maximum wait time (in seconds) that the initial synchronization will\nwait for a response from the leader when fetching initial collection data.\nThis wait time can be used to control after what time the initial synchronization\nwill give up waiting for a response and fail. This value is relevant even\nfor continuous replication when `autoResync` is set to `true` because this\nmay re-start the initial synchronization when the leader cannot provide\nlog data the follower requires.\nThis value will be ignored if set to `0`.\n", "type": "integer" }, "maxConnectRetries": { "description": "the maximum number of connection attempts the applier\nwill make in a row. If the applier cannot establish a connection to the\nendpoint in this number of attempts, it will stop itself.\n", "type": "integer" }, "password": { "description": "the password to use when connecting to the leader.\n", "type": "string" }, "requestTimeout": { "description": "the timeout (in seconds) for individual requests to the endpoint.\n", "type": "integer" }, "requireFromPresent": { "description": "if set to `true`, then the replication applier will check\nat start of its continuous replication if the start tick from the dump phase\nis still present on the leader. If not, then there would be data loss. If\n`requireFromPresent` is `true`, the replication applier will abort with an\nappropriate error message. If set to `false`, then the replication applier will\nstill start, and ignore the data loss.\n", "type": "boolean" }, "restrictCollections": { "description": "an optional array of collections for use with `restrictType`.\nIf `restrictType` is `include`, only the specified collections\nwill be synchronized. If `restrictType` is `exclude`, all but the specified\ncollections will be synchronized.\n", "items": { "type": "string" }, "type": "array" }, "restrictType": { "description": "an optional string value for collection filtering. When\nspecified, the allowed values are `include` or `exclude`.\n", "type": "string" }, "username": { "description": "an optional ArangoDB username to use when connecting to the leader.\n", "type": "string" }, "verbose": { "description": "if set to `true`, then a log line will be emitted for all operations\nperformed by the replication applier. This should be used for debugging\nreplication\nproblems only.\n", "type": "boolean" } }, "required": [ "endpoint", "database", "password", "includeSystem" ], "type": "object" } } } }, "responses": { "200": { "description": "is returned if the request was executed successfully.\n" }, "400": { "description": "is returned if the configuration is incomplete or malformed.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred during synchronization or when starting the\ncontinuous replication.\n" }, "501": { "description": "is returned when this operation is called on a Coordinator in a cluster deployment.\n" } }, "summary": "Turn a server into a follower of another", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/revisions/documents": { "put": { "description": "\u003e **WARNING:**\nThis revision-based replication endpoint will only work with collections\ncreated in ArangoDB v3.8.0 or later.\n\n\nReturns documents by revision for replication.\n\nThe body of the request should be JSON/VelocyPack and should consist of an\narray of string-encoded revision IDs:\n\n```\n[\n \u003cString, revision\u003e,\n \u003cString, revision\u003e,\n ...\n \u003cString, revision\u003e\n]\n```\n\nIn particular, the revisions should be sorted in ascending order of their\ndecoded values.\n\nThe result will be a JSON/VelocyPack array of document objects. If there is no\ndocument corresponding to a particular requested revision, an empty object will\nbe returned in its place.\n\nThe response may be truncated if it would be very long. In this case, the\nresponse array length will be less than the request array length, and\nsubsequent requests can be made for the omitted documents.\n\nEach `\u003cString, revision\u003e` value type is a 64-bit value encoded as a string of\n11 characters, using the same encoding as our document `_rev` values. The\nreason for this is that 64-bit values cannot necessarily be represented in full\nin JavaScript, as it handles all numbers as floating point, and can only\nrepresent up to `2^53-1` faithfully.\n", "operationId": "listReplicationRevisionDocuments", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name or id of the collection to query.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The id of the snapshot to use\n", "in": "query", "name": "batchId", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully and data was returned.\n" }, "401": { "description": "is returned if necessary parameters are missing or incorrect\n" }, "404": { "description": "is returned when the collection or snapshot could not be found.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" }, "501": { "description": "is returned if called on a collection which doesn't support sync-by-revision\n" } }, "summary": "Get documents by revision", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/revisions/ranges": { "put": { "description": "\u003e **WARNING:**\nThis revision-based replication endpoint will only work with the RocksDB\nengine, and with collections created in ArangoDB v3.8.0 or later.\n\n\nReturns the revision IDs of documents within the requested ranges.\n\nThe body of the request should be JSON/VelocyPack and should consist of an\narray of pairs of string-encoded revision IDs:\n\n```\n[\n [\u003cString, revision\u003e, \u003cString, revision\u003e],\n [\u003cString, revision\u003e, \u003cString, revision\u003e],\n ...\n [\u003cString, revision\u003e, \u003cString, revision\u003e]\n]\n```\n\nIn particular, the pairs should be non-overlapping, and sorted in ascending\norder of their decoded values.\n\nThe result will be JSON/VelocyPack in the following format:\n```\n{\n ranges: [\n [\u003cString, revision\u003e, \u003cString, revision\u003e, ... \u003cString, revision\u003e],\n [\u003cString, revision\u003e, \u003cString, revision\u003e, ... \u003cString, revision\u003e],\n ...,\n [\u003cString, revision\u003e, \u003cString, revision\u003e, ... \u003cString, revision\u003e]\n ]\n resume: \u003cString, revision\u003e\n}\n```\n\nThe `resume` field is optional. If specified, then the response is to be\nconsidered partial, only valid through the revision specified. A subsequent\nrequest should be made with the same request body, but specifying the `resume`\nURL parameter with the value specified. The subsequent response will pick up\nfrom the appropriate request pair, and omit any complete ranges or revisions\nwhich are less than the requested resume revision. As an example (ignoring the\nstring-encoding for a moment), if ranges `[1, 3], [5, 9], [12, 15]` are\nrequested, then a first response may return `[], [5, 6]` with a resume point of\n`7` and a subsequent response might be `[8], [12, 13]`.\n\nIf a requested range contains no revisions, then an empty array is returned.\nEmpty ranges will not be omitted.\n\nEach `\u003cString, revision\u003e` value type is a 64-bit value encoded as a string of\n11 characters, using the same encoding as our document `_rev` values. The\nreason for this is that 64-bit values cannot necessarily be represented in full\nin JavaScript, as it handles all numbers as floating point, and can only\nrepresent up to `2^53-1` faithfully.\n", "operationId": "listReplicationRevisionRanges", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name or id of the collection to query.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The id of the snapshot to use\n", "in": "query", "name": "batchId", "required": true, "schema": { "type": "number" } }, { "description": "The revision at which to resume, if a previous request was truncated\n", "in": "query", "name": "resume", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully and data was returned.\n" }, "401": { "description": "is returned if necessary parameters are missing or incorrect\n" }, "404": { "description": "is returned when the collection or snapshot could not be found.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" }, "501": { "description": "is returned if called on a collection which doesn't support sync-by-revision\n" } }, "summary": "List document revision IDs within requested ranges", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/revisions/tree": { "get": { "description": "\u003e **WARNING:**\nThis revision-based replication endpoint will only work with collections\ncreated in ArangoDB v3.8.0 or later.\n\n\nReturns the Merkle tree associated with the specified collection.\n\nThe result will be JSON/VelocyPack in the following format:\n```\n{\n version: \u003cNumber\u003e,\n branchingFactor: \u003cNumber\u003e\n maxDepth: \u003cNumber\u003e,\n rangeMin: \u003cString, revision\u003e,\n rangeMax: \u003cString, revision\u003e,\n nodes: [\n { count: \u003cNumber\u003e, hash: \u003cString, revision\u003e },\n { count: \u003cNumber\u003e, hash: \u003cString, revision\u003e },\n ...\n { count: \u003cNumber\u003e, hash: \u003cString, revision\u003e }\n ]\n}\n```\n\nAt the moment, there is only one version, 1, so this can safely be ignored for\nnow.\n\nEach `\u003cString, revision\u003e` value type is a 64-bit value encoded as a string of\n11 characters, using the same encoding as our document `_rev` values. The\nreason for this is that 64-bit values cannot necessarily be represented in full\nin JavaScript, as it handles all numbers as floating point, and can only\nrepresent up to `2^53-1` faithfully.\n\nThe node count should correspond to a full tree with the given `maxDepth` and\n`branchingFactor`. The nodes are laid out in level-order tree traversal, so the\nroot is at index `0`, its children at indices `[1, branchingFactor]`, and so\non.\n", "operationId": "getReplicationRevisionTree", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name or id of the collection to query.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } }, { "description": "The id of the snapshot to use\n", "in": "query", "name": "batchId", "required": true, "schema": { "type": "number" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully and data was returned.\n" }, "401": { "description": "is returned if necessary parameters are missing\n" }, "404": { "description": "is returned when the collection or snapshot could not be found.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" }, "501": { "description": "is returned if called on a collection which doesn't support sync-by-revision\n" } }, "summary": "Get the replication revision tree", "tags": [ "Replication" ] }, "post": { "description": "\u003e **WARNING:**\nThis revision-based replication endpoint will only work with collections\ncreated in ArangoDB v3.8.0 or later.\n\n\nRebuilds the Merkle tree for a collection.\n\nIf successful, there will be no return body.\n", "operationId": "rebuildReplicationRevisionTree", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name or id of the collection to query.\n", "in": "query", "name": "collection", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "is returned if the request was executed successfully.\n" }, "401": { "description": "is returned if necessary parameters are missing\n" }, "404": { "description": "is returned when the collection or could not be found.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" }, "501": { "description": "is returned if called on a collection which doesn't support sync-by-revision\n" } }, "summary": "Rebuild the replication revision tree", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/server-id": { "get": { "description": "Returns the servers id. The id is also returned by other replication API\nmethods, and this method is an easy means of determining a server's id.\n\nThe body of the response is a JSON object with the attribute `serverId`. The\nserver id is returned as a string.\n", "operationId": "getReplicationServerId", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" } }, "summary": "Get the replication server ID", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/replication/sync": { "put": { "description": "Starts a full data synchronization from a remote endpoint into the local\nArangoDB database.\n\nThe *sync* method can be used by replication clients to connect an ArangoDB database\nto a remote endpoint, fetch the remote list of collections and indexes, and collection\ndata. It will thus create a local backup of the state of data at the remote ArangoDB\ndatabase. *sync* works on a per-database level.\n\n*sync* will first fetch the list of collections and indexes from the remote endpoint.\nIt does so by calling the *inventory* API of the remote database. It will then purge\ndata in the local ArangoDB database, and after start will transfer collection data\nfrom the remote database to the local ArangoDB database. It will extract data from the\nremote database by calling the remote database's *dump* API until all data are fetched.\n\nIn case of success, the body of the response is a JSON object with the following\nattributes:\n\n- *collections*: an array of collections that were transferred from the endpoint\n\n- *lastLogTick*: the last log tick on the endpoint at the time the transfer\n was started. Use this value as the *from* value when starting the continuous\n synchronization later.\n\nWARNING: calling this method will synchronize data from the collections found\non the remote endpoint to the local ArangoDB database. All data in the local\ncollections will be purged and replaced with data from the endpoint.\n\nUse with caution!\n\n\u003e **INFO:**\nThis method is not supported on a Coordinator in a cluster deployment.\n", "operationId": "startReplicationSync", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "database": { "description": "the database name on the leader (if not specified, defaults to the\nname of the local current database).\n", "type": "string" }, "endpoint": { "description": "the leader endpoint to connect to (e.g. \"tcp://192.168.173.13:8529\").\n", "type": "string" }, "includeSystem": { "description": "whether or not system collection operations will be applied\n", "type": "boolean" }, "incremental": { "description": "if set to *true*, then an incremental synchronization method will be used\nfor synchronizing data in collections. This method is useful when\ncollections already exist locally, and only the remaining differences need\nto be transferred from the remote endpoint. In this case, the incremental\nsynchronization can be faster than a full synchronization.\nThe default value is *false*, meaning that the complete data from the remote\ncollection will be transferred.\n", "type": "boolean" }, "initialSyncMaxWaitTime": { "description": "the maximum wait time (in seconds) that the initial synchronization will\nwait for a response from the leader when fetching initial collection data.\nThis wait time can be used to control after what time the initial synchronization\nwill give up waiting for a response and fail.\nThis value will be ignored if set to *0*.\n", "type": "integer" }, "password": { "description": "the password to use when connecting to the endpoint.\n", "type": "string" }, "restrictCollections": { "description": "an optional array of collections for use with\n*restrictType*. If *restrictType* is *include*, only the specified collections\nwill be synchronized. If *restrictType* is *exclude*, all but the specified\ncollections will be synchronized.\n", "items": { "type": "string" }, "type": "array" }, "restrictType": { "description": "an optional string value for collection filtering. When\nspecified, the allowed values are *include* or *exclude*.\n", "type": "string" }, "username": { "description": "an optional ArangoDB username to use when connecting to the endpoint.\n", "type": "string" } }, "required": [ "endpoint", "password" ], "type": "object" } } } }, "responses": { "200": { "description": "is returned if the request was executed successfully.\n" }, "400": { "description": "is returned if the configuration is incomplete or malformed.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred during synchronization.\n" }, "501": { "description": "is returned when this operation is called on a Coordinator in a cluster deployment.\n" } }, "summary": "Start replication from a remote endpoint", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/tasks": { "get": { "deprecated": true, "description": "Fetches all existing tasks on the server.\n", "operationId": "listTasks", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "A list of all tasks.\n", "items": { "properties": { "command": { "description": "The JavaScript function for this task.\n", "type": "string" }, "created": { "description": "The timestamp when this task was created.\n", "type": "number" }, "database": { "description": "The database this task belongs to.\n", "type": "string" }, "id": { "description": "A string identifying the task.\n", "type": "string" }, "name": { "description": "A user-friendly name for the task.\n", "type": "string" }, "offset": { "description": "Time offset in seconds from the `created` timestamp.\n", "type": "number" }, "period": { "description": "This task should run each `period` seconds.\n", "type": "number" }, "type": { "description": "What type of task is this [ `periodic`, `timed`]\n - periodic are tasks that repeat periodically\n - timed are tasks that execute once at a specific time\n", "type": "string" } }, "required": [ "name", "id", "created", "type", "period", "offset", "command", "database" ], "type": "object" }, "type": "array" } } }, "description": "The list of tasks.\n" } }, "summary": "List all tasks", "tags": [ "Tasks" ] }, "post": { "deprecated": true, "description": "Creates a new task with a generated identifier.\n", "operationId": "createTask", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "command": { "description": "The JavaScript code to be executed.\n", "type": "string" }, "name": { "default": "user-defined task", "description": "The name of the task.\n", "type": "string" }, "offset": { "default": 0, "description": "The number of seconds for the initial delay.\n", "type": "integer" }, "params": { "description": "The value to be passed to the command.\nIt can be of any type.\n" }, "period": { "description": "The number of seconds between the executions.\n", "type": "integer" } }, "required": [ "command" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "command": { "description": "The JavaScript code of this task.\n", "type": "string" }, "created": { "description": "The timestamp when this task was created.\n", "type": "number" }, "database": { "description": "The database this task belongs to.\n", "type": "string" }, "id": { "description": "A string identifying the task.\n", "type": "string" }, "name": { "description": "The name of the task.\n", "type": "string" }, "offset": { "description": "The time offset in seconds from the created timestamp.\n", "type": "number" }, "period": { "description": "The task runs every `period` seconds.\n", "type": "number" }, "type": { "description": "The kind of the task:\n- `\"periodic\"`: The task repeats periodically\n- `\"timed\"`: The task executes once at a specific time\n", "enum": [ "periodic", "timed" ], "type": "string" } }, "required": [ "id", "name", "created", "type", "period", "offset", "command", "database" ], "type": "object" } } }, "description": "The task has been registered.\n" }, "400": { "description": "The task can't be registered because the request is invalid.\n" } }, "summary": "Create a task", "tags": [ "Tasks" ] } }, "/_db/{database-name}/_api/tasks/{id}": { "delete": { "deprecated": true, "description": "Deletes the task identified by `id` on the server.\n", "operationId": "deleteTask", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has administrate access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The id of the task to delete.\n", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "`false` in this case\n", "type": "boolean" } }, "required": [ "code", "error" ], "type": "object" } } }, "description": "If the task was deleted, *HTTP 200* is returned.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" } }, "required": [ "code", "error", "errorMessage" ], "type": "object" } } }, "description": "If the task `id` is unknown, then an *HTTP 404* is returned.\n" } }, "summary": "Delete a task", "tags": [ "Tasks" ] }, "get": { "deprecated": true, "description": "fetches one existing task on the server specified by `id`\n", "operationId": "getTask", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The id of the task to fetch.\n", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The function in question.\n", "properties": { "command": { "description": "The JavaScript function for this task.\n", "type": "string" }, "created": { "description": "The timestamp when this task was created.\n", "type": "number" }, "database": { "description": "The database this task belongs to.\n", "type": "string" }, "id": { "description": "A string identifying the task.\n", "type": "string" }, "name": { "description": "A user-friendly name for the task.\n", "type": "string" }, "offset": { "description": "Time offset in seconds from the `created` timestamp.\n", "type": "number" }, "period": { "description": "This task should run each `period` seconds.\n", "type": "number" }, "type": { "description": "What type of task is this [ `periodic`, `timed`]\n - periodic are tasks that repeat periodically\n - timed are tasks that execute once at a specific time\n", "type": "string" } }, "required": [ "name", "id", "created", "type", "period", "offset", "command", "database" ], "type": "object" } } }, "description": "The requested task.\n" } }, "summary": "Get a task", "tags": [ "Tasks" ] }, "put": { "deprecated": true, "description": "Registers a new task with the specified ID.\n\nNot compatible with load balancers.\n", "operationId": "createTaskWithId", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The id of the task to create\n", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "command": { "description": "The JavaScript code to be executed.\n", "type": "string" }, "name": { "description": "The name of the task.\n", "type": "string" }, "offset": { "default": 0, "description": "The number of seconds for the initial delay.\n", "type": "integer" }, "params": { "description": "The value to be passed to the command.\nIt can be of any type.\n" }, "period": { "description": "The number of seconds between the executions.\n", "type": "integer" } }, "required": [ "command" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "command": { "description": "The JavaScript code of this task.\n", "type": "string" }, "created": { "description": "The timestamp when this task was created.\n", "type": "number" }, "database": { "description": "The database this task belongs to.\n", "type": "string" }, "id": { "description": "The user-provided string identifying the task.\n", "type": "string" }, "name": { "description": "The name of the task.\n", "type": "string" }, "offset": { "description": "The time offset in seconds from the created timestamp.\n", "type": "number" }, "period": { "description": "The task runs every `period` seconds.\n", "type": "number" }, "type": { "description": "The kind of the task:\n- `\"periodic\"`: The task repeats periodically\n- `\"timed\"`: The task executes once at a specific time\n", "enum": [ "periodic", "timed" ], "type": "string" } }, "required": [ "id", "name", "created", "type", "period", "offset", "command", "database" ], "type": "object" } } }, "description": "The task has been registered.\n" }, "400": { "description": "The task can't be registered because the request is invalid.\n" }, "409": { "description": "A task with the specified `id` already exists.\n" } }, "summary": "Create a task with ID", "tags": [ "Tasks" ] } }, "/_db/{database-name}/_api/transaction": { "get": { "description": "List the currently running Stream Transactions.\nIn a cluster, the list contains the transactions from all Coordinators.\n", "operationId": "listStreamTransactions", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "transactions": { "description": "An array of currently running transactions. In a cluster, this\ncontains the transactions from all Coordinators.\n", "items": { "properties": { "id": { "description": "The identifier of the transaction.\n", "type": "string" }, "state": { "const": "running", "description": "The status of the transaction. Always `running`\nif it's in the list of running transactions.\n", "type": "string" } }, "required": [ "id", "state" ], "type": "object" }, "type": "array" } }, "required": [ "transactions" ], "type": "object" } } }, "description": "The list of transactions can be retrieved successfully.\n" } }, "summary": "List the running Stream Transactions", "tags": [ "Transactions" ] }, "post": { "deprecated": true, "description": "\u003e **WARNING:**\nJavaScript Transactions are deprecated from v3.12.0 onward and are\nremoved in v4.0.\n\n\nThe transaction description must be passed in the body of the POST request.\n\nIf the transaction is fully executed and committed on the server,\n*HTTP 200* will be returned. Additionally, the return value of the\ncode defined in `action` will be returned in the `result` attribute.\n\nFor successfully committed transactions, the returned JSON object has the\nfollowing properties:\n\n- `error`: boolean flag to indicate if an error occurred (`false`\n in this case)\n\n- `code`: the HTTP status code\n\n- `result`: the return value of the transaction\n\nIf the transaction specification is either missing or malformed, the server\nwill respond with *HTTP 400*.\n\nThe body of the response will then contain a JSON object with additional error\ndetails. The object has the following attributes:\n\n- `error`: boolean flag to indicate that an error occurred (`true` in this case)\n\n- `code`: the HTTP status code\n\n- `errorNum`: the server error number\n\n- `errorMessage`: a descriptive error message\n\nIf a transaction fails to commit, either by an exception thrown in the\n`action` code, or by an internal error, the server will respond with\nan error.\nAny other errors will be returned with any of the return codes\n*HTTP 400*, *HTTP 409*, or *HTTP 500*.\n", "operationId": "executeJavaScriptTransaction", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "action": { "description": "The actual transaction operations to be executed, in the\nform of stringified JavaScript code. The code is executed on the server\nside, with late binding. It is thus critical that the code specified in\n`action` properly sets up all the variables it needs.\nIf the code specified in `action` ends with a return statement, the\nvalue returned is also returned by the REST API in the `result`\nattribute if the transaction committed successfully.\n", "type": "string" }, "allowImplicit": { "default": true, "description": "Allow reading from undeclared collections.\n", "type": "boolean" }, "collections": { "description": "Must be a JSON object that can have one or all sub-attributes\n`read`, `write` or `exclusive`, each being an array of collection names or a\nsingle collection name as string. Collections that will be written to in the\ntransaction must be declared with the `write` or `exclusive` attribute or it\nwill fail, whereas non-declared collections from which is solely read will be\nadded lazily. The optional sub-attribute `allowImplicit` can be set to `false`\nto let transactions fail in case of undeclared collections for reading.\nCollections for reading should be fully declared if possible, to avoid\ndeadlocks.\n", "properties": { "exclusive": { "description": "A single collection or a list of collections to acquire\nexclusive write access for.\n" }, "read": { "description": "A single collection or a list of collections to use in\nthe transaction in read-only mode.\n" }, "write": { "description": "A single collection or a list of collections to use in\nthe transaction in write or read mode.\n" } }, "type": "object" }, "lockTimeout": { "default": 900, "description": "The timeout in seconds for waiting on collection locks.\nThis option is only meaningful when using exclusive locks.\nSet `lockTimeout` to `0` to make ArangoDB not time out\nwaiting for a lock.\n", "type": "integer" }, "maxTransactionSize": { "default": 18446744073709551615, "description": "Transaction size limit in bytes.\n", "type": "integer" }, "params": { "description": "Optional argument passed to `action`. Can be of any type.\n" }, "waitForSync": { "description": "An optional boolean flag that, if set, forces the\ntransaction to write all data to disk before returning.\n", "type": "boolean" } }, "required": [ "collections", "action" ], "type": "object" } } } }, "responses": { "200": { "description": "If the transaction is fully executed and committed on the server,\n*HTTP 200* will be returned.\n" }, "400": { "description": "If the transaction specification is either missing or malformed, the server\nwill respond with *HTTP 400*.\n" }, "404": { "description": "If the transaction specification contains an unknown collection, the server\nwill respond with *HTTP 404*.\n" }, "500": { "description": "Exceptions thrown by users will make the server respond with a return code of\n*HTTP 500*\n" } }, "summary": "Execute a JavaScript Transaction", "tags": [ "Transactions" ] } }, "/_db/{database-name}/_api/transaction/begin": { "post": { "description": "Begin a Stream Transaction that allows clients to call selected APIs over a\nshort period of time, referencing the transaction ID, and have the server\nexecute the operations transactionally.\n\nCommitting or aborting a running transaction must be done by the client.\nIt is bad practice to not commit or abort a transaction once you are done\nusing it. It forces the server to keep resources and collection locks\nuntil the entire transaction times out.\n\nThe transaction description must be passed in the body of the POST request.\n", "operationId": "beginStreamTransaction", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Set this header to `true` to allow the Coordinator to ask any shard replica for\nthe data, not only the shard leader. This may result in \"dirty reads\".\n\nThis header decides about dirty reads for the entire transaction. Individual\nread operations, that are performed as part of the transaction, cannot override it.\n", "in": "header", "name": "x-arango-allow-dirty-read", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "allowImplicit": { "default": true, "description": "Allow reading from undeclared collections.\n", "type": "boolean" }, "collections": { "description": "Must be a JSON object that can have the sub-attributes\n`read`, `write`, and `exclusive`, each being an array of collection names or a\nsingle collection name as string. Collections that will be written to in the\ntransaction must be declared with the `write` or `exclusive` attribute or the\nrespective write operations will fail (but not automatically abort the\nStream Transaction), whereas non-declared collections from which is solely\nread will be added lazily.\n", "properties": { "exclusive": { "description": "A single collection or a list of collections to acquire\nexclusive write access for.\n" }, "read": { "description": "A single collection or a list of collections to use in\nthe transaction in read-only mode.\n" }, "write": { "description": "A single collection or a list of collections to use in\nthe transaction in write or read mode.\n" } }, "type": "object" }, "lockTimeout": { "default": 900, "description": "The timeout in seconds for waiting on collection locks.\nThis option is only meaningful when using exclusive locks.\nSet `lockTimeout` to `0` to make ArangoDB not time out\nwaiting for a lock.\n", "type": "integer" }, "maxTransactionSize": { "description": "Transaction size limit in bytes.\n\nDefault: Controlled by the [`--transaction.streaming-max-transaction-size` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--transactionstreaming-max-transaction-size).\n", "type": "integer" }, "skipFastLockRound": { "default": false, "description": "Whether to disable fast locking for write operations.\n\nSkipping the fast lock round can be faster overall if there are many concurrent\nStream Transactions queued that all try to lock the same collection exclusively.\nIt avoids deadlocking and retrying which can occur with the fast locking by\nguaranteeing a deterministic locking order at the expense of each actual\nlocking operation taking longer.\n\nFast locking should not be skipped for read-only Stream Transactions because\nit degrades performance if there are no concurrent transactions that use\nexclusive locks on the same collection.\n", "type": "boolean" }, "waitForSync": { "description": "An optional boolean flag that, if set, forces the\ntransaction to write all data to disk before returning.\n", "type": "boolean" } }, "required": [ "collections" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 201, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "An object describing the started transaction.\n", "properties": { "id": { "description": "The identifier of the transaction.\n", "type": "string" }, "status": { "const": "running", "description": "The status of the transaction. Always `running` for a\nsuccessfully started transaction.\n", "type": "string" } }, "required": [ "id", "status" ], "type": "object" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "The transaction has been started on the server.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The transaction specification is either missing or malformed.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The transaction specification contains an unknown collection.\n" } }, "summary": "Begin a Stream Transaction", "tags": [ "Transactions" ] } }, "/_db/{database-name}/_api/transaction/{transaction-id}": { "delete": { "description": "Abort a running server-side transaction. Aborting is an idempotent operation.\nIt is not an error to abort a transaction more than once.\n\nThe server remembers a transaction's final state for a limited time after\nit ends. As a result, the response can vary depending on when you call\nthis endpoint:\n\n- While the transaction is still tracked: aborting an already-aborted\n transaction returns `200` (idempotent), and aborting an already-committed\n transaction returns `400`.\n- The first abort against an unknown identifier returns `404` and records\n it as aborted. Subsequent aborts for the same identifier return `200`\n until the record is garbage-collected, after which the identifier is\n again unknown and the next abort once more returns `404`.\n", "operationId": "abortStreamTransaction", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The transaction identifier,\n", "in": "path", "name": "transaction-id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "An object describing the aborted transaction.\n", "properties": { "id": { "description": "The identifier of the transaction.\n", "type": "string" }, "status": { "const": "aborted", "description": "The status of the transaction. Always `aborted` for a\nsuccessfully aborted transaction.\n", "type": "string" } }, "required": [ "id", "status" ], "type": "object" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "The transaction has been aborted.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The transaction identifier is malformed, or the transaction is in\na state that does not allow aborting (for example, it was\nalready committed).\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "No transaction is known under the specified identifier.\n" } }, "summary": "Abort a Stream Transaction", "tags": [ "Transactions" ] }, "get": { "description": "Retrieve the status of a Stream Transaction by its identifier.\n\nAfter a transaction is committed or aborted, the server remembers its\nfinal state for a limited time. During this window, querying the\ntransaction returns its final status (`committed` or `aborted`). Once\nthe server garbage-collects this record, the same identifier becomes\nunknown and the endpoint returns `404`.\n", "operationId": "getStreamTransaction", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The transaction identifier.\n", "in": "path", "name": "transaction-id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "An object describing the status of the transaction.\n", "properties": { "id": { "description": "The identifier of the transaction.\n", "type": "string" }, "status": { "description": "The status of the transaction.\n", "enum": [ "running", "committed", "aborted" ], "type": "string" } }, "required": [ "id", "status" ], "type": "object" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "The transaction is found and its status returned.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The transaction identifier is either missing or malformed.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "No transaction was found with the specified identifier.\n" } }, "summary": "Get the status of a Stream Transaction", "tags": [ "Transactions" ] }, "put": { "description": "Commit a running server-side transaction. Committing is an idempotent operation.\nIt is not an error to commit a transaction more than once.\n\nThe server remembers a transaction's final state for a limited time after\nit ends. As a result, the response can vary depending on when you call\nthis endpoint:\n\n- While the transaction is still tracked: committing an already-committed\n transaction returns `200` (idempotent), and committing an already-aborted\n transaction returns `400`.\n- Once the server has garbage-collected the transaction's record, the\n identifier is no longer known and the endpoint returns `404`.\n", "operationId": "commitStreamTransaction", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The transaction identifier,\n", "in": "path", "name": "transaction-id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "An object describing the committed transaction.\n", "properties": { "id": { "description": "The identifier of the transaction.\n", "type": "string" }, "status": { "const": "committed", "description": "The status of the transaction. Always `committed` for a\nsuccessfully committed transaction.\n", "type": "string" } }, "required": [ "id", "status" ], "type": "object" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "The transaction has been committed.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The transaction identifier is malformed, or the transaction is in\na state that does not allow committing (for example, it was\nalready aborted).\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "No transaction is known under the specified identifier.\n" } }, "summary": "Commit a Stream Transaction", "tags": [ "Transactions" ] } }, "/_db/{database-name}/_api/user": { "get": { "description": "Fetches data about all users. You need the *Administrate* server access level\nin order to execute this REST call. Otherwise, you will only get information\nabout yourself.\n\nThe call will return a JSON object with at least the following\nattributes on success:\n\n- `user`: The name of the user as a string.\n- `active`: Whether the user account is able to log in to the database system.\n- `extra`: A JSON object with extra user information. It is used by the web\n interface to store graph viewer settings and saved queries.\n", "operationId": "listUsers", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The users that were found.\n" }, "401": { "description": "Returned if you have *No access* database access level to the `_system`\ndatabase.\n" }, "403": { "description": "Returned if you have *No access* server access level.\n" } }, "summary": "List available users", "tags": [ "Users" ] }, "post": { "description": "Create a new user. You need server access level *Administrate* in order to\nexecute this REST call.\n", "operationId": "createUser", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "active": { "default": true, "description": "Whether the user account should be able to log in to the database system.\n", "type": "boolean" }, "extra": { "description": "A JSON object with extra user information. It is used by the web interface\nto store graph viewer settings and saved queries. Should not be set or\nmodified by end users, as custom attributes will not be preserved.\n", "type": "object" }, "passwd": { "default": "", "description": "The user password as a string. If not specified, it defaults to an empty\nstring.\n", "type": "string" }, "user": { "description": "The name of the user as a string. This is mandatory.\n", "type": "string" } }, "required": [ "user" ], "type": "object" } } } }, "responses": { "201": { "description": "Returned if the user can be added by the server\n" }, "400": { "description": "If the JSON representation is malformed or mandatory data is missing\nfrom the request.\n" }, "401": { "description": "Returned if you have *No access* database access level to the `_system`\ndatabase.\n" }, "403": { "description": "Returned if you have *No access* server access level.\n" }, "409": { "description": "Returned if a user with the same name already exists.\n" } }, "summary": "Create a user", "tags": [ "Users" ] } }, "/_db/{database-name}/_api/user/{user}": { "delete": { "description": "Removes an existing user, identified by `user`.\n\nYou need *Administrate* permissions for the server access level in order to\nexecute this REST call.\n", "operationId": "deleteUser", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the user\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Is returned if the user was removed by the server\n" }, "401": { "description": "Returned if you have *No access* database access level to the `_system`\ndatabase.\n" }, "403": { "description": "Returned if you have *No access* server access level.\n" }, "404": { "description": "The specified user does not exist\n" } }, "summary": "Remove a user", "tags": [ "Users" ] }, "get": { "description": "Fetches data about the specified user. You can fetch information about\nyourself or you need the *Administrate* server access level in order to\nexecute this REST call.\n", "operationId": "getUser", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the user\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The user was found.\n" }, "401": { "description": "Returned if you have *No access* database access level to the `_system`\ndatabase.\n" }, "403": { "description": "Returned if you have *No access* server access level.\n" }, "404": { "description": "The user with the specified name does not exist.\n" } }, "summary": "Get a user", "tags": [ "Users" ] }, "patch": { "description": "Partially modifies the data of an existing user. You need server access level\n*Administrate* in order to execute this REST call. Additionally, users can\nchange their own data.\n", "operationId": "updateUserData", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the user.\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "active": { "description": "Whether the user account should be able to log in to the database system.\n", "type": "boolean" }, "extra": { "description": "A JSON object with extra user information. It is used by the web interface\nto store graph viewer settings and saved queries. Should not be set or\nmodified by end users, as custom attributes will not be preserved.\n", "type": "object" }, "passwd": { "description": "The user password as a string.\n", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Is returned if the user data can be replaced by the server.\n" }, "400": { "description": "The JSON representation is malformed or mandatory data is missing from the request.\n" }, "401": { "description": "Returned if you have *No access* database access level to the *_system*\ndatabase.\n" }, "403": { "description": "Returned if you have *No access* server access level.\n" }, "404": { "description": "The specified user does not exist\n" } }, "summary": "Update a user", "tags": [ "Users" ] }, "put": { "description": "Replaces the data of an existing user. This resets the user's\naccess levels for databases and collections. You need server access level\n*Administrate* in order to execute this REST call. Additionally, users can\nchange their own data.\n", "operationId": "replaceUserData", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the user.\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "active": { "default": true, "description": "Whether the user account should be able to log in to the database system.\n", "type": "boolean" }, "extra": { "description": "A JSON object with extra user information. It is used by the web interface\nto store graph viewer settings and saved queries. Should not be set or\nmodified by end users, as custom attributes will not be preserved.\n", "type": "object" }, "passwd": { "default": "", "description": "The user password as a string. If not specified, it defaults to an empty\nstring.\n", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Is returned if the user data can be replaced by the server.\n" }, "400": { "description": "The JSON representation is malformed or mandatory data is missing from the request\n" }, "401": { "description": "Returned if you have *No access* database access level to the *_system*\ndatabase.\n" }, "403": { "description": "Returned if you have *No access* server access level.\n" }, "404": { "description": "The specified user does not exist\n" } }, "summary": "Replace a user", "tags": [ "Users" ] } }, "/_db/{database-name}/_api/user/{user}/database": { "get": { "description": "Fetch the list of databases available to the specified `user`.\n\nYou need *Administrate* permissions for the server access level in order to\nexecute this REST call.\n\nThe call will return a JSON object with the per-database access\nprivileges for the specified user. The `result` object will contain\nthe databases names as object keys, and the associated privileges\nfor the database as values.\n\nIn case you specified `full`, the result will contain the permissions\nfor the databases as well as the permissions for the collections.\n", "operationId": "listUserDatabases", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the user for which you want to query the databases.\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "Return the full set of access levels for all databases and all collections.\n", "in": "query", "name": "full", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "Returned if the list of available databases can be returned.\n" }, "400": { "description": "If the access privileges are not right etc.\n" }, "401": { "description": "Returned if you have *No access* database access level to the `_system`\ndatabase.\n" }, "403": { "description": "Returned if you have *No access* server access level.\n" } }, "summary": "List a user\u0026rsquo;s accessible databases", "tags": [ "Users" ] } }, "/_db/{database-name}/_api/user/{user}/database/{dbname}": { "delete": { "description": "Clears the database access level for the database `dbname` of user `user`. As\nconsequence, the default database access level is used. If there is no defined\ndefault database access level, it defaults to *No access*.\n\nYou need write permissions (*Administrate* access level) for the `_system`\ndatabase in order to execute this REST call.\n", "operationId": "deleteUserDatabasePermissions", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the user.\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "The name of the database to clear the access level for.\n", "in": "path", "name": "dbname", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Returned if the access permissions were changed successfully.\n" }, "400": { "description": "If the JSON representation is malformed or mandatory data is missing\nfrom the request.\n" } }, "summary": "Clear a user\u0026rsquo;s database access level", "tags": [ "Users" ] }, "get": { "description": "Fetch the database access level for a specific database\n", "operationId": "getUserDatabasePermissions", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the user for which you want to query the databases.\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "The name of the database to query the access level of.\n", "in": "path", "name": "dbname", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the access level can be returned\n" }, "400": { "description": "If the access privileges are not right etc.\n" }, "401": { "description": "Returned if you have *No access* database access level to the `_system`\ndatabase.\n" }, "403": { "description": "Returned if you have *No access* server access level.\n" } }, "summary": "Get a user\u0026rsquo;s database access level", "tags": [ "Users" ] }, "put": { "description": "Sets the database access levels for the database `dbname` of user `user`. You\nneed the *Administrate* server access level in order to execute this REST\ncall.\n", "operationId": "setUserDatabasePermissions", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the user.\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "The name of the database to set the access level for.\n", "in": "path", "name": "dbname", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "grant": { "description": "- `\"rw\"`: Set the database access level to *Administrate*.\n- `\"ro\"`: Set the database access level to *Access*.\n- `\"none\"`: Set the database access level to *No access*.\n", "enum": [ "rw", "ro", "none" ], "type": "string" } }, "required": [ "grant" ], "type": "object" } } } }, "responses": { "200": { "description": "Returned if the access level was changed successfully.\n" }, "400": { "description": "If the JSON representation is malformed or mandatory data is missing\nfrom the request.\n" }, "401": { "description": "Returned if you have *No access* database access level to the `_system`\ndatabase.\n" }, "403": { "description": "Returned if you have *No access* server access level.\n" } }, "summary": "Set a user\u0026rsquo;s database access level", "tags": [ "Users" ] } }, "/_db/{database-name}/_api/user/{user}/database/{dbname}/{collection}": { "delete": { "description": "Clears the collection access level for the collection `collection` in the\ndatabase `dbname` of user `user`. As consequence, the default collection\naccess level is used. If there is no defined default collection access level,\nit defaults to *No access*.\n\nYou need write permissions (*Administrate* access level) for the `_system`\ndatabase in order to execute this REST call.\n", "operationId": "deleteUserCollectionPermissions", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the user.\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "The name of the database to clear the access level for.\n", "in": "path", "name": "dbname", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection to clear the access level for.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Returned if the access permissions were changed successfully.\n" }, "400": { "description": "If there was an error\n" } }, "summary": "Clear a user\u0026rsquo;s collection access level", "tags": [ "Users" ] }, "get": { "description": "Returns the collection access level for a specific collection\n", "operationId": "getUserCollectionPermissions", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the user for which you want to query the databases.\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "The name of the database to query the access level of.\n", "in": "path", "name": "dbname", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection to query the access level of.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned if the access level can be returned\n" }, "400": { "description": "If the access privileges are not right etc.\n" }, "401": { "description": "Returned if you have *No access* database access level to the `_system`\ndatabase.\n" }, "403": { "description": "Returned if you have *No access* server access level.\n" } }, "summary": "Get a user\u0026rsquo;s collection access level", "tags": [ "Users" ] }, "put": { "description": "Sets the collection access level for the `collection` in the database `dbname`\nfor user `user`. You need the *Administrate* server access level in order to\nexecute this REST call.\n", "operationId": "setUserCollectionPermissions", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database and administrate access to the `_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the user.\n", "in": "path", "name": "user", "required": true, "schema": { "type": "string" } }, { "description": "The name of the database to set the access level for.\n", "in": "path", "name": "dbname", "required": true, "schema": { "type": "string" } }, { "description": "The name of the collection to set the access level for.\n", "in": "path", "name": "collection", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "grant": { "description": "- `\"rw\"`: Set the collection access level to *Read/Write*.\n- `\"ro\"`: Set the collection access level to *Read Only*.\n- `\"none\"`: Set the collection access level to *No access*.\n", "enum": [ "rw", "ro", "none" ], "type": "string" } }, "required": [ "grant" ], "type": "object" } } } }, "responses": { "200": { "description": "Returned if the access permissions were changed successfully.\n" }, "400": { "description": "If the JSON representation is malformed or mandatory data is missing\nfrom the request.\n" }, "401": { "description": "Returned if you have *No access* database access level to the `_system`\ndatabase.\n" }, "403": { "description": "Returned if you have *No access* server access level.\n" } }, "summary": "Set a user\u0026rsquo;s collection access level", "tags": [ "Users" ] } }, "/_db/{database-name}/_api/version": { "get": { "description": "Returns the server name and version number.\n", "operationId": "getVersion", "parameters": [ { "description": "The name of a database. Which database you use doesn't matter as long\nas the user account you authenticate with has at least read access\nto this database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "If set to `true` and if the user account you authenticate with has\nadministrate access to the `_system` database, the response contains\na `details` attribute with additional information about included\ncomponents and their versions. The attribute names and internals of\nthe `details` object may vary depending on platform and ArangoDB version.\n", "in": "query", "name": "details", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "apiVersions": { "description": "The available versions of the HTTP API.\n", "items": { "enum": [ "v0" ], "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "deprecatedApiVersions": { "description": "The versions of the HTTP API that are still supported by\nthis ArangoDB server version but should no longer be used\nbecause of their pending removal in the next major version.\n", "items": { "enum": [], "type": "string" }, "type": "array", "uniqueItems": true }, "details": { "description": "an optional JSON object with additional details. This is\nreturned only if the `details` query parameter is set to `true` in the\nrequest.\n", "properties": { "architecture": { "const": "64bit", "description": "The CPU architecture in terms of bitness.\n", "type": "string" }, "arm": { "description": "Whether the server binary has been compiled for an ARM CPU.\n", "enum": [ "true", "false" ], "type": "string" }, "asan": { "description": "Whether the server has been compiled with the\nASAN address sanitizer enabled.\n", "enum": [ "true", "false" ], "type": "string" }, "assertions": { "description": "Whether the server has assertions compiled in\n(only in development builds).\n", "enum": [ "true", "false" ], "type": "string" }, "avx": { "description": "Whether the server binary has been compiled with\nAVX instruction support.\n", "enum": [ "true", "false" ], "type": "string" }, "avx2": { "description": "Whether the server binary has been compiled with\nAVX2 instruction support.\n", "enum": [ "true", "false" ], "type": "string" }, "boost-version": { "description": "Which version of the Boost library is used.\n", "type": "string" }, "build-date": { "description": "The date when this binary was created.\n", "type": "string" }, "build-id": { "description": "The Git commit hash this was compiled from.\n", "type": "string" }, "build-repository": { "description": "Reference to the Git ID this was compiled from.\n", "type": "string" }, "compiler": { "description": "The compiler that has been used.\n", "type": "string" }, "coverage": { "description": "Whether this build has code coverage instrumentation.\n", "enum": [ "true", "false" ], "type": "string" }, "cplusplus": { "description": "The C++ standards version.\n", "type": "string" }, "curl-version": { "description": "The linked cURL version, or `\"none\"` if not linked.\n", "type": "string" }, "debug": { "description": "Whether this is a debug build, `\"false\"` for\nproduction binaries.\n", "enum": [ "true", "false" ], "type": "string" }, "endianness": { "const": "little", "description": "The byte order of the system, detected at runtime.\n", "type": "string" }, "enterprise-build-repository": { "description": "Reference to the enterprise Git ID this was compiled from.\n", "type": "string" }, "enterprise-version": { "const": "enterprise", "description": "Only present if this is a build that includes the\nnon-public enterprise code.\n", "type": "string" }, "failure-tests": { "description": "Whether the facility to invoke fatal errors is compiled\nin, `\"false\"` for production binaries.\n", "enum": [ "true", "false" ], "type": "string" }, "faiss": { "description": "The FAISS library version, if linked.\n", "type": "string" }, "fd-client-event-handler": { "description": "Which method is used to handle fd-sets, typically `poll`\non Linux.\n", "type": "string" }, "fd-setsize": { "description": "If not `poll`, the fd setsize is valid for the maximum\nnumber of file descriptors.\n", "type": "string" }, "full-version-string": { "description": "The full version string including the build ID and\nthe versions of major dependencies.\n", "type": "string" }, "host": { "description": "The host ID.\n", "type": "string" }, "icu-version": { "description": "The version of the bundled ICU library.\n", "type": "string" }, "ipo": { "description": "Whether interprocedural optimization was enabled.\n", "enum": [ "true", "false" ], "type": "string" }, "iresearch-version": { "description": "The ArangoSearch/IResearch library version.\n", "type": "string" }, "jemalloc": { "description": "Whether the jemalloc memory allocator is used,\ntypically `\"true\"`\n", "enum": [ "true", "false" ], "type": "string" }, "libunwind": { "description": "Whether libunwind is linked for stack unwinding.\n", "type": "string" }, "license": { "description": "Whether this build of ArangoDB includes the non-public\nenterprise code. Reports `\"enterprise\"` for both the\nCommunity Edition and Enterprise Edition if you use the\nprepackaged binaries or official container images.\n", "enum": [ "community", "enterprise" ], "type": "string" }, "maintainer-mode": { "description": "Whether the server has been compiled in maintainer mode,\n`\"false\"` for production binaries.\n", "enum": [ "true", "false" ], "type": "string" }, "memory-profiler": { "description": "Whether the memory profiler is enabled.\n", "enum": [ "true", "false" ], "type": "string" }, "mode": { "description": "The mode the server runs in. **Deprecated**\n", "enum": [ "server", "console", "script" ], "type": "string" }, "ndebug": { "description": "Whether NDEBUG was defined for the build.\n", "enum": [ "true", "false" ], "type": "string" }, "openmp": { "description": "The OpenMP version used for parallelization.\n", "type": "string" }, "openssl-version": { "description": "The OpenSSL version that is linked.\n", "type": "string" }, "openssl-version-compile-time": { "description": "The OpenSSL version at compile time.\n", "type": "string" }, "openssl-version-run-time": { "description": "The OpenSSL version at run time.\n", "type": "string" }, "optimization-flags": { "description": "The compiler optimization flags used for this build.\n", "type": "string" }, "pic": { "description": "The position-independent code setting.\n", "type": "string" }, "pie": { "description": "The position-independent executable setting.\n", "type": "string" }, "platform": { "const": "linux", "description": "The operating system the server has been compiled for.\n", "type": "string" }, "reactor-type": { "const": "epoll", "description": "", "type": "string" }, "replication2-enabled": { "description": "Whether replication2 is enabled.\n", "enum": [ "true", "false" ], "type": "string" }, "rocksdb-version": { "description": "The rocksdb version this release bundles.\n", "type": "string" }, "role": { "description": "The server role.\n- `\"SINGLE\"`: Standalone single server\n- `\"PRIMARY\"`: DB-Server of a cluster\n- `\"COORDINATOR\"`: Coordinator of a cluster\n- `\"AGENT\"`: Part of the cluster's Agency\n", "enum": [ "SINGLE", "PRIMARY", "COORDINATOR", "AGENT" ], "type": "string" }, "server-version": { "description": "The ArangoDB release version.\n", "type": "string" }, "sizeof int": { "description": "Number of bytes for integers.\n", "type": "string" }, "sizeof long": { "description": "Number of bytes for long integers.\n", "type": "string" }, "sizeof void*": { "description": "Number of bytes for void pointers.\n", "type": "string" }, "sse42": { "description": "Whether the server binary has been compiled with\nSSE 4.2 instruction support.\n", "type": "string" }, "tsan": { "description": "Whether this was compiled with the thread sanitizer.\n", "enum": [ "true", "false" ], "type": "string" }, "unaligned-access": { "description": "Whether this system supports unaligned memory accesses.\n", "enum": [ "true", "false" ], "type": "string" }, "v8-version": { "description": "The bundled V8 JavaScript engine version.\n", "type": "string" }, "vpack-version": { "description": "The version of the used VelocyPack implementation.\n", "type": "string" }, "zlib-version": { "description": "The version of the bundled zlib compression library.\n", "type": "string" } }, "type": "object" }, "license": { "description": "Whether this build of ArangoDB includes the non-public\nenterprise code. Reports `\"enterprise\"` for both the\nCommunity Edition and Enterprise Edition if you use the\nprepackaged binaries or official container images.\n", "enum": [ "community", "enterprise" ], "type": "string" }, "requestedApiVersion": { "description": "The HTTP API version specified for this request via the\n`/_arango/{api-version}` prefix, or the default API version\nif not specified.\n", "enum": [ "v0" ], "type": "string" }, "server": { "const": "arango", "description": "", "type": "string" }, "version": { "description": "The server version string in the format `major.minor.sub`.\nThe `major` and `minor` parts are numeric, and `sub` is a\nnumber that may have a version suffix starting with\na hyphen minus (e.g. `3.12.7-2` or `4.0.0-devel`).\n", "type": "string" } }, "required": [ "server", "license", "version", "apiVersions", "deprecatedApiVersions", "requestedApiVersion" ], "type": "object" } } }, "description": "is returned in all cases.\n" } }, "summary": "Get the server version", "tags": [ "Administration" ] } }, "/_db/{database-name}/_api/view": { "get": { "description": "Returns an object containing a listing of all Views in the current database,\nregardless of their type.\n", "operationId": "listViews", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "The result object.\n", "items": { "properties": { "globallyUniqueId": { "description": "A unique identifier of the View. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the View (deprecated).\n", "type": "string" }, "name": { "description": "The name of the View.\n", "example": "coll", "type": "string" }, "type": { "description": "The type of the View.\n", "enum": [ "arangosearch", "search-alias" ], "type": "string" } }, "required": [ "name", "type", "id", "globallyUniqueId" ], "type": "object" }, "type": "array" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "The list of Views.\n" } }, "summary": "List all Views", "tags": [ "Views" ] }, "post": { "description": "Creates a new View with a given name and properties if it does not\nalready exist.\n", "operationId": "createView", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cleanupIntervalStep": { "default": 2, "description": "Wait at least this many commits between removing unused files in the\nArangoSearch data directory (`0` = disable).\nFor the case where the consolidation policies merge segments often (i.e. a lot\nof commit+consolidate), a lower value causes a lot of disk space to be\nwasted.\nFor the case where the consolidation policies rarely merge segments (i.e. few\ninserts/deletes), a higher value impacts performance without any added\nbenefits.\n\n_Background:_\n With every \"commit\" or \"consolidate\" operation, a new state of the View's\n internal data structures is created on disk.\n Old states/snapshots are released once there are no longer any users\n remaining.\n However, the files for the released states/snapshots are left on disk, and\n only removed by \"cleanup\" operation.\n", "type": "integer" }, "commitIntervalMsec": { "default": 1000, "description": "Wait at least this many milliseconds between committing View data store\nchanges and making documents visible to queries (`0` = disable).\nFor the case where there are a lot of inserts/updates, a higher value causes the\nindex not to account for them and memory usage continues to grow until the commit.\nA lower value impacts performance, including the case where there are no or only a\nfew inserts/updates because of synchronous locking, and it wastes disk space for\neach commit call.\n\n_Background:_\n For data retrieval, ArangoSearch follows the concept of\n \"eventually-consistent\", i.e. eventually all the data in ArangoDB will be\n matched by corresponding query expressions.\n The concept of ArangoSearch \"commit\" operations is introduced to\n control the upper-bound on the time until document addition/removals are\n actually reflected by corresponding query expressions.\n Once a \"commit\" operation is complete, all documents added/removed prior to\n the start of the \"commit\" operation will be reflected by queries invoked in\n subsequent ArangoDB transactions, in-progress ArangoDB transactions will\n still continue to return a repeatable-read state.\n", "type": "integer" }, "consolidationIntervalMsec": { "default": 5000, "description": "Wait at least this many milliseconds between applying `consolidationPolicy` to\nconsolidate the View data store and possibly release space on the filesystem\n(`0` = disable).\nFor the case where there are a lot of data modification operations, a higher\nvalue could potentially have the data store consume more space and file handles.\nFor the case where there are a few data modification operations, a lower value\nimpacts performance due to no segment candidates being available for\nconsolidation.\n\n_Background:_\n For data modification, ArangoSearch follows the concept of a\n \"versioned data store\". Thus old versions of data may be removed once there\n are no longer any users of the old data. The frequency of the cleanup and\n compaction operations are governed by `consolidationIntervalMsec` and the\n candidates for compaction are selected via `consolidationPolicy`.\n", "type": "integer" }, "consolidationPolicy": { "description": "The consolidation policy to apply for selecting which segments should be merged.\n\n- If the `tier` type is used, then the `maxSkewThreshold`,\n `minDeletionRatio`, `segments*`, and `minScore` properties are available.\n- If the `bytes_accum` type is used, then the `threshold` property is available.\n\n_Background:_\n With each ArangoDB transaction that inserts documents, one or more\n ArangoSearch-internal segments get created.\n Similarly, for removed documents, the segments that contain such documents\n have these documents marked as 'deleted'.\n Over time, this approach causes a lot of small and sparse segments to be\n created.\n A \"consolidation\" operation selects one or more segments and copies all of\n their valid documents into a single new segment, thereby allowing the\n search algorithm to perform more optimally and for extra file handles to be\n released once old segments are no longer used.\n", "properties": { "maxSkewThreshold": { "default": 0.4, "description": "This option is available from v3.12.7 onward:\n\nThe skew describes how much segment files vary in file size. It is a number\nbetween `0.0` and `1.0` and is calculated by dividing the largest file size\nof a set of segment files by the total size. For example, the skew of a\n200 MiB, 300 MiB, and 500 MiB segment file is `0.5` (`500 / 1000`).\n\nA large `maxSkewThreshold` value allows merging large segment files with\nsmaller ones, consolidation occurs more frequently, and there are fewer\nsegment files on disk at all times. While this may potentially improve the\nread performance and use fewer file descriptors, frequent consolidations\ncause a higher write load and thus a higher write amplification.\n\nOn the other hand, a small threshold value triggers the consolidation only\nwhen there are a large number of segment files that don't vary in size a lot.\nConsolidation occurs less frequently, reducing the write amplification, but\nit can result in a greater number of segment files on disk.\n\nMultiple combinations of candidate segments are checked and the one with\nthe lowest skew value is selected for consolidation. The selection process\npicks the greatest number of segments that together have the lowest skew value\nwhile ensuring that the size of the new consolidated segment remains under\nthe configured `segmentsBytesMax`.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minDeletionRatio": { "default": 0.5, "description": "This option is available from v3.12.7 onward:\n\nThe `minDeletionRatio` represents the minimum required deletion ratio\nin one or more segments to perform a cleanup of those segments.\nIt is a number between `0.0` and `1.0`.\n\nThe deletion ratio is the percentage of deleted documents across one or\nmore segment files and is calculated by dividing the number of deleted\ndocuments by the total number of documents in a segment or a group of\nsegments. For example, if there is a segment with 1000 documents of which\n300 are deleted and another segment with 1000 documents of which 700 are\ndeleted, the deletion ratio is `0.5` (50%, calculated as `1000 / 2000`).\n\nThe `minDeletionRatio` threshold must be carefully selected. A smaller\nvalue leads to earlier cleanup of deleted documents from segments and\nthus reclamation of disk space but it generates a higher write load.\nA very large value lowers the write amplification but at the same time\nthe system can be left with a large number of segment files with a high\npercentage of deleted documents that occupy disk space unnecessarily.\n\nDuring cleanup, the segment files are first arranged in decreasing\norder of their individual deletion ratios. Then the largest subset of\nsegments whose collective deletion ratio is greater than or equal to\n`minDeletionRatio` is picked.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minScore": { "default": 0, "description": "This option is only available up to v3.12.6:\n\nFilter out consolidation candidates with a score less than this.\n", "type": "integer" }, "segmentsBytesFloor": { "default": 25165824, "description": "This option is only available up to v3.12.6:\n\nDefines the value (in bytes) to treat all smaller segments\nas equal for consolidation selection.\n", "type": "integer" }, "segmentsBytesMax": { "default": 8589934592, "description": "Maximum allowed size of all consolidated segments in bytes.\n", "type": "integer" }, "segmentsMax": { "default": 200, "description": "This option is only available up to v3.12.6:\n\nThe maximum number of segments that are evaluated as\ncandidates for consolidation.\n", "type": "integer" }, "segmentsMin": { "default": 50, "description": "This option is only available up to v3.12.6:\n\nThe minimum number of segments that are\nevaluated as candidates for consolidation\n", "type": "integer" }, "threshold": { "default": 0, "description": "A value in the range `[0.0, 1.0]`.\n", "maximum": 1, "minimum": 0, "type": "number" }, "type": { "default": "tier", "description": "The segment candidates for the \"consolidation\" operation are selected based\nupon several possible configurable formulas as defined by their types.\nThe currently supported types are:\n- `\"tier\"`: consolidate based on segment byte size skew and live\n document count as dictated by the customization attributes. \n- `\"bytes_accum\"`: consolidate if and only if\n `{threshold} \u003e (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes`\n i.e. the sum of all candidate segment byte size is less than the total\n segment byte size multiplied by the `{threshold}`.\n", "enum": [ "tier", "bytes_accum" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "links": { "description": "Expects an object with the attribute keys being names of to be linked collections,\nand the link properties as attribute values. Example:\n\n```json\n{\n \"name\": \"arangosearch\",\n \"links\": {\n \"coll\": {\n \"fields\": {\n \"my_attribute\": {\n \"fields\": {\n \"my_sub_attribute\": {\n \"analyzers\": [\"text_en\"]\n }\n }\n }\n }\n }\n }\n}\n```\n\nSee [`arangosearch` View Link Properties](https://docs.arango.ai/arangodb/3.12/indexes-and-search/arangosearch/arangosearch-views-reference/#link-properties)\nfor details.\n", "type": "object" }, "name": { "description": "The name of the View.\n", "type": "string" }, "optimizeTopK": { "default": [], "description": "An array of strings defining sort expressions that you want to optimize.\nThis is also known as _WAND optimization_ (introduced in v3.12.0).\n\nThis option is immutable.\n\nIf you query a View with the `SEARCH` operation in combination with a\n`SORT` and `LIMIT` operation, search results can be retrieved faster if the\n`SORT` expression matches one of the optimized expressions.\n\nOnly sorting by highest rank is supported, that is, sorting by the result\nof a scoring function in descending order (`DESC`). Use `@doc` in the expression\nwhere you would normally pass the document variable emitted by the `SEARCH`\noperation to the scoring function.\n\nYou can define up to 64 expressions per View.\n\nExample: `[\"BM25(@doc) DESC\", \"TFIDF(@doc, true) DESC\"]`\n", "items": { "type": "string" }, "type": "array" }, "primaryKeyCache": { "description": "If you enable this option, then the primary key columns are always cached in\nmemory (introduced in v3.9.6). This can improve the\nperformance of queries that return many documents. Otherwise, these values are\nmemory-mapped and it is up to the operating system to load them from disk into\nmemory and to evict them from memory.\n\nThis option is immutable.\n\nSee the `--arangosearch.columns-cache-limit` startup option to control the\nmemory consumption of this cache. You can reduce the memory usage of the column\ncache in cluster deployments by only using the cache for leader shards, see the\n`--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6).\n", "type": "boolean" }, "primarySort": { "default": [], "description": "You can define a primary sort order to enable an AQL\noptimization. If a query iterates over all documents of a View,\nwants to sort them by attribute values and the (left-most)\nfields to sort by as well as their sorting direction match\nwith the `primarySort` definition, then the `SORT` operation is\noptimized away. This option is immutable.\n\nExpects an array of objects, each specifying a field\n(attribute path) and a sort direction:\n`[ { \"field\": \"attr\", \"direction\": \"asc\"}, … ]`\n", "items": { "properties": { "direction": { "description": "The sort direction.\n\n- `\"asc\"` for ascending\n- `\"desc\"` for descending\n", "enum": [ "asc", "desc" ], "type": "string" }, "field": { "description": "An attribute path. The `.` character denotes sub-attributes.\n", "type": "string" } }, "required": [ "field", "direction" ], "type": "object" }, "type": "array" }, "primarySortCache": { "description": "If you enable this option, then the primary sort columns are always cached in\nmemory. This can improve the\nperformance of queries that utilize the primary sort order. Otherwise, these\nvalues are memory-mapped and it is up to the operating system to load them from\ndisk into memory and to evict them from memory.\n\nThis option is immutable.\n\nSee the `--arangosearch.columns-cache-limit` startup option to control the\nmemory consumption of this cache. You can reduce the memory usage of the column\ncache in cluster deployments by only using the cache for leader shards, see the\n`--arangosearch.columns-cache-only-leader` startup option.\n", "type": "boolean" }, "primarySortCompression": { "default": "lz4", "description": "Defines how to compress the primary sort data.\n\n- `\"lz4\"`: use LZ4 fast compression.\n- `\"none\"`: disable compression to trade space for speed.\n\nThis option is immutable.\n", "enum": [ "lz4", "none" ], "type": "string" }, "storedValues": { "default": [], "description": "An array of objects to describe which document attributes to store in the View\nindex. It can then cover search queries, which means the\ndata can be taken from the index directly and accessing the storage engine can\nbe avoided.\n\nThis option is immutable.\n\nEach object is expected in the following form:\n\n`{ \"fields\": [ \"attr1\", \"attr2\", ... \"attrN\" ], \"compression\": \"none\", \"cache\": false }`\n\nYou may use the following shorthand notations on View creation instead of\nan array of objects as described above. The default compression and cache\nsettings are used in this case:\n\n- An array of strings, like `[\"attr1\", \"attr2\"]`, to place each attribute into\n a separate column of the index.\n\n- An array of arrays of strings, like `[[\"attr1\", \"attr2\"]]`, to place the\n attributes into a single column of the index, or `[[\"attr1\"], [\"attr2\"]]`\n to place each attribute into a separate column. You can also mix it with the\n full form:\n\n ```json\n [\n [\"attr1\"],\n [\"attr2\", \"attr3\"],\n { \"fields\": [\"attr4\", \"attr5\"], \"cache\": true }\n ]\n ```\n\nThe `storedValues` option is not to be confused with the `storeValues` option,\nwhich allows you to store meta data about attribute values in the View index.\n", "items": { "properties": { "cache": { "default": false, "description": "Whether to always cache stored values in memory.\nThis can improve the query performance if stored values are involved.\nOtherwise, these values are memory-mapped and it is up to the operating system\nto load them from disk into memory and to evict them from memory.\n\nSee the `--arangosearch.columns-cache-limit` startup option to control the\nmemory consumption of this cache. You can reduce the memory usage of the\ncolumn cache in cluster deployments by only using the cache for leader shards,\nsee the `--arangosearch.columns-cache-only-leader` startup option.\n", "type": "boolean" }, "compression": { "default": "lz4", "description": "Defines the compression type used for the internal column-store.\n\n- `\"lz4\"`: LZ4 fast compression\n- `\"none\"`: no compression\n", "enum": [ "lz4", "none" ], "type": "string" }, "fields": { "description": "An array of strings with one or more document attribute paths.\nThe specified attributes are placed into a single column of the index.\nA column with all fields that are involved in common search queries is\nideal for performance. The column should not include too many unneeded\nfields, however.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "fields" ], "type": "object" }, "type": "array" }, "type": { "description": "The type of the View. Needs to be set to `\"arangosearch\"`.\nThis option is immutable.\n", "example": "arangosearch", "type": "string" }, "writebufferActive": { "default": 0, "description": "Maximum number of concurrent active writers (segments) that perform a\ntransaction. Other writers (segments) wait till current active writers\n(segments) finish (immutable, `0` = disable).\n", "type": "integer" }, "writebufferIdle": { "default": 64, "description": "Maximum number of writers (segments) cached in the pool\n(immutable, `0` = disable).\n", "type": "integer" }, "writebufferSizeMax": { "default": 33554432, "description": "Maximum memory byte size per writer (segment) before a writer (segment) flush\nis triggered. The value `0` turns off this limit for any writer (buffer) and data\nis flushed periodically based on the value defined for the flush thread\n(ArangoDB server startup option). This should be used carefully due to\nhigh potential memory consumption (immutable, `0` = disable).\n", "type": "integer" } }, "required": [ "name", "type" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "cleanupIntervalStep": { "description": "Wait at least this many commits between removing unused files in the\nArangoSearch data directory (`0` = disabled).\n", "type": "integer" }, "commitIntervalMsec": { "description": "Wait at least this many milliseconds between committing View data store\nchanges and making documents visible to queries (`0` = disabled).\n", "type": "integer" }, "consolidationIntervalMsec": { "description": "Wait at least this many milliseconds between applying `consolidationPolicy` to\nconsolidate the View data store and possibly release space on the filesystem\n(`0` = disabled).\n", "type": "integer" }, "consolidationPolicy": { "description": "The consolidation policy to apply for selecting which segments should be merged.\n\n- If the `tier` type is used, then the `maxSkewThreshold`,\n`minDeletionRatio`, `segments*`, and `minScore` properties are available.\n- If the `bytes_accum` type is used, then the `threshold` property is available.\n", "properties": { "maxSkewThreshold": { "description": "This option is available from v3.12.7 onward:\n\nThe skew describes how much segment files vary in file size. It is a number\nbetween `0.0` and `1.0` and is calculated by dividing the largest file size\nof a set of segment files by the total size. For example, the skew of a\n200 MiB, 300 MiB, and 500 MiB segment file is `0.5` (`500 / 1000`).\n\nA large `maxSkewThreshold` value allows merging large segment files with\nsmaller ones, consolidation occurs more frequently, and there are fewer\nsegment files on disk at all times. While this may potentially improve the\nread performance and use fewer file descriptors, frequent consolidations\ncause a higher write load and thus a higher write amplification.\n\nOn the other hand, a small threshold value triggers the consolidation only\nwhen there are a large number of segment files that don't vary in size a lot.\nConsolidation occurs less frequently, reducing the write amplification, but\nit can result in a greater number of segment files on disk.\n\nMultiple combinations of candidate segments are checked and the one with\nthe lowest skew value is selected for consolidation. The selection process\npicks the greatest number of segments that together have the lowest skew value\nwhile ensuring that the size of the new consolidated segment remains under\nthe configured `segmentsBytesMax`.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minDeletionRatio": { "description": "This option is available from v3.12.7 onward:\n\nThe `minDeletionRatio` represents the minimum required deletion ratio\nin one or more segments to perform a cleanup of those segments.\nIt is a number between `0.0` and `1.0`.\n\nThe deletion ratio is the percentage of deleted documents across one or\nmore segment files and is calculated by dividing the number of deleted\ndocuments by the total number of documents in a segment or a group of\nsegments. For example, if there is a segment with 1000 documents of which\n300 are deleted and another segment with 1000 documents of which 700 are\ndeleted, the deletion ratio is `0.5` (50%, calculated as `1000 / 2000`).\n\nThe `minDeletionRatio` threshold must be carefully selected. A smaller\nvalue leads to earlier cleanup of deleted documents from segments and\nthus reclamation of disk space but it generates a higher write load.\nA very large value lowers the write amplification but at the same time\nthe system can be left with a large number of segment files with a high\npercentage of deleted documents that occupy disk space unnecessarily.\n\nDuring cleanup, the segment files are first arranged in decreasing\norder of their individual deletion ratios. Then the largest subset of\nsegments whose collective deletion ratio is greater than or equal to\n`minDeletionRatio` is picked.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minScore": { "description": "This option is only available up to v3.12.6:\n\nFilter out consolidation candidates with a score less than this.\n", "type": "integer" }, "segmentsBytesFloor": { "description": "This option is only available up to v3.12.6:\n\nDefines the value (in bytes) to treat all smaller segments\nas equal for consolidation selection.\n", "type": "integer" }, "segmentsBytesMax": { "description": "Maximum allowed size of all consolidated segments in bytes.\n", "type": "integer" }, "segmentsMax": { "description": "This option is only available up to v3.12.6:\n\nThe maximum number of segments that are evaluated as\ncandidates for consolidation.\n", "type": "integer" }, "segmentsMin": { "description": "This option is only available up to v3.12.6:\n\nThe minimum number of segments that are\nevaluated as candidates for consolidation\n", "type": "integer" }, "threshold": { "description": "A value in the range `[0.0, 1.0]`\n", "maximum": 1, "minimum": 0, "type": "number" }, "type": { "description": "The segment candidates for the \"consolidation\" operation are selected based\nupon several possible configurable formulas as defined by their types.\nThe currently supported types are:\n- `\"tier\"`: consolidate based on segment byte size skew and live\n document count as dictated by the customization attributes.\n- `\"bytes_accum\"`: consolidate if and only if\n `{threshold} \u003e (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes`\n i.e. the sum of all candidate segment byte size is less than the total\n segment byte size multiplied by the `{threshold}`.\n", "enum": [ "tier", "bytes_accum" ], "type": "string" } }, "type": "object" }, "globallyUniqueId": { "description": "A unique identifier of the View. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the View (deprecated).\n", "type": "string" }, "links": { "description": "An object with the attribute keys being names of to be linked collections,\nand the link properties as attribute values. See\n[`arangosearch` View Link Properties](https://docs.arango.ai/arangodb/3.12/indexes-and-search/arangosearch/arangosearch-views-reference/#link-properties)\nfor details.\n", "type": "object" }, "name": { "description": "The name of the View.\n", "example": "coll", "type": "string" }, "optimizeTopK": { "description": "An array of strings defining sort expressions that can be optimized.\nThis is also known as _WAND optimization_ (introduced in v3.12.0).\n", "items": { "type": "string" }, "type": "array" }, "primaryKeyCache": { "description": "Whether the primary key columns are always cached in memory.\n", "type": "boolean" }, "primarySort": { "description": "The primary sort order, described by an array of objects, each specifying\na field (attribute path) and a sort direction.\n", "items": { "properties": { "asc": { "description": "The sort direction.\n\n- `true` for ascending\n- `false` for descending\n", "type": "boolean" }, "field": { "description": "An attribute path. The `.` character denotes sub-attributes.\n", "type": "string" } }, "required": [ "field", "asc" ], "type": "object" }, "type": "array" }, "primarySortCache": { "description": "Whether the primary sort columns are always cached in memory.\n", "type": "boolean" }, "primarySortCompression": { "description": "Defines how the primary sort data is compressed.\n\n- `\"lz4\"`: LZ4 fast compression\n- `\"none\"`: no compression\n", "enum": [ "lz4", "none" ], "type": "string" }, "storedValues": { "description": "An array of objects that describes which document attributes are stored\nin the View index for covering search queries, which means the data can\nbe taken from the index directly and accessing the storage engine can\nbe avoided.\n", "items": { "properties": { "cache": { "description": "Whether stored values are always cached in memory.\n", "type": "boolean" }, "compression": { "description": "The compression type used for the internal column-store.\n\n- `\"lz4\"`: LZ4 fast compression\n- `\"none\"`: no compression\n", "enum": [ "lz4", "none" ], "type": "string" }, "fields": { "description": "An array of strings with one or more document attribute paths.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "fields" ], "type": "object" }, "type": "array" }, "type": { "description": "The type of the View (`\"arangosearch\"`).\n", "example": "arangosearch", "type": "string" }, "writebufferActive": { "description": "Maximum number of concurrent active writers (segments) that perform a\ntransaction. Other writers (segments) wait till current active writers\n(segments) finish (`0` = disabled).\n", "type": "integer" }, "writebufferIdle": { "description": "Maximum number of writers (segments) cached in the pool (`0` = disabled).\n", "type": "integer" }, "writebufferSizeMax": { "description": "Maximum memory byte size per writer (segment) before a writer (segment) flush\nis triggered. `0` value turns off this limit for any writer (buffer) and data\nis flushed periodically based on the value defined for the flush thread\n(`0` = disabled).\n", "type": "integer" } }, "required": [ "links", "primarySort", "primarySortCompression", "optimizeTopK", "storedValues", "cleanupIntervalStep", "commitIntervalMsec", "consolidationIntervalMsec", "consolidationPolicy", "writebufferIdle", "writebufferActive", "writebufferSizeMax", "id", "name", "type", "globallyUniqueId" ], "type": "object" } } }, "description": "The View has been created.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `name` or `type` attribute is missing or invalid.\n" }, "409": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 409, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A View called `name` already exists.\n" } }, "summary": "Create an arangosearch View", "tags": [ "Views" ] } }, "/_db/{database-name}/_api/view#searchalias": { "post": { "description": "Creates a new View with a given name and properties if it does not\nalready exist.\n", "operationId": "createViewSearchAlias", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "indexes": { "description": "A list of inverted indexes to add to the View.\n", "items": { "properties": { "collection": { "description": "The name of a collection.\n", "type": "string" }, "index": { "description": "The name of an inverted index of the `collection`, or the index ID without\nthe `\u003ccollection\u003e/` prefix.\n", "type": "string" } }, "required": [ "collection", "index" ], "type": "object" }, "type": "array" }, "name": { "description": "The name of the View.\n", "type": "string" }, "type": { "description": "The type of the View. Needs to be set to `\"search-alias\"`.\nThis option is immutable.\n", "example": "search-alias", "type": "string" } }, "required": [ "name", "type" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "globallyUniqueId": { "description": "A unique identifier of the View. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the View (deprecated).\n", "type": "string" }, "indexes": { "description": "The list of the View's inverted indexes.\n", "items": { "properties": { "collection": { "description": "The name of a collection.\n", "type": "string" }, "index": { "description": "The name of an inverted index of the `collection`.\n", "type": "string" } }, "required": [ "collection", "index" ], "type": "object" }, "type": "array" }, "name": { "description": "The name of the View.\n", "type": "string" }, "type": { "description": "The type of the View (`\"search-alias\"`).\n", "example": "search-alias", "type": "string" } }, "required": [ "name", "type", "id", "globallyUniqueId", "indexes" ], "type": "object" } } }, "description": "The View has been created.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `name` or `type` attribute or one of the `collection` or `index`\nattributes is missing or invalid.\nerror is returned.\n" }, "409": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 409, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A View called `name` already exists.\n" } }, "summary": "Create a search-alias View", "tags": [ "Views" ] } }, "/_db/{database-name}/_api/view/{view-name}": { "delete": { "description": "Deletes the View identified by `view-name`.\n", "operationId": "deleteView", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the View to drop.\n", "in": "path", "name": "view-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "result": { "description": "The value `true`.\n", "example": true, "type": "boolean" } }, "required": [ "error", "code", "result" ], "type": "object" } } }, "description": "The View has been dropped successfully.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `view-name` path parameter is missing or invalid.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A View called `view-name` could not be found.\n" } }, "summary": "Drop a View", "tags": [ "Views" ] }, "get": { "description": "Returns the basic information about a specific View.\n", "operationId": "getView", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the View.\n", "in": "path", "name": "view-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the View. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the View (deprecated).\n", "type": "string" }, "name": { "description": "The name of the View.\n", "example": "coll", "type": "string" }, "type": { "description": "The type of the View (`\"arangosearch\"`).\n", "example": "arangosearch", "type": "string" } }, "required": [ "error", "code", "name", "type", "id", "globallyUniqueId" ], "type": "object" } } }, "description": "The basic information about the View.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A View called `view-name` could not be found.\n" } }, "summary": "Get information about a View", "tags": [ "Views" ] } }, "/_db/{database-name}/_api/view/{view-name}#searchalias": { "get": { "description": "Returns the basic information about a specific View.\n", "operationId": "getViewSearchAlias", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the View.\n", "in": "path", "name": "view-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the View. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the View (deprecated).\n", "type": "string" }, "name": { "description": "The name of the View.\n", "example": "coll", "type": "string" }, "type": { "description": "The type of the View (`\"search-alias\"`).\n", "example": "search-alias", "type": "string" } }, "required": [ "error", "code", "name", "type", "id", "globallyUniqueId" ], "type": "object" } } }, "description": "The basic information about the View.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A View called `view-name` could not be found.\n" } }, "summary": "Get information about a View", "tags": [ "Views" ] } }, "/_db/{database-name}/_api/view/{view-name}/properties": { "get": { "description": "Returns an object containing the definition of the View identified by `view-name`.\n", "operationId": "getViewProperties", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the View.\n", "in": "path", "name": "view-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cleanupIntervalStep": { "description": "Wait at least this many commits between removing unused files in the\nArangoSearch data directory (`0` = disabled).\n", "type": "integer" }, "code": { "description": "The HTTP response status code.\n", "example": 200, "type": "integer" }, "commitIntervalMsec": { "description": "Wait at least this many milliseconds between committing View data store\nchanges and making documents visible to queries (`0` = disabled).\n", "type": "integer" }, "consolidationIntervalMsec": { "description": "Wait at least this many milliseconds between applying `consolidationPolicy` to\nconsolidate the View data store and possibly release space on the filesystem\n(`0` = disabled).\n", "type": "integer" }, "consolidationPolicy": { "description": "The consolidation policy to apply for selecting which segments should be merged.\n\n- If the `tier` type is used, then the `maxSkewThreshold`,\n`minDeletionRatio`, `segments*`, and `minScore` properties are available.\n- If the `bytes_accum` type is used, then the `threshold` property is available.\n", "properties": { "maxSkewThreshold": { "description": "This option is available from v3.12.7 onward:\n\nThe skew describes how much segment files vary in file size. It is a number\nbetween `0.0` and `1.0` and is calculated by dividing the largest file size\nof a set of segment files by the total size. For example, the skew of a\n200 MiB, 300 MiB, and 500 MiB segment file is `0.5` (`500 / 1000`).\n\nA large `maxSkewThreshold` value allows merging large segment files with\nsmaller ones, consolidation occurs more frequently, and there are fewer\nsegment files on disk at all times. While this may potentially improve the\nread performance and use fewer file descriptors, frequent consolidations\ncause a higher write load and thus a higher write amplification.\n\nOn the other hand, a small threshold value triggers the consolidation only\nwhen there are a large number of segment files that don't vary in size a lot.\nConsolidation occurs less frequently, reducing the write amplification, but\nit can result in a greater number of segment files on disk.\n\nMultiple combinations of candidate segments are checked and the one with\nthe lowest skew value is selected for consolidation. The selection process\npicks the greatest number of segments that together have the lowest skew value\nwhile ensuring that the size of the new consolidated segment remains under\nthe configured `segmentsBytesMax`.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minDeletionRatio": { "description": "This option is available from v3.12.7 onward:\n\nThe `minDeletionRatio` represents the minimum required deletion ratio\nin one or more segments to perform a cleanup of those segments.\nIt is a number between `0.0` and `1.0`.\n\nThe deletion ratio is the percentage of deleted documents across one or\nmore segment files and is calculated by dividing the number of deleted\ndocuments by the total number of documents in a segment or a group of\nsegments. For example, if there is a segment with 1000 documents of which\n300 are deleted and another segment with 1000 documents of which 700 are\ndeleted, the deletion ratio is `0.5` (50%, calculated as `1000 / 2000`).\n\nThe `minDeletionRatio` threshold must be carefully selected. A smaller\nvalue leads to earlier cleanup of deleted documents from segments and\nthus reclamation of disk space but it generates a higher write load.\nA very large value lowers the write amplification but at the same time\nthe system can be left with a large number of segment files with a high\npercentage of deleted documents that occupy disk space unnecessarily.\n\nDuring cleanup, the segment files are first arranged in decreasing\norder of their individual deletion ratios. Then the largest subset of\nsegments whose collective deletion ratio is greater than or equal to\n`minDeletionRatio` is picked.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minScore": { "description": "This option is only available up to v3.12.6:\n\nFilter out consolidation candidates with a score less than this.\n", "type": "integer" }, "segmentsBytesFloor": { "description": "This option is only available up to v3.12.6:\n\nDefines the value (in bytes) to treat all smaller segments\nas equal for consolidation selection.\n", "type": "integer" }, "segmentsBytesMax": { "description": "Maximum allowed size of all consolidated segments in bytes.\n", "type": "integer" }, "segmentsMax": { "description": "This option is only available up to v3.12.6:\n\nThe maximum number of segments that are evaluated as\ncandidates for consolidation.\n", "type": "integer" }, "segmentsMin": { "description": "This option is only available up to v3.12.6:\n\nThe minimum number of segments that are\nevaluated as candidates for consolidation\n", "type": "integer" }, "threshold": { "description": "A value in the range `[0.0, 1.0]`\n", "maximum": 1, "minimum": 0, "type": "number" }, "type": { "description": "The segment candidates for the \"consolidation\" operation are selected based\nupon several possible configurable formulas as defined by their types.\nThe currently supported types are:\n- `\"tier\"`: consolidate based on segment byte size skew and live\n document count as dictated by the customization attributes.\n- `\"bytes_accum\"`: consolidate if and only if\n `{threshold} \u003e (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes`\n i.e. the sum of all candidate segment byte size is less than the total\n segment byte size multiplied by the `{threshold}`.\n", "enum": [ "tier", "bytes_accum" ], "type": "string" } }, "type": "object" }, "error": { "description": "A flag indicating that no error occurred.\n", "example": false, "type": "boolean" }, "globallyUniqueId": { "description": "A unique identifier of the View. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the View (deprecated).\n", "type": "string" }, "links": { "description": "An object with the attribute keys being names of to be linked collections,\nand the link properties as attribute values. See\n[`arangosearch` View Link Properties](https://docs.arango.ai/arangodb/3.12/indexes-and-search/arangosearch/arangosearch-views-reference/#link-properties)\nfor details.\n", "type": "object" }, "name": { "description": "The name of the View.\n", "example": "coll", "type": "string" }, "optimizeTopK": { "description": "An array of strings defining sort expressions that can be optimized.\nThis is also known as _WAND optimization_ (introduced in v3.12.0).\n", "items": { "type": "string" }, "type": "array" }, "primaryKeyCache": { "description": "Whether the primary key columns are always cached in memory.\n", "type": "boolean" }, "primarySort": { "description": "The primary sort order, described by an array of objects, each specifying\na field (attribute path) and a sort direction.\n", "items": { "properties": { "asc": { "description": "The sort direction.\n\n- `true` for ascending\n- `false` for descending\n", "type": "boolean" }, "field": { "description": "An attribute path. The `.` character denotes sub-attributes.\n", "type": "string" } }, "required": [ "field", "asc" ], "type": "object" }, "type": "array" }, "primarySortCache": { "description": "Whether the primary sort columns are always cached in memory.\n", "type": "boolean" }, "primarySortCompression": { "description": "Defines how the primary sort data is compressed.\n\n- `\"lz4\"`: LZ4 fast compression\n- `\"none\"`: no compression\n", "enum": [ "lz4", "none" ], "type": "string" }, "storedValues": { "description": "An array of objects that describes which document attributes are stored\nin the View index for covering search queries, which means the data can\nbe taken from the index directly and accessing the storage engine can\nbe avoided.\n", "items": { "properties": { "cache": { "description": "Whether stored values are always cached in memory.\n", "type": "boolean" }, "compression": { "description": "The compression type used for the internal column-store.\n\n- `\"lz4\"`: LZ4 fast compression\n- `\"none\"`: no compression\n", "enum": [ "lz4", "none" ], "type": "string" }, "fields": { "description": "An array of strings with one or more document attribute paths.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "fields" ], "type": "object" }, "type": "array" }, "type": { "description": "The type of the View (`\"arangosearch\"`).\n", "example": "arangosearch", "type": "string" }, "writebufferActive": { "description": "Maximum number of concurrent active writers (segments) that perform a\ntransaction. Other writers (segments) wait till current active writers\n(segments) finish (`0` = disabled).\n", "type": "integer" }, "writebufferIdle": { "description": "Maximum number of writers (segments) cached in the pool (`0` = disabled).\n", "type": "integer" }, "writebufferSizeMax": { "description": "Maximum memory byte size per writer (segment) before a writer (segment) flush\nis triggered. `0` value turns off this limit for any writer (buffer) and data\nis flushed periodically based on the value defined for the flush thread\n(`0` = disabled).\n", "type": "integer" } }, "required": [ "error", "code", "links", "primarySort", "primarySortCompression", "optimizeTopK", "storedValues", "cleanupIntervalStep", "commitIntervalMsec", "consolidationIntervalMsec", "consolidationPolicy", "writebufferIdle", "writebufferActive", "writebufferSizeMax", "id", "name", "type", "globallyUniqueId" ], "type": "object" } } }, "description": "An object with a full description of the specified View, including\n`arangosearch` View type-dependent properties.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `view-name` path parameter is missing or invalid.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A View called `view-name` could not be found.\n" } }, "summary": "Get the properties of a View", "tags": [ "Views" ] }, "patch": { "description": "Partially changes the properties of a View by updating the specified attributes.\n", "operationId": "updateViewProperties", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the View.\n", "in": "path", "name": "view-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cleanupIntervalStep": { "description": "Wait at least this many commits between removing unused files in the\nArangoSearch data directory (`0` = disable).\nFor the case where the consolidation policies merge segments often (i.e. a lot\nof commit+consolidate), a lower value causes a lot of disk space to be\nwasted.\nFor the case where the consolidation policies rarely merge segments (i.e. few\ninserts/deletes), a higher value impacts performance without any added\nbenefits.\n\n_Background:_\n With every \"commit\" or \"consolidate\" operation, a new state of the View's\n internal data structures is created on disk.\n Old states/snapshots are released once there are no longer any users\n remaining.\n However, the files for the released states/snapshots are left on disk, and\n only removed by \"cleanup\" operation.\n", "type": "integer" }, "commitIntervalMsec": { "description": "Wait at least this many milliseconds between committing View data store\nchanges and making documents visible to queries (`0` = disable).\nFor the case where there are a lot of inserts/updates, a higher value causes the\nindex not to account for them and memory usage continues to grow until the commit.\nA lower value impacts performance, including the case where there are no or only a\nfew inserts/updates because of synchronous locking, and it wastes disk space for\neach commit call.\n\n_Background:_\n For data retrieval, ArangoSearch follows the concept of\n \"eventually-consistent\", i.e. eventually all the data in ArangoDB will be\n matched by corresponding query expressions.\n The concept of ArangoSearch \"commit\" operations is introduced to\n control the upper-bound on the time until document addition/removals are\n actually reflected by corresponding query expressions.\n Once a \"commit\" operation is complete, all documents added/removed prior to\n the start of the \"commit\" operation will be reflected by queries invoked in\n subsequent ArangoDB transactions, in-progress ArangoDB transactions will\n still continue to return a repeatable-read state.\n", "type": "integer" }, "consolidationIntervalMsec": { "description": "Wait at least this many milliseconds between applying `consolidationPolicy` to\nconsolidate the View data store and possibly release space on the filesystem\n(`0` = disable).\nFor the case where there are a lot of data modification operations, a higher\nvalue could potentially have the data store consume more space and file handles.\nFor the case where there are a few data modification operations, a lower value\nimpacts performance due to no segment candidates being available for\nconsolidation.\n\n_Background:_\n For data modification, ArangoSearch follows the concept of a\n \"versioned data store\". Thus old versions of data may be removed once there\n are no longer any users of the old data. The frequency of the cleanup and\n compaction operations are governed by `consolidationIntervalMsec` and the\n candidates for compaction are selected via `consolidationPolicy`.\n", "type": "integer" }, "consolidationPolicy": { "description": "The consolidation policy to apply for selecting which segments should be merged.\n\n- If the `tier` type is used, then the `maxSkewThreshold`,\n`minDeletionRatio`, `segments*`, and `minScore` properties are available.\n- If the `bytes_accum` type is used, then the `threshold` property is available.\n\n_Background:_\n With each ArangoDB transaction that inserts documents, one or more\n ArangoSearch-internal segments get created.\n Similarly, for removed documents, the segments that contain such documents\n have these documents marked as 'deleted'.\n Over time, this approach causes a lot of small and sparse segments to be\n created.\n A \"consolidation\" operation selects one or more segments and copies all of\n their valid documents into a single new segment, thereby allowing the\n search algorithm to perform more optimally and for extra file handles to be\n released once old segments are no longer used.\n", "properties": { "maxSkewThreshold": { "default": 0.4, "description": "This option is available from v3.12.7 onward:\n\nThe skew describes how much segment files vary in file size. It is a number\nbetween `0.0` and `1.0` and is calculated by dividing the largest file size\nof a set of segment files by the total size. For example, the skew of a\n200 MiB, 300 MiB, and 500 MiB segment file is `0.5` (`500 / 1000`).\n\nA large `maxSkewThreshold` value allows merging large segment files with\nsmaller ones, consolidation occurs more frequently, and there are fewer\nsegment files on disk at all times. While this may potentially improve the\nread performance and use fewer file descriptors, frequent consolidations\ncause a higher write load and thus a higher write amplification.\n\nOn the other hand, a small threshold value triggers the consolidation only\nwhen there are a large number of segment files that don't vary in size a lot.\nConsolidation occurs less frequently, reducing the write amplification, but\nit can result in a greater number of segment files on disk.\n\nMultiple combinations of candidate segments are checked and the one with\nthe lowest skew value is selected for consolidation. The selection process\npicks the greatest number of segments that together have the lowest skew value\nwhile ensuring that the size of the new consolidated segment remains under\nthe configured `segmentsBytesMax`.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minDeletionRatio": { "default": 0.5, "description": "This option is available from v3.12.7 onward:\n\nThe `minDeletionRatio` represents the minimum required deletion ratio\nin one or more segments to perform a cleanup of those segments.\nIt is a number between `0.0` and `1.0`.\n\nThe deletion ratio is the percentage of deleted documents across one or\nmore segment files and is calculated by dividing the number of deleted\ndocuments by the total number of documents in a segment or a group of\nsegments. For example, if there is a segment with 1000 documents of which\n300 are deleted and another segment with 1000 documents of which 700 are\ndeleted, the deletion ratio is `0.5` (50%, calculated as `1000 / 2000`).\n\nThe `minDeletionRatio` threshold must be carefully selected. A smaller\nvalue leads to earlier cleanup of deleted documents from segments and\nthus reclamation of disk space but it generates a higher write load.\nA very large value lowers the write amplification but at the same time\nthe system can be left with a large number of segment files with a high\npercentage of deleted documents that occupy disk space unnecessarily.\n\nDuring cleanup, the segment files are first arranged in decreasing\norder of their individual deletion ratios. Then the largest subset of\nsegments whose collective deletion ratio is greater than or equal to\n`minDeletionRatio` is picked.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minScore": { "default": 0, "description": "This option is only available up to v3.12.6:\n\nFilter out consolidation candidates with a score less than this.\n", "type": "integer" }, "segmentsBytesFloor": { "default": 25165824, "description": "This option is only available up to v3.12.6:\n\nDefines the value (in bytes) to treat all smaller segments\nas equal for consolidation selection.\n", "type": "integer" }, "segmentsBytesMax": { "default": 8589934592, "description": "Maximum allowed size of all consolidated segments in bytes.\n", "type": "integer" }, "segmentsMax": { "default": 200, "description": "This option is only available up to v3.12.6:\n\nThe maximum number of segments that are evaluated as\ncandidates for consolidation.\n", "type": "integer" }, "segmentsMin": { "default": 50, "description": "This option is only available up to v3.12.6:\n\nThe minimum number of segments that are\nevaluated as candidates for consolidation\n", "type": "integer" }, "threshold": { "default": 0, "description": "A value in the range `[0.0, 1.0]`.\n", "maximum": 1, "minimum": 0, "type": "number" }, "type": { "description": "The segment candidates for the \"consolidation\" operation are selected based\nupon several possible configurable formulas as defined by their types.\nThe currently supported types are:\n- `\"tier\"`: consolidate based on segment byte size skew and live\n document count as dictated by the customization attributes. \n- `\"bytes_accum\"`: consolidate if and only if\n `{threshold} \u003e (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes`\n i.e. the sum of all candidate segment byte size is less than the total\n segment byte size multiplied by the `{threshold}`.\n", "enum": [ "tier", "bytes_accum" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "links": { "description": "Expects an object with the attribute keys being names of to be linked collections,\nand the link properties as attribute values. Example:\n\n```json\n{\n \"name\": \"arangosearch\",\n \"links\": {\n \"coll\": {\n \"fields\": {\n \"my_attribute\": {\n \"fields\": {\n \"my_sub_attribute\": {\n \"analyzers\": [\"text_en\"]\n }\n }\n }\n }\n }\n }\n}\n```\n\nSee [`arangosearch` View Link Properties](https://docs.arango.ai/arangodb/3.12/indexes-and-search/arangosearch/arangosearch-views-reference/#link-properties)\nfor details.\n", "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cleanupIntervalStep": { "description": "Wait at least this many commits between removing unused files in the\nArangoSearch data directory (`0` = disabled).\n", "type": "integer" }, "commitIntervalMsec": { "description": "Wait at least this many milliseconds between committing View data store\nchanges and making documents visible to queries (`0` = disabled).\n", "type": "integer" }, "consolidationIntervalMsec": { "description": "Wait at least this many milliseconds between applying `consolidationPolicy` to\nconsolidate the View data store and possibly release space on the filesystem\n(`0` = disabled).\n", "type": "integer" }, "consolidationPolicy": { "description": "The consolidation policy to apply for selecting which segments should be merged.\n\n- If the `tier` type is used, then the `maxSkewThreshold`,\n`minDeletionRatio`, `segments*`, and `minScore` properties are available.\n- If the `bytes_accum` type is used, then the `threshold` property is available.\n", "properties": { "maxSkewThreshold": { "description": "This option is available from v3.12.7 onward:\n\nThe skew describes how much segment files vary in file size. It is a number\nbetween `0.0` and `1.0` and is calculated by dividing the largest file size\nof a set of segment files by the total size. For example, the skew of a\n200 MiB, 300 MiB, and 500 MiB segment file is `0.5` (`500 / 1000`).\n\nA large `maxSkewThreshold` value allows merging large segment files with\nsmaller ones, consolidation occurs more frequently, and there are fewer\nsegment files on disk at all times. While this may potentially improve the\nread performance and use fewer file descriptors, frequent consolidations\ncause a higher write load and thus a higher write amplification.\n\nOn the other hand, a small threshold value triggers the consolidation only\nwhen there are a large number of segment files that don't vary in size a lot.\nConsolidation occurs less frequently, reducing the write amplification, but\nit can result in a greater number of segment files on disk.\n\nMultiple combinations of candidate segments are checked and the one with\nthe lowest skew value is selected for consolidation. The selection process\npicks the greatest number of segments that together have the lowest skew value\nwhile ensuring that the size of the new consolidated segment remains under\nthe configured `segmentsBytesMax`.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minDeletionRatio": { "description": "This option is available from v3.12.7 onward:\n\nThe `minDeletionRatio` represents the minimum required deletion ratio\nin one or more segments to perform a cleanup of those segments.\nIt is a number between `0.0` and `1.0`.\n\nThe deletion ratio is the percentage of deleted documents across one or\nmore segment files and is calculated by dividing the number of deleted\ndocuments by the total number of documents in a segment or a group of\nsegments. For example, if there is a segment with 1000 documents of which\n300 are deleted and another segment with 1000 documents of which 700 are\ndeleted, the deletion ratio is `0.5` (50%, calculated as `1000 / 2000`).\n\nThe `minDeletionRatio` threshold must be carefully selected. A smaller\nvalue leads to earlier cleanup of deleted documents from segments and\nthus reclamation of disk space but it generates a higher write load.\nA very large value lowers the write amplification but at the same time\nthe system can be left with a large number of segment files with a high\npercentage of deleted documents that occupy disk space unnecessarily.\n\nDuring cleanup, the segment files are first arranged in decreasing\norder of their individual deletion ratios. Then the largest subset of\nsegments whose collective deletion ratio is greater than or equal to\n`minDeletionRatio` is picked.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minScore": { "description": "This option is only available up to v3.12.6:\n\nFilter out consolidation candidates with a score less than this.\n", "type": "integer" }, "segmentsBytesFloor": { "description": "This option is only available up to v3.12.6:\n\nDefines the value (in bytes) to treat all smaller segments\nas equal for consolidation selection.\n", "type": "integer" }, "segmentsBytesMax": { "description": "Maximum allowed size of all consolidated segments in bytes.\n", "type": "integer" }, "segmentsMax": { "description": "This option is only available up to v3.12.6:\n\nThe maximum number of segments that are evaluated as\ncandidates for consolidation.\n", "type": "integer" }, "segmentsMin": { "description": "This option is only available up to v3.12.6:\n\nThe minimum number of segments that are\nevaluated as candidates for consolidation\n", "type": "integer" }, "threshold": { "description": "A value in the range `[0.0, 1.0]`\n", "maximum": 1, "minimum": 0, "type": "number" }, "type": { "description": "The segment candidates for the \"consolidation\" operation are selected based\nupon several possible configurable formulas as defined by their types.\nThe currently supported types are:\n- `\"tier\"`: consolidate based on segment byte size skew and live\n document count as dictated by the customization attributes.\n- `\"bytes_accum\"`: consolidate if and only if\n `{threshold} \u003e (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes`\n i.e. the sum of all candidate segment byte size is less than the total\n segment byte size multiplied by the `{threshold}`.\n", "enum": [ "tier", "bytes_accum" ], "type": "string" } }, "type": "object" }, "globallyUniqueId": { "description": "A unique identifier of the View. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the View (deprecated).\n", "type": "string" }, "links": { "description": "An object with the attribute keys being names of to be linked collections,\nand the link properties as attribute values. See\n[`arangosearch` View Link Properties](https://docs.arango.ai/arangodb/3.12/indexes-and-search/arangosearch/arangosearch-views-reference/#link-properties)\nfor details.\n", "type": "object" }, "name": { "description": "The name of the View.\n", "example": "coll", "type": "string" }, "optimizeTopK": { "description": "An array of strings defining sort expressions that can be optimized.\nThis is also known as _WAND optimization_ (introduced in v3.12.0).\n", "items": { "type": "string" }, "type": "array" }, "primaryKeyCache": { "description": "Whether the primary key columns are always cached in memory.\n", "type": "boolean" }, "primarySort": { "description": "The primary sort order, described by an array of objects, each specifying\na field (attribute path) and a sort direction.\n", "items": { "properties": { "asc": { "description": "The sort direction.\n\n- `true` for ascending\n- `false` for descending\n", "type": "boolean" }, "field": { "description": "An attribute path. The `.` character denotes sub-attributes.\n", "type": "string" } }, "required": [ "field", "asc" ], "type": "object" }, "type": "array" }, "primarySortCache": { "description": "Whether the primary sort columns are always cached in memory.\n", "type": "boolean" }, "primarySortCompression": { "description": "Defines how the primary sort data is compressed.\n\n- `\"lz4\"`: LZ4 fast compression\n- `\"none\"`: no compression\n", "enum": [ "lz4", "none" ], "type": "string" }, "storedValues": { "description": "An array of objects that describes which document attributes are stored\nin the View index for covering search queries, which means the data can\nbe taken from the index directly and accessing the storage engine can\nbe avoided.\n", "items": { "properties": { "cache": { "description": "Whether stored values are always cached in memory.\n", "type": "boolean" }, "compression": { "description": "The compression type used for the internal column-store.\n\n- `\"lz4\"`: LZ4 fast compression\n- `\"none\"`: no compression\n", "enum": [ "lz4", "none" ], "type": "string" }, "fields": { "description": "An array of strings with one or more document attribute paths.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "fields" ], "type": "object" }, "type": "array" }, "type": { "description": "The type of the View (`\"arangosearch\"`).\n", "example": "arangosearch", "type": "string" }, "writebufferActive": { "description": "Maximum number of concurrent active writers (segments) that perform a\ntransaction. Other writers (segments) wait till current active writers\n(segments) finish (`0` = disabled).\n", "type": "integer" }, "writebufferIdle": { "description": "Maximum number of writers (segments) cached in the pool (`0` = disabled).\n", "type": "integer" }, "writebufferSizeMax": { "description": "Maximum memory byte size per writer (segment) before a writer (segment) flush\nis triggered. `0` value turns off this limit for any writer (buffer) and data\nis flushed periodically based on the value defined for the flush thread\n(`0` = disabled).\n", "type": "integer" } }, "required": [ "links", "primarySort", "primarySortCompression", "optimizeTopK", "storedValues", "cleanupIntervalStep", "commitIntervalMsec", "consolidationIntervalMsec", "consolidationPolicy", "writebufferIdle", "writebufferActive", "writebufferSizeMax", "id", "name", "type", "globallyUniqueId" ], "type": "object" } } }, "description": "The View has been updated successfully.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `view-name` path parameter is missing or invalid.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A View called `view-name` could not be found.\n" } }, "summary": "Update the properties of an arangosearch View", "tags": [ "Views" ] }, "put": { "description": "Changes all properties of a View by replacing them, except for immutable properties.\n", "operationId": "replaceViewProperties", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the View.\n", "in": "path", "name": "view-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "cleanupIntervalStep": { "default": 2, "description": "Wait at least this many commits between removing unused files in the\nArangoSearch data directory (`0` = disable).\nFor the case where the consolidation policies merge segments often (i.e. a lot\nof commit+consolidate), a lower value causes a lot of disk space to be\nwasted.\nFor the case where the consolidation policies rarely merge segments (i.e. few\ninserts/deletes), a higher value impacts performance without any added\nbenefits.\n\n_Background:_\n With every \"commit\" or \"consolidate\" operation, a new state of the View's\n internal data structures is created on disk.\n Old states/snapshots are released once there are no longer any users\n remaining.\n However, the files for the released states/snapshots are left on disk, and\n only removed by \"cleanup\" operation.\n", "type": "integer" }, "commitIntervalMsec": { "default": 1000, "description": "Wait at least this many milliseconds between committing View data store\nchanges and making documents visible to queries (`0` = disable).\nFor the case where there are a lot of inserts/updates, a higher value causes the\nindex not to account for them and memory usage continues to grow until the commit.\nA lower value impacts performance, including the case where there are no or only a\nfew inserts/updates because of synchronous locking, and it wastes disk space for\neach commit call.\n\n_Background:_\n For data retrieval, ArangoSearch follows the concept of\n \"eventually-consistent\", i.e. eventually all the data in ArangoDB will be\n matched by corresponding query expressions.\n The concept of ArangoSearch \"commit\" operations is introduced to\n control the upper-bound on the time until document addition/removals are\n actually reflected by corresponding query expressions.\n Once a \"commit\" operation is complete, all documents added/removed prior to\n the start of the \"commit\" operation will be reflected by queries invoked in\n subsequent ArangoDB transactions, in-progress ArangoDB transactions will\n still continue to return a repeatable-read state.\n", "type": "integer" }, "consolidationIntervalMsec": { "default": 5000, "description": "Wait at least this many milliseconds between applying `consolidationPolicy` to\nconsolidate the View data store and possibly release space on the filesystem\n(`0` = disable).\nFor the case where there are a lot of data modification operations, a higher\nvalue could potentially have the data store consume more space and file handles.\nFor the case where there are a few data modification operations, a lower value\nimpacts performance due to no segment candidates being available for\nconsolidation.\n\n_Background:_\n For data modification, ArangoSearch follows the concept of a\n \"versioned data store\". Thus old versions of data may be removed once there\n are no longer any users of the old data. The frequency of the cleanup and\n compaction operations are governed by `consolidationIntervalMsec` and the\n candidates for compaction are selected via `consolidationPolicy`.\n", "type": "integer" }, "consolidationPolicy": { "description": "The consolidation policy to apply for selecting which segments should be merged.\n\n- If the `tier` type is used, then the `maxSkewThreshold`,\n`minDeletionRatio`, `segments*`, and `minScore` properties are available.\n- If the `bytes_accum` type is used, then the `threshold` property is available.\n\n_Background:_\n With each ArangoDB transaction that inserts documents, one or more\n ArangoSearch-internal segments get created.\n Similarly, for removed documents, the segments that contain such documents\n have these documents marked as 'deleted'.\n Over time, this approach causes a lot of small and sparse segments to be\n created.\n A \"consolidation\" operation selects one or more segments and copies all of\n their valid documents into a single new segment, thereby allowing the\n search algorithm to perform more optimally and for extra file handles to be\n released once old segments are no longer used.\n", "properties": { "maxSkewThreshold": { "default": 0.4, "description": "This option is available from v3.12.7 onward:\n\nThe skew describes how much segment files vary in file size. It is a number\nbetween `0.0` and `1.0` and is calculated by dividing the largest file size\nof a set of segment files by the total size. For example, the skew of a\n200 MiB, 300 MiB, and 500 MiB segment file is `0.5` (`500 / 1000`).\n\nA large `maxSkewThreshold` value allows merging large segment files with\nsmaller ones, consolidation occurs more frequently, and there are fewer\nsegment files on disk at all times. While this may potentially improve the\nread performance and use fewer file descriptors, frequent consolidations\ncause a higher write load and thus a higher write amplification.\n\nOn the other hand, a small threshold value triggers the consolidation only\nwhen there are a large number of segment files that don't vary in size a lot.\nConsolidation occurs less frequently, reducing the write amplification, but\nit can result in a greater number of segment files on disk.\n\nMultiple combinations of candidate segments are checked and the one with\nthe lowest skew value is selected for consolidation. The selection process\npicks the greatest number of segments that together have the lowest skew value\nwhile ensuring that the size of the new consolidated segment remains under\nthe configured `segmentsBytesMax`.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minDeletionRatio": { "default": 0.5, "description": "This option is available from v3.12.7 onward:\n\nThe `minDeletionRatio` represents the minimum required deletion ratio\nin one or more segments to perform a cleanup of those segments.\nIt is a number between `0.0` and `1.0`.\n\nThe deletion ratio is the percentage of deleted documents across one or\nmore segment files and is calculated by dividing the number of deleted\ndocuments by the total number of documents in a segment or a group of\nsegments. For example, if there is a segment with 1000 documents of which\n300 are deleted and another segment with 1000 documents of which 700 are\ndeleted, the deletion ratio is `0.5` (50%, calculated as `1000 / 2000`).\n\nThe `minDeletionRatio` threshold must be carefully selected. A smaller\nvalue leads to earlier cleanup of deleted documents from segments and\nthus reclamation of disk space but it generates a higher write load.\nA very large value lowers the write amplification but at the same time\nthe system can be left with a large number of segment files with a high\npercentage of deleted documents that occupy disk space unnecessarily.\n\nDuring cleanup, the segment files are first arranged in decreasing\norder of their individual deletion ratios. Then the largest subset of\nsegments whose collective deletion ratio is greater than or equal to\n`minDeletionRatio` is picked.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minScore": { "default": 0, "description": "This option is only available up to v3.12.6:\n\nFilter out consolidation candidates with a score less than this.\n", "type": "integer" }, "segmentsBytesFloor": { "default": 25165824, "description": "This option is only available up to v3.12.6:\n\nDefines the value (in bytes) to treat all smaller segments\nas equal for consolidation selection.\n", "type": "integer" }, "segmentsBytesMax": { "default": 8589934592, "description": "Maximum allowed size of all consolidated segments in bytes.\n", "type": "integer" }, "segmentsMax": { "default": 200, "description": "This option is only available up to v3.12.6:\n\nThe maximum number of segments that are evaluated as\ncandidates for consolidation.\n", "type": "integer" }, "segmentsMin": { "default": 50, "description": "This option is only available up to v3.12.6:\n\nThe minimum number of segments that are\nevaluated as candidates for consolidation\n", "type": "integer" }, "threshold": { "default": 0, "description": "A value in the range `[0.0, 1.0]`.\n", "maximum": 1, "minimum": 0, "type": "number" }, "type": { "default": "tier", "description": "The segment candidates for the \"consolidation\" operation are selected based\nupon several possible configurable formulas as defined by their types.\nThe currently supported types are:\n- `\"tier\"`: consolidate based on segment byte size skew and live\n document count as dictated by the customization attributes. \n- `\"bytes_accum\"`: consolidate if and only if\n `{threshold} \u003e (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes`\n i.e. the sum of all candidate segment byte size is less than the total\n segment byte size multiplied by the `{threshold}`.\n", "enum": [ "tier", "bytes_accum" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "links": { "description": "Expects an object with the attribute keys being names of to be linked collections,\nand the link properties as attribute values. Example:\n\n```json\n{\n \"name\": \"arangosearch\",\n \"links\": {\n \"coll\": {\n \"fields\": {\n \"my_attribute\": {\n \"fields\": {\n \"my_sub_attribute\": {\n \"analyzers\": [\"text_en\"]\n }\n }\n }\n }\n }\n }\n}\n```\n\nSee [`arangosearch` View Link Properties](https://docs.arango.ai/arangodb/3.12/indexes-and-search/arangosearch/arangosearch-views-reference/#link-properties)\nfor details.\n", "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cleanupIntervalStep": { "description": "Wait at least this many commits between removing unused files in the\nArangoSearch data directory (`0` = disabled).\n", "type": "integer" }, "commitIntervalMsec": { "description": "Wait at least this many milliseconds between committing View data store\nchanges and making documents visible to queries (`0` = disabled).\n", "type": "integer" }, "consolidationIntervalMsec": { "description": "Wait at least this many milliseconds between applying `consolidationPolicy` to\nconsolidate the View data store and possibly release space on the filesystem\n(`0` = disabled).\n", "type": "integer" }, "consolidationPolicy": { "description": "The consolidation policy to apply for selecting which segments should be merged.\n\n- If the `tier` type is used, then the `maxSkewThreshold`,\n`minDeletionRatio`, `segments*`, and `minScore` properties are available.\n- If the `bytes_accum` type is used, then the `threshold` property is available.\n", "properties": { "maxSkewThreshold": { "description": "This option is available from v3.12.7 onward:\n\nThe skew describes how much segment files vary in file size. It is a number\nbetween `0.0` and `1.0` and is calculated by dividing the largest file size\nof a set of segment files by the total size. For example, the skew of a\n200 MiB, 300 MiB, and 500 MiB segment file is `0.5` (`500 / 1000`).\n\nA large `maxSkewThreshold` value allows merging large segment files with\nsmaller ones, consolidation occurs more frequently, and there are fewer\nsegment files on disk at all times. While this may potentially improve the\nread performance and use fewer file descriptors, frequent consolidations\ncause a higher write load and thus a higher write amplification.\n\nOn the other hand, a small threshold value triggers the consolidation only\nwhen there are a large number of segment files that don't vary in size a lot.\nConsolidation occurs less frequently, reducing the write amplification, but\nit can result in a greater number of segment files on disk.\n\nMultiple combinations of candidate segments are checked and the one with\nthe lowest skew value is selected for consolidation. The selection process\npicks the greatest number of segments that together have the lowest skew value\nwhile ensuring that the size of the new consolidated segment remains under\nthe configured `segmentsBytesMax`.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minDeletionRatio": { "description": "This option is available from v3.12.7 onward:\n\nThe `minDeletionRatio` represents the minimum required deletion ratio\nin one or more segments to perform a cleanup of those segments.\nIt is a number between `0.0` and `1.0`.\n\nThe deletion ratio is the percentage of deleted documents across one or\nmore segment files and is calculated by dividing the number of deleted\ndocuments by the total number of documents in a segment or a group of\nsegments. For example, if there is a segment with 1000 documents of which\n300 are deleted and another segment with 1000 documents of which 700 are\ndeleted, the deletion ratio is `0.5` (50%, calculated as `1000 / 2000`).\n\nThe `minDeletionRatio` threshold must be carefully selected. A smaller\nvalue leads to earlier cleanup of deleted documents from segments and\nthus reclamation of disk space but it generates a higher write load.\nA very large value lowers the write amplification but at the same time\nthe system can be left with a large number of segment files with a high\npercentage of deleted documents that occupy disk space unnecessarily.\n\nDuring cleanup, the segment files are first arranged in decreasing\norder of their individual deletion ratios. Then the largest subset of\nsegments whose collective deletion ratio is greater than or equal to\n`minDeletionRatio` is picked.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minScore": { "description": "This option is only available up to v3.12.6:\n\nFilter out consolidation candidates with a score less than this.\n", "type": "integer" }, "segmentsBytesFloor": { "description": "This option is only available up to v3.12.6:\n\nDefines the value (in bytes) to treat all smaller segments\nas equal for consolidation selection.\n", "type": "integer" }, "segmentsBytesMax": { "description": "Maximum allowed size of all consolidated segments in bytes.\n", "type": "integer" }, "segmentsMax": { "description": "This option is only available up to v3.12.6:\n\nThe maximum number of segments that are evaluated as\ncandidates for consolidation.\n", "type": "integer" }, "segmentsMin": { "description": "This option is only available up to v3.12.6:\n\nThe minimum number of segments that are\nevaluated as candidates for consolidation\n", "type": "integer" }, "threshold": { "description": "A value in the range `[0.0, 1.0]`\n", "maximum": 1, "minimum": 0, "type": "number" }, "type": { "description": "The segment candidates for the \"consolidation\" operation are selected based\nupon several possible configurable formulas as defined by their types.\nThe currently supported types are:\n- `\"tier\"`: consolidate based on segment byte size skew and live\n document count as dictated by the customization attributes.\n- `\"bytes_accum\"`: consolidate if and only if\n `{threshold} \u003e (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes`\n i.e. the sum of all candidate segment byte size is less than the total\n segment byte size multiplied by the `{threshold}`.\n", "enum": [ "tier", "bytes_accum" ], "type": "string" } }, "type": "object" }, "globallyUniqueId": { "description": "A unique identifier of the View. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the View (deprecated).\n", "type": "string" }, "links": { "description": "An object with the attribute keys being names of to be linked collections,\nand the link properties as attribute values. See\n[`arangosearch` View Link Properties](https://docs.arango.ai/arangodb/3.12/indexes-and-search/arangosearch/arangosearch-views-reference/#link-properties)\nfor details.\n", "type": "object" }, "name": { "description": "The name of the View.\n", "example": "coll", "type": "string" }, "optimizeTopK": { "description": "An array of strings defining sort expressions that can be optimized.\nThis is also known as _WAND optimization_ (introduced in v3.12.0).\n", "items": { "type": "string" }, "type": "array" }, "primaryKeyCache": { "description": "Whether the primary key columns are always cached in memory.\n", "type": "boolean" }, "primarySort": { "description": "The primary sort order, described by an array of objects, each specifying\na field (attribute path) and a sort direction.\n", "items": { "properties": { "asc": { "description": "The sort direction.\n\n- `true` for ascending\n- `false` for descending\n", "type": "boolean" }, "field": { "description": "An attribute path. The `.` character denotes sub-attributes.\n", "type": "string" } }, "required": [ "field", "asc" ], "type": "object" }, "type": "array" }, "primarySortCache": { "description": "Whether the primary sort columns are always cached in memory.\n", "type": "boolean" }, "primarySortCompression": { "description": "Defines how the primary sort data is compressed.\n\n- `\"lz4\"`: LZ4 fast compression\n- `\"none\"`: no compression\n", "enum": [ "lz4", "none" ], "type": "string" }, "storedValues": { "description": "An array of objects that describes which document attributes are stored\nin the View index for covering search queries, which means the data can\nbe taken from the index directly and accessing the storage engine can\nbe avoided.\n", "items": { "properties": { "cache": { "description": "Whether stored values are always cached in memory.\n", "type": "boolean" }, "compression": { "description": "The compression type used for the internal column-store.\n\n- `\"lz4\"`: LZ4 fast compression\n- `\"none\"`: no compression\n", "enum": [ "lz4", "none" ], "type": "string" }, "fields": { "description": "An array of strings with one or more document attribute paths.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "fields" ], "type": "object" }, "type": "array" }, "type": { "description": "The type of the View (`\"arangosearch\"`).\n", "example": "arangosearch", "type": "string" }, "writebufferActive": { "description": "Maximum number of concurrent active writers (segments) that perform a\ntransaction. Other writers (segments) wait till current active writers\n(segments) finish (`0` = disabled).\n", "type": "integer" }, "writebufferIdle": { "description": "Maximum number of writers (segments) cached in the pool (`0` = disabled).\n", "type": "integer" }, "writebufferSizeMax": { "description": "Maximum memory byte size per writer (segment) before a writer (segment) flush\nis triggered. `0` value turns off this limit for any writer (buffer) and data\nis flushed periodically based on the value defined for the flush thread\n(`0` = disabled).\n", "type": "integer" } }, "required": [ "links", "primarySort", "primarySortCompression", "optimizeTopK", "storedValues", "cleanupIntervalStep", "commitIntervalMsec", "consolidationIntervalMsec", "consolidationPolicy", "writebufferIdle", "writebufferActive", "writebufferSizeMax", "id", "name", "type", "globallyUniqueId" ], "type": "object" } } }, "description": "The View has been updated successfully.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `view-name` path parameter is missing or invalid.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A View called `view-name` could not be found.\n" } }, "summary": "Replace the properties of an arangosearch View", "tags": [ "Views" ] } }, "/_db/{database-name}/_api/view/{view-name}/properties#searchalias": { "get": { "description": "Returns an object containing the definition of the View identified by `view-name`.\n", "operationId": "getViewPropertiesSearchAlias", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the View.\n", "in": "path", "name": "view-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "globallyUniqueId": { "description": "A unique identifier of the View. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the View (deprecated).\n", "type": "string" }, "indexes": { "description": "The list of the View's inverted indexes.\n", "items": { "properties": { "collection": { "description": "The name of a collection.\n", "type": "string" }, "index": { "description": "The name of an inverted index of the `collection`.\n", "type": "string" } }, "required": [ "collection", "index" ], "type": "object" }, "type": "array" }, "name": { "description": "The name of the View.\n", "type": "string" }, "type": { "description": "The type of the View (`\"search-alias\"`).\n", "example": "search-alias", "type": "string" } }, "required": [ "name", "type", "id", "globallyUniqueId", "indexes" ], "type": "object" } } }, "description": "An object with a full description of the specified View, including\n`search-alias` View type-dependent properties.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `view-name` parameter is missing or invalid.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A View called `view-name` could not be found.\n" } }, "summary": "Read properties of a View", "tags": [ "Views" ] }, "patch": { "description": "Updates the list of indexes of a `search-alias` View.\n", "operationId": "updateViewPropertiesSearchAlias", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the View.\n", "in": "path", "name": "view-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "indexes": { "description": "A list of inverted indexes to add to or remove from the View.\n", "items": { "properties": { "collection": { "description": "The name of a collection.\n", "type": "string" }, "index": { "description": "The name of an inverted index of the `collection`, or the index ID without\nthe `\u003ccollection\u003e/` prefix.\n", "type": "string" }, "operation": { "default": "add", "description": "Whether to add or remove the index to the stored `indexes` property of the View.\n", "enum": [ "add", "del" ], "type": "string" } }, "required": [ "collection", "index" ], "type": "object" }, "type": "array" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "globallyUniqueId": { "description": "A unique identifier of the View. This is an internal property.\n", "type": "string" }, "id": { "description": "The identifier of the View.\n", "type": "string" }, "indexes": { "description": "The list of inverted indexes that are part of the View.\n", "items": { "properties": { "collection": { "description": "The name of a collection.\n", "type": "string" }, "index": { "description": "The name of an inverted index of the `collection`.\n", "type": "string" } }, "required": [ "collection", "index" ], "type": "object" }, "type": "array" }, "name": { "description": "The name of the View.\n", "type": "string" }, "type": { "description": "The View type (`\"search-alias\"`).\n", "type": "string" } }, "required": [ "name", "type", "id", "globallyUniqueId", "indexes" ], "type": "object" } } }, "description": "The View has been updated successfully.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `view-name` parameter is missing or invalid.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A View called `view-name` could not be found.\n" } }, "summary": "Update the properties of a search-alias View", "tags": [ "Views" ] }, "put": { "description": "Replaces the list of indexes of a `search-alias` View.\n", "operationId": "replaceViewPropertiesSearchAlias", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the View.\n", "in": "path", "name": "view-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "indexes": { "description": "A list of inverted indexes for the View.\n", "items": { "properties": { "collection": { "description": "The name of a collection.\n", "type": "string" }, "index": { "description": "The name of an inverted index of the `collection`, or the index ID without\nthe `\u003ccollection\u003e/` prefix.\n", "type": "string" } }, "required": [ "collection", "index" ], "type": "object" }, "type": "array" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "globallyUniqueId": { "description": "A unique identifier of the View. This is an internal property.\n", "type": "string" }, "id": { "description": "The identifier of the View.\n", "type": "string" }, "indexes": { "description": "The list of inverted indexes that are part of the View.\n", "items": { "properties": { "collection": { "description": "The name of a collection.\n", "type": "string" }, "index": { "description": "The name of an inverted index of the `collection`.\n", "type": "string" } }, "required": [ "collection", "index" ], "type": "object" }, "type": "array" }, "name": { "description": "The name of the View.\n", "type": "string" }, "type": { "description": "The View type (`\"search-alias\"`).\n", "type": "string" } }, "required": [ "name", "type", "id", "globallyUniqueId", "indexes" ], "type": "object" } } }, "description": "The View has been updated successfully.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `view-name` parameter is missing or invalid.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A View called `view-name` could not be found.\n" } }, "summary": "Replace the properties of a search-alias View", "tags": [ "Views" ] } }, "/_db/{database-name}/_api/view/{view-name}/rename": { "put": { "description": "Renames a View.\n\n\u003e **INFO:**\nRenaming Views is not supported in cluster deployments.\n", "operationId": "renameView", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the View to rename.\n", "in": "path", "name": "view-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "The new name for the View.\n", "type": "string" } }, "required": [ "name" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cleanupIntervalStep": { "description": "Wait at least this many commits between removing unused files in the\nArangoSearch data directory (`0` = disabled).\n", "type": "integer" }, "commitIntervalMsec": { "description": "Wait at least this many milliseconds between committing View data store\nchanges and making documents visible to queries (`0` = disabled).\n", "type": "integer" }, "consolidationIntervalMsec": { "description": "Wait at least this many milliseconds between applying `consolidationPolicy` to\nconsolidate the View data store and possibly release space on the filesystem\n(`0` = disabled).\n", "type": "integer" }, "consolidationPolicy": { "description": "The consolidation policy to apply for selecting which segments should be merged.\n\n- If the `tier` type is used, then the `maxSkewThreshold`,\n`minDeletionRatio`, `segments*`, and `minScore` properties are available.\n- If the `bytes_accum` type is used, then the `threshold` property is available.\n", "properties": { "maxSkewThreshold": { "description": "This option is available from v3.12.7 onward:\n\nThe skew describes how much segment files vary in file size. It is a number\nbetween `0.0` and `1.0` and is calculated by dividing the largest file size\nof a set of segment files by the total size. For example, the skew of a\n200 MiB, 300 MiB, and 500 MiB segment file is `0.5` (`500 / 1000`).\n\nA large `maxSkewThreshold` value allows merging large segment files with\nsmaller ones, consolidation occurs more frequently, and there are fewer\nsegment files on disk at all times. While this may potentially improve the\nread performance and use fewer file descriptors, frequent consolidations\ncause a higher write load and thus a higher write amplification.\n\nOn the other hand, a small threshold value triggers the consolidation only\nwhen there are a large number of segment files that don't vary in size a lot.\nConsolidation occurs less frequently, reducing the write amplification, but\nit can result in a greater number of segment files on disk.\n\nMultiple combinations of candidate segments are checked and the one with\nthe lowest skew value is selected for consolidation. The selection process\npicks the greatest number of segments that together have the lowest skew value\nwhile ensuring that the size of the new consolidated segment remains under\nthe configured `segmentsBytesMax`.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minDeletionRatio": { "description": "This option is available from v3.12.7 onward:\n\nThe `minDeletionRatio` represents the minimum required deletion ratio\nin one or more segments to perform a cleanup of those segments.\nIt is a number between `0.0` and `1.0`.\n\nThe deletion ratio is the percentage of deleted documents across one or\nmore segment files and is calculated by dividing the number of deleted\ndocuments by the total number of documents in a segment or a group of\nsegments. For example, if there is a segment with 1000 documents of which\n300 are deleted and another segment with 1000 documents of which 700 are\ndeleted, the deletion ratio is `0.5` (50%, calculated as `1000 / 2000`).\n\nThe `minDeletionRatio` threshold must be carefully selected. A smaller\nvalue leads to earlier cleanup of deleted documents from segments and\nthus reclamation of disk space but it generates a higher write load.\nA very large value lowers the write amplification but at the same time\nthe system can be left with a large number of segment files with a high\npercentage of deleted documents that occupy disk space unnecessarily.\n\nDuring cleanup, the segment files are first arranged in decreasing\norder of their individual deletion ratios. Then the largest subset of\nsegments whose collective deletion ratio is greater than or equal to\n`minDeletionRatio` is picked.\n", "maximum": 1, "minimum": 0, "type": "number" }, "minScore": { "description": "This option is only available up to v3.12.6:\n\nFilter out consolidation candidates with a score less than this.\n", "type": "integer" }, "segmentsBytesFloor": { "description": "This option is only available up to v3.12.6:\n\nDefines the value (in bytes) to treat all smaller segments\nas equal for consolidation selection.\n", "type": "integer" }, "segmentsBytesMax": { "description": "Maximum allowed size of all consolidated segments in bytes.\n", "type": "integer" }, "segmentsMax": { "description": "This option is only available up to v3.12.6:\n\nThe maximum number of segments that are evaluated as\ncandidates for consolidation.\n", "type": "integer" }, "segmentsMin": { "description": "This option is only available up to v3.12.6:\n\nThe minimum number of segments that are\nevaluated as candidates for consolidation\n", "type": "integer" }, "threshold": { "description": "A value in the range `[0.0, 1.0]`\n", "maximum": 1, "minimum": 0, "type": "number" }, "type": { "description": "The segment candidates for the \"consolidation\" operation are selected based\nupon several possible configurable formulas as defined by their types.\nThe currently supported types are:\n- `\"tier\"`: consolidate based on segment byte size skew and live\n document count as dictated by the customization attributes.\n- `\"bytes_accum\"`: consolidate if and only if\n `{threshold} \u003e (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes`\n i.e. the sum of all candidate segment byte size is less than the total\n segment byte size multiplied by the `{threshold}`.\n", "enum": [ "tier", "bytes_accum" ], "type": "string" } }, "type": "object" }, "globallyUniqueId": { "description": "A unique identifier of the View. This is an internal property.\n", "type": "string" }, "id": { "description": "A unique identifier of the View (deprecated).\n", "type": "string" }, "links": { "description": "An object with the attribute keys being names of to be linked collections,\nand the link properties as attribute values. See\n[`arangosearch` View Link Properties](https://docs.arango.ai/arangodb/3.12/indexes-and-search/arangosearch/arangosearch-views-reference/#link-properties)\nfor details.\n", "type": "object" }, "name": { "description": "The name of the View.\n", "example": "coll", "type": "string" }, "optimizeTopK": { "description": "An array of strings defining sort expressions that can be optimized.\nThis is also known as _WAND optimization_ (introduced in v3.12.0).\n", "items": { "type": "string" }, "type": "array" }, "primaryKeyCache": { "description": "Whether the primary key columns are always cached in memory.\n", "type": "boolean" }, "primarySort": { "description": "The primary sort order, described by an array of objects, each specifying\na field (attribute path) and a sort direction.\n", "items": { "properties": { "asc": { "description": "The sort direction.\n\n- `true` for ascending\n- `false` for descending\n", "type": "boolean" }, "field": { "description": "An attribute path. The `.` character denotes sub-attributes.\n", "type": "string" } }, "required": [ "field", "asc" ], "type": "object" }, "type": "array" }, "primarySortCache": { "description": "Whether the primary sort columns are always cached in memory.\n", "type": "boolean" }, "primarySortCompression": { "description": "Defines how the primary sort data is compressed.\n\n- `\"lz4\"`: LZ4 fast compression\n- `\"none\"`: no compression\n", "enum": [ "lz4", "none" ], "type": "string" }, "storedValues": { "description": "An array of objects that describes which document attributes are stored\nin the View index for covering search queries, which means the data can\nbe taken from the index directly and accessing the storage engine can\nbe avoided.\n", "items": { "properties": { "cache": { "description": "Whether stored values are always cached in memory.\n", "type": "boolean" }, "compression": { "description": "The compression type used for the internal column-store.\n\n- `\"lz4\"`: LZ4 fast compression\n- `\"none\"`: no compression\n", "enum": [ "lz4", "none" ], "type": "string" }, "fields": { "description": "An array of strings with one or more document attribute paths.\n", "items": { "type": "string" }, "type": "array" } }, "required": [ "fields" ], "type": "object" }, "type": "array" }, "type": { "description": "The type of the View (`\"arangosearch\"`).\n", "example": "arangosearch", "type": "string" }, "writebufferActive": { "description": "Maximum number of concurrent active writers (segments) that perform a\ntransaction. Other writers (segments) wait till current active writers\n(segments) finish (`0` = disabled).\n", "type": "integer" }, "writebufferIdle": { "description": "Maximum number of writers (segments) cached in the pool (`0` = disabled).\n", "type": "integer" }, "writebufferSizeMax": { "description": "Maximum memory byte size per writer (segment) before a writer (segment) flush\nis triggered. `0` value turns off this limit for any writer (buffer) and data\nis flushed periodically based on the value defined for the flush thread\n(`0` = disabled).\n", "type": "integer" } }, "required": [ "links", "primarySort", "primarySortCompression", "optimizeTopK", "storedValues", "cleanupIntervalStep", "commitIntervalMsec", "consolidationIntervalMsec", "consolidationPolicy", "writebufferIdle", "writebufferActive", "writebufferSizeMax", "id", "name", "type", "globallyUniqueId" ], "type": "object" } } }, "description": "The View has been renamed successfully.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `view-name` path parameter is missing or invalid.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A View called `view-name` could not be found.\n" } }, "summary": "Rename a View", "tags": [ "Views" ] } }, "/_db/{database-name}/_api/view/{view-name}/rename#searchalias": { "put": { "description": "Renames a View.\n\n\u003e **INFO:**\nRenaming Views is not supported in cluster deployments.\n", "operationId": "renameViewSearchAlias", "parameters": [ { "description": "The name of the database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "The name of the View to rename.\n", "in": "path", "name": "view-name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "name": { "description": "The new name for the View.\n", "type": "string" } }, "required": [ "name" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "globallyUniqueId": { "description": "A unique identifier of the View. This is an internal property.\n", "type": "string" }, "id": { "description": "The identifier of the View.\n", "type": "string" }, "indexes": { "description": "The list of inverted indexes that are part of the View.\n", "items": { "properties": { "collection": { "description": "The name of a collection.\n", "type": "string" }, "index": { "description": "The name of an inverted index of the `collection`.\n", "type": "string" } }, "required": [ "collection", "index" ], "type": "object" }, "type": "array" }, "name": { "description": "The name of the View.\n", "type": "string" }, "type": { "description": "The View type (`\"search-alias\"`).\n", "type": "string" } }, "required": [ "name", "type", "id", "globallyUniqueId", "indexes" ], "type": "object" } } }, "description": "The View has been renamed successfully.\n" }, "400": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 400, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "The `view-name` parameter is missing or invalid.\n" }, "404": { "content": { "application/json": { "schema": { "properties": { "code": { "description": "The HTTP response status code.\n", "example": 404, "type": "integer" }, "error": { "description": "A flag indicating that an error occurred.\n", "example": true, "type": "boolean" }, "errorMessage": { "description": "A descriptive error message.\n", "type": "string" }, "errorNum": { "description": "The ArangoDB error number for the error that occurred.\n", "type": "integer" } }, "required": [ "error", "code", "errorNum", "errorMessage" ], "type": "object" } } }, "description": "A View called `view-name` could not be found.\n" } }, "summary": "Rename a View", "tags": [ "Views" ] } }, "/_db/{database-name}/_api/wal/lastTick": { "get": { "description": "Returns the last available tick value that can be served from the server's\nreplication log. This corresponds to the tick of the latest successful operation.\n\nThe result is a JSON object containing the attributes `tick`, `time` and `server`.\n- `tick`: contains the last available tick, `time`\n- `time`: the server time as string in format `YYYY-MM-DDTHH:MM:SSZ`\n- `server`: An object with fields `version` and `serverId`\n\n\u003e **INFO:**\nThis method is not supported on a Coordinator in a cluster deployment.\n", "operationId": "getWalLastTick", "parameters": [ { "description": "The name of a database. The user account you authenticate with needs\nat least read access to this database and administrate access to the\n`_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" }, "501": { "description": "is returned when this operation is called on a Coordinator in a cluster deployment.\n" } }, "summary": "Get the last available tick value", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/wal/range": { "get": { "description": "Returns the currently available ranges of tick values for all Write-Ahead Log\n(WAL) files. The tick values can be used to determine if certain\ndata (identified by tick value) are still available for replication.\n\nThe body of the response contains a JSON object.\n- `tickMin`: minimum tick available\n- `tickMax`: maximum tick available\n- `time`: the server time as string in format `YYYY-MM-DDTHH:MM:SSZ`\n- `server`: An object with fields `version` and `serverId`\n", "operationId": "getWalRange", "parameters": [ { "description": "The name of a database. The user account you authenticate with needs\nat least read access to this database and administrate access to the\n`_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the tick ranges could be determined successfully.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if the server operations state could not be determined.\n" }, "501": { "description": "is returned when this operation is called on a Coordinator in a cluster deployment.\n" } }, "summary": "Get the tick ranges available in the WAL", "tags": [ "Replication" ] } }, "/_db/{database-name}/_api/wal/tail": { "get": { "description": "Returns data from the server's write-ahead log (also named replication log). This method can be called\nby replication clients after an initial synchronization of data. The method\nreturns all \"recent\" logged operations from the server. Clients\ncan replay and apply these operations locally so they get to the same data\nstate as the server.\n\nClients can call this method repeatedly to incrementally fetch all changes\nfrom the server. In this case, they should provide the `from` value so\nthey only get returned the log events since their last fetch.\n\nWhen the `from` query parameter is not used, the server returns log\nentries starting at the beginning of its replication log. When the `from`\nparameter is used, the server only returns log entries which have\nhigher tick values than the specified `from` value (note: the log entry with a\ntick value equal to `from` is excluded). Use the `from` value when\nincrementally fetching log data.\n\nThe `to` query parameter can be used to optionally restrict the upper bound of\nthe result to a certain tick value. If used, the result contains only log events\nwith tick values up to (including) `to`. In incremental fetching, there is no\nneed to use the `to` parameter. It only makes sense in special situations,\nwhen only parts of the change log are required.\n\nThe `chunkSize` query parameter can be used to control the size of the result.\nIt must be specified in bytes. The `chunkSize` value is only honored\napproximately. Otherwise, a too low `chunkSize` value could cause the server\nto not be able to put just one log entry into the result and return it.\nTherefore, the `chunkSize` value is only consulted after a log entry has\nbeen written into the result. If the result size is then greater than\n`chunkSize`, the server responds with as many log entries as there are\nin the response already. If the result size is still less than `chunkSize`,\nthe server tries to return more data if there's more data left to return.\n\nIf `chunkSize` is not specified, some server-side default value is used.\n\nThe `Content-Type` of the result is `application/x-arango-dump`. This is an\neasy-to-process format, with all log events going onto separate lines in the\nresponse body. Each log event itself is a JSON object, with at least the\nfollowing attributes:\n\n- `tick`: the log event tick value\n\n- `type`: the log event type\n\nIndividual log events also have additional attributes, depending on the\nevent type. A few common attributes which are used for multiple events types\nare:\n\n- `cuid`: globally unique id of the View or collection the event was for\n\n- `db`: the database name the event was for\n\n- `tid`: id of the transaction the event was contained in\n\n- `data`: the original document data\n\nFor a more detailed description of the individual replication event types\nand their data structures, see the Operation Types.\n\nThe response also contains the following HTTP headers:\n\n- `x-arango-replication-active`: whether or not the logger is active. Clients\n can use this flag as an indication for their polling frequency. If the\n logger is not active and there are no more replication events available, it\n might be sensible for a client to abort, or to go to sleep for a long time\n and try again later to check whether the logger has been activated.\n\n- `x-arango-replication-lastincluded`: the tick value of the last included\n value in the result. In incremental log fetching, this value can be used\n as the `from` value for the following request. **Note** that if the result is\n empty, the value is `0`. This value should not be used as `from` value\n by clients in the next request (otherwise the server would return the log\n events from the start of the log again).\n\n- `x-arango-replication-lastscanned`: the last tick the server scanned while\n computing the operation log. This might include operations the server did not\n returned to you due to various reasons (i.e. the value was filtered or skipped).\n You may use this value in the `lastScanned` header to allow the RocksDB storage engine\n to break up requests over multiple responses.\n\n- `x-arango-replication-lasttick`: the last tick value the server has\n logged in its write ahead log (not necessarily included in the result). By comparing the last\n tick and last included tick values, clients have an approximate indication of\n how many events there are still left to fetch.\n\n- `x-arango-replication-frompresent`: is set to _true_ if server returned\n all tick values starting from the specified tick in the _from_ parameter.\n Should this be set to false the server did not have these operations anymore\n and the client might have missed operations.\n\n- `x-arango-replication-checkmore`: whether or not there already exists more\n log data which the client could fetch immediately. If there is more log data\n available, the client could call the tailing API again with an adjusted `from`\n value to fetch remaining log entries until there are no more.\n\n If there isn't any more log data to fetch, the client might decide to go\n to sleep for a while before calling the logger again.\n\n\u003e **INFO:**\nThis method is not supported on a Coordinator in a cluster deployment.\n", "operationId": "getWalTail", "parameters": [ { "description": "The name of a database. The user account you authenticate with needs\nat least read access to this database and administrate access to the\n`_system` database.\n", "example": "_system", "in": "path", "name": "database-name", "required": true, "schema": { "type": "string" } }, { "description": "Whether operations for all databases should be included. If set to `false`,\nonly the operations for the current database are included. The value `true` is\nonly valid on the `_system` database.\n", "in": "query", "name": "global", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Exclusive lower bound tick value for results. On successive calls\nto this API you should set this to the value returned\nwith the `x-arango-replication-lastincluded` header (unless that header\ncontains 0).\n", "in": "query", "name": "from", "required": false, "schema": { "type": "number" } }, { "description": "Inclusive upper bound tick value for results.\n", "in": "query", "name": "to", "required": false, "schema": { "type": "number" } }, { "description": "Should be set to the value of the `x-arango-replication-lastscanned` header\nor alternatively `0` on the first try. This allows the RocksDB storage engine to break up\nlarge transactions over multiple responses.\n", "in": "query", "name": "lastScanned", "required": false, "schema": { "type": "number" } }, { "description": "Approximate maximum size of the returned result.\n", "in": "query", "name": "chunkSize", "required": false, "schema": { "type": "number" } }, { "description": "The ID of the client used to tail results. The server uses this to\nkeep operations until the client has fetched them. Must be a positive integer.\n\u003e **INFO:**\nEither `syncerId` or `serverId` is required to fetch all operations.\n", "in": "query", "name": "syncerId", "required": false, "schema": { "type": "number" } }, { "description": "The ID of the client machine. If `syncerId` is unset, the server uses\nthis to keep operations until the client has fetched them. Must be a positive\ninteger.\n\u003e **INFO:**\nEither `syncerId` or `serverId` is required to fetch all operations.\n", "in": "query", "name": "serverId", "required": false, "schema": { "type": "number" } }, { "description": "Short description of the client, used for informative purposes only.\n", "in": "query", "name": "clientInfo", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "is returned if the request was executed successfully, and there are log\nevents available for the requested range. The response body is not empty\nin this case.\n" }, "204": { "description": "is returned if the request was executed successfully, but there are no log\nevents available for the requested range. The response body is empty\nin this case.\n" }, "400": { "description": "is returned if either the `from` or `to` values are invalid.\n" }, "405": { "description": "is returned when an invalid HTTP method is used.\n" }, "500": { "description": "is returned if an error occurred while assembling the response.\n" }, "501": { "description": "is returned when this operation is called on a Coordinator in a cluster deployment.\n" } }, "summary": "Tail recent server operations", "tags": [ "Replication" ] } }, "/_open/auth": { "post": { "description": "Obtain a JSON Web Token (JWT) from the credentials of an ArangoDB user account\nor a user's access token.\nYou can use the JWT in the `Authorization` HTTP header as a `Bearer` token to\nauthenticate requests.\n\nThe lifetime for the token is controlled by the `--server.session-timeout`\nstartup option.\n", "operationId": "createSessionToken", "requestBody": { "content": { "application/json": { "schema": { "properties": { "password": { "description": "The password of the ArangoDB user or an access token.\n", "type": "string" }, "username": { "description": "The name of an ArangoDB user.\n\nIt is optional if you specify an access token in `password`\nbut required if you use the user's password.\n", "type": "string" } }, "required": [ "password" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "jwt": { "description": "The encoded JWT session token.\n", "type": "string" } }, "required": [ "jwt" ], "type": "object" } } }, "description": "Successfully created a session token.\n" }, "400": { "description": "An HTTP `400 Bad Request` status code is returned if the request misses required\nattributes or if it is otherwise malformed.\n" }, "401": { "description": "An HTTP `401 Unauthorized` status code is returned if the user credentials are\nincorrect.\n" }, "404": { "description": "An HTTP `404 Not Found` status code is returned if the server has authentication\ndisabled and the endpoint is thus not available.\n" } }, "summary": "Create a JWT session token", "tags": [ "Authentication" ] } } }, "tags": [ { "description": "Manage session tokens and JWT secrets", "name": "Authentication" }, { "description": "Manage ArangoDB user accounts", "name": "Users" }, { "description": "Manage databases for organizing collections", "name": "Databases" }, { "description": "Manage collections for organizing documents", "name": "Collections" }, { "description": "Perform CRUD operations on JSON-based records", "name": "Documents" }, { "description": "Manage named graphs and query edges", "name": "Graphs" }, { "description": "Run, process, and manage AQL queries", "name": "Queries" }, { "description": "Run distributed graph algorithms", "name": "Pregel" }, { "description": "Execute JavaScript and Stream Transactions", "name": "Transactions" }, { "description": "Improve the performance of queries", "name": "Indexes" }, { "description": "Manage Views to use ArangoSearch for information retrieval", "name": "Views" }, { "description": "Manage Analyzers for transforming data", "name": "Analyzers" }, { "description": "Load JSON data in bulk", "name": "Import" }, { "description": "Manage microservices written in JavaScript", "name": "Foxx" }, { "description": "Execute requests asynchronously", "name": "Jobs" }, { "description": "Set up JavaScript code to run periodically or timed", "name": "Tasks" }, { "description": "Run multiple operations using a single request", "name": "Batch Requests" }, { "description": "Control data replication for deployments", "name": "Replication" }, { "description": "Access logs, statistics, and metrics", "name": "Monitoring" }, { "description": "Configure audit logging, encryption at rest and encryption in transit", "name": "Security" }, { "description": "Get server information, manage licenses, shut down nodes, and more", "name": "Administration" }, { "description": "Get information, monitor, and administrate cluster deployments", "name": "Cluster" }, { "description": "Manage incremental data backups", "name": "Hot Backups" } ] }