-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/view/69032
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 40
+content-length: 52
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -28354,18 +28598,20 @@ x-content-type-options: nosniff
-Using a name:
-
-
+With the full response format:
+
+
+
+
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/view/productsView
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database?full=true
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 40
+content-length: 457
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -28373,18 +28619,42 @@ x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
- "result" : true
+ "result" : {
+ "_system" : {
+ "permission" : "rw",
+ "collections" : {
+ "animals" : "undefined",
+ "_statistics" : "undefined",
+ "demo" : "undefined",
+ "_users" : "undefined",
+ "_graphs" : "undefined",
+ "_statistics15" : "undefined",
+ "_statisticsRaw" : "undefined",
+ "_analyzers" : "undefined",
+ "_aqlfunctions" : "undefined",
+ "_queues" : "undefined",
+ "_jobs" : "undefined",
+ "_apps" : "undefined",
+ "_appbundles" : "undefined",
+ "_frontend" : "undefined",
+ "*" : "undefined"
+ }
+ },
+ "*" : {
+ "permission" : "none"
+ }
+ }
}
-
Hide response body
-
+
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/view/productsView
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database?full=true
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 40
+content-length: 457
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -28393,46 +28663,57 @@ x-content-type-options: nosniff
+
+
+
@endDocuBlock
-
-@startDocuBlock get_api_view_name
+
+@startDocuBlock UserHandling_fetchDatabasePermission
-@brief returns a View
+@brief Get specific database access level
-@RESTHEADER{GET /_api/view/{view-name}, Return information about a View, getViews:Properties}
+@RESTHEADER{GET /_api/user/{user}/database/{dbname}, Get the database access level}
@RESTURLPARAMETERS
-@RESTURLPARAM{view-name,string,required}
-The name of the View.
+@RESTURLPARAM{user,string,required}
+The name of the user for which you want to query the databases.
+
+@RESTURLPARAM{dbname,string,required}
+The name of the database to query
@RESTDESCRIPTION
-The result is an object briefly describing the View with the following attributes:
-- *id*: The identifier of the View
-- *name*: The name of the View
-- *type*: The type of the View as string
+Fetch the database access level for a specific database
@RESTRETURNCODES
-@RESTRETURNCODE{404}
-If the *view-name* is unknown, then a *HTTP 404* is returned.
+@RESTRETURNCODE{200}
+Returned if the access level can be returned
-@EXAMPLES
+@RESTRETURNCODE{400}
+If the access privileges are not right etc.
-Using an identifier:
+@RESTRETURNCODE{401}
+Returned if you have *No access* database access level to the *_system*
+database.
+@RESTRETURNCODE{403}
+Returned if you have *No access* server access level.
-
-
+@EXAMPLES
+
+
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/69050
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 124
+content-length: 40
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -28440,21 +28721,18 @@ x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
- "type" : "arangosearch",
- "name" : "productsView",
- "id" : "69050",
- "globallyUniqueId" : "h4B0D1F61ADB6/69050"
+ "result" : "rw"
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/69050
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 124
+content-length: 40
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -28465,18 +28743,58 @@ x-content-type-options: nosniff
-Using a name:
+
+@endDocuBlock
-
-
+
+@startDocuBlock UserHandling_fetchCollectionPermission
+
+@brief Get the collection access level
+
+@RESTHEADER{GET /_api/user/{user}/database/{dbname}/{collection}, Get the specific collection access level}
+
+@RESTURLPARAMETERS
+
+@RESTURLPARAM{user,string,required}
+The name of the user for which you want to query the databases.
+
+@RESTURLPARAM{dbname,string,required}
+The name of the database to query
+
+@RESTURLPARAM{collection,string,required}
+The name of the collection
+
+@RESTDESCRIPTION
+Returns the collection access level for a specific collection
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+Returned if the access level can be returned
+
+@RESTRETURNCODE{400}
+If the access privileges are not right etc.
+
+@RESTRETURNCODE{401}
+Returned if you have *No access* database access level to the *_system*
+database.
+
+@RESTRETURNCODE{403}
+Returned if you have *No access* server access level.
+
+@EXAMPLES
+
+
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/productsView
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system/_users
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 124
+content-length: 42
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -28484,21 +28802,18 @@ x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
- "type" : "arangosearch",
- "name" : "productsView",
- "id" : "69055",
- "globallyUniqueId" : "h4B0D1F61ADB6/69055"
+ "result" : "none"
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/productsView
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system/_users
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 124
+content-length: 42
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -28508,106 +28823,101 @@ x-content-type-options: nosniff
+
+
@endDocuBlock
-
-@startDocuBlock get_api_view_properties
+
+@startDocuBlock UserHandling_replace
-@brief reads the properties of the specified View
+@brief Replace an existing user.
-@RESTHEADER{GET /_api/view/{view-name}/properties, Read properties of a View, getView}
+@RESTHEADER{PUT /_api/user/{user}, Replace User}
@RESTURLPARAMETERS
-@RESTDESCRIPTION
-Returns an object containing the definition of the View identified by *view-name*.
+@RESTURLPARAM{user,string,required}
+The name of the user.
-@RESTURLPARAM{view-name,string,required}
-The name of the View.
+@RESTBODYPARAM{passwd,string,required,string}
+The user password as a string. If not specified, it will default to an empty
+string.
+
+@RESTBODYPARAM{active,boolean,optional,}
+An optional flag that specifies whether the user is active. If not
+specified, this will default to *true*.
+
+@RESTBODYPARAM{extra,object,optional,}
+A JSON object with extra user information. It is used by the web interface
+to store graph viewer settings and saved queries. Should not be set or
+modified by end users, as custom attributes will not be preserved.
@RESTDESCRIPTION
-The result is an object with a full description of a specific View, including
-View type dependent properties.
+Replaces the data of an existing user. You need server access level
+*Administrate* in order to execute this REST call. Additionally, a user can
+change his/her own data.
@RESTRETURNCODES
+@RESTRETURNCODE{200}
+Is returned if the user data can be replaced by the server.
+
@RESTRETURNCODE{400}
-If the *view-name* is missing, then a *HTTP 400* is returned.
+The JSON representation is malformed or mandatory data is missing from the request
+
+@RESTRETURNCODE{401}
+Returned if you have *No access* database access level to the *_system*
+database.
+
+@RESTRETURNCODE{403}
+Returned if you have *No access* server access level.
@RESTRETURNCODE{404}
-If the *view-name* is unknown, then a *HTTP 404* is returned.
+The specified user does not exist
@EXAMPLES
-Using an identifier:
-
-
-
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/69065/properties
+shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
+{
+ "passwd" : "secure"
+}
+EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 652
+content-length: 72
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "error" : false,
- "code" : 200,
- "writebufferSizeMax" : 33554432,
- "writebufferIdle" : 64,
- "cleanupIntervalStep" : 2,
- "commitIntervalMsec" : 1000,
- "consolidationIntervalMsec" : 1000,
- "consolidationPolicy" : {
- "type" : "tier",
- "segmentsBytesFloor" : 2097152,
- "segmentsBytesMax" : 5368709120,
- "segmentsMax" : 10,
- "segmentsMin" : 1,
- "minScore" : 0
- },
- "primarySortCompression" : "lz4",
- "writebufferActive" : 0,
- "links" : {
- "books" : {
- "analyzers" : [
- "identity"
- ],
- "fields" : {
- "title" : {
- "analyzers" : [
- "text_en"
- ]
- }
- },
- "includeAllFields" : false,
- "storeValues" : "none",
- "trackListPositions" : false
- }
+ "user" : "admin@myapp",
+ "active" : true,
+ "extra" : {
},
- "globallyUniqueId" : "h4B0D1F61ADB6/69065",
- "name" : "productsView",
- "id" : "69065",
- "storedValues" : [ ],
- "primarySort" : [ ],
- "type" : "arangosearch"
+ "error" : false,
+ "code" : 200
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/69065/properties
+shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
+{
+ "passwd" : "secure"
+}
+EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 652
+content-length: 72
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -28618,74 +28928,98 @@ x-content-type-options: nosniff
-Using a name:
+@endDocuBlock
-
-
+
+
+@startDocuBlock UserHandling_modify
+
+@brief Modify attributes of an existing user
+
+@RESTHEADER{PATCH /_api/user/{user}, Modify User}
+
+@RESTURLPARAMETERS
+
+@RESTURLPARAM{user,string,required}
+The name of the user.
+
+@RESTBODYPARAM{passwd,string,required,string}
+The user password as a string.
+
+@RESTBODYPARAM{active,boolean,optional,}
+An optional flag that specifies whether the user is active.
+
+@RESTBODYPARAM{extra,object,optional,}
+A JSON object with extra user information. It is used by the web interface
+to store graph viewer settings and saved queries. Should not be set or
+modified by end users, as custom attributes will not be preserved.
+
+@RESTDESCRIPTION
+Partially updates the data of an existing user. You need server access level
+*Administrate* in order to execute this REST call. Additionally, a user can
+change his/her own data.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+Is returned if the user data can be replaced by the server.
+
+@RESTRETURNCODE{400}
+The JSON representation is malformed or mandatory data is missing from the request.
+
+@RESTRETURNCODE{401}
+Returned if you have *No access* database access level to the *_system*
+database.
+
+@RESTRETURNCODE{403}
+Returned if you have *No access* server access level.
+
+@RESTRETURNCODE{404}
+The specified user does not exist
+
+@EXAMPLES
+
+
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/productsView/properties
+shell> curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
+{
+ "passwd" : "secure"
+}
+EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 652
+content-length: 72
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "error" : false,
- "code" : 200,
- "writebufferSizeMax" : 33554432,
- "writebufferIdle" : 64,
- "cleanupIntervalStep" : 2,
- "commitIntervalMsec" : 1000,
- "consolidationIntervalMsec" : 1000,
- "consolidationPolicy" : {
- "type" : "tier",
- "segmentsBytesFloor" : 2097152,
- "segmentsBytesMax" : 5368709120,
- "segmentsMax" : 10,
- "segmentsMin" : 1,
- "minScore" : 0
- },
- "primarySortCompression" : "lz4",
- "writebufferActive" : 0,
- "links" : {
- "books" : {
- "analyzers" : [
- "identity"
- ],
- "fields" : {
- "title" : {
- "analyzers" : [
- "text_en"
- ]
- }
- },
- "includeAllFields" : false,
- "storeValues" : "none",
- "trackListPositions" : false
- }
+ "user" : "admin@myapp",
+ "active" : true,
+ "extra" : {
},
- "globallyUniqueId" : "h4B0D1F61ADB6/69082",
- "name" : "productsView",
- "id" : "69082",
- "storedValues" : [ ],
- "primarySort" : [ ],
- "type" : "arangosearch"
+ "error" : false,
+ "code" : 200
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/productsView/properties
+shell> curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
+{
+ "passwd" : "secure"
+}
+EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 652
+content-length: 72
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -28695,80 +29029,101 @@ x-content-type-options: nosniff
+
+
@endDocuBlock
-
-@startDocuBlock get_api_views
+
+@startDocuBlock UserHandling_create
-@brief returns all Views
+@brief Create a new user.
-@RESTHEADER{GET /_api/view, List all Views, getViews:AllViews}
+@RESTHEADER{POST /_api/user, Create User}
+
+@RESTBODYPARAM{user,string,required,string}
+The name of the user as a string. This is mandatory.
+
+@RESTBODYPARAM{passwd,string,required,string}
+The user password as a string. If not specified, it will default to an empty
+string.
+
+@RESTBODYPARAM{active,boolean,optional,}
+An optional flag that specifies whether the user is active. If not
+specified, this will default to *true*.
+
+@RESTBODYPARAM{extra,object,optional,}
+A JSON object with extra user information. It is used by the web interface
+to store graph viewer settings and saved queries. Should not be set or
+modified by end users, as custom attributes will not be preserved.
@RESTDESCRIPTION
-Returns an object containing a listing of all Views in a database, regardless
-of their type. It is an array of objects with the following attributes:
-- *id*
-- *name*
-- *type*
+Create a new user. You need server access level *Administrate* in order to
+execute this REST call.
@RESTRETURNCODES
-@RESTRETURNCODE{200}
-The list of Views
+@RESTRETURNCODE{201}
+Returned if the user can be added by the server
-@EXAMPLES
+@RESTRETURNCODE{400}
+If the JSON representation is malformed or mandatory data is missing
+from the request.
-Return information about all Views:
+@RESTRETURNCODE{401}
+Returned if you have *No access* database access level to the *_system*
+database.
+@RESTRETURNCODE{403}
+Returned if you have *No access* server access level.
-
-
+@RESTRETURNCODE{409}
+Returned if a user with the same name already exists.
+
+@EXAMPLES
+
+
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user <<EOF
+{
+ "user" : "admin@example",
+ "passwd" : "secure"
+}
+EOF
-HTTP/1.1 200 OK
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 328
+content-length: 74
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
+ "user" : "admin@example",
+ "active" : true,
+ "extra" : {
+ },
"error" : false,
- "code" : 200,
- "result" : [
- {
- "globallyUniqueId" : "h4B0D1F61ADB6/101",
- "id" : "101",
- "name" : "demoView",
- "type" : "arangosearch"
- },
- {
- "globallyUniqueId" : "h4B0D1F61ADB6/69040",
- "id" : "69040",
- "name" : "productsView",
- "type" : "arangosearch"
- },
- {
- "globallyUniqueId" : "h4B0D1F61ADB6/69043",
- "id" : "69043",
- "name" : "reviewsView",
- "type" : "arangosearch"
- }
- ]
+ "code" : 201
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user <<EOF
+{
+ "user" : "admin@example",
+ "passwd" : "secure"
+}
+EOF
-HTTP/1.1 200 OK
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 328
+content-length: 74
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -28778,202 +29133,90 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-
-
-@startDocuBlock patch_api_view_properties_arangosearch
-
-@brief partially changes properties of an ArangoSearch View
-
-@RESTHEADER{PATCH /_api/view/{view-name}/properties#ArangoSearch, Partially changes properties of an ArangoSearch View, modifyViewPartial}
-
-@RESTURLPARAMETERS
-
-@RESTURLPARAM{view-name,string,required}
-The name of the View.
-@RESTBODYPARAM{links,object,optional,}
-Expects an object with the attribute keys being names of to be linked collections,
-and the link properties as attribute values. See
-[ArangoSearch View Link Properties](https://www.arangodb.com/docs/stable/arangosearch-views.html#link-properties)
-for details.
+@endDocuBlock
-@RESTBODYPARAM{cleanupIntervalStep,integer,optional,int64}
-Wait at least this many commits between removing unused files in the
-ArangoSearch data directory (default: 2, to disable use: 0).
-For the case where the consolidation policies merge segments often (i.e. a lot
-of commit+consolidate), a lower value will cause a lot of disk space to be
-wasted.
-For the case where the consolidation policies rarely merge segments (i.e. few
-inserts/deletes), a higher value will impact performance without any added
-benefits.
-_Background:_
- With every "commit" or "consolidate" operation a new state of the View
- internal data-structures is created on disk.
- Old states/snapshots are released once there are no longer any users
- remaining.
- However, the files for the released states/snapshots are left on disk, and
- only removed by "cleanup" operation.
-@RESTBODYPARAM{commitIntervalMsec,integer,optional,int64}
-Wait at least this many milliseconds between committing View data store
-changes and making documents visible to queries (default: 1000, to disable
-use: 0).
-For the case where there are a lot of inserts/updates, a lower value, until
-commit, will cause the index not to account for them and memory usage would
-continue to grow.
-For the case where there are a few inserts/updates, a higher value will impact
-performance and waste disk space for each commit call without any added
-benefits.
+@startDocuBlock UserHandling_grantDatabase
-_Background:_
- For data retrieval ArangoSearch Views follow the concept of
- "eventually-consistent", i.e. eventually all the data in ArangoDB will be
- matched by corresponding query expressions.
- The concept of ArangoSearch View "commit" operation is introduced to
- control the upper-bound on the time until document addition/removals are
- actually reflected by corresponding query expressions.
- Once a "commit" operation is complete all documents added/removed prior to
- the start of the "commit" operation will be reflected by queries invoked in
- subsequent ArangoDB transactions, in-progress ArangoDB transactions will
- still continue to return a repeatable-read state.
+@brief Set the database access level.
-@RESTBODYPARAM{consolidationIntervalMsec,integer,optional,int64}
-Wait at least this many milliseconds between applying 'consolidationPolicy' to
-consolidate View data store and possibly release space on the filesystem
-(default: 10000, to disable use: 0).
-For the case where there are a lot of data modification operations, a higher
-value could potentially have the data store consume more space and file handles.
-For the case where there are a few data modification operations, a lower value
-will impact performance due to no segment candidates available for
-consolidation.
+@RESTHEADER{PUT /_api/user/{user}/database/{dbname}, Set the database access level}
-_Background:_
- For data modification ArangoSearch Views follow the concept of a
- "versioned data store". Thus old versions of data may be removed once there
- are no longer any users of the old data. The frequency of the cleanup and
- compaction operations are governed by 'consolidationIntervalMsec' and the
- candidates for compaction are selected via 'consolidationPolicy'.
+@RESTBODYPARAM{grant,string,required,string}
+Use "rw" to set the database access level to *Administrate*.
+Use "ro" to set the database access level to *Access*.
+Use "none" to set the database access level to *No access*.
-@RESTBODYPARAM{consolidationPolicy,object,optional,}
-The consolidation policy to apply for selecting which segments should be merged
-(default: {})
+@RESTURLPARAMETERS
-_Background:_
- With each ArangoDB transaction that inserts documents one or more
- ArangoSearch internal segments gets created.
- Similarly for removed documents the segments that contain such documents
- will have these documents marked as 'deleted'.
- Over time this approach causes a lot of small and sparse segments to be
- created.
- A "consolidation" operation selects one or more segments and copies all of
- their valid documents into a single new segment, thereby allowing the
- search algorithm to perform more optimally and for extra file handles to be
- released once old segments are no longer used.
+@RESTURLPARAM{user,string,required}
+The name of the user.
-Sub-properties:
- - `type` (string, _optional_):
- The segment candidates for the "consolidation" operation are selected based
- upon several possible configurable formulas as defined by their types.
- The currently supported types are:
- - `"tier"` (default): consolidate based on segment byte size and live
- document count as dictated by the customization attributes. If this type
- is used, then below `segments*` and `minScore` properties are available.
- - `"bytes_accum"`: consolidate if and only if
- `{threshold} > (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes`
- i.e. the sum of all candidate segment byte size is less than the total
- segment byte size multiplied by the `{threshold}`. If this type is used,
- then below `threshold` property is available.
- - `threshold` (number, _optional_): value in the range `[0.0, 1.0]`
- - `segmentsBytesFloor` (number, _optional_): Defines the value (in bytes) to
- treat all smaller segments as equal for consolidation selection
- (default: 2097152)
- - `segmentsBytesMax` (number, _optional_): Maximum allowed size of all
- consolidated segments in bytes (default: 5368709120)
- - `segmentsMax` (number, _optional_): The maximum number of segments that will
- be evaluated as candidates for consolidation (default: 10)
- - `segmentsMin` (number, _optional_): The minimum number of segments that will
- be evaluated as candidates for consolidation (default: 1)
- - `minScore` (number, _optional_): (default: 0)
+@RESTURLPARAM{dbname,string,required}
+The name of the database.
@RESTDESCRIPTION
-Changes the properties of a View by updating the specified attributes.
-
-On success an object with the following attributes is returned:
-- *id*: The identifier of the View
-- *name*: The name of the View
-- *type*: The View type
-- all additional ArangoSearch View implementation specific properties
+Sets the database access levels for the database *dbname* of user *user*. You
+need the *Administrate* server access level in order to execute this REST
+call.
@RESTRETURNCODES
+@RESTRETURNCODE{200}
+Returned if the access level was changed successfully.
+
@RESTRETURNCODE{400}
-If the *view-name* is missing, then a *HTTP 400* is returned.
+If the JSON representation is malformed or mandatory data is missing
+from the request.
-@RESTRETURNCODE{404}
-If the *view-name* is unknown, then a *HTTP 404* is returned.
+@RESTRETURNCODE{401}
+Returned if you have *No access* database access level to the *_system*
+database.
+
+@RESTRETURNCODE{403}
+Returned if you have *No access* server access level.
@EXAMPLES
-
-
+
+
-shell> curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view/productsView/properties <<EOF
+shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp/database/_system <<EOF
{
- "locale" : "en"
+ "grant" : "rw"
}
EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 475
+content-length: 41
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "globallyUniqueId" : "h4B0D1F61ADB6/69094",
- "id" : "69094",
- "name" : "productsView",
- "type" : "arangosearch",
- "cleanupIntervalStep" : 2,
- "commitIntervalMsec" : 1000,
- "consolidationIntervalMsec" : 1000,
- "consolidationPolicy" : {
- "type" : "tier",
- "segmentsBytesFloor" : 2097152,
- "segmentsBytesMax" : 5368709120,
- "segmentsMax" : 10,
- "segmentsMin" : 1,
- "minScore" : 0
- },
- "primarySort" : [ ],
- "primarySortCompression" : "lz4",
- "storedValues" : [ ],
- "writebufferActive" : 0,
- "writebufferIdle" : 64,
- "writebufferSizeMax" : 33554432,
- "links" : {
- }
+ "_system" : "rw",
+ "error" : false,
+ "code" : 200
}
-
Hide response body
-
+
-shell> curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view/productsView/properties <<EOF
+shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp/database/_system <<EOF
{
- "locale" : "en"
+ "grant" : "rw"
}
EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 475
+content-length: 41
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -28983,296 +29226,170 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-@startDocuBlock post_api_view_arangosearch
+@endDocuBlock
-@brief creates an ArangoSearch View
-@RESTHEADER{POST /_api/view#arangosearch, Create an ArangoSearch View, createView}
-@RESTBODYPARAM{name,string,required,string}
-The name of the View.
+@startDocuBlock UserHandling_revokeDatabase
-@RESTBODYPARAM{type,string,required,string}
-The type of the View. Must be equal to *"arangosearch"*.
-This option is immutable.
+@brief Clear the database access level, revert back to the default access level
-@RESTBODYPARAM{links,object,optional,}
-Expects an object with the attribute keys being names of to be linked collections,
-and the link properties as attribute values. See
-[ArangoSearch View Link Properties](https://www.arangodb.com/docs/stable/arangosearch-views.html#link-properties)
-for details.
+@RESTHEADER{DELETE /_api/user/{user}/database/{dbname}, Clear the database access level}
-@RESTBODYPARAM{primarySort,array,optional,object}
-A primary sort order can be defined to enable an AQL optimization. If a query
-iterates over all documents of a View, wants to sort them by attribute values
-and the (left-most) fields to sort by as well as their sorting direction match
-with the `primarySort` definition, then the `SORT` operation is optimized away.
-This option is immutable.
+@RESTURLPARAMETERS
-Expects an array of objects, each specifying a field (attribute path) and a
-sort direction (`"asc` for ascending, `"desc"` for descending):
-`[ { "field": "attr", "direction": "asc"}, … ]`
+@RESTURLPARAM{user,string,required}
+The name of the user.
-@RESTBODYPARAM{primarySortCompression,string,optional,string}
-Defines how to compress the primary sort data (introduced in v3.7.1).
-ArangoDB v3.5 and v3.6 always compress the index using LZ4.
+@RESTURLPARAM{dbname,string,required}
+The name of the database.
-This option is immutable.
+@RESTDESCRIPTION
+Clears the database access level for the database *dbname* of user *user*. As
+consequence the default database access level is used. If there is no defined
+default database access level, it defaults to *No access*. You need permission
+to the *_system* database in order to execute this REST call.
-- `"lz4"` (default): use LZ4 fast compression.
-- `"none"`: disable compression to trade space for speed.
+@RESTRETURNCODES
-@RESTBODYPARAM{primarySortCache,boolean,optional,}
-If you enable this option, then the primary sort columns are always cached in
-memory (introduced in v3.9.6, Enterprise Edition only). This can improve the
-performance of queries that utilize the primary sort order. Otherwise, these
-values are memory-mapped and it is up to the operating system to load them from
-disk into memory and to evict them from memory.
+@RESTRETURNCODE{202}
+Returned if the access permissions were changed successfully.
-This option is immutable.
+@RESTRETURNCODE{400}
+If the JSON representation is malformed or mandatory data is missing
+from the request.
-See the `--arangosearch.columns-cache-limit` startup option to control the
-memory consumption of this cache.
+@EXAMPLES
-@RESTBODYPARAM{primaryKeyCache,boolean,optional,}
-If you enable this option, then the primary key columns are always cached in
-memory (introduced in v3.9.6, Enterprise Edition only). This can improve the
-performance of queries that return many documents. Otherwise, these values are
-memory-mapped and it is up to the operating system to load them from disk into
-memory and to evict them from memory.
-This option is immutable.
+
+
+
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/user/admin@myapp/database/_system
-See the `--arangosearch.columns-cache-limit` startup option to control the
-memory consumption of this cache.
+HTTP/1.1 202 Accepted
+content-type: application/json
+connection: Keep-Alive
+content-length: 26
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTBODYPARAM{storedValues,array,optional,object}
-An array of objects to describe which document attributes to store in the View
-index (introduced in v3.7.1). It can then cover search queries, which means the
-data can be taken from the index directly and accessing the storage engine can
-be avoided.
-
-This option is immutable.
+{
+ "error" : false,
+ "code" : 202
+}
+
+
Hide response body
+
+
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/user/admin@myapp/database/_system
-Each object is expected in the following form:
+HTTP/1.1 202 Accepted
+content-type: application/json
+connection: Keep-Alive
+content-length: 26
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
Show response body
+
+
-
+
+
-shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view <<EOF
+shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp/database/_system/reports <<EOF
{
- "name" : "products",
- "type" : "arangosearch"
+ "grant" : "rw"
}
EOF
-HTTP/1.1 201 Created
+HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 471
+content-length: 49
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "globallyUniqueId" : "h4B0D1F61ADB6/69100",
- "id" : "69100",
- "name" : "products",
- "type" : "arangosearch",
- "cleanupIntervalStep" : 2,
- "commitIntervalMsec" : 1000,
- "consolidationIntervalMsec" : 1000,
- "consolidationPolicy" : {
- "type" : "tier",
- "segmentsBytesFloor" : 2097152,
- "segmentsBytesMax" : 5368709120,
- "segmentsMax" : 10,
- "segmentsMin" : 1,
- "minScore" : 0
- },
- "primarySort" : [ ],
- "primarySortCompression" : "lz4",
- "storedValues" : [ ],
- "writebufferActive" : 0,
- "writebufferIdle" : 64,
- "writebufferSizeMax" : 33554432,
- "links" : {
- }
+ "_system/reports" : "rw",
+ "error" : false,
+ "code" : 200
}
-
Hide response body
-
+
-shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view <<EOF
+shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp/database/_system/reports <<EOF
{
- "name" : "products",
- "type" : "arangosearch"
+ "grant" : "rw"
}
EOF
-HTTP/1.1 201 Created
+HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 471
+content-length: 49
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -29281,202 +29398,75 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-
-
-@startDocuBlock put_api_view_properties_arangosearch
-
-@brief changes all properties of an ArangoSearch View
-
-@RESTHEADER{PUT /_api/view/{view-name}/properties#ArangoSearch, Change properties of an ArangoSearch View, modifyView}
-@RESTURLPARAMETERS
-@RESTURLPARAM{view-name,string,required}
-The name of the View.
-@RESTBODYPARAM{links,object,optional,}
-Expects an object with the attribute keys being names of to be linked collections,
-and the link properties as attribute values. See
-[ArangoSearch View Link Properties](https://www.arangodb.com/docs/stable/arangosearch-views.html#link-properties)
-for details.
+@endDocuBlock
-@RESTBODYPARAM{cleanupIntervalStep,integer,optional,int64}
-Wait at least this many commits between removing unused files in the
-ArangoSearch data directory (default: 2, to disable use: 0).
-For the case where the consolidation policies merge segments often (i.e. a lot
-of commit+consolidate), a lower value will cause a lot of disk space to be
-wasted.
-For the case where the consolidation policies rarely merge segments (i.e. few
-inserts/deletes), a higher value will impact performance without any added
-benefits.
-_Background:_
- With every "commit" or "consolidate" operation a new state of the View
- internal data-structures is created on disk.
- Old states/snapshots are released once there are no longer any users
- remaining.
- However, the files for the released states/snapshots are left on disk, and
- only removed by "cleanup" operation.
-@RESTBODYPARAM{commitIntervalMsec,integer,optional,int64}
-Wait at least this many milliseconds between committing View data store
-changes and making documents visible to queries (default: 1000, to disable
-use: 0).
-For the case where there are a lot of inserts/updates, a lower value, until
-commit, will cause the index not to account for them and memory usage would
-continue to grow.
-For the case where there are a few inserts/updates, a higher value will impact
-performance and waste disk space for each commit call without any added
-benefits.
+@startDocuBlock UserHandling_revokeCollection
-_Background:_
- For data retrieval ArangoSearch Views follow the concept of
- "eventually-consistent", i.e. eventually all the data in ArangoDB will be
- matched by corresponding query expressions.
- The concept of ArangoSearch View "commit" operation is introduced to
- control the upper-bound on the time until document addition/removals are
- actually reflected by corresponding query expressions.
- Once a "commit" operation is complete all documents added/removed prior to
- the start of the "commit" operation will be reflected by queries invoked in
- subsequent ArangoDB transactions, in-progress ArangoDB transactions will
- still continue to return a repeatable-read state.
+@brief Clear the collection access level, revert back to the default access level
-@RESTBODYPARAM{consolidationIntervalMsec,integer,optional,int64}
-Wait at least this many milliseconds between applying 'consolidationPolicy' to
-consolidate View data store and possibly release space on the filesystem
-(default: 10000, to disable use: 0).
-For the case where there are a lot of data modification operations, a higher
-value could potentially have the data store consume more space and file handles.
-For the case where there are a few data modification operations, a lower value
-will impact performance due to no segment candidates available for
-consolidation.
+@RESTHEADER{DELETE /_api/user/{user}/database/{dbname}/{collection}, Clear the collection access level}
-_Background:_
- For data modification ArangoSearch Views follow the concept of a
- "versioned data store". Thus old versions of data may be removed once there
- are no longer any users of the old data. The frequency of the cleanup and
- compaction operations are governed by 'consolidationIntervalMsec' and the
- candidates for compaction are selected via 'consolidationPolicy'.
+@RESTURLPARAMETERS
-@RESTBODYPARAM{consolidationPolicy,object,optional,}
-The consolidation policy to apply for selecting which segments should be merged
-(default: {})
+@RESTURLPARAM{user,string,required}
+The name of the user.
-_Background:_
- With each ArangoDB transaction that inserts documents one or more
- ArangoSearch internal segments gets created.
- Similarly for removed documents the segments that contain such documents
- will have these documents marked as 'deleted'.
- Over time this approach causes a lot of small and sparse segments to be
- created.
- A "consolidation" operation selects one or more segments and copies all of
- their valid documents into a single new segment, thereby allowing the
- search algorithm to perform more optimally and for extra file handles to be
- released once old segments are no longer used.
+@RESTURLPARAM{dbname,string,required}
+The name of the database.
-Sub-properties:
- - `type` (string, _optional_):
- The segment candidates for the "consolidation" operation are selected based
- upon several possible configurable formulas as defined by their types.
- The currently supported types are:
- - `"tier"` (default): consolidate based on segment byte size and live
- document count as dictated by the customization attributes. If this type
- is used, then below `segments*` and `minScore` properties are available.
- - `"bytes_accum"`: consolidate if and only if
- `{threshold} > (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes`
- i.e. the sum of all candidate segment byte size is less than the total
- segment byte size multiplied by the `{threshold}`. If this type is used,
- then below `threshold` property is available.
- - `threshold` (number, _optional_): value in the range `[0.0, 1.0]`
- - `segmentsBytesFloor` (number, _optional_): Defines the value (in bytes) to
- treat all smaller segments as equal for consolidation selection
- (default: 2097152)
- - `segmentsBytesMax` (number, _optional_): Maximum allowed size of all
- consolidated segments in bytes (default: 5368709120)
- - `segmentsMax` (number, _optional_): The maximum number of segments that will
- be evaluated as candidates for consolidation (default: 10)
- - `segmentsMin` (number, _optional_): The minimum number of segments that will
- be evaluated as candidates for consolidation (default: 1)
- - `minScore` (number, _optional_): (default: 0)
+@RESTURLPARAM{collection,string,required}
+The name of the collection.
@RESTDESCRIPTION
-Changes the properties of a View by replacing them.
-
-On success an object with the following attributes is returned:
-- *id*: The identifier of the View
-- *name*: The name of the View
-- *type*: The View type
-- all additional ArangoSearch View implementation specific properties
+Clears the collection access level for the collection *collection* in the
+database *dbname* of user *user*. As consequence the default collection
+access level is used. If there is no defined default collection access level,
+it defaults to *No access*. You need permissions to the *_system* database in
+order to execute this REST call.
@RESTRETURNCODES
-@RESTRETURNCODE{400}
-If the *view-name* is missing, then a *HTTP 400* is returned.
+@RESTRETURNCODE{202}
+Returned if the access permissions were changed successfully.
-@RESTRETURNCODE{404}
-If the *view-name* is unknown, then a *HTTP 404* is returned.
+@RESTRETURNCODE{400}
+If there was an error
@EXAMPLES
-
-
+
+
-shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view/productsView/properties <<EOF
-{
- "locale" : "en"
-}
-EOF
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/user/admin@myapp/database/_system/reports
-HTTP/1.1 200 OK
+HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
-content-length: 475
+content-length: 26
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "globallyUniqueId" : "h4B0D1F61ADB6/69105",
- "id" : "69105",
- "name" : "productsView",
- "type" : "arangosearch",
- "cleanupIntervalStep" : 2,
- "commitIntervalMsec" : 1000,
- "consolidationIntervalMsec" : 1000,
- "consolidationPolicy" : {
- "type" : "tier",
- "segmentsBytesFloor" : 2097152,
- "segmentsBytesMax" : 5368709120,
- "segmentsMax" : 10,
- "segmentsMin" : 1,
- "minScore" : 0
- },
- "primarySort" : [ ],
- "primarySortCompression" : "lz4",
- "storedValues" : [ ],
- "writebufferActive" : 0,
- "writebufferIdle" : 64,
- "writebufferSizeMax" : 33554432,
- "links" : {
- }
+ "error" : false,
+ "code" : 202
}
-
Hide response body
-
+
-shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view/productsView/properties <<EOF
-{
- "locale" : "en"
-}
-EOF
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/user/admin@myapp/database/_system/reports
-HTTP/1.1 200 OK
+HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
-content-length: 475
+content-length: 26
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -29486,56 +29476,67 @@ x-content-type-options: nosniff
+
+
@endDocuBlock
-
-@startDocuBlock put_api_view_rename
-@brief renames a View
+@startDocuBlock UserHandling_fetchDatabaseList
-@RESTHEADER{PUT /_api/view/{view-name}/rename, Rename a View, modifyView:rename}
+@brief List the accessible databases for a user
+
+@RESTHEADER{GET /_api/user/{user}/database/, List the accessible databases for a user}
@RESTURLPARAMETERS
-@RESTURLPARAM{view-name,string,required}
-The name of the View to rename.
+@RESTURLPARAM{user,string,required}
+The name of the user for which you want to query the databases.
+
+@RESTQUERYPARAMETERS
+
+@RESTQUERYPARAM{full,boolean,optional}
+Return the full set of access levels for all databases and all collections.
@RESTDESCRIPTION
-Renames a View. Expects an object with the attribute(s)
-- *name*: The new name
+Fetch the list of databases available to the specified *user*. You need
+*Administrate* for the server access level in order to execute this REST call.
-It returns an object with the attributes
-- *id*: The identifier of the View.
-- *name*: The new name of the View.
-- *type*: The View type.
+The call will return a JSON object with the per-database access
+privileges for the specified user. The *result* object will contain
+the databases names as object keys, and the associated privileges
+for the database as values.
-**Note**: This method is not available in a cluster.
+In case you specified *full*, the result will contain the permissions
+for the databases as well as the permissions for the collections.
@RESTRETURNCODES
+@RESTRETURNCODE{200}
+Returned if the list of available databases can be returned.
+
@RESTRETURNCODE{400}
-If the *view-name* is missing, then a *HTTP 400* is returned.
+If the access privileges are not right etc.
-@RESTRETURNCODE{404}
-If the *view-name* is unknown, then a *HTTP 404* is returned.
+@RESTRETURNCODE{401}
+Returned if you have *No access* database access level to the *_system*
+database.
+
+@RESTRETURNCODE{403}
+Returned if you have *No access* server access level.
@EXAMPLES
-
-
+
+
-shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view/productsView/rename <<EOF
-{
- "name" : "catalogView"
-}
-EOF
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 123
+content-length: 52
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -29543,25 +29544,20 @@ x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
- "type" : "arangosearch",
- "name" : "catalogView",
- "id" : "69112",
- "globallyUniqueId" : "h4B0D1F61ADB6/69112"
+ "result" : {
+ "_system" : "rw"
+ }
}
-
Hide response body
-
+
-shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view/productsView/rename <<EOF
-{
- "name" : "catalogView"
-}
-EOF
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 123
+content-length: 52
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -29571,64 +29567,67 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-
-@startDocuBlock delete_api_control_pregel_cancel
-@brief Cancel an ongoing Pregel execution
+With the full response format:
-@RESTHEADER{DELETE /_api/control_pregel/{id}, Cancel Pregel job execution}
-@RESTURLPARAMETERS
-
-@RESTURLPARAM{id,number,required}
-Pregel execution identifier.
-
-@RESTDESCRIPTION
-Cancel an execution which is still running, and discard any intermediate
-results. This will immediately free all memory taken up by the execution, and
-will make you lose all intermediary data.
-
-You might get inconsistent results if you requested to store the results and
-then cancel an execution when it is already in its `"storing"` state (or
-`"done"` state in versions prior to 3.7.1). The data is written multi-threaded
-into all collection shards at once. This means there are multiple transactions
-simultaneously. A transaction might already be committed when you cancel the
-execution job. Therefore, you might see some updated documents, while other
-documents have no or stale results from a previous execution.
-
-@RESTRETURNCODES
-
-@RESTRETURNCODE{200}
-HTTP 200 will be returned in case the job execution id was valid.
-
-@RESTRETURNCODE{404}
-An HTTP 404 error is returned if no Pregel job with the specified execution number
-is found or the execution number is invalid.
-
-@EXAMPLES
-
-Cancel a Pregel job to stop the execution or to free up the results if it was
-started with `"store": false` and is in the done state:
+
+
+
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database?full=true
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 457
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-
-
+{
+
"error" :
false,
+
"code" :
200,
+
"result" : {
+
"_system" : {
+
"permission" :
"rw",
+
"collections" : {
+
"animals" :
"undefined",
+
"_statistics" :
"undefined",
+
"demo" :
"undefined",
+
"_users" :
"undefined",
+
"_graphs" :
"undefined",
+
"_statistics15" :
"undefined",
+
"_statisticsRaw" :
"undefined",
+
"_analyzers" :
"undefined",
+
"_aqlfunctions" :
"undefined",
+
"_queues" :
"undefined",
+
"_jobs" :
"undefined",
+
"_apps" :
"undefined",
+
"_appbundles" :
"undefined",
+
"_frontend" :
"undefined",
+
"*" :
"undefined"
+ }
+ },
+
"*" : {
+
"permission" :
"none"
+ }
+ }
+}
+
+
Hide response body
+
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/control_pregel/68547
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database?full=true
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 2
+content-length: 457
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-
-""
-
+
Show response body
+
+
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system
-
-@startDocuBlock get_api_control_pregel_status
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 40
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@brief Get the status of a Pregel execution
+{
+ "error" : false,
+ "code" : 200,
+ "result" : "rw"
+}
+
+
Hide response body
+
+
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system
-@RESTHEADER{GET /_api/control_pregel/{id}, Get Pregel job execution status}
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 40
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
-
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/control_pregel/68842
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system/_users
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 397
+content-length: 42
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "id" : "68842",
- "database" : "_system",
- "algorithm" : "WCC",
- "created" : "2023-06-24T15:42:52Z",
- "expires" : "2023-06-24T15:52:52Z",
- "ttl" : 600,
- "state" : "done",
- "gss" : 11,
- "totalRuntime" : 0.0023889541625976562,
- "startupTime" : 0.0005812644958496094,
- "computationTime" : 0.0007395744323730469,
- "storageTime" : 0.001069784164428711,
- "aggregators" : {
- },
- "sendCount" : 370,
- "receivedCount" : 370,
- "reports" : [ ],
- "vertexCount" : 36,
- "edgeCount" : 36
+ "error" : false,
+ "code" : 200,
+ "result" : "none"
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/control_pregel/68842
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system/_users
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 397
+content-length: 42
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -29848,124 +29794,103 @@ x-content-type-options: nosniff
-
-
@endDocuBlock
-
-@startDocuBlock post_api_control_pregel_start
-
-@brief Start the execution of a Pregel algorithm
-
-@RESTHEADER{POST /_api/control_pregel, Start Pregel job execution}
-
-@RESTBODYPARAM{algorithm,string,required,string}
-Name of the algorithm. One of:
-- `"pagerank"` - Page Rank
-- `"sssp"` - Single-Source Shortest Path
-- `"connectedcomponents"` - Connected Components
-- `"wcc"` - Weakly Connected Components
-- `"scc"` - Strongly Connected Components
-- `"hits"` - Hyperlink-Induced Topic Search
-- `"effectivecloseness"` - Effective Closeness
-- `"linerank"` - LineRank
-- `"labelpropagation"` - Label Propagation
-- `"slpa"` - Speaker-Listener Label Propagation
-@RESTBODYPARAM{graphName,string,optional,string}
-Name of a graph. Either this or the parameters `vertexCollections` and
-`edgeCollections` are required.
-Please note that there are special sharding requirements for graphs in order
-to be used with Pregel.
+@startDocuBlock UserHandling_replace
-@RESTBODYPARAM{vertexCollections,array,optional,string}
-List of vertex collection names.
-Please note that there are special sharding requirements for collections in order
-to be used with Pregel.
+@brief Replace an existing user.
-@RESTBODYPARAM{edgeCollections,array,optional,string}
-List of edge collection names.
-Please note that there are special sharding requirements for collections in order
-to be used with Pregel.
+@RESTHEADER{PUT /_api/user/{user}, Replace User}
-@RESTBODYPARAM{params,object,optional,}
-General as well as algorithm-specific options.
+@RESTURLPARAMETERS
-The most important general option is "store", which controls whether the results
-computed by the Pregel job are written back into the source collections or not.
+@RESTURLPARAM{user,string,required}
+The name of the user.
-Another important general option is "parallelism", which controls the number of
-parallel threads that will work on the Pregel job at most. If "parallelism" is not
-specified, a default value may be used. In addition, the value of "parallelism"
-may be effectively capped at some server-specific value.
+@RESTBODYPARAM{passwd,string,required,string}
+The user password as a string. If not specified, it will default to an empty
+string.
-The option "useMemoryMaps" controls whether to use disk based files to store
-temporary results. This might make the computation disk-bound, but allows you to
-run computations which would not fit into main memory. It is recommended to set
-this flag for larger datasets.
+@RESTBODYPARAM{active,boolean,optional,}
+An optional flag that specifies whether the user is active. If not
+specified, this will default to *true*.
-The attribute "shardKeyAttribute" specifies the shard key that edge collections are
-sharded after (default: `"vertex"`).
+@RESTBODYPARAM{extra,object,optional,}
+A JSON object with extra user information. It is used by the web interface
+to store graph viewer settings and saved queries. Should not be set or
+modified by end users, as custom attributes will not be preserved.
@RESTDESCRIPTION
-To start an execution you need to specify the algorithm name and a named graph
-(SmartGraph in cluster). Alternatively you can specify the vertex and edge
-collections. Additionally you can specify custom parameters which vary for each
-algorithm, see [Pregel - Available Algorithms](https://www.arangodb.com/docs/stable/graphs-pregel.html#available-algorithms).
+Replaces the data of an existing user. You need server access level
+*Administrate* in order to execute this REST call. Additionally, a user can
+change his/her own data.
@RESTRETURNCODES
@RESTRETURNCODE{200}
-HTTP 200 is returned in case the Pregel was successfully created and the reply
-body is a string with the `id` to query for the status or to cancel the
-execution.
+Is returned if the user data can be replaced by the server.
@RESTRETURNCODE{400}
-An HTTP 400 error is returned if the set of collections for the Pregel job includes
-a system collection, or if the collections to not conform to the sharding requirements
-for Pregel jobs.
+The JSON representation is malformed or mandatory data is missing from the request
-@RESTRETURNCODE{403}
-An HTTP 403 error is returned if there are not sufficient privileges to access
-the collections specified for the Pregel job.
+@RESTRETURNCODE{401}
+Returned if you have *No access* database access level to the *_system*
+database.
+@RESTRETURNCODE{403}
+Returned if you have *No access* server access level.
@RESTRETURNCODE{404}
-An HTTP 404 error is returned if the specified "algorithm" is not found, or the
-graph specified in "graphName" is not found, or at least one the collections
-specified in "vertexCollections" or "edgeCollections" is not found.
+The specified user does not exist
@EXAMPLES
-Run the Weakly Connected Components (WCC) algorithm against a graph and store
-the results in the vertices as attribute `component`:
-
-
-
+
+
-shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/control_pregel <<EOF
+shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
{
- "algorithm" : "wcc",
- "graphName" : "connectedComponentsGraph",
- "params" : {
- "maxGSS" : 36,
- "resultField" : "component"
- }
+ "passwd" : "secure"
}
EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 7
+content-length: 72
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-"68694"
+{
+ "user" : "admin@myapp",
+ "active" : true,
+ "extra" : {
+ },
+ "error" : false,
+ "code" : 200
+}
+
Hide response body
+
+
+shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
+{
+ "passwd" : "secure"
+}
+EOF
+
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 72
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
@@ -29973,773 +29898,951 @@ x-content-type-options: nosniff
-
-
-
@endDocuBlock
-
-@startDocuBlock DeleteApiQueryCache
-
-@brief clears the AQL query results cache
-
-@RESTHEADER{DELETE /_api/query-cache, Clears any results in the AQL query results cache, clearCache}
-
-@RESTDESCRIPTION
-clears the query results cache for the current database
-@RESTRETURNCODES
-@RESTRETURNCODE{200}
-The server will respond with *HTTP 200* when the cache was cleared
-successfully.
+@startDocuBlock UserHandling_modify
-@RESTRETURNCODE{400}
-The server will respond with *HTTP 400* in case of a malformed request.
-@endDocuBlock
+@brief Modify attributes of an existing user
+@RESTHEADER{PATCH /_api/user/{user}, Modify User}
-
-@startDocuBlock DeleteApiQueryKill
+@RESTURLPARAMETERS
-@brief kills an AQL query
+@RESTURLPARAM{user,string,required}
+The name of the user.
-@RESTHEADER{DELETE /_api/query/{query-id}, Kills a running AQL query, deleteQuery}
+@RESTBODYPARAM{passwd,string,required,string}
+The user password as a string.
-@RESTURLPARAMETERS
+@RESTBODYPARAM{active,boolean,optional,}
+An optional flag that specifies whether the user is active.
-@RESTURLPARAM{query-id,string,required}
-The id of the query.
+@RESTBODYPARAM{extra,object,optional,}
+A JSON object with extra user information. It is used by the web interface
+to store graph viewer settings and saved queries. Should not be set or
+modified by end users, as custom attributes will not be preserved.
@RESTDESCRIPTION
-Kills a running query in the currently selected database. The query will be
-terminated at the next cancelation point.
-
-@RESTQUERYPARAMETERS
-
-@RESTQUERYPARAM{all,boolean,optional}
-If set to *true*, will attempt to kill the specified query in all databases,
-not just the selected one.
-Using the parameter is only allowed in the system database and with superuser
-privileges.
+Partially updates the data of an existing user. You need server access level
+*Administrate* in order to execute this REST call. Additionally, a user can
+change his/her own data.
@RESTRETURNCODES
@RESTRETURNCODE{200}
-The server will respond with *HTTP 200* when the query was still running when
-the kill request was executed and the query's kill flag was set.
+Is returned if the user data can be replaced by the server.
@RESTRETURNCODE{400}
-The server will respond with *HTTP 400* in case of a malformed request.
+The JSON representation is malformed or mandatory data is missing from the request.
+
+@RESTRETURNCODE{401}
+Returned if you have *No access* database access level to the *_system*
+database.
@RESTRETURNCODE{403}
-*HTTP 403* is returned in case the *all* parameter was used, but the request
-was made in a different database than _system, or by an non-privileged user.
+Returned if you have *No access* server access level.
@RESTRETURNCODE{404}
-The server will respond with *HTTP 404* when no query with the specified
-id was found.
-@endDocuBlock
-
+The specified user does not exist
-
-@startDocuBlock DeleteApiQuerySlow
+@EXAMPLES
-@brief clears the list of slow AQL queries
-@RESTHEADER{DELETE /_api/query/slow, Clears the list of slow AQL queries, deleteSlowQueries}
+
+
+
+shell> curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
+{
+ "passwd" : "secure"
+}
+EOF
-@RESTDESCRIPTION
-Clears the list of slow AQL queries in the currently selected database
-
-@RESTQUERYPARAMETERS
-
-@RESTQUERYPARAM{all,boolean,optional}
-If set to *true*, will clear the slow query history in all databases, not just
-the selected one.
-Using the parameter is only allowed in the system database and with superuser
-privileges.
-
-@RESTRETURNCODES
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 72
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTRETURNCODE{200}
-The server will respond with *HTTP 200* when the list of queries was
-cleared successfully.
+{
+ "user" : "admin@myapp",
+ "active" : true,
+ "extra" : {
+ },
+ "error" : false,
+ "code" : 200
+}
+
+
Hide response body
+
+
+shell> curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/admin@myapp <<EOF
+{
+ "passwd" : "secure"
+}
+EOF
-@RESTRETURNCODE{400}
-The server will respond with *HTTP 400* in case of a malformed request.
-@endDocuBlock
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 72
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
-
-@startDocuBlock GetApiQueryCacheCurrent
-@brief returns a list of the stored results in the AQL query results cache
-@RESTHEADER{GET /_api/query-cache/entries, Returns the currently cached query results, readQueries}
-@RESTDESCRIPTION
-Returns an array containing the AQL query results currently stored in the query results
-cache of the selected database. Each result is a JSON object with the following attributes:
+@endDocuBlock
-- *hash*: the query result's hash
-- *query*: the query string
+@endDocuBlock
-- *bindVars*: the query's bind parameters. this attribute is only shown if tracking for
- bind variables was enabled at server start
-- *size*: the size of the query result and bind parameters, in bytes
+
+@startDocuBlock UserHandling_delete
-- *results*: number of documents/rows in the query result
+@brief delete a user permanently.
-- *started*: the date and time when the query was stored in the cache
+@RESTHEADER{DELETE /_api/user/{user}, Remove User}
-- *hits*: number of times the result was served from the cache (can be
- *0* for queries that were only stored in the cache but were never accessed
- again afterwards)
+@RESTURLPARAMETERS
-- *runTime*: the query's run time
+@RESTURLPARAM{user,string,required}
+The name of the user
-- *dataSources*: an array of collections/Views the query was using
+@RESTDESCRIPTION
+Removes an existing user, identified by *user*. You need *Administrate* for
+the server access level in order to execute this REST call.
@RESTRETURNCODES
-@RESTRETURNCODE{200}
-Is returned when the list of results can be retrieved successfully.
+@RESTRETURNCODE{202}
+Is returned if the user was removed by the server
-@RESTRETURNCODE{400}
-The server will respond with *HTTP 400* in case of a malformed request,
+@RESTRETURNCODE{401}
+Returned if you have *No access* database access level to the *_system*
+database.
-@endDocuBlock
+@RESTRETURNCODE{403}
+Returned if you have *No access* server access level.
+@RESTRETURNCODE{404}
+The specified user does not exist
-
-@startDocuBlock GetApiQueryCacheProperties
+@EXAMPLES
-@brief returns the global configuration for the AQL query results cache
-@RESTHEADER{GET /_api/query-cache/properties, Returns the global properties for the AQL query results cache, readProperties}
+
+
+
+shell> curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/userToDelete@myapp <<EOF
+{
+}
+EOF
-@RESTDESCRIPTION
-Returns the global AQL query results cache configuration. The configuration is a
-JSON object with the following properties:
+HTTP/1.1 202 Accepted
+content-type: application/json
+connection: Keep-Alive
+content-length: 26
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-- *mode*: the mode the AQL query results cache operates in. The mode is one of the following
- values: *off*, *on* or *demand*.
+{
+ "error" : false,
+ "code" : 202
+}
+
+
Hide response body
+
+
+shell> curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/user/userToDelete@myapp <<EOF
+{
+}
+EOF
-- *maxResults*: the maximum number of query results that will be stored per database-specific
- cache.
+HTTP/1.1 202 Accepted
+content-type: application/json
+connection: Keep-Alive
+content-length: 26
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
-- *maxResultsSize*: the maximum cumulated size of query results that will be stored per
- database-specific cache.
-- *maxEntrySize*: the maximum individual result size of queries that will be stored per
- database-specific cache.
-- *includeSystem*: whether or not results of queries that involve system collections will be
- stored in the query results cache.
-@RESTRETURNCODES
-@RESTRETURNCODE{200}
-Is returned if the properties can be retrieved successfully.
+@endDocuBlock
-@RESTRETURNCODE{400}
-The server will respond with *HTTP 400* in case of a malformed request,
-@endDocuBlock
+
+@startDocuBlock UserHandling_fetch
+@brief fetch the properties of a user.
-
-@startDocuBlock GetApiQueryCurrent
+@RESTHEADER{GET /_api/user/{user}, Fetch User}
-@brief returns a list of currently running AQL queries
+@RESTURLPARAMETERS
-@RESTHEADER{GET /_api/query/current, Returns the currently running AQL queries, readQuery:current}
+@RESTURLPARAM{user,string,required}
+The name of the user
@RESTDESCRIPTION
-Returns an array containing the AQL queries currently running in the selected
-database. Each query is a JSON object with the following attributes:
+Fetches data about the specified user. You can fetch information about
+yourself or you need the *Administrate* server access level in order to
+execute this REST call.
-- *id*: the query's id
+@RESTRETURNCODES
-- *database*: the name of the database the query runs in
+@RESTRETURNCODE{200}
+The user was found.
-- *user*: the name of the user that started the query
+@RESTRETURNCODE{401}
+Returned if you have *No access* database access level to the *_system*
+database.
-- *query*: the query string (potentially truncated)
+@RESTRETURNCODE{403}
+Returned if you have *No access* server access level.
-- *bindVars*: the bind parameter values used by the query
+@RESTRETURNCODE{404}
+The user with the specified name does not exist.
-- *started*: the date and time when the query was started
+@EXAMPLES
-- *runTime*: the query's run time up to the point the list of queries was
- queried
-- *state*: the query's current execution state (as a string). One of:
- - `"initializing"`
- - `"parsing"`
- - `"optimizing ast"`
- - `"loading collections"`
- - `"instantiating plan"`
- - `"optimizing plan"`
- - `"executing"`
- - `"finalizing"`
- - `"finished"`
- - `"killed"`
- - `"invalid"`
+
+
+
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/admin@myapp
-- *stream*: whether or not the query uses a streaming cursor
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 72
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTQUERYPARAMETERS
+{
+ "user" : "admin@myapp",
+ "active" : true,
+ "extra" : {
+ },
+ "error" : false,
+ "code" : 200
+}
+
+
Hide response body
+
+
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user/admin@myapp
-@RESTQUERYPARAM{all,boolean,optional}
-If set to *true*, will return the currently running queries in all databases,
-not just the selected one.
-Using the parameter is only allowed in the system database and with superuser
-privileges.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 72
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
-@RESTRETURNCODES
-@RESTRETURNCODE{200}
-Is returned when the list of queries can be retrieved successfully.
-@RESTRETURNCODE{400}
-The server will respond with *HTTP 400* in case of a malformed request,
-@RESTRETURNCODE{403}
-*HTTP 403* is returned in case the *all* parameter was used, but the request
-was made in a different database than _system, or by an non-privileged user.
@endDocuBlock
-
-@startDocuBlock GetApiQueryProperties
+
+@startDocuBlock UserHandling_fetchProperties
-@brief returns the configuration for the AQL query tracking
+@brief fetch the properties of a user.
-@RESTHEADER{GET /_api/query/properties, Returns the properties for the AQL query tracking, readQueryProperties}
+@RESTHEADER{GET /_api/user/, List available Users}
@RESTDESCRIPTION
-Returns the current query tracking configuration. The configuration is a
-JSON object with the following properties:
+Fetches data about all users. You need the *Administrate* server access level
+in order to execute this REST call. Otherwise, you will only get information
+about yourself.
-- *enabled*: if set to *true*, then queries will be tracked. If set to
- *false*, neither queries nor slow queries will be tracked.
+The call will return a JSON object with at least the following
+attributes on success:
-- *trackSlowQueries*: if set to *true*, then slow queries will be tracked
- in the list of slow queries if their runtime exceeds the value set in
- *slowQueryThreshold*. In order for slow queries to be tracked, the *enabled*
- property must also be set to *true*.
+- *user*: The name of the user as a string.
+- *active*: An optional flag that specifies whether the user is active.
+- *extra*: A JSON object with extra user information. It is used by the web
+ interface to store graph viewer settings and saved queries.
-- *trackBindVars*: if set to *true*, then bind variables used in queries will
- be tracked.
+@RESTRETURNCODES
-- *maxSlowQueries*: the maximum number of slow queries to keep in the list
- of slow queries. If the list of slow queries is full, the oldest entry in
- it will be discarded when additional slow queries occur.
+@RESTRETURNCODE{200}
+The users that were found.
-- *slowQueryThreshold*: the threshold value for treating a query as slow. A
- query with a runtime greater or equal to this threshold value will be
- put into the list of slow queries when slow query tracking is enabled.
- The value for *slowQueryThreshold* is specified in seconds.
+@RESTRETURNCODE{401}
+Returned if you have *No access* database access level to the *_system*
+database.
-- *maxQueryStringLength*: the maximum query string length to keep in the
- list of queries. Query strings can have arbitrary lengths, and this property
- can be used to save memory in case very long query strings are used. The
- value is specified in bytes.
+@RESTRETURNCODE{403}
+Returned if you have *No access* server access level.
-@RESTRETURNCODES
+@EXAMPLES
-@RESTRETURNCODE{200}
-Is returned if properties were retrieved successfully.
-@RESTRETURNCODE{400}
-The server will respond with *HTTP 400* in case of a malformed request,
+
+
+
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user
-@endDocuBlock
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 164
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+{
+ "error" : false,
+ "code" : 200,
+ "result" : [
+ {
+ "user" : "tester",
+ "active" : false,
+ "extra" : {
+ }
+ },
+ {
+ "user" : "admin",
+ "active" : true,
+ "extra" : {
+ }
+ },
+ {
+ "user" : "root",
+ "active" : true,
+ "extra" : {
+ }
+ }
+ ]
+}
+
+
Hide response body
+
+
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/user
-
-@startDocuBlock GetApiQuerySlow
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 164
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
Show response body
+
+
-@brief returns a list of slow running AQL queries
-@RESTHEADER{GET /_api/query/slow, Returns the list of slow AQL queries, readQuery:Slow}
-@RESTDESCRIPTION
-Returns an array containing the last AQL queries that are finished and
-have exceeded the slow query threshold in the selected database.
-The maximum amount of queries in the list can be controlled by setting
-the query tracking property `maxSlowQueries`. The threshold for treating
-a query as *slow* can be adjusted by setting the query tracking property
-`slowQueryThreshold`.
-Each query is a JSON object with the following attributes:
+@endDocuBlock
-- *id*: the query's id
-- *database*: the name of the database the query runs in
+
+@startDocuBlock batch_processing
-- *user*: the name of the user that started the query
+@brief executes a batch request
-- *query*: the query string (potentially truncated)
+@RESTHEADER{POST /_api/batch,executes a batch request, RestBatchHandler}
-- *bindVars*: the bind parameter values used by the query
+@RESTALLBODYPARAM{body,string,required}
+The multipart batch request, consisting of the envelope and the individual
+batch parts.
-- *started*: the date and time when the query was started
+@RESTDESCRIPTION
+Executes a batch request. A batch request can contain any number of
+other requests that can be sent to ArangoDB in isolation. The benefit of
+using batch requests is that batching requests requires less client/server
+roundtrips than when sending isolated requests.
-- *runTime*: the query's total run time
+All parts of a batch request are executed serially on the server. The
+server will return the results of all parts in a single response when all
+parts are finished.
-- *state*: the query's current execution state (will always be "finished"
- for the list of slow queries)
+Technically, a batch request is a multipart HTTP request, with
+content-type `multipart/form-data`. A batch request consists of an
+envelope and the individual batch part actions. Batch part actions
+are "regular" HTTP requests, including full header and an optional body.
+Multiple batch parts are separated by a boundary identifier. The
+boundary identifier is declared in the batch envelope. The MIME content-type
+for each individual batch part must be `application/x-arango-batchpart`.
-- *stream*: whether or not the query uses a streaming cursor
+Please note that when constructing the individual batch parts, you must
+use CRLF (`\r\n`) as the line terminator as in regular HTTP messages.
-@RESTQUERYPARAMETERS
+The response sent by the server will be an `HTTP 200` response, with an
+optional error summary header `x-arango-errors`. This header contains the
+number of batch part operations that failed with an HTTP error code of at
+least 400. This header is only present in the response if the number of
+errors is greater than zero.
-@RESTQUERYPARAM{all,boolean,optional}
-If set to *true*, will return the slow queries from all databases, not just
-the selected one.
-Using the parameter is only allowed in the system database and with superuser
-privileges.
+The response sent by the server is a multipart response, too. It contains
+the individual HTTP responses for all batch parts, including the full HTTP
+result header (with status code and other potential headers) and an
+optional result body. The individual batch parts in the result are
+seperated using the same boundary value as specified in the request.
+
+The order of batch parts in the response will be the same as in the
+original client request. Client can additionally use the `Content-Id`
+MIME header in a batch part to define an individual id for each batch part.
+The server will return this id is the batch part responses, too.
@RESTRETURNCODES
@RESTRETURNCODE{200}
-Is returned when the list of queries can be retrieved successfully.
+is returned if the batch was received successfully. HTTP 200 is returned
+even if one or multiple batch part actions failed.
@RESTRETURNCODE{400}
-The server will respond with *HTTP 400* in case of a malformed request,
+is returned if the batch envelope is malformed or incorrectly formatted.
+This code will also be returned if the content-type of the overall batch
+request or the individual MIME parts is not as expected.
-@RESTRETURNCODE{403}
-*HTTP 403* is returned in case the *all* parameter was used, but the request
-was made in a different database than _system, or by an non-privileged user.
+@RESTRETURNCODE{405}
+is returned when an invalid HTTP method is used.
-@endDocuBlock
+@EXAMPLES
+Sending a batch request with five batch parts:
-
-@startDocuBlock PostApiQueryProperties
+- GET /_api/version
-@brief parse an AQL query and return information about it
+- DELETE /_api/collection/products
-@RESTHEADER{POST /_api/query, Parse an AQL query, parseQuery}
+- POST /_api/collection/products
-@RESTDESCRIPTION
-This endpoint is for query validation only. To actually query the database,
-see `/api/cursor`.
+- GET /_api/collection/products/figures
-@RESTBODYPARAM{query,string,required,string}
-To validate a query string without executing it, the query string can be
-passed to the server via an HTTP POST request.
+- DELETE /_api/collection/products
-@RESTRETURNCODES
+The boundary (`SomeBoundaryValue`) is passed to the server in the HTTP
+`Content-Type` HTTP header.
+*Please note the reply is not displayed all accurate.*
-@RESTRETURNCODE{200}
-If the query is valid, the server will respond with *HTTP 200* and
-return the names of the bind parameters it found in the query (if any) in
-the *bindVars* attribute of the response. It will also return an array
-of the collections used in the query in the *collections* attribute.
-If a query can be parsed successfully, the *ast* attribute of the returned
-JSON will contain the abstract syntax tree representation of the query.
-The format of the *ast* is subject to change in future versions of
-ArangoDB, but it can be used to inspect how ArangoDB interprets a given
-query. Note that the abstract syntax tree will be returned without any
-optimizations applied to it.
-@RESTRETURNCODE{400}
-The server will respond with *HTTP 400* in case of a malformed request,
-or if the query contains a parse error. The body of the response will
-contain the error details embedded in a JSON object.
+
-@RESTBODYPARAM{trackSlowQueries,boolean,required,}
-If set to *true*, then slow queries will be tracked
-in the list of slow queries if their runtime exceeds the value set in
-*slowQueryThreshold*. In order for slow queries to be tracked, the *enabled*
-property must also be set to *true*.
-@RESTBODYPARAM{trackBindVars,boolean,required,}
-If set to *true*, then the bind variables used in queries will be tracked
-along with queries.
-@RESTBODYPARAM{maxSlowQueries,integer,required,int64}
-The maximum number of slow queries to keep in the list
-of slow queries. If the list of slow queries is full, the oldest entry in
-it will be discarded when additional slow queries occur.
-@RESTBODYPARAM{slowQueryThreshold,integer,required,int64}
-The threshold value for treating a query as slow. A
-query with a runtime greater or equal to this threshold value will be
-put into the list of slow queries when slow query tracking is enabled.
-The value for *slowQueryThreshold* is specified in seconds.
-@RESTBODYPARAM{maxQueryStringLength,integer,required,int64}
-The maximum query string length to keep in the list of queries.
-Query strings can have arbitrary lengths, and this property
-can be used to save memory in case very long query strings are used. The
-value is specified in bytes.
-@RESTDESCRIPTION
-The properties need to be passed in the attribute *properties* in the body
-of the HTTP request. *properties* needs to be a JSON object.
-After the properties have been changed, the current set of properties will
-be returned in the HTTP response.
-@RESTRETURNCODES
-@RESTRETURNCODE{200}
-Is returned if the properties were changed successfully.
+Sending a batch request, setting the boundary implicitly (the server will
+in this case try to find the boundary at the beginning of the request body).
-@RESTRETURNCODE{400}
-The server will respond with *HTTP 400* in case of a malformed request,
-@endDocuBlock
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/batch <<EOF
+--SomeBoundaryValue
+Content-Type: application/x-arango-batchpart
+DELETE /_api/collection/notexisting1 HTTP/1.1
-
-@startDocuBlock delete_api_aqlfunction
+--SomeBoundaryValue
+Content-Type: application/x-arango-batchpart
-@brief remove an existing AQL user function
+DELETE _api/collection/notexisting2 HTTP/1.1
+--SomeBoundaryValue--
-@RESTHEADER{DELETE /_api/aqlfunction/{name}, Remove existing AQL user function, RestAqlUserFunctionsHandler:Remove}
+EOF
-@RESTURLPARAMETERS
+HTTP/1.1 200 OK
+content-type: unset
+connection: Keep-Alive
+content-length: 598
+server: ArangoDB
+x-arango-errors: 2
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTURLPARAM{name,string,required}
-the name of the AQL user function.
+--SomeBoundaryValue
+Content-Type: application/x-arango-batchpart
-@RESTQUERYPARAMETERS
+HTTP/1.1 404 Not Found
+Server:
+Connection: Close
+Content-Type: application/json; charset=utf-8
+Content-Length: 87
-@RESTQUERYPARAM{group,string,optional}
-- *true*: The function name provided in *name* is treated as
- a namespace prefix, and all functions in the specified namespace will be deleted.
- The returned number of deleted functions may become 0 if none matches the string.
-- *false*: The function name provided in *name* must be fully
- qualified, including any namespaces. If none matches the *name*, HTTP 404 is returned.
+{
+ "code" : 404,
+ "error" : true,
+ "errorMessage" : "collection or view not found",
+ "errorNum" : 1203
+}↩
-@RESTDESCRIPTION
-Removes an existing AQL user function or function group, identified by *name*.
+--SomeBoundaryValue
+Content-Type: application/x-arango-batchpart
-@RESTRETURNCODES
+HTTP/1.1 404 Not Found
+Server:
+Connection: Close
+Content-Type: application/json; charset=utf-8
+Content-Length: 101
-@RESTRETURNCODE{200}
-If the function can be removed by the server, the server will respond with
-*HTTP 200*.
+{
+ "error" : true,
+ "code" : 404,
+ "errorNum" : 404,
+ "errorMessage" : "unknown path '_api/collection/notexisting2'"
+}↩
-@RESTREPLYBODY{error,boolean,required,}
-boolean flag to indicate whether an error occurred (*false* in this case)
+--SomeBoundaryValue--
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/batch <<EOF
+--SomeBoundaryValue
+Content-Type: application/x-arango-batchpart
-@RESTREPLYBODY{code,integer,required,int64}
-the HTTP status code
+DELETE /_api/collection/notexisting1 HTTP/1.1
-@RESTREPLYBODY{deletedCount,integer,required,int64}
-The number of deleted user functions, always `1` when `group` is set to *false*.
-Any number `>= 0` when `group` is set to *true*
+--SomeBoundaryValue
+Content-Type: application/x-arango-batchpart
-@RESTRETURNCODE{400}
-If the user function name is malformed, the server will respond with *HTTP 400*.
+DELETE _api/collection/notexisting2 HTTP/1.1
+--SomeBoundaryValue--
-@RESTREPLYBODY{error,boolean,required,}
-boolean flag to indicate whether an error occurred (*true* in this case)
+EOF
-@RESTREPLYBODY{code,integer,required,int64}
-the HTTP status code
+HTTP/1.1 200 OK
+content-type: unset
+connection: Keep-Alive
+content-length: 598
+server: ArangoDB
+x-arango-errors: 2
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
-@RESTREPLYBODY{errorNum,integer,required,int64}
-the server error number
-@RESTREPLYBODY{errorMessage,string,required,string}
-a descriptive error message
-@RESTRETURNCODE{404}
-If the specified user user function does not exist, the server will respond with *HTTP 404*.
-@RESTREPLYBODY{error,boolean,required,}
-boolean flag to indicate whether an error occurred (*true* in this case)
+@endDocuBlock
-@RESTREPLYBODY{code,integer,required,int64}
-the HTTP status code
-@RESTREPLYBODY{errorNum,integer,required,int64}
-the server error number
+
+@startDocuBlock import_document
-@RESTREPLYBODY{errorMessage,string,required,string}
-a descriptive error message
+@brief imports documents from JSON-encoded lists
-@EXAMPLES
+@RESTHEADER{POST /_api/import#document,imports document values, RestImportHandler#document}
-deletes a function:
+@RESTALLBODYPARAM{documents,string,required}
+The body must consist of JSON-encoded arrays of attribute values, with one
+line per document. The first row of the request must be a JSON-encoded
+array of attribute names. These attribute names are used for the data in the
+subsequent lines.
+@RESTQUERYPARAMETERS
-
-
+@RESTQUERYPARAM{collection,string,required}
+The collection name.
+
+@RESTQUERYPARAM{fromPrefix,string,optional}
+An optional prefix for the values in `_from` attributes. If specified, the
+value is automatically prepended to each `_from` input value. This allows
+specifying just the keys for `_from`.
+
+@RESTQUERYPARAM{toPrefix,string,optional}
+An optional prefix for the values in `_to` attributes. If specified, the
+value is automatically prepended to each `_to` input value. This allows
+specifying just the keys for `_to`.
+
+@RESTQUERYPARAM{overwrite,boolean,optional}
+If this parameter has a value of `true` or `yes`, then all data in the
+collection will be removed prior to the import. Note that any existing
+index definitions will be preserved.
+
+@RESTQUERYPARAM{waitForSync,boolean,optional}
+Wait until documents have been synced to disk before returning.
+
+@RESTQUERYPARAM{onDuplicate,string,optional}
+Controls what action is carried out in case of a unique key constraint
+violation. Possible values are:
+- *error*: this will not import the current document because of the unique
+ key constraint violation. This is the default setting.
+- *update*: this will update an existing document in the database with the
+ data specified in the request. Attributes of the existing document that
+ are not present in the request will be preserved.
+- *replace*: this will replace an existing document in the database with the
+ data specified in the request.
+- *ignore*: this will not update an existing document and simply ignore the
+ error caused by the unique key constraint violation.
+Note that *update*, *replace* and *ignore* will only work when the
+import document in the request contains the *_key* attribute. *update* and
+*replace* may also fail because of secondary unique key constraint
+violations.
+
+@RESTQUERYPARAM{complete,boolean,optional}
+If set to `true` or `yes`, it will make the whole import fail if any error
+occurs. Otherwise the import will continue even if some documents cannot
+be imported.
+
+@RESTQUERYPARAM{details,boolean,optional}
+If set to `true` or `yes`, the result will include an attribute `details`
+with details about documents that could not be imported.
+
+@RESTDESCRIPTION
+Creates documents in the collection identified by `collection-name`.
+The first line of the request body must contain a JSON-encoded array of
+attribute names. All following lines in the request body must contain
+JSON-encoded arrays of attribute values. Each line is interpreted as a
+separate document, and the values specified will be mapped to the array
+of attribute names specified in the first header line.
+
+The response is a JSON object with the following attributes:
+
+- `created`: number of documents imported.
+
+- `errors`: number of documents that were not imported due to an error.
+
+- `empty`: number of empty lines found in the input (will only contain a
+ value greater zero for types `documents` or `auto`).
+
+- `updated`: number of updated/replaced documents (in case `onDuplicate`
+ was set to either `update` or `replace`).
+
+- `ignored`: number of failed but ignored insert operations (in case
+ `onDuplicate` was set to `ignore`).
+
+- `details`: if query parameter `details` is set to true, the result will
+ contain a `details` attribute which is an array with more detailed
+ information about which documents could not be inserted.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{201}
+is returned if all documents could be imported successfully.
+
+@RESTRETURNCODE{400}
+is returned if `type` contains an invalid value, no `collection` is
+specified, the documents are incorrectly encoded, or the request
+is malformed.
+
+@RESTRETURNCODE{404}
+is returned if `collection` or the `_from` or `_to` attributes of an
+imported edge refer to an unknown collection.
+
+@RESTRETURNCODE{409}
+is returned if the import would trigger a unique key violation and
+`complete` is set to `true`.
+
+@RESTRETURNCODE{500}
+is returned if the server cannot auto-generate a document key (out of keys
+error) for a document with no user-defined key.
+
+@EXAMPLES
+
+Importing two documents, with attributes `_key`, `value1` and `value2` each. One
+line in the import data is empty
+
+
+
+
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/square::x::y
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products <<EOF
+[ "_key", "value1", "value2" ]
+[ "abc", 25, "test" ]
-HTTP/1.1 200 OK
+[ "foo", "bar", "baz" ]
+EOF
+
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 43
+content-length: 72
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
- "code" : 200,
- "deletedCount" : 1
+ "created" : 2,
+ "errors" : 0,
+ "empty" : 1,
+ "updated" : 0,
+ "ignored" : 0
}
-
Hide response body
-
+
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/square::x::y
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products <<EOF
+[ "_key", "value1", "value2" ]
+[ "abc", 25, "test" ]
-HTTP/1.1 200 OK
+[ "foo", "bar", "baz" ]
+EOF
+
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 43
+content-length: 72
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -30752,38 +30855,48 @@ x-content-type-options: nosniff
-function not found:
+Importing into an edge collection, with attributes `_from`, `_to` and `name`
-
-
+
+
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/myfunction::x::y
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=links <<EOF
+[ "_from", "_to", "name" ]
+[ "products/123","products/234", "some name" ]
+[ "products/332", "products/abc", "other name" ]
+EOF
-HTTP/1.1 404 Not Found
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 114
+content-length: 72
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "code" : 404,
- "error" : true,
- "errorMessage" : "no AQL user function with name 'myfunction::x::y' found",
- "errorNum" : 1582
+ "error" : false,
+ "created" : 2,
+ "errors" : 0,
+ "empty" : 0,
+ "updated" : 0,
+ "ignored" : 0
}
-
Hide response body
-
+
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/myfunction::x::y
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=links <<EOF
+[ "_from", "_to", "name" ]
+[ "products/123","products/234", "some name" ]
+[ "products/332", "products/abc", "other name" ]
+EOF
-HTTP/1.1 404 Not Found
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 114
+content-length: 72
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -30793,99 +30906,112 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-
-
-@startDocuBlock get_api_aqlfunction
-
-@brief gets all reqistered AQL user functions
-
-@RESTHEADER{GET /_api/aqlfunction, Return registered AQL user functions, RestAqlUserFunctionsHandler:List}
-
-@RESTQUERYPARAMETERS
-
-@RESTQUERYPARAM{namespace,string,optional}
-Returns all registered AQL user functions from namespace *namespace* under *result*.
-
-@RESTDESCRIPTION
-Returns all registered AQL user functions.
-
-The call will return a JSON array with status codes and all user functions found under *result*.
-@RESTRETURNCODES
-@RESTRETURNCODE{200}
-on success *HTTP 200* is returned.
-@RESTREPLYBODY{error,boolean,required,}
-boolean flag to indicate whether an error occurred (*false* in this case)
+Importing into an edge collection, omitting `_from` or `_to`
-@RESTREPLYBODY{code,integer,required,int64}
-the HTTP status code
-@RESTREPLYBODY{result,array,required,aql_userfunction_struct}
-All functions, or the ones matching the *namespace* parameter
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=links&details=true <<EOF
+[ "name" ]
+[ "some name" ]
+[ "other name" ]
+EOF
-@RESTSTRUCT{name,aql_userfunction_struct,string,required,}
-The fully qualified name of the user function
+HTTP/1.1 201 Created
+content-type: application/json
+connection: Keep-Alive
+content-length: 281
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTSTRUCT{code,aql_userfunction_struct,string,required,}
-A string representation of the function body
+{
+ "error" : false,
+ "created" : 0,
+ "errors" : 2,
+ "empty" : 0,
+ "updated" : 0,
+ "ignored" : 0,
+ "details" : [
+ "at position 1: missing '_from' or '_to' attribute, offending document: {\"name\":\"some name\"}",
+ "at position 2: missing '_from' or '_to' attribute, offending document: {\"name\":\"other name\"}"
+ ]
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=links&details=true <<EOF
+[ "name" ]
+[ "some name" ]
+[ "other name" ]
+EOF
-@RESTSTRUCT{isDeterministic,aql_userfunction_struct,boolean,required,}
-an optional boolean value to indicate whether the function
-results are fully deterministic (function return value solely depends on
-the input value and return value is the same for repeated calls with same
-input). The *isDeterministic* attribute is currently not used but may be
-used later for optimizations.
+HTTP/1.1 201 Created
+content-type: application/json
+connection: Keep-Alive
+content-length: 281
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
-
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/test
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&details=true <<EOF
+[ "_key", "value1", "value2" ]
+[ "abc", 25, "test" ]
+["abc", "bar", "baz" ]
+EOF
-HTTP/1.1 200 OK
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 38
+content-length: 244
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
- "code" : 200,
- "result" : [ ]
+ "created" : 1,
+ "errors" : 1,
+ "empty" : 0,
+ "updated" : 0,
+ "ignored" : 0,
+ "details" : [
+ "at position 1: creating document failed with error 'unique constraint violated', offending document: {\"_key\":\"abc\",\"value1\":\"bar\",\"value2\":\"baz\"}"
+ ]
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/test
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&details=true <<EOF
+[ "_key", "value1", "value2" ]
+[ "abc", 25, "test" ]
+["abc", "bar", "baz" ]
+EOF
-HTTP/1.1 200 OK
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 38
+content-length: 244
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -30896,121 +31022,148 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-@startDocuBlock post_api_aqlfunction
+Violating a unique constraint, not allowing partial imports
-@brief create a new AQL user function
-@RESTHEADER{POST /_api/aqlfunction, Create AQL user function, RestAqlUserFunctionsHandler:create}
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&complete=true <<EOF
+[ "_key", "value1", "value2" ]
+[ "abc", 25, "test" ]
+["abc", "bar", "baz" ]
+EOF
-@RESTBODYPARAM{name,string,required,string}
-the fully qualified name of the user functions.
+HTTP/1.1 409 Conflict
+content-type: application/json
+connection: Keep-Alive
+content-length: 85
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTBODYPARAM{code,string,required,string}
-a string representation of the function body.
+{
+ "code" : 409,
+ "error" : true,
+ "errorMessage" : "unique constraint violated",
+ "errorNum" : 1210
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&complete=true <<EOF
+[ "_key", "value1", "value2" ]
+[ "abc", 25, "test" ]
+["abc", "bar", "baz" ]
+EOF
-@RESTBODYPARAM{isDeterministic,boolean,optional,}
-an optional boolean value to indicate whether the function
-results are fully deterministic (function return value solely depends on
-the input value and return value is the same for repeated calls with same
-input). The *isDeterministic* attribute is currently not used but may be
-used later for optimizations.
+HTTP/1.1 409 Conflict
+content-type: application/json
+connection: Keep-Alive
+content-length: 85
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products <<EOF
+[ "_key", "value1", "value2" ]
+[ "abc", 25, "test" ]
+["foo", "bar", "baz" ]
+EOF
-@RESTREPLYBODY{error,boolean,required,}
-boolean flag to indicate whether an error occurred (*false* in this case)
+HTTP/1.1 404 Not Found
+content-type: application/json
+connection: Keep-Alive
+content-length: 97
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTREPLYBODY{code,integer,required,int64}
-the HTTP status code
+{
+ "code" : 404,
+ "error" : true,
+ "errorMessage" : "collection or view not found: products",
+ "errorNum" : 1203
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products <<EOF
+[ "_key", "value1", "value2" ]
+[ "abc", 25, "test" ]
+["foo", "bar", "baz" ]
+EOF
-@RESTREPLYBODY{isNewlyCreated,boolean,required,}
-boolean flag to indicate whether the function was newly created (*true* in this case)
+HTTP/1.1 404 Not Found
+content-type: application/json
+connection: Keep-Alive
+content-length: 97
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
-
+
+
-shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/aqlfunction <<EOF
-{
- "name" : "myfunctions::temperature::celsiustofahrenheit",
- "code" : "function (celsius) { return celsius * 1.8 + 32; }",
- "isDeterministic" : true
-}
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products <<EOF
+{ "_key": "foo", "value1": "bar" }
EOF
-HTTP/1.1 201 Created
+HTTP/1.1 400 Bad Request
content-type: application/json
connection: Keep-Alive
-content-length: 48
+content-length: 92
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "error" : false,
- "code" : 201,
- "isNewlyCreated" : true
+ "code" : 400,
+ "error" : true,
+ "errorMessage" : "no JSON array found in second line",
+ "errorNum" : 400
}
-
Hide response body
-
+
-shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/aqlfunction <<EOF
-{
- "name" : "myfunctions::temperature::celsiustofahrenheit",
- "code" : "function (celsius) { return celsius * 1.8 + 32; }",
- "isDeterministic" : true
-}
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products <<EOF
+{ "_key": "foo", "value1": "bar" }
EOF
-HTTP/1.1 201 Created
+HTTP/1.1 400 Bad Request
content-type: application/json
connection: Keep-Alive
-content-length: 48
+content-length: 92
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -31021,226 +31174,343 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-
-
-@startDocuBlock post_api_explain
-@brief explain an AQL query and return information about it
+@endDocuBlock
-@RESTHEADER{POST /_api/explain, Explain an AQL query, explainQuery}
-A JSON object describing the query and query parameters.
+
+@startDocuBlock import_json
-@RESTBODYPARAM{query,string,required,string}
-the query which you want explained; If the query references any bind variables,
-these must also be passed in the attribute *bindVars*. Additional
-options for the query can be passed in the *options* attribute.
+@brief imports documents from JSON
-@RESTBODYPARAM{bindVars,array,optional,object}
-key/value pairs representing the bind parameters.
+@RESTHEADER{POST /_api/import#json,imports documents from JSON, RestImportHandler}
-@RESTBODYPARAM{options,object,optional,explain_options}
-Options for the query
+@RESTALLBODYPARAM{documents,string,required}
+The body must either be a JSON-encoded array of objects or a string with
+multiple JSON objects separated by newlines.
-@RESTSTRUCT{allPlans,explain_options,boolean,optional,}
-if set to *true*, all possible execution plans will be returned.
-The default is *false*, meaning only the optimal plan will be returned.
+@RESTQUERYPARAMETERS
-@RESTSTRUCT{maxNumberOfPlans,explain_options,integer,optional,int64}
-an optional maximum number of plans that the optimizer is
-allowed to generate. Setting this attribute to a low value allows to put a
-cap on the amount of work the optimizer does.
+@RESTQUERYPARAM{type,string,required}
+Determines how the body of the request will be interpreted. `type` can have
+the following values:
+- `documents`: when this type is used, each line in the request body is
+ expected to be an individual JSON-encoded document. Multiple JSON objects
+ in the request body need to be separated by newlines.
+- `list`: when this type is used, the request body must contain a single
+ JSON-encoded array of individual objects to import.
+- `auto`: if set, this will automatically determine the body type (either
+ `documents` or `list`).
-@RESTSTRUCT{optimizer,explain_options,object,optional,explain_options_optimizer}
-Options related to the query optimizer.
+@RESTQUERYPARAM{collection,string,required}
+The collection name.
-@RESTSTRUCT{rules,explain_options_optimizer,array,optional,string}
-A list of to-be-included or to-be-excluded optimizer rules can be put into this
-attribute, telling the optimizer to include or exclude specific rules. To disable
-a rule, prefix its name with a `-`, to enable a rule, prefix it with a `+`. There is
-also a pseudo-rule `all`, which matches all optimizer rules. `-all` disables all rules.
+@RESTQUERYPARAM{fromPrefix,string,optional}
+An optional prefix for the values in `_from` attributes. If specified, the
+value is automatically prepended to each `_from` input value. This allows
+specifying just the keys for `_from`.
-@RESTDESCRIPTION
+@RESTQUERYPARAM{toPrefix,string,optional}
+An optional prefix for the values in `_to` attributes. If specified, the
+value is automatically prepended to each `_to` input value. This allows
+specifying just the keys for `_to`.
-To explain how an AQL query would be executed on the server, the query string
-can be sent to the server via an HTTP POST request. The server will then validate
-the query and create an execution plan for it. The execution plan will be
-returned, but the query will not be executed.
+@RESTQUERYPARAM{overwrite,boolean,optional}
+If this parameter has a value of `true` or `yes`, then all data in the
+collection will be removed prior to the import. Note that any existing
+index definitions will be preserved.
-The execution plan that is returned by the server can be used to estimate the
-probable performance of the query. Though the actual performance will depend
-on many different factors, the execution plan normally can provide some rough
-estimates on the amount of work the server needs to do in order to actually run
-the query.
+@RESTQUERYPARAM{waitForSync,boolean,optional}
+Wait until documents have been synced to disk before returning.
-By default, the explain operation will return the optimal plan as chosen by
-the query optimizer The optimal plan is the plan with the lowest total estimated
-cost. The plan will be returned in the attribute *plan* of the response object.
-If the option *allPlans* is specified in the request, the result will contain
-all plans created by the optimizer. The plans will then be returned in the
-attribute *plans*.
+@RESTQUERYPARAM{onDuplicate,string,optional}
+Controls what action is carried out in case of a unique key constraint
+violation. Possible values are:
+- *error*: this will not import the current document because of the unique
+ key constraint violation. This is the default setting.
+- *update*: this will update an existing document in the database with the
+ data specified in the request. Attributes of the existing document that
+ are not present in the request will be preserved.
+- *replace*: this will replace an existing document in the database with the
+ data specified in the request.
+- *ignore*: this will not update an existing document and simply ignore the
+ error caused by a unique key constraint violation.
+Note that that *update*, *replace* and *ignore* will only work when the
+import document in the request contains the *_key* attribute. *update* and
+*replace* may also fail because of secondary unique key constraint violations.
-The result will also contain an attribute *warnings*, which is an array of
-warnings that occurred during optimization or execution plan creation. Additionally,
-a *stats* attribute is contained in the result with some optimizer statistics.
-If *allPlans* is set to *false*, the result will contain an attribute *cacheable*
-that states whether the query results can be cached on the server if the query
-result cache were used. The *cacheable* attribute is not present when *allPlans*
-is set to *true*.
+@RESTQUERYPARAM{complete,boolean,optional}
+If set to `true` or `yes`, it will make the whole import fail if any error
+occurs. Otherwise the import will continue even if some documents cannot
+be imported.
-Each plan in the result is a JSON object with the following attributes:
-- *nodes*: the array of execution nodes of the plan.
+@RESTQUERYPARAM{details,boolean,optional}
+If set to `true` or `yes`, the result will include an attribute `details`
+with details about documents that could not be imported.
-- *estimatedCost*: the total estimated cost for the plan. If there are multiple
- plans, the optimizer will choose the plan with the lowest total cost.
+@RESTDESCRIPTION
+Creates documents in the collection identified by `collection-name`.
+The JSON representations of the documents must be passed as the body of the
+POST request. The request body can either consist of multiple lines, with
+each line being a single stand-alone JSON object, or a singe JSON array with
+sub-objects.
-- *collections*: an array of collections used in the query
+The response is a JSON object with the following attributes:
-- *rules*: an array of rules the optimizer applied.
+- `created`: number of documents imported.
-- *variables*: array of variables used in the query (note: this may contain
- internal variables created by the optimizer)
+- `errors`: number of documents that were not imported due to an error.
+
+- `empty`: number of empty lines found in the input (will only contain a
+ value greater zero for types `documents` or `auto`).
+
+- `updated`: number of updated/replaced documents (in case `onDuplicate`
+ was set to either `update` or `replace`).
+
+- `ignored`: number of failed but ignored insert operations (in case
+ `onDuplicate` was set to `ignore`).
+
+- `details`: if query parameter `details` is set to true, the result will
+ contain a `details` attribute which is an array with more detailed
+ information about which documents could not be inserted.
@RESTRETURNCODES
-@RESTRETURNCODE{200}
-If the query is valid, the server will respond with *HTTP 200* and
-return the optimal execution plan in the *plan* attribute of the response.
-If option *allPlans* was set in the request, an array of plans will be returned
-in the *allPlans* attribute instead.
+@RESTRETURNCODE{201}
+is returned if all documents could be imported successfully.
@RESTRETURNCODE{400}
-The server will respond with *HTTP 400* in case of a malformed request,
-or if the query contains a parse error. The body of the response will
-contain the error details embedded in a JSON object.
-Omitting bind variables if the query references any will also result
-in an *HTTP 400* error.
+is returned if `type` contains an invalid value, no `collection` is
+specified, the documents are incorrectly encoded, or the request
+is malformed.
@RESTRETURNCODE{404}
-The server will respond with *HTTP 404* in case a non-existing collection is
-accessed in the query.
+is returned if `collection` or the `_from` or `_to` attributes of an
+imported edge refer to an unknown collection.
+
+@RESTRETURNCODE{409}
+is returned if the import would trigger a unique key violation and
+`complete` is set to `true`.
+
+@RESTRETURNCODE{500}
+is returned if the server cannot auto-generate a document key (out of keys
+error) for a document with no user-defined key.
@EXAMPLES
-Valid query
+Importing documents with heterogenous attributes from a JSON array
-
-
+
+
-shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
-{
- "query" : "FOR p IN products RETURN p"
-}
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=list <<EOF
+[
+ {
+ "_key" : "abc",
+ "value1" : 25,
+ "value2" : "test",
+ "allowed" : true
+ },
+ {
+ "_key" : "foo",
+ "name" : "baz"
+ },
+ {
+ "name" : {
+ "detailed" : "detailed name",
+ "short" : "short name"
+ }
+ }
+]
EOF
-HTTP/1.1 200 OK
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 1003
+content-length: 72
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "plan" : {
- "nodes" : [
- {
- "type" : "SingletonNode",
- "dependencies" : [ ],
- "id" : 1,
- "estimatedCost" : 1,
- "estimatedNrItems" : 1
- },
- {
- "type" : "EnumerateCollectionNode",
- "dependencies" : [
- 1
- ],
- "id" : 2,
- "estimatedCost" : 12,
- "estimatedNrItems" : 10,
- "random" : false,
- "indexHint" : {
- "forced" : false,
- "type" : "none"
- },
- "outVariable" : {
- "id" : 0,
- "name" : "p",
- "isDataFromCollection" : true
- },
- "projections" : [ ],
- "count" : false,
- "producesResult" : true,
- "readOwnWrites" : false,
- "maxProjections" : 5,
- "database" : "_system",
- "collection" : "products",
- "satellite" : false,
- "isSatellite" : false,
- "isSatelliteOf" : null
- },
- {
- "type" : "ReturnNode",
- "dependencies" : [
- 2
- ],
- "id" : 3,
- "estimatedCost" : 22,
- "estimatedNrItems" : 10,
- "inVariable" : {
- "id" : 0,
- "name" : "p",
- "isDataFromCollection" : true
- },
- "count" : true
- }
- ],
- "rules" : [ ],
- "collections" : [
- {
- "name" : "products",
- "type" : "read"
- }
- ],
- "variables" : [
- {
- "id" : 0,
- "name" : "p",
- "isDataFromCollection" : true
- }
- ],
- "estimatedCost" : 22,
- "estimatedNrItems" : 10,
- "isModificationQuery" : false
+ "error" : false,
+ "created" : 3,
+ "errors" : 0,
+ "empty" : 0,
+ "updated" : 0,
+ "ignored" : 0
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=list <<EOF
+[
+ {
+ "_key" : "abc",
+ "value1" : 25,
+ "value2" : "test",
+ "allowed" : true
},
- "cacheable" : true,
- "warnings" : [ ],
- "stats" : {
- "rulesExecuted" : 41,
- "rulesSkipped" : 0,
- "plansCreated" : 1
+ {
+ "_key" : "foo",
+ "name" : "baz"
},
+ {
+ "name" : {
+ "detailed" : "detailed name",
+ "short" : "short name"
+ }
+ }
+]
+EOF
+
+HTTP/1.1 201 Created
+content-type: application/json
+connection: Keep-Alive
+content-length: 72
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+
+
+
+
+Importing documents from individual JSON lines
+
+
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=documents <<EOF
+{ "_key": "abc", "value1": 25, "value2": "test","allowed": true }
+{ "_key": "foo", "name": "baz" }
+
+{ "name": { "detailed": "detailed name", "short": "short name" } }
+
+EOF
+
+HTTP/1.1 201 Created
+content-type: application/json
+connection: Keep-Alive
+content-length: 72
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
+{
"error" : false,
- "code" : 200
+ "created" : 3,
+ "errors" : 0,
+ "empty" : 1,
+ "updated" : 0,
+ "ignored" : 0
}
-
Hide response body
-
+
-shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=documents <<EOF
+{ "_key": "abc", "value1": 25, "value2": "test","allowed": true }
+{ "_key": "foo", "name": "baz" }
+
+{ "name": { "detailed": "detailed name", "short": "short name" } }
+
+EOF
+
+HTTP/1.1 201 Created
+content-type: application/json
+connection: Keep-Alive
+content-length: 72
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+
+
+
+Using the auto type detection
+
+
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=auto <<EOF
+[
+ {
+ "_key" : "abc",
+ "value1" : 25,
+ "value2" : "test",
+ "allowed" : true
+ },
+ {
+ "_key" : "foo",
+ "name" : "baz"
+ },
+ {
+ "name" : {
+ "detailed" : "detailed name",
+ "short" : "short name"
+ }
+ }
+]
+EOF
+
+HTTP/1.1 201 Created
+content-type: application/json
+connection: Keep-Alive
+content-length: 72
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
{
- "query" : "FOR p IN products RETURN p"
+ "error" : false,
+ "created" : 3,
+ "errors" : 0,
+ "empty" : 0,
+ "updated" : 0,
+ "ignored" : 0
}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=auto <<EOF
+[
+ {
+ "_key" : "abc",
+ "value1" : 25,
+ "value2" : "test",
+ "allowed" : true
+ },
+ {
+ "_key" : "foo",
+ "name" : "baz"
+ },
+ {
+ "name" : {
+ "detailed" : "detailed name",
+ "short" : "short name"
+ }
+ }
+]
EOF
-HTTP/1.1 200 OK
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 1003
+content-length: 72
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -31252,253 +31522,1230 @@ x-content-type-options: nosniff
-A plan with some optimizer rules applied
+Importing into an edge collection, with attributes `_from`, `_to` and `name`
-
-
+
+
+
-shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=links&type=documents <<EOF
+{ "_from": "products/123", "_to": "products/234" }
+{"_from": "products/332", "_to": "products/abc", "name": "other name" }
+EOF
+
+HTTP/1.1 201 Created
+content-type: application/json
+connection: Keep-Alive
+content-length: 72
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
{
- "query" : "FOR p IN products LET a = p.id FILTER a == 4 LET name = p.name SORT p.id LIMIT 1 RETURN name"
+ "error" : false,
+ "created" : 2,
+ "errors" : 0,
+ "empty" : 0,
+ "updated" : 0,
+ "ignored" : 0
}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=links&type=documents <<EOF
+{ "_from": "products/123", "_to": "products/234" }
+{"_from": "products/332", "_to": "products/abc", "name": "other name" }
EOF
-HTTP/1.1 200 OK
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 2627
+content-length: 72
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+
+
+
+
+Importing into an edge collection, omitting `_from` or `_to`
+
+
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=links&type=list&details=true <<EOF
+[
+ {
+ "name" : "some name"
+ }
+]
+EOF
+
+HTTP/1.1 201 Created
+content-type: application/json
+connection: Keep-Alive
+content-length: 182
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "plan" : {
- "nodes" : [
- {
- "type" : "SingletonNode",
- "dependencies" : [ ],
- "id" : 1,
- "estimatedCost" : 1,
- "estimatedNrItems" : 1
- },
- {
- "type" : "IndexNode",
- "dependencies" : [
- 1
- ],
- "id" : 11,
- "estimatedCost" : 4.3719280948873624,
- "estimatedNrItems" : 1,
- "outVariable" : {
- "id" : 0,
- "name" : "p",
- "isDataFromCollection" : true
- },
- "projections" : [
- "name"
- ],
- "count" : false,
- "producesResult" : true,
- "readOwnWrites" : false,
- "maxProjections" : 5,
- "database" : "_system",
- "collection" : "products",
- "satellite" : false,
- "isSatellite" : false,
- "isSatelliteOf" : null,
- "needsGatherNodeSort" : true,
- "indexCoversProjections" : false,
- "indexes" : [
- {
- "id" : "67972",
- "type" : "skiplist",
- "name" : "idx_1769599266965159936",
- "fields" : [
- "id"
- ],
- "selectivityEstimate" : 1,
- "unique" : false,
- "sparse" : false,
- "deduplicate" : true,
- "estimates" : true
- }
- ],
- "condition" : {
- "type" : "n-ary or",
- "typeID" : 63,
+ "error" : false,
+ "created" : 0,
+ "errors" : 1,
+ "empty" : 0,
+ "updated" : 0,
+ "ignored" : 0,
+ "details" : [
+ "at position 1: missing '_from' or '_to' attribute, offending document: {\"name\":\"some name\"}"
+ ]
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=links&type=list&details=true <<EOF
+[
+ {
+ "name" : "some name"
+ }
+]
+EOF
+
+HTTP/1.1 201 Created
+content-type: application/json
+connection: Keep-Alive
+content-length: 182
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+
+
+
+
+Violating a unique constraint, but allow partial imports
+
+
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=documents&details=true <<EOF
+{ "_key": "abc", "value1": 25, "value2": "test" }
+{ "_key": "abc", "value1": "bar", "value2": "baz" }
+EOF
+
+HTTP/1.1 201 Created
+content-type: application/json
+connection: Keep-Alive
+content-length: 244
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
+{
+ "error" : false,
+ "created" : 1,
+ "errors" : 1,
+ "empty" : 0,
+ "updated" : 0,
+ "ignored" : 0,
+ "details" : [
+ "at position 1: creating document failed with error 'unique constraint violated', offending document: {\"_key\":\"abc\",\"value1\":\"bar\",\"value2\":\"baz\"}"
+ ]
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=documents&details=true <<EOF
+{ "_key": "abc", "value1": 25, "value2": "test" }
+{ "_key": "abc", "value1": "bar", "value2": "baz" }
+EOF
+
+HTTP/1.1 201 Created
+content-type: application/json
+connection: Keep-Alive
+content-length: 244
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+
+
+
+
+Violating a unique constraint, not allowing partial imports
+
+
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=documents&complete=true <<EOF
+{ "_key": "abc", "value1": 25, "value2": "test" }
+{ "_key": "abc", "value1": "bar", "value2": "baz" }
+EOF
+
+HTTP/1.1 409 Conflict
+content-type: application/json
+connection: Keep-Alive
+content-length: 85
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
+{
+ "code" : 409,
+ "error" : true,
+ "errorMessage" : "unique constraint violated",
+ "errorNum" : 1210
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=documents&complete=true <<EOF
+{ "_key": "abc", "value1": 25, "value2": "test" }
+{ "_key": "abc", "value1": "bar", "value2": "baz" }
+EOF
+
+HTTP/1.1 409 Conflict
+content-type: application/json
+connection: Keep-Alive
+content-length: 85
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+
+
+
+
+Using a non-existing collection
+
+
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=documents <<EOF
+{ "name": "test" }
+EOF
+
+HTTP/1.1 404 Not Found
+content-type: application/json
+connection: Keep-Alive
+content-length: 97
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
+{
+ "code" : 404,
+ "error" : true,
+ "errorMessage" : "collection or view not found: products",
+ "errorNum" : 1203
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=documents <<EOF
+{ "name": "test" }
+EOF
+
+HTTP/1.1 404 Not Found
+content-type: application/json
+connection: Keep-Alive
+content-length: 97
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+
+
+
+
+Using a malformed body
+
+
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=list <<EOF
+{ }
+EOF
+
+HTTP/1.1 400 Bad Request
+content-type: application/json
+connection: Keep-Alive
+content-length: 95
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
+{
+ "code" : 400,
+ "error" : true,
+ "errorMessage" : "expecting a JSON array in the request",
+ "errorNum" : 400
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/import?collection=products&type=list <<EOF
+{ }
+EOF
+
+HTTP/1.1 400 Bad Request
+content-type: application/json
+connection: Keep-Alive
+content-length: 95
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+
+
+
+@endDocuBlock
+
+
+
+@startDocuBlock DeleteApiQueryCache
+
+@brief clears the AQL query results cache
+
+@RESTHEADER{DELETE /_api/query-cache, Clears any results in the AQL query results cache, clearCache}
+
+@RESTDESCRIPTION
+clears the query results cache for the current database
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+The server will respond with *HTTP 200* when the cache was cleared
+successfully.
+
+@RESTRETURNCODE{400}
+The server will respond with *HTTP 400* in case of a malformed request.
+@endDocuBlock
+
+
+
+@startDocuBlock DeleteApiQueryKill
+
+@brief kills an AQL query
+
+@RESTHEADER{DELETE /_api/query/{query-id}, Kills a running AQL query, deleteQuery}
+
+@RESTURLPARAMETERS
+
+@RESTURLPARAM{query-id,string,required}
+The id of the query.
+
+@RESTDESCRIPTION
+Kills a running query in the currently selected database. The query will be
+terminated at the next cancelation point.
+
+@RESTQUERYPARAMETERS
+
+@RESTQUERYPARAM{all,boolean,optional}
+If set to *true*, will attempt to kill the specified query in all databases,
+not just the selected one.
+Using the parameter is only allowed in the system database and with superuser
+privileges.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+The server will respond with *HTTP 200* when the query was still running when
+the kill request was executed and the query's kill flag was set.
+
+@RESTRETURNCODE{400}
+The server will respond with *HTTP 400* in case of a malformed request.
+
+@RESTRETURNCODE{403}
+*HTTP 403* is returned in case the *all* parameter was used, but the request
+was made in a different database than _system, or by an non-privileged user.
+
+@RESTRETURNCODE{404}
+The server will respond with *HTTP 404* when no query with the specified
+id was found.
+@endDocuBlock
+
+
+
+@startDocuBlock DeleteApiQuerySlow
+
+@brief clears the list of slow AQL queries
+
+@RESTHEADER{DELETE /_api/query/slow, Clears the list of slow AQL queries, deleteSlowQueries}
+
+@RESTDESCRIPTION
+Clears the list of slow AQL queries in the currently selected database
+
+@RESTQUERYPARAMETERS
+
+@RESTQUERYPARAM{all,boolean,optional}
+If set to *true*, will clear the slow query history in all databases, not just
+the selected one.
+Using the parameter is only allowed in the system database and with superuser
+privileges.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+The server will respond with *HTTP 200* when the list of queries was
+cleared successfully.
+
+@RESTRETURNCODE{400}
+The server will respond with *HTTP 400* in case of a malformed request.
+@endDocuBlock
+
+
+
+@startDocuBlock GetApiQueryCacheCurrent
+
+@brief returns a list of the stored results in the AQL query results cache
+
+@RESTHEADER{GET /_api/query-cache/entries, Returns the currently cached query results, readQueries}
+
+@RESTDESCRIPTION
+Returns an array containing the AQL query results currently stored in the query results
+cache of the selected database. Each result is a JSON object with the following attributes:
+
+- *hash*: the query result's hash
+
+- *query*: the query string
+
+- *bindVars*: the query's bind parameters. this attribute is only shown if tracking for
+ bind variables was enabled at server start
+
+- *size*: the size of the query result and bind parameters, in bytes
+
+- *results*: number of documents/rows in the query result
+
+- *started*: the date and time when the query was stored in the cache
+
+- *hits*: number of times the result was served from the cache (can be
+ *0* for queries that were only stored in the cache but were never accessed
+ again afterwards)
+
+- *runTime*: the query's run time
+
+- *dataSources*: an array of collections/Views the query was using
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+Is returned when the list of results can be retrieved successfully.
+
+@RESTRETURNCODE{400}
+The server will respond with *HTTP 400* in case of a malformed request,
+
+@endDocuBlock
+
+
+
+@startDocuBlock GetApiQueryCacheProperties
+
+@brief returns the global configuration for the AQL query results cache
+
+@RESTHEADER{GET /_api/query-cache/properties, Returns the global properties for the AQL query results cache, readProperties}
+
+@RESTDESCRIPTION
+Returns the global AQL query results cache configuration. The configuration is a
+JSON object with the following properties:
+
+- *mode*: the mode the AQL query results cache operates in. The mode is one of the following
+ values: *off*, *on* or *demand*.
+
+- *maxResults*: the maximum number of query results that will be stored per database-specific
+ cache.
+
+- *maxResultsSize*: the maximum cumulated size of query results that will be stored per
+ database-specific cache.
+
+- *maxEntrySize*: the maximum individual result size of queries that will be stored per
+ database-specific cache.
+
+- *includeSystem*: whether or not results of queries that involve system collections will be
+ stored in the query results cache.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+Is returned if the properties can be retrieved successfully.
+
+@RESTRETURNCODE{400}
+The server will respond with *HTTP 400* in case of a malformed request,
+
+@endDocuBlock
+
+
+
+@startDocuBlock GetApiQueryCurrent
+
+@brief returns a list of currently running AQL queries
+
+@RESTHEADER{GET /_api/query/current, Returns the currently running AQL queries, readQuery:current}
+
+@RESTDESCRIPTION
+Returns an array containing the AQL queries currently running in the selected
+database. Each query is a JSON object with the following attributes:
+
+- *id*: the query's id
+
+- *database*: the name of the database the query runs in
+
+- *user*: the name of the user that started the query
+
+- *query*: the query string (potentially truncated)
+
+- *bindVars*: the bind parameter values used by the query
+
+- *started*: the date and time when the query was started
+
+- *runTime*: the query's run time up to the point the list of queries was
+ queried
+
+- *state*: the query's current execution state (as a string). One of:
+ - `"initializing"`
+ - `"parsing"`
+ - `"optimizing ast"`
+ - `"loading collections"`
+ - `"instantiating plan"`
+ - `"optimizing plan"`
+ - `"executing"`
+ - `"finalizing"`
+ - `"finished"`
+ - `"killed"`
+ - `"invalid"`
+
+- *stream*: whether or not the query uses a streaming cursor
+
+@RESTQUERYPARAMETERS
+
+@RESTQUERYPARAM{all,boolean,optional}
+If set to *true*, will return the currently running queries in all databases,
+not just the selected one.
+Using the parameter is only allowed in the system database and with superuser
+privileges.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+Is returned when the list of queries can be retrieved successfully.
+
+@RESTRETURNCODE{400}
+The server will respond with *HTTP 400* in case of a malformed request,
+
+@RESTRETURNCODE{403}
+*HTTP 403* is returned in case the *all* parameter was used, but the request
+was made in a different database than _system, or by an non-privileged user.
+
+@endDocuBlock
+
+
+
+@startDocuBlock GetApiQueryProperties
+
+@brief returns the configuration for the AQL query tracking
+
+@RESTHEADER{GET /_api/query/properties, Returns the properties for the AQL query tracking, readQueryProperties}
+
+@RESTDESCRIPTION
+Returns the current query tracking configuration. The configuration is a
+JSON object with the following properties:
+
+- *enabled*: if set to *true*, then queries will be tracked. If set to
+ *false*, neither queries nor slow queries will be tracked.
+
+- *trackSlowQueries*: if set to *true*, then slow queries will be tracked
+ in the list of slow queries if their runtime exceeds the value set in
+ *slowQueryThreshold*. In order for slow queries to be tracked, the *enabled*
+ property must also be set to *true*.
+
+- *trackBindVars*: if set to *true*, then bind variables used in queries will
+ be tracked.
+
+- *maxSlowQueries*: the maximum number of slow queries to keep in the list
+ of slow queries. If the list of slow queries is full, the oldest entry in
+ it will be discarded when additional slow queries occur.
+
+- *slowQueryThreshold*: the threshold value for treating a query as slow. A
+ query with a runtime greater or equal to this threshold value will be
+ put into the list of slow queries when slow query tracking is enabled.
+ The value for *slowQueryThreshold* is specified in seconds.
+
+- *maxQueryStringLength*: the maximum query string length to keep in the
+ list of queries. Query strings can have arbitrary lengths, and this property
+ can be used to save memory in case very long query strings are used. The
+ value is specified in bytes.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+Is returned if properties were retrieved successfully.
+
+@RESTRETURNCODE{400}
+The server will respond with *HTTP 400* in case of a malformed request,
+
+@endDocuBlock
+
+
+
+@startDocuBlock GetApiQuerySlow
+
+@brief returns a list of slow running AQL queries
+
+@RESTHEADER{GET /_api/query/slow, Returns the list of slow AQL queries, readQuery:Slow}
+
+@RESTDESCRIPTION
+Returns an array containing the last AQL queries that are finished and
+have exceeded the slow query threshold in the selected database.
+The maximum amount of queries in the list can be controlled by setting
+the query tracking property `maxSlowQueries`. The threshold for treating
+a query as *slow* can be adjusted by setting the query tracking property
+`slowQueryThreshold`.
+
+Each query is a JSON object with the following attributes:
+
+- *id*: the query's id
+
+- *database*: the name of the database the query runs in
+
+- *user*: the name of the user that started the query
+
+- *query*: the query string (potentially truncated)
+
+- *bindVars*: the bind parameter values used by the query
+
+- *started*: the date and time when the query was started
+
+- *runTime*: the query's total run time
+
+- *state*: the query's current execution state (will always be "finished"
+ for the list of slow queries)
+
+- *stream*: whether or not the query uses a streaming cursor
+
+@RESTQUERYPARAMETERS
+
+@RESTQUERYPARAM{all,boolean,optional}
+If set to *true*, will return the slow queries from all databases, not just
+the selected one.
+Using the parameter is only allowed in the system database and with superuser
+privileges.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+Is returned when the list of queries can be retrieved successfully.
+
+@RESTRETURNCODE{400}
+The server will respond with *HTTP 400* in case of a malformed request,
+
+@RESTRETURNCODE{403}
+*HTTP 403* is returned in case the *all* parameter was used, but the request
+was made in a different database than _system, or by an non-privileged user.
+
+@endDocuBlock
+
+
+
+@startDocuBlock PostApiQueryProperties
+
+@brief parse an AQL query and return information about it
+
+@RESTHEADER{POST /_api/query, Parse an AQL query, parseQuery}
+
+@RESTDESCRIPTION
+This endpoint is for query validation only. To actually query the database,
+see `/api/cursor`.
+
+@RESTBODYPARAM{query,string,required,string}
+To validate a query string without executing it, the query string can be
+passed to the server via an HTTP POST request.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+If the query is valid, the server will respond with *HTTP 200* and
+return the names of the bind parameters it found in the query (if any) in
+the *bindVars* attribute of the response. It will also return an array
+of the collections used in the query in the *collections* attribute.
+If a query can be parsed successfully, the *ast* attribute of the returned
+JSON will contain the abstract syntax tree representation of the query.
+The format of the *ast* is subject to change in future versions of
+ArangoDB, but it can be used to inspect how ArangoDB interprets a given
+query. Note that the abstract syntax tree will be returned without any
+optimizations applied to it.
+
+@RESTRETURNCODE{400}
+The server will respond with *HTTP 400* in case of a malformed request,
+or if the query contains a parse error. The body of the response will
+contain the error details embedded in a JSON object.
+
+@EXAMPLES
+
+a valid query
+
+
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/query <<EOF
+{ "query" : "FOR i IN 1..100 FILTER i > 10 LIMIT 2 RETURN i * 3" }
+EOF
+
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 620
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
+{
+ "error" : false,
+ "code" : 200,
+ "parsed" : true,
+ "collections" : [ ],
+ "bindVars" : [ ],
+ "ast" : [
+ {
+ "type" : "root",
+ "subNodes" : [
+ {
+ "type" : "for",
"subNodes" : [
{
- "type" : "n-ary and",
- "typeID" : 62,
+ "type" : "variable",
+ "name" : "i",
+ "id" : 0
+ },
+ {
+ "type" : "range",
"subNodes" : [
{
- "type" : "compare ==",
- "typeID" : 25,
- "excludesNull" : false,
- "subNodes" : [
- {
- "type" : "attribute access",
- "typeID" : 35,
- "name" : "id",
- "subNodes" : [
- {
- "type" : "reference",
- "typeID" : 45,
- "name" : "p",
- "id" : 0
- }
- ]
- },
- {
- "type" : "value",
- "typeID" : 40,
- "value" : 4,
- "vType" : "int",
- "vTypeID" : 2
- }
- ]
+ "type" : "value",
+ "value" : 1
+ },
+ {
+ "type" : "value",
+ "value" : 100
}
]
+ },
+ {
+ "type" : "no-op"
}
]
},
- "sorted" : true,
- "ascending" : true,
- "reverse" : false,
- "evalFCalls" : true,
- "limit" : 0
- },
- {
- "type" : "LimitNode",
- "dependencies" : [
- 11
- ],
- "id" : 9,
- "estimatedCost" : 5.3719280948873624,
- "estimatedNrItems" : 1,
- "offset" : 0,
- "limit" : 1,
- "fullCount" : false
- },
- {
- "type" : "CalculationNode",
- "dependencies" : [
- 9
- ],
- "id" : 6,
- "estimatedCost" : 6.3719280948873624,
- "estimatedNrItems" : 1,
- "expression" : {
- "type" : "attribute access",
- "typeID" : 35,
- "name" : "name",
+ {
+ "type" : "filter",
"subNodes" : [
{
- "type" : "reference",
- "typeID" : 45,
- "name" : "p",
- "id" : 0
+ "type" : "compare >",
+ "subNodes" : [
+ {
+ "type" : "reference",
+ "name" : "i",
+ "id" : 0
+ },
+ {
+ "type" : "value",
+ "value" : 10
+ }
+ ]
}
]
},
- "outVariable" : {
- "id" : 2,
- "name" : "name",
- "isDataFromCollection" : false
- },
- "canThrow" : false,
- "expressionType" : "attribute"
- },
- {
- "type" : "ReturnNode",
- "dependencies" : [
- 6
- ],
- "id" : 10,
- "estimatedCost" : 7.3719280948873624,
- "estimatedNrItems" : 1,
- "inVariable" : {
- "id" : 2,
- "name" : "name",
- "isDataFromCollection" : false
+ {
+ "type" : "limit",
+ "subNodes" : [
+ {
+ "type" : "value",
+ "value" : 0
+ },
+ {
+ "type" : "value",
+ "value" : 2
+ }
+ ]
},
- "count" : true
- }
- ],
- "rules" : [
- "move-calculations-up",
- "remove-redundant-calculations",
- "remove-unnecessary-calculations",
- "move-calculations-up-2",
- "use-indexes",
- "remove-filter-covered-by-index",
- "use-index-for-sort",
- "remove-unnecessary-calculations-2",
- "move-calculations-down",
- "reduce-extraction-to-projection"
- ],
- "collections" : [
- {
- "name" : "products",
- "type" : "read"
- }
- ],
- "variables" : [
- {
- "id" : 6,
- "name" : "5",
- "isDataFromCollection" : false
- },
- {
- "id" : 4,
- "name" : "3",
- "isDataFromCollection" : false
- },
- {
- "id" : 2,
- "name" : "name",
- "isDataFromCollection" : false
- },
- {
- "id" : 1,
- "name" : "a",
- "isDataFromCollection" : false
- },
- {
- "id" : 0,
- "name" : "p",
- "isDataFromCollection" : true
- }
- ],
- "estimatedCost" : 7.3719280948873624,
- "estimatedNrItems" : 1,
- "isModificationQuery" : false
- },
- "cacheable" : true,
- "warnings" : [ ],
- "stats" : {
- "rulesExecuted" : 43,
- "rulesSkipped" : 0,
- "plansCreated" : 1
- },
+ {
+ "type" : "return",
+ "subNodes" : [
+ {
+ "type" : "times",
+ "subNodes" : [
+ {
+ "type" : "reference",
+ "name" : "i",
+ "id" : 0
+ },
+ {
+ "type" : "value",
+ "value" : 3
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/query <<EOF
+{ "query" : "FOR i IN 1..100 FILTER i > 10 LIMIT 2 RETURN i * 3" }
+EOF
+
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 620
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+
+
+
+an invalid query
+
+
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/query <<EOF
+{ "query" : "FOR i IN 1..100 FILTER i = 1 LIMIT 2 RETURN i * 3" }
+EOF
+
+HTTP/1.1 400 Bad Request
+content-type: application/json
+connection: Keep-Alive
+content-length: 143
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
+{
+ "code" : 400,
+ "error" : true,
+ "errorMessage" : "syntax error, unexpected assignment near '= 1 LIMIT 2 RETURN i * 3' at position 1:26",
+ "errorNum" : 1501
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/query <<EOF
+{ "query" : "FOR i IN 1..100 FILTER i = 1 LIMIT 2 RETURN i * 3" }
+EOF
+
+HTTP/1.1 400 Bad Request
+content-type: application/json
+connection: Keep-Alive
+content-length: 143
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+
+
+@endDocuBlock
+
+
+
+@startDocuBlock PutApiQueryCacheProperties
+
+@brief changes the configuration for the AQL query results cache
+
+@RESTHEADER{PUT /_api/query-cache/properties, Globally adjusts the AQL query results cache properties, replaceProperties:QueryCache}
+
+@RESTDESCRIPTION
+After the properties have been changed, the current set of properties will
+be returned in the HTTP response.
+
+Note: changing the properties may invalidate all results in the cache.
+The global properties for AQL query cache.
+The properties need to be passed in the attribute *properties* in the body
+of the HTTP request. *properties* needs to be a JSON object with the following
+properties:
+
+@RESTBODYPARAM{mode,string,optional,string}
+ the mode the AQL query cache should operate in. Possible values are *off*, *on* or *demand*.
+
+@RESTBODYPARAM{maxResults,integer,optional,int64}
+the maximum number of query results that will be stored per database-specific cache.
+
+@RESTBODYPARAM{maxResultsSize,integer,optional,int64}
+the maximum cumulated size of query results that will be stored per database-specific cache.
+
+@RESTBODYPARAM{maxEntrySize,integer,optional,int64}
+the maximum individual size of query results that will be stored per database-specific cache.
+
+@RESTBODYPARAM{includeSystem,boolean,optional,}
+whether or not to store results of queries that involve system collections.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+Is returned if the properties were changed successfully.
+
+@RESTRETURNCODE{400}
+The server will respond with *HTTP 400* in case of a malformed request,
+
+@endDocuBlock
+
+
+
+@startDocuBlock PutApiQueryProperties
+
+@brief changes the configuration for the AQL query tracking
+
+@RESTHEADER{PUT /_api/query/properties, Changes the properties for the AQL query tracking, replaceProperties}
+
+@RESTBODYPARAM{enabled,boolean,required,}
+If set to *true*, then queries will be tracked. If set to
+*false*, neither queries nor slow queries will be tracked.
+
+@RESTBODYPARAM{trackSlowQueries,boolean,required,}
+If set to *true*, then slow queries will be tracked
+in the list of slow queries if their runtime exceeds the value set in
+*slowQueryThreshold*. In order for slow queries to be tracked, the *enabled*
+property must also be set to *true*.
+
+@RESTBODYPARAM{trackBindVars,boolean,required,}
+If set to *true*, then the bind variables used in queries will be tracked
+along with queries.
+
+@RESTBODYPARAM{maxSlowQueries,integer,required,int64}
+The maximum number of slow queries to keep in the list
+of slow queries. If the list of slow queries is full, the oldest entry in
+it will be discarded when additional slow queries occur.
+
+@RESTBODYPARAM{slowQueryThreshold,integer,required,int64}
+The threshold value for treating a query as slow. A
+query with a runtime greater or equal to this threshold value will be
+put into the list of slow queries when slow query tracking is enabled.
+The value for *slowQueryThreshold* is specified in seconds.
+
+@RESTBODYPARAM{maxQueryStringLength,integer,required,int64}
+The maximum query string length to keep in the list of queries.
+Query strings can have arbitrary lengths, and this property
+can be used to save memory in case very long query strings are used. The
+value is specified in bytes.
+
+@RESTDESCRIPTION
+The properties need to be passed in the attribute *properties* in the body
+of the HTTP request. *properties* needs to be a JSON object.
+
+After the properties have been changed, the current set of properties will
+be returned in the HTTP response.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+Is returned if the properties were changed successfully.
+
+@RESTRETURNCODE{400}
+The server will respond with *HTTP 400* in case of a malformed request,
+
+@endDocuBlock
+
+
+
+@startDocuBlock delete_api_aqlfunction
+
+@brief remove an existing AQL user function
+
+@RESTHEADER{DELETE /_api/aqlfunction/{name}, Remove existing AQL user function, RestAqlUserFunctionsHandler:Remove}
+
+@RESTURLPARAMETERS
+
+@RESTURLPARAM{name,string,required}
+the name of the AQL user function.
+
+@RESTQUERYPARAMETERS
+
+@RESTQUERYPARAM{group,string,optional}
+- *true*: The function name provided in *name* is treated as
+ a namespace prefix, and all functions in the specified namespace will be deleted.
+ The returned number of deleted functions may become 0 if none matches the string.
+- *false*: The function name provided in *name* must be fully
+ qualified, including any namespaces. If none matches the *name*, HTTP 404 is returned.
+
+@RESTDESCRIPTION
+Removes an existing AQL user function or function group, identified by *name*.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+If the function can be removed by the server, the server will respond with
+*HTTP 200*.
+
+@RESTREPLYBODY{error,boolean,required,}
+boolean flag to indicate whether an error occurred (*false* in this case)
+
+@RESTREPLYBODY{code,integer,required,int64}
+the HTTP status code
+
+@RESTREPLYBODY{deletedCount,integer,required,int64}
+The number of deleted user functions, always `1` when `group` is set to *false*.
+Any number `>= 0` when `group` is set to *true*
+
+@RESTRETURNCODE{400}
+If the user function name is malformed, the server will respond with *HTTP 400*.
+
+@RESTREPLYBODY{error,boolean,required,}
+boolean flag to indicate whether an error occurred (*true* in this case)
+
+@RESTREPLYBODY{code,integer,required,int64}
+the HTTP status code
+
+@RESTREPLYBODY{errorNum,integer,required,int64}
+the server error number
+
+@RESTREPLYBODY{errorMessage,string,required,string}
+a descriptive error message
+
+@RESTRETURNCODE{404}
+If the specified user user function does not exist, the server will respond with *HTTP 404*.
+
+@RESTREPLYBODY{error,boolean,required,}
+boolean flag to indicate whether an error occurred (*true* in this case)
+
+@RESTREPLYBODY{code,integer,required,int64}
+the HTTP status code
+
+@RESTREPLYBODY{errorNum,integer,required,int64}
+the server error number
+
+@RESTREPLYBODY{errorMessage,string,required,string}
+a descriptive error message
+
+@EXAMPLES
+
+deletes a function:
+
+
+
+
+
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/square::x::y
+
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 43
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
+{
"error" : false,
- "code" : 200
+ "code" : 200,
+ "deletedCount" : 1
+}
+
+
Hide response body
+
+
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/square::x::y
+
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 43
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
Show response body
+
+
+
+
+
+
+
+
+function not found:
+
+
+
+
+
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/myfunction::x::y
+
+HTTP/1.1 404 Not Found
+content-type: application/json
+connection: Keep-Alive
+content-length: 114
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
+{
+ "code" : 404,
+ "error" : true,
+ "errorMessage" : "no AQL user function with name 'myfunction::x::y' found",
+ "errorNum" : 1582
}
-
Hide response body
-
+
-shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/myfunction::x::y
+
+HTTP/1.1 404 Not Found
+content-type: application/json
+connection: Keep-Alive
+content-length: 114
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
Show response body
+
+
+
+
+
+@endDocuBlock
+
+
+
+@startDocuBlock get_api_aqlfunction
+
+@brief gets all reqistered AQL user functions
+
+@RESTHEADER{GET /_api/aqlfunction, Return registered AQL user functions, RestAqlUserFunctionsHandler:List}
+
+@RESTQUERYPARAMETERS
+
+@RESTQUERYPARAM{namespace,string,optional}
+Returns all registered AQL user functions from namespace *namespace* under *result*.
+
+@RESTDESCRIPTION
+Returns all registered AQL user functions.
+
+The call will return a JSON array with status codes and all user functions found under *result*.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+on success *HTTP 200* is returned.
+
+@RESTREPLYBODY{error,boolean,required,}
+boolean flag to indicate whether an error occurred (*false* in this case)
+
+@RESTREPLYBODY{code,integer,required,int64}
+the HTTP status code
+
+@RESTREPLYBODY{result,array,required,aql_userfunction_struct}
+All functions, or the ones matching the *namespace* parameter
+
+@RESTSTRUCT{name,aql_userfunction_struct,string,required,}
+The fully qualified name of the user function
+
+@RESTSTRUCT{code,aql_userfunction_struct,string,required,}
+A string representation of the function body
+
+@RESTSTRUCT{isDeterministic,aql_userfunction_struct,boolean,required,}
+an optional boolean value to indicate whether the function
+results are fully deterministic (function return value solely depends on
+the input value and return value is the same for repeated calls with same
+input). The *isDeterministic* attribute is currently not used but may be
+used later for optimizations.
+
+@RESTRETURNCODE{400}
+If the user function name is malformed, the server will respond with *HTTP 400*.
+
+@RESTREPLYBODY{error,boolean,required,}
+boolean flag to indicate whether an error occurred (*true* in this case)
+
+@RESTREPLYBODY{code,integer,required,int64}
+the HTTP status code
+
+@RESTREPLYBODY{errorNum,integer,required,int64}
+the server error number
+
+@RESTREPLYBODY{errorMessage,string,required,string}
+a descriptive error message
+
+@EXAMPLES
+
+
+
+
+
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/test
+
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 38
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
{
- "query" : "FOR p IN products LET a = p.id FILTER a == 4 LET name = p.name SORT p.id LIMIT 1 RETURN name"
+ "error" : false,
+ "code" : 200,
+ "result" : [ ]
}
-EOF
+
+
Hide response body
+
+
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/test
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 2627
+content-length: 38
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -31509,337 +32756,121 @@ x-content-type-options: nosniff
+@endDocuBlock
-Using some options
+
+@startDocuBlock post_api_aqlfunction
+
+@brief create a new AQL user function
-
-
+@RESTHEADER{POST /_api/aqlfunction, Create AQL user function, RestAqlUserFunctionsHandler:create}
+
+@RESTBODYPARAM{name,string,required,string}
+the fully qualified name of the user functions.
+
+@RESTBODYPARAM{code,string,required,string}
+a string representation of the function body.
+
+@RESTBODYPARAM{isDeterministic,boolean,optional,}
+an optional boolean value to indicate whether the function
+results are fully deterministic (function return value solely depends on
+the input value and return value is the same for repeated calls with same
+input). The *isDeterministic* attribute is currently not used but may be
+used later for optimizations.
+
+@RESTDESCRIPTION
+
+In case of success, HTTP 200 is returned.
+If the function isn't valid etc. HTTP 400 including a detailed error message will be returned.
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+If the function already existed and was replaced by the
+call, the server will respond with *HTTP 200*.
+
+@RESTREPLYBODY{error,boolean,required,}
+boolean flag to indicate whether an error occurred (*false* in this case)
+
+@RESTREPLYBODY{code,integer,required,int64}
+the HTTP status code
+
+@RESTREPLYBODY{isNewlyCreated,boolean,required,}
+boolean flag to indicate whether the function was newly created (*false* in this case)
+
+@RESTRETURNCODE{201}
+If the function can be registered by the server, the server will respond with
+*HTTP 201*.
+
+@RESTREPLYBODY{error,boolean,required,}
+boolean flag to indicate whether an error occurred (*false* in this case)
+
+@RESTREPLYBODY{code,integer,required,int64}
+the HTTP status code
+
+@RESTREPLYBODY{isNewlyCreated,boolean,required,}
+boolean flag to indicate whether the function was newly created (*true* in this case)
+
+@RESTRETURNCODE{400}
+If the JSON representation is malformed or mandatory data is missing from the
+request, the server will respond with *HTTP 400*.
+
+@RESTREPLYBODY{error,boolean,required,}
+boolean flag to indicate whether an error occurred (*true* in this case)
+
+@RESTREPLYBODY{code,integer,required,int64}
+the HTTP status code
+
+@RESTREPLYBODY{errorNum,integer,required,int64}
+the server error number
+
+@RESTREPLYBODY{errorMessage,string,required,string}
+a descriptive error message
+
+@EXAMPLES
+
+
+
+
-shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/aqlfunction <<EOF
{
- "query" : "FOR p IN products LET a = p.id FILTER a == 4 LET name = p.name SORT p.id LIMIT 1 RETURN name",
- "options" : {
- "maxNumberOfPlans" : 2,
- "allPlans" : true,
- "optimizer" : {
- "rules" : [
- "-all",
- "+use-index-for-sort",
- "+use-index-range"
- ]
- }
- }
+ "name" : "myfunctions::temperature::celsiustofahrenheit",
+ "code" : "function (celsius) { return celsius * 1.8 + 32; }",
+ "isDeterministic" : true
}
EOF
-HTTP/1.1 200 OK
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 3148
+content-length: 48
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "plans" : [
- {
- "nodes" : [
- {
- "type" : "SingletonNode",
- "dependencies" : [ ],
- "id" : 1,
- "estimatedCost" : 1,
- "estimatedNrItems" : 1
- },
- {
- "type" : "IndexNode",
- "dependencies" : [
- 1
- ],
- "id" : 11,
- "estimatedCost" : 11,
- "estimatedNrItems" : 10,
- "outVariable" : {
- "id" : 0,
- "name" : "p",
- "isDataFromCollection" : true
- },
- "projections" : [ ],
- "count" : false,
- "producesResult" : true,
- "readOwnWrites" : false,
- "maxProjections" : 5,
- "database" : "_system",
- "collection" : "products",
- "satellite" : false,
- "isSatellite" : false,
- "isSatelliteOf" : null,
- "needsGatherNodeSort" : true,
- "indexCoversProjections" : false,
- "indexes" : [
- {
- "id" : "68005",
- "type" : "skiplist",
- "name" : "idx_1769599266981937152",
- "fields" : [
- "id"
- ],
- "selectivityEstimate" : 1,
- "unique" : false,
- "sparse" : false,
- "deduplicate" : true,
- "estimates" : true
- }
- ],
- "condition" : {
- },
- "sorted" : true,
- "ascending" : true,
- "reverse" : false,
- "evalFCalls" : true,
- "limit" : 0
- },
- {
- "type" : "CalculationNode",
- "dependencies" : [
- 11
- ],
- "id" : 3,
- "estimatedCost" : 21,
- "estimatedNrItems" : 10,
- "expression" : {
- "type" : "attribute access",
- "typeID" : 35,
- "name" : "id",
- "subNodes" : [
- {
- "type" : "reference",
- "typeID" : 45,
- "name" : "p",
- "id" : 0
- }
- ]
- },
- "outVariable" : {
- "id" : 1,
- "name" : "a",
- "isDataFromCollection" : false
- },
- "canThrow" : false,
- "expressionType" : "attribute"
- },
- {
- "type" : "CalculationNode",
- "dependencies" : [
- 3
- ],
- "id" : 4,
- "estimatedCost" : 31,
- "estimatedNrItems" : 10,
- "expression" : {
- "type" : "compare ==",
- "typeID" : 25,
- "excludesNull" : false,
- "subNodes" : [
- {
- "type" : "reference",
- "typeID" : 45,
- "name" : "a",
- "id" : 1
- },
- {
- "type" : "value",
- "typeID" : 40,
- "value" : 4,
- "vType" : "int",
- "vTypeID" : 2
- }
- ]
- },
- "outVariable" : {
- "id" : 4,
- "name" : "3",
- "isDataFromCollection" : false
- },
- "canThrow" : false,
- "expressionType" : "simple"
- },
- {
- "type" : "FilterNode",
- "dependencies" : [
- 4
- ],
- "id" : 5,
- "estimatedCost" : 41,
- "estimatedNrItems" : 10,
- "inVariable" : {
- "id" : 4,
- "name" : "3",
- "isDataFromCollection" : false
- }
- },
- {
- "type" : "CalculationNode",
- "dependencies" : [
- 5
- ],
- "id" : 6,
- "estimatedCost" : 51,
- "estimatedNrItems" : 10,
- "expression" : {
- "type" : "attribute access",
- "typeID" : 35,
- "name" : "name",
- "subNodes" : [
- {
- "type" : "reference",
- "typeID" : 45,
- "name" : "p",
- "id" : 0
- }
- ]
- },
- "outVariable" : {
- "id" : 2,
- "name" : "name",
- "isDataFromCollection" : false
- },
- "canThrow" : false,
- "expressionType" : "attribute"
- },
- {
- "type" : "CalculationNode",
- "dependencies" : [
- 6
- ],
- "id" : 7,
- "estimatedCost" : 61,
- "estimatedNrItems" : 10,
- "expression" : {
- "type" : "attribute access",
- "typeID" : 35,
- "name" : "id",
- "subNodes" : [
- {
- "type" : "reference",
- "typeID" : 45,
- "name" : "p",
- "id" : 0
- }
- ]
- },
- "outVariable" : {
- "id" : 6,
- "name" : "5",
- "isDataFromCollection" : false
- },
- "canThrow" : false,
- "expressionType" : "attribute"
- },
- {
- "type" : "LimitNode",
- "dependencies" : [
- 7
- ],
- "id" : 9,
- "estimatedCost" : 62,
- "estimatedNrItems" : 1,
- "offset" : 0,
- "limit" : 1,
- "fullCount" : false
- },
- {
- "type" : "ReturnNode",
- "dependencies" : [
- 9
- ],
- "id" : 10,
- "estimatedCost" : 63,
- "estimatedNrItems" : 1,
- "inVariable" : {
- "id" : 2,
- "name" : "name",
- "isDataFromCollection" : false
- },
- "count" : true
- }
- ],
- "rules" : [
- "use-index-for-sort"
- ],
- "collections" : [
- {
- "name" : "products",
- "type" : "read"
- }
- ],
- "variables" : [
- {
- "id" : 6,
- "name" : "5",
- "isDataFromCollection" : false
- },
- {
- "id" : 4,
- "name" : "3",
- "isDataFromCollection" : false
- },
- {
- "id" : 2,
- "name" : "name",
- "isDataFromCollection" : false
- },
- {
- "id" : 1,
- "name" : "a",
- "isDataFromCollection" : false
- },
- {
- "id" : 0,
- "name" : "p",
- "isDataFromCollection" : true
- }
- ],
- "estimatedCost" : 63,
- "estimatedNrItems" : 1,
- "isModificationQuery" : false
- }
- ],
- "warnings" : [ ],
- "stats" : {
- "rulesExecuted" : 4,
- "rulesSkipped" : 37,
- "plansCreated" : 1
- },
"error" : false,
- "code" : 200
+ "code" : 201,
+ "isNewlyCreated" : true
}
-
Hide response body
-
+
-shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
-{
- "query" : "FOR p IN products LET a = p.id FILTER a == 4 LET name = p.name SORT p.id LIMIT 1 RETURN name",
- "options" : {
- "maxNumberOfPlans" : 2,
- "allPlans" : true,
- "optimizer" : {
- "rules" : [
- "-all",
- "+use-index-for-sort",
- "+use-index-range"
- ]
- }
- }
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/aqlfunction <<EOF
+{
+ "name" : "myfunctions::temperature::celsiustofahrenheit",
+ "code" : "function (celsius) { return celsius * 1.8 + 32; }",
+ "isDeterministic" : true
}
EOF
-HTTP/1.1 200 OK
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 3148
+content-length: 48
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -31850,170 +32881,203 @@ x-content-type-options: nosniff
+@endDocuBlock
-Returning all plans
+
+@startDocuBlock post_api_explain
-
-
+@brief explain an AQL query and return information about it
+
+@RESTHEADER{POST /_api/explain, Explain an AQL query, explainQuery}
+
+A JSON object describing the query and query parameters.
+
+@RESTBODYPARAM{query,string,required,string}
+the query which you want explained; If the query references any bind variables,
+these must also be passed in the attribute *bindVars*. Additional
+options for the query can be passed in the *options* attribute.
+
+@RESTBODYPARAM{bindVars,array,optional,object}
+key/value pairs representing the bind parameters.
+
+@RESTBODYPARAM{options,object,optional,explain_options}
+Options for the query
+
+@RESTSTRUCT{allPlans,explain_options,boolean,optional,}
+if set to *true*, all possible execution plans will be returned.
+The default is *false*, meaning only the optimal plan will be returned.
+
+@RESTSTRUCT{maxNumberOfPlans,explain_options,integer,optional,int64}
+an optional maximum number of plans that the optimizer is
+allowed to generate. Setting this attribute to a low value allows to put a
+cap on the amount of work the optimizer does.
+
+@RESTSTRUCT{optimizer,explain_options,object,optional,explain_options_optimizer}
+Options related to the query optimizer.
+
+@RESTSTRUCT{rules,explain_options_optimizer,array,optional,string}
+A list of to-be-included or to-be-excluded optimizer rules can be put into this
+attribute, telling the optimizer to include or exclude specific rules. To disable
+a rule, prefix its name with a `-`, to enable a rule, prefix it with a `+`. There is
+also a pseudo-rule `all`, which matches all optimizer rules. `-all` disables all rules.
+
+@RESTDESCRIPTION
+
+To explain how an AQL query would be executed on the server, the query string
+can be sent to the server via an HTTP POST request. The server will then validate
+the query and create an execution plan for it. The execution plan will be
+returned, but the query will not be executed.
+
+The execution plan that is returned by the server can be used to estimate the
+probable performance of the query. Though the actual performance will depend
+on many different factors, the execution plan normally can provide some rough
+estimates on the amount of work the server needs to do in order to actually run
+the query.
+
+By default, the explain operation will return the optimal plan as chosen by
+the query optimizer The optimal plan is the plan with the lowest total estimated
+cost. The plan will be returned in the attribute *plan* of the response object.
+If the option *allPlans* is specified in the request, the result will contain
+all plans created by the optimizer. The plans will then be returned in the
+attribute *plans*.
+
+The result will also contain an attribute *warnings*, which is an array of
+warnings that occurred during optimization or execution plan creation. Additionally,
+a *stats* attribute is contained in the result with some optimizer statistics.
+If *allPlans* is set to *false*, the result will contain an attribute *cacheable*
+that states whether the query results can be cached on the server if the query
+result cache were used. The *cacheable* attribute is not present when *allPlans*
+is set to *true*.
+
+Each plan in the result is a JSON object with the following attributes:
+- *nodes*: the array of execution nodes of the plan.
+
+- *estimatedCost*: the total estimated cost for the plan. If there are multiple
+ plans, the optimizer will choose the plan with the lowest total cost.
+
+- *collections*: an array of collections used in the query
+
+- *rules*: an array of rules the optimizer applied.
+
+- *variables*: array of variables used in the query (note: this may contain
+ internal variables created by the optimizer)
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+If the query is valid, the server will respond with *HTTP 200* and
+return the optimal execution plan in the *plan* attribute of the response.
+If option *allPlans* was set in the request, an array of plans will be returned
+in the *allPlans* attribute instead.
+
+@RESTRETURNCODE{400}
+The server will respond with *HTTP 400* in case of a malformed request,
+or if the query contains a parse error. The body of the response will
+contain the error details embedded in a JSON object.
+Omitting bind variables if the query references any will also result
+in an *HTTP 400* error.
+
+@RESTRETURNCODE{404}
+The server will respond with *HTTP 404* in case a non-existing collection is
+accessed in the query.
+
+@EXAMPLES
+
+Valid query
+
+
+
+
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{
- "query" : "FOR p IN products FILTER p.id == 25 RETURN p",
- "options" : {
- "allPlans" : true
- }
+ "query" : "FOR p IN products RETURN p"
}
EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 1709
+content-length: 1003
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "plans" : [
- {
- "nodes" : [
- {
- "type" : "SingletonNode",
- "dependencies" : [ ],
- "id" : 1,
- "estimatedCost" : 1,
- "estimatedNrItems" : 1
- },
- {
- "type" : "IndexNode",
- "dependencies" : [
- 1
- ],
- "id" : 6,
- "estimatedCost" : 1,
- "estimatedNrItems" : 0,
- "outVariable" : {
- "id" : 0,
- "name" : "p",
- "isDataFromCollection" : true
- },
- "projections" : [ ],
- "count" : false,
- "producesResult" : true,
- "readOwnWrites" : false,
- "maxProjections" : 5,
- "database" : "_system",
- "collection" : "products",
- "satellite" : false,
- "isSatellite" : false,
- "isSatelliteOf" : null,
- "needsGatherNodeSort" : false,
- "indexCoversProjections" : false,
- "indexes" : [
- {
- "id" : "67941",
- "type" : "hash",
- "name" : "idx_1769599266942091264",
- "fields" : [
- "id"
- ],
- "selectivityEstimate" : 1,
- "unique" : false,
- "sparse" : false,
- "deduplicate" : true,
- "estimates" : true
- }
- ],
- "condition" : {
- "type" : "n-ary or",
- "typeID" : 63,
- "subNodes" : [
- {
- "type" : "n-ary and",
- "typeID" : 62,
- "subNodes" : [
- {
- "type" : "compare ==",
- "typeID" : 25,
- "excludesNull" : false,
- "subNodes" : [
- {
- "type" : "attribute access",
- "typeID" : 35,
- "name" : "id",
- "subNodes" : [
- {
- "type" : "reference",
- "typeID" : 45,
- "name" : "p",
- "id" : 0
- }
- ]
- },
- {
- "type" : "value",
- "typeID" : 40,
- "value" : 25,
- "vType" : "int",
- "vTypeID" : 2
- }
- ]
- }
- ]
- }
- ]
- },
- "sorted" : true,
- "ascending" : true,
- "reverse" : false,
- "evalFCalls" : true,
- "limit" : 0
+ "plan" : {
+ "nodes" : [
+ {
+ "type" : "SingletonNode",
+ "dependencies" : [ ],
+ "id" : 1,
+ "estimatedCost" : 1,
+ "estimatedNrItems" : 1
+ },
+ {
+ "type" : "EnumerateCollectionNode",
+ "dependencies" : [
+ 1
+ ],
+ "id" : 2,
+ "estimatedCost" : 12,
+ "estimatedNrItems" : 10,
+ "random" : false,
+ "indexHint" : {
+ "forced" : false,
+ "type" : "none"
},
- {
- "type" : "ReturnNode",
- "dependencies" : [
- 6
- ],
- "id" : 5,
- "estimatedCost" : 1,
- "estimatedNrItems" : 0,
- "inVariable" : {
- "id" : 0,
- "name" : "p",
- "isDataFromCollection" : true
- },
- "count" : true
- }
- ],
- "rules" : [
- "use-indexes",
- "remove-filter-covered-by-index",
- "remove-unnecessary-calculations-2"
- ],
- "collections" : [
- {
- "name" : "products",
- "type" : "read"
- }
- ],
- "variables" : [
- {
- "id" : 2,
- "name" : "1",
- "isDataFromCollection" : false
+ "outVariable" : {
+ "id" : 0,
+ "name" : "p",
+ "isDataFromCollection" : true
},
- {
+ "projections" : [ ],
+ "count" : false,
+ "producesResult" : true,
+ "readOwnWrites" : false,
+ "maxProjections" : 5,
+ "database" : "_system",
+ "collection" : "products",
+ "satellite" : false,
+ "isSatellite" : false,
+ "isSatelliteOf" : null
+ },
+ {
+ "type" : "ReturnNode",
+ "dependencies" : [
+ 2
+ ],
+ "id" : 3,
+ "estimatedCost" : 22,
+ "estimatedNrItems" : 10,
+ "inVariable" : {
"id" : 0,
"name" : "p",
"isDataFromCollection" : true
- }
- ],
- "estimatedCost" : 1,
- "estimatedNrItems" : 0,
- "isModificationQuery" : false
- }
- ],
+ },
+ "count" : true
+ }
+ ],
+ "rules" : [ ],
+ "collections" : [
+ {
+ "name" : "products",
+ "type" : "read"
+ }
+ ],
+ "variables" : [
+ {
+ "id" : 0,
+ "name" : "p",
+ "isDataFromCollection" : true
+ }
+ ],
+ "estimatedCost" : 22,
+ "estimatedNrItems" : 10,
+ "isModificationQuery" : false
+ },
+ "cacheable" : true,
"warnings" : [ ],
"stats" : {
"rulesExecuted" : 41,
@@ -32024,22 +33088,19 @@ x-content-type-options: nosniff
"code" : 200
}
-
Hide response body
-
+
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{
- "query" : "FOR p IN products FILTER p.id == 25 RETURN p",
- "options" : {
- "allPlans" : true
- }
+ "query" : "FOR p IN products RETURN p"
}
EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 1709
+content-length: 1003
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -32051,22 +33112,22 @@ x-content-type-options: nosniff
-A query that produces a warning
+A plan with some optimizer rules applied
-
-
+
+
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{
- "query" : "FOR i IN 1..10 RETURN 1 / 0"
+ "query" : "FOR p IN products LET a = p.id FILTER a == 4 LET name = p.name SORT p.id LIMIT 1 RETURN name"
}
EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 1686
+content-length: 2627
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -32082,137 +33143,202 @@ x-content-type-options: nosniff
"estimatedNrItems" : 1
},
{
- "type" : "CalculationNode",
+ "type" : "IndexNode",
"dependencies" : [
1
],
- "id" : 2,
- "estimatedCost" : 2,
+ "id" : 11,
+ "estimatedCost" : 4.3719280948873624,
"estimatedNrItems" : 1,
- "expression" : {
- "type" : "range",
- "typeID" : 49,
+ "outVariable" : {
+ "id" : 0,
+ "name" : "p",
+ "isDataFromCollection" : true
+ },
+ "projections" : [
+ "name"
+ ],
+ "count" : false,
+ "producesResult" : true,
+ "readOwnWrites" : false,
+ "maxProjections" : 5,
+ "database" : "_system",
+ "collection" : "products",
+ "satellite" : false,
+ "isSatellite" : false,
+ "isSatelliteOf" : null,
+ "needsGatherNodeSort" : true,
+ "indexCoversProjections" : false,
+ "indexes" : [
+ {
+ "id" : "67972",
+ "type" : "skiplist",
+ "name" : "idx_1775847842073542657",
+ "fields" : [
+ "id"
+ ],
+ "selectivityEstimate" : 1,
+ "unique" : false,
+ "sparse" : false,
+ "deduplicate" : true,
+ "estimates" : true
+ }
+ ],
+ "condition" : {
+ "type" : "n-ary or",
+ "typeID" : 63,
"subNodes" : [
{
- "type" : "value",
- "typeID" : 40,
- "value" : 1,
- "vType" : "int",
- "vTypeID" : 2
- },
- {
- "type" : "value",
- "typeID" : 40,
- "value" : 10,
- "vType" : "int",
- "vTypeID" : 2
+ "type" : "n-ary and",
+ "typeID" : 62,
+ "subNodes" : [
+ {
+ "type" : "compare ==",
+ "typeID" : 25,
+ "excludesNull" : false,
+ "subNodes" : [
+ {
+ "type" : "attribute access",
+ "typeID" : 35,
+ "name" : "id",
+ "subNodes" : [
+ {
+ "type" : "reference",
+ "typeID" : 45,
+ "name" : "p",
+ "id" : 0
+ }
+ ]
+ },
+ {
+ "type" : "value",
+ "typeID" : 40,
+ "value" : 4,
+ "vType" : "int",
+ "vTypeID" : 2
+ }
+ ]
+ }
+ ]
}
]
},
- "outVariable" : {
- "id" : 2,
- "name" : "1",
- "isDataFromCollection" : false
- },
- "canThrow" : false,
- "expressionType" : "simple"
+ "sorted" : true,
+ "ascending" : true,
+ "reverse" : false,
+ "evalFCalls" : true,
+ "limit" : 0
},
{
- "type" : "CalculationNode",
+ "type" : "LimitNode",
"dependencies" : [
- 2
+ 11
],
- "id" : 4,
- "estimatedCost" : 3,
+ "id" : 9,
+ "estimatedCost" : 5.3719280948873624,
"estimatedNrItems" : 1,
- "expression" : {
- "type" : "value",
- "typeID" : 40,
- "value" : null,
- "vType" : "null",
- "vTypeID" : 0
- },
- "outVariable" : {
- "id" : 4,
- "name" : "3",
- "isDataFromCollection" : false,
- "constantValue" : null
- },
- "canThrow" : false,
- "expressionType" : "json"
+ "offset" : 0,
+ "limit" : 1,
+ "fullCount" : false
},
{
- "type" : "EnumerateListNode",
+ "type" : "CalculationNode",
"dependencies" : [
- 4
+ 9
],
- "id" : 3,
- "estimatedCost" : 13,
- "estimatedNrItems" : 10,
- "inVariable" : {
- "id" : 2,
- "name" : "1",
- "isDataFromCollection" : false
+ "id" : 6,
+ "estimatedCost" : 6.3719280948873624,
+ "estimatedNrItems" : 1,
+ "expression" : {
+ "type" : "attribute access",
+ "typeID" : 35,
+ "name" : "name",
+ "subNodes" : [
+ {
+ "type" : "reference",
+ "typeID" : 45,
+ "name" : "p",
+ "id" : 0
+ }
+ ]
},
"outVariable" : {
- "id" : 0,
- "name" : "i",
+ "id" : 2,
+ "name" : "name",
"isDataFromCollection" : false
- }
+ },
+ "canThrow" : false,
+ "expressionType" : "attribute"
},
{
"type" : "ReturnNode",
"dependencies" : [
- 3
+ 6
],
- "id" : 5,
- "estimatedCost" : 23,
- "estimatedNrItems" : 10,
+ "id" : 10,
+ "estimatedCost" : 7.3719280948873624,
+ "estimatedNrItems" : 1,
"inVariable" : {
- "id" : 4,
- "name" : "3",
- "isDataFromCollection" : false,
- "constantValue" : null
+ "id" : 2,
+ "name" : "name",
+ "isDataFromCollection" : false
},
"count" : true
}
],
"rules" : [
"move-calculations-up",
- "move-calculations-up-2"
+ "remove-redundant-calculations",
+ "remove-unnecessary-calculations",
+ "move-calculations-up-2",
+ "use-indexes",
+ "remove-filter-covered-by-index",
+ "use-index-for-sort",
+ "remove-unnecessary-calculations-2",
+ "move-calculations-down",
+ "reduce-extraction-to-projection"
+ ],
+ "collections" : [
+ {
+ "name" : "products",
+ "type" : "read"
+ }
],
- "collections" : [ ],
"variables" : [
+ {
+ "id" : 6,
+ "name" : "5",
+ "isDataFromCollection" : false
+ },
{
"id" : 4,
"name" : "3",
- "isDataFromCollection" : false,
- "constantValue" : null
+ "isDataFromCollection" : false
},
{
"id" : 2,
- "name" : "1",
+ "name" : "name",
"isDataFromCollection" : false
},
{
- "id" : 0,
- "name" : "i",
+ "id" : 1,
+ "name" : "a",
"isDataFromCollection" : false
+ },
+ {
+ "id" : 0,
+ "name" : "p",
+ "isDataFromCollection" : true
}
],
- "estimatedCost" : 23,
- "estimatedNrItems" : 10,
+ "estimatedCost" : 7.3719280948873624,
+ "estimatedNrItems" : 1,
"isModificationQuery" : false
},
- "cacheable" : false,
- "warnings" : [
- {
- "code" : 1562,
- "message" : "division by zero"
- }
- ],
+ "cacheable" : true,
+ "warnings" : [ ],
"stats" : {
- "rulesExecuted" : 41,
+ "rulesExecuted" : 43,
"rulesSkipped" : 0,
"plansCreated" : 1
},
@@ -32220,19 +33346,19 @@ x-content-type-options: nosniff
"code" : 200
}
-
Hide response body
-
+
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{
- "query" : "FOR i IN 1..10 RETURN 1 / 0"
+ "query" : "FOR p IN products LET a = p.id FILTER a == 4 LET name = p.name SORT p.id LIMIT 1 RETURN name"
}
EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 1686
+content-length: 2627
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -32244,232 +33370,336 @@ x-content-type-options: nosniff
-Invalid query (missing bind parameter)
-
-
-
-
-
-shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
-{
- "query" : "FOR p IN products FILTER p.id == @id LIMIT 2 RETURN p.n"
-}
-EOF
+Using some options
-HTTP/1.1 400 Bad Request
-content-type: application/json
-connection: Keep-Alive
-content-length: 126
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-{
- "code" : 400,
- "error" : true,
- "errorMessage" : "no value specified for declared bind parameter 'id' (while parsing)",
- "errorNum" : 1551
-}
-
-
Hide response body
-
+
+
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{
- "query" : "FOR p IN products FILTER p.id == @id LIMIT 2 RETURN p.n"
+ "query" : "FOR p IN products LET a = p.id FILTER a == 4 LET name = p.name SORT p.id LIMIT 1 RETURN name",
+ "options" : {
+ "maxNumberOfPlans" : 2,
+ "allPlans" : true,
+ "optimizer" : {
+ "rules" : [
+ "-all",
+ "+use-index-for-sort",
+ "+use-index-range"
+ ]
+ }
+ }
}
EOF
-HTTP/1.1 400 Bad Request
-content-type: application/json
-connection: Keep-Alive
-content-length: 126
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-Show response body
-
-
-
-
-
-
-
-The data returned in the **plan** attribute of the result contains one element per AQL top-level statement
-(i.e. `FOR`, `RETURN`, `FILTER` etc.). If the query optimizer removed some unnecessary statements,
-the result might also contain less elements than there were top-level statements in the AQL query.
-
-The following example shows a query with a non-sensible filter condition that
-the optimizer has removed so that there are less top-level statements.
-
-
-
-
-
-shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
-{ "query" : "FOR i IN [ 1, 2, 3 ] FILTER 1 == 2 RETURN i" }
-EOF
-
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 1430
+content-length: 3148
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "plan" : {
- "nodes" : [
- {
- "type" : "SingletonNode",
- "dependencies" : [ ],
- "id" : 1,
- "estimatedCost" : 1,
- "estimatedNrItems" : 1
- },
- {
- "type" : "CalculationNode",
- "dependencies" : [
- 1
- ],
- "id" : 2,
- "estimatedCost" : 2,
- "estimatedNrItems" : 1,
- "expression" : {
- "type" : "array",
- "typeID" : 41,
- "subNodes" : [
- {
- "type" : "value",
- "typeID" : 40,
- "value" : 1,
- "vType" : "int",
- "vTypeID" : 2
- },
- {
- "type" : "value",
- "typeID" : 40,
- "value" : 2,
- "vType" : "int",
- "vTypeID" : 2
- },
+ "plans" : [
+ {
+ "nodes" : [
+ {
+ "type" : "SingletonNode",
+ "dependencies" : [ ],
+ "id" : 1,
+ "estimatedCost" : 1,
+ "estimatedNrItems" : 1
+ },
+ {
+ "type" : "IndexNode",
+ "dependencies" : [
+ 1
+ ],
+ "id" : 11,
+ "estimatedCost" : 11,
+ "estimatedNrItems" : 10,
+ "outVariable" : {
+ "id" : 0,
+ "name" : "p",
+ "isDataFromCollection" : true
+ },
+ "projections" : [ ],
+ "count" : false,
+ "producesResult" : true,
+ "readOwnWrites" : false,
+ "maxProjections" : 5,
+ "database" : "_system",
+ "collection" : "products",
+ "satellite" : false,
+ "isSatellite" : false,
+ "isSatelliteOf" : null,
+ "needsGatherNodeSort" : true,
+ "indexCoversProjections" : false,
+ "indexes" : [
{
- "type" : "value",
- "typeID" : 40,
- "value" : 3,
- "vType" : "int",
- "vTypeID" : 2
+ "id" : "68005",
+ "type" : "skiplist",
+ "name" : "idx_1775847842081931264",
+ "fields" : [
+ "id"
+ ],
+ "selectivityEstimate" : 1,
+ "unique" : false,
+ "sparse" : false,
+ "deduplicate" : true,
+ "estimates" : true
}
- ]
+ ],
+ "condition" : {
+ },
+ "sorted" : true,
+ "ascending" : true,
+ "reverse" : false,
+ "evalFCalls" : true,
+ "limit" : 0
},
- "outVariable" : {
- "id" : 2,
- "name" : "1",
- "isDataFromCollection" : false,
- "constantValue" : [
- 1,
- 2,
- 3
- ]
+ {
+ "type" : "CalculationNode",
+ "dependencies" : [
+ 11
+ ],
+ "id" : 3,
+ "estimatedCost" : 21,
+ "estimatedNrItems" : 10,
+ "expression" : {
+ "type" : "attribute access",
+ "typeID" : 35,
+ "name" : "id",
+ "subNodes" : [
+ {
+ "type" : "reference",
+ "typeID" : 45,
+ "name" : "p",
+ "id" : 0
+ }
+ ]
+ },
+ "outVariable" : {
+ "id" : 1,
+ "name" : "a",
+ "isDataFromCollection" : false
+ },
+ "canThrow" : false,
+ "expressionType" : "attribute"
},
- "canThrow" : false,
- "expressionType" : "json"
- },
- {
- "type" : "EnumerateListNode",
- "dependencies" : [
- 2
- ],
- "id" : 3,
- "estimatedCost" : 5,
- "estimatedNrItems" : 3,
- "inVariable" : {
- "id" : 2,
- "name" : "1",
- "isDataFromCollection" : false,
- "constantValue" : [
- 1,
- 2,
+ {
+ "type" : "CalculationNode",
+ "dependencies" : [
3
- ]
+ ],
+ "id" : 4,
+ "estimatedCost" : 31,
+ "estimatedNrItems" : 10,
+ "expression" : {
+ "type" : "compare ==",
+ "typeID" : 25,
+ "excludesNull" : false,
+ "subNodes" : [
+ {
+ "type" : "reference",
+ "typeID" : 45,
+ "name" : "a",
+ "id" : 1
+ },
+ {
+ "type" : "value",
+ "typeID" : 40,
+ "value" : 4,
+ "vType" : "int",
+ "vTypeID" : 2
+ }
+ ]
+ },
+ "outVariable" : {
+ "id" : 4,
+ "name" : "3",
+ "isDataFromCollection" : false
+ },
+ "canThrow" : false,
+ "expressionType" : "simple"
},
- "outVariable" : {
- "id" : 0,
- "name" : "i",
- "isDataFromCollection" : false
+ {
+ "type" : "FilterNode",
+ "dependencies" : [
+ 4
+ ],
+ "id" : 5,
+ "estimatedCost" : 41,
+ "estimatedNrItems" : 10,
+ "inVariable" : {
+ "id" : 4,
+ "name" : "3",
+ "isDataFromCollection" : false
+ }
+ },
+ {
+ "type" : "CalculationNode",
+ "dependencies" : [
+ 5
+ ],
+ "id" : 6,
+ "estimatedCost" : 51,
+ "estimatedNrItems" : 10,
+ "expression" : {
+ "type" : "attribute access",
+ "typeID" : 35,
+ "name" : "name",
+ "subNodes" : [
+ {
+ "type" : "reference",
+ "typeID" : 45,
+ "name" : "p",
+ "id" : 0
+ }
+ ]
+ },
+ "outVariable" : {
+ "id" : 2,
+ "name" : "name",
+ "isDataFromCollection" : false
+ },
+ "canThrow" : false,
+ "expressionType" : "attribute"
+ },
+ {
+ "type" : "CalculationNode",
+ "dependencies" : [
+ 6
+ ],
+ "id" : 7,
+ "estimatedCost" : 61,
+ "estimatedNrItems" : 10,
+ "expression" : {
+ "type" : "attribute access",
+ "typeID" : 35,
+ "name" : "id",
+ "subNodes" : [
+ {
+ "type" : "reference",
+ "typeID" : 45,
+ "name" : "p",
+ "id" : 0
+ }
+ ]
+ },
+ "outVariable" : {
+ "id" : 6,
+ "name" : "5",
+ "isDataFromCollection" : false
+ },
+ "canThrow" : false,
+ "expressionType" : "attribute"
+ },
+ {
+ "type" : "LimitNode",
+ "dependencies" : [
+ 7
+ ],
+ "id" : 9,
+ "estimatedCost" : 62,
+ "estimatedNrItems" : 1,
+ "offset" : 0,
+ "limit" : 1,
+ "fullCount" : false
+ },
+ {
+ "type" : "ReturnNode",
+ "dependencies" : [
+ 9
+ ],
+ "id" : 10,
+ "estimatedCost" : 63,
+ "estimatedNrItems" : 1,
+ "inVariable" : {
+ "id" : 2,
+ "name" : "name",
+ "isDataFromCollection" : false
+ },
+ "count" : true
}
- },
- {
- "type" : "NoResultsNode",
- "dependencies" : [
- 3
- ],
- "id" : 4,
- "estimatedCost" : 0.5,
- "estimatedNrItems" : 0
- },
- {
- "type" : "ReturnNode",
- "dependencies" : [
- 4
- ],
- "id" : 5,
- "estimatedCost" : 0.5,
- "estimatedNrItems" : 0,
- "inVariable" : {
- "id" : 0,
- "name" : "i",
+ ],
+ "rules" : [
+ "use-index-for-sort"
+ ],
+ "collections" : [
+ {
+ "name" : "products",
+ "type" : "read"
+ }
+ ],
+ "variables" : [
+ {
+ "id" : 6,
+ "name" : "5",
"isDataFromCollection" : false
},
- "count" : true
- }
- ],
- "rules" : [ ],
- "collections" : [ ],
- "variables" : [
- {
- "id" : 2,
- "name" : "1",
- "isDataFromCollection" : false,
- "constantValue" : [
- 1,
- 2,
- 3
- ]
- },
- {
- "id" : 0,
- "name" : "i",
- "isDataFromCollection" : false
- }
- ],
- "estimatedCost" : 0.5,
- "estimatedNrItems" : 0,
- "isModificationQuery" : false
- },
- "cacheable" : true,
+ {
+ "id" : 4,
+ "name" : "3",
+ "isDataFromCollection" : false
+ },
+ {
+ "id" : 2,
+ "name" : "name",
+ "isDataFromCollection" : false
+ },
+ {
+ "id" : 1,
+ "name" : "a",
+ "isDataFromCollection" : false
+ },
+ {
+ "id" : 0,
+ "name" : "p",
+ "isDataFromCollection" : true
+ }
+ ],
+ "estimatedCost" : 63,
+ "estimatedNrItems" : 1,
+ "isModificationQuery" : false
+ }
+ ],
"warnings" : [ ],
"stats" : {
- "rulesExecuted" : 41,
- "rulesSkipped" : 0,
+ "rulesExecuted" : 4,
+ "rulesSkipped" : 37,
"plansCreated" : 1
},
"error" : false,
"code" : 200
}
-
Hide response body
-
+
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
-{ "query" : "FOR i IN [ 1, 2, 3 ] FILTER 1 == 2 RETURN i" }
+{
+ "query" : "FOR p IN products LET a = p.id FILTER a == 4 LET name = p.name SORT p.id LIMIT 1 RETURN name",
+ "options" : {
+ "maxNumberOfPlans" : 2,
+ "allPlans" : true,
+ "optimizer" : {
+ "rules" : [
+ "-all",
+ "+use-index-for-sort",
+ "+use-index-range"
+ ]
+ }
+ }
+}
EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 1430
+content-length: 3148
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -32480,355 +33710,196 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-
-
-@startDocuBlock job_cancel
-
-@brief cancels an async job
-
-@RESTHEADER{PUT /_api/job/{job-id}/cancel, Cancel async job, putJobMethod:cancel}
-
-@RESTURLPARAMETERS
-
-@RESTURLPARAM{job-id,string,required}
-The async job id.
-
-@RESTDESCRIPTION
-Cancels the currently running job identified by job-id. Note that it still
-might take some time to actually cancel the running async job.
-
-@RESTRETURNCODES
-
-@RESTRETURNCODE{200}
-cancel has been initiated.
-
-@RESTRETURNCODE{400}
-is returned if no job-id was specified in the request. In this case,
-no x-arango-async-id HTTP header will be returned.
-
-@RESTRETURNCODE{404}
-is returned if the job was not found or already deleted or fetched from
-the job result list. In this case, no x-arango-async-id HTTP header will
-be returned.
-@EXAMPLES
+Returning all plans
-
-
+
+
-shell> curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/cursor <<EOF
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{
- "query" : "FOR i IN 1..10 FOR j IN 1..10 LET x = sleep(1.0) FILTER i == 5 && j == 5 RETURN 42"
+ "query" : "FOR p IN products FILTER p.id == 25 RETURN p",
+ "options" : {
+ "allPlans" : true
+ }
}
EOF
-HTTP/1.1 202 Accepted
-content-type: text/plain
-connection: Keep-Alive
-content-length: 0
-server: ArangoDB
-x-arango-async-id: 81805
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 9
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
-[
- "81805"
-]
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81805/cancel
-
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 15
+content-length: 1709
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "result" : true
+ "plans" : [
+ {
+ "nodes" : [
+ {
+ "type" : "SingletonNode",
+ "dependencies" : [ ],
+ "id" : 1,
+ "estimatedCost" : 1,
+ "estimatedNrItems" : 1
+ },
+ {
+ "type" : "IndexNode",
+ "dependencies" : [
+ 1
+ ],
+ "id" : 6,
+ "estimatedCost" : 1,
+ "estimatedNrItems" : 0,
+ "outVariable" : {
+ "id" : 0,
+ "name" : "p",
+ "isDataFromCollection" : true
+ },
+ "projections" : [ ],
+ "count" : false,
+ "producesResult" : true,
+ "readOwnWrites" : false,
+ "maxProjections" : 5,
+ "database" : "_system",
+ "collection" : "products",
+ "satellite" : false,
+ "isSatellite" : false,
+ "isSatelliteOf" : null,
+ "needsGatherNodeSort" : false,
+ "indexCoversProjections" : false,
+ "indexes" : [
+ {
+ "id" : "67941",
+ "type" : "hash",
+ "name" : "idx_1775847842059911169",
+ "fields" : [
+ "id"
+ ],
+ "selectivityEstimate" : 1,
+ "unique" : false,
+ "sparse" : false,
+ "deduplicate" : true,
+ "estimates" : true
+ }
+ ],
+ "condition" : {
+ "type" : "n-ary or",
+ "typeID" : 63,
+ "subNodes" : [
+ {
+ "type" : "n-ary and",
+ "typeID" : 62,
+ "subNodes" : [
+ {
+ "type" : "compare ==",
+ "typeID" : 25,
+ "excludesNull" : false,
+ "subNodes" : [
+ {
+ "type" : "attribute access",
+ "typeID" : 35,
+ "name" : "id",
+ "subNodes" : [
+ {
+ "type" : "reference",
+ "typeID" : 45,
+ "name" : "p",
+ "id" : 0
+ }
+ ]
+ },
+ {
+ "type" : "value",
+ "typeID" : 40,
+ "value" : 25,
+ "vType" : "int",
+ "vTypeID" : 2
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ "sorted" : true,
+ "ascending" : true,
+ "reverse" : false,
+ "evalFCalls" : true,
+ "limit" : 0
+ },
+ {
+ "type" : "ReturnNode",
+ "dependencies" : [
+ 6
+ ],
+ "id" : 5,
+ "estimatedCost" : 1,
+ "estimatedNrItems" : 0,
+ "inVariable" : {
+ "id" : 0,
+ "name" : "p",
+ "isDataFromCollection" : true
+ },
+ "count" : true
+ }
+ ],
+ "rules" : [
+ "use-indexes",
+ "remove-filter-covered-by-index",
+ "remove-unnecessary-calculations-2"
+ ],
+ "collections" : [
+ {
+ "name" : "products",
+ "type" : "read"
+ }
+ ],
+ "variables" : [
+ {
+ "id" : 2,
+ "name" : "1",
+ "isDataFromCollection" : false
+ },
+ {
+ "id" : 0,
+ "name" : "p",
+ "isDataFromCollection" : true
+ }
+ ],
+ "estimatedCost" : 1,
+ "estimatedNrItems" : 0,
+ "isModificationQuery" : false
+ }
+ ],
+ "warnings" : [ ],
+ "stats" : {
+ "rulesExecuted" : 41,
+ "rulesSkipped" : 0,
+ "plansCreated" : 1
+ },
+ "error" : false,
+ "code" : 200
}
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 9
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
-[
- "81805"
-]
-
Hide response body
-
+
-shell> curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/cursor <<EOF
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
{
- "query" : "FOR i IN 1..10 FOR j IN 1..10 LET x = sleep(1.0) FILTER i == 5 && j == 5 RETURN 42"
+ "query" : "FOR p IN products FILTER p.id == 25 RETURN p",
+ "options" : {
+ "allPlans" : true
+ }
}
EOF
-HTTP/1.1 202 Accepted
-content-type: text/plain
-connection: Keep-Alive
-content-length: 0
-server: ArangoDB
-x-arango-async-id: 81805
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 9
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81805/cancel
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 15
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 9
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-Show response body
-
-
-
-
-
-
-
-@endDocuBlock
-
-
-
-@startDocuBlock job_delete
-
-@brief deletes an async job result
-
-@RESTHEADER{DELETE /_api/job/{type}#by-type, Deletes async job, deleteJob:byType}
-
-@RESTURLPARAMETERS
-
-@RESTURLPARAM{type,string,required}
-The type of jobs to delete. type can be:
-* *all*: Deletes all jobs results. Currently executing or queued async
- jobs will not be stopped by this call.
-* *expired*: Deletes expired results. To determine the expiration status of a
- result, pass the stamp query parameter. stamp needs to be a UNIX timestamp,
- and all async job results created at a lower timestamp will be deleted.
-* *an actual job-id*: In this case, the call will remove the result of the
- specified async job. If the job is currently executing or queued, it will
- not be aborted.
-
-@RESTQUERYPARAMETERS
-
-@RESTQUERYPARAM{stamp,number,optional}
-A UNIX timestamp specifying the expiration threshold when type is expired.
-
-@RESTDESCRIPTION
-Deletes either all job results, expired job results, or the result of a
-specific job.
-Clients can use this method to perform an eventual garbage collection of job
-results.
-
-@RESTRETURNCODES
-
-@RESTRETURNCODE{200}
-is returned if the deletion operation was carried out successfully.
-This code will also be returned if no results were deleted.
-
-@RESTRETURNCODE{400}
-is returned if type is not specified or has an invalid value.
-
-@RESTRETURNCODE{404}
-is returned if type is a job-id but no async job with the specified id was
-found.
-
-@EXAMPLES
-
-Deleting all jobs:
-
-
-
-
-
-shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
-
-HTTP/1.1 202 Accepted
-content-type: text/plain
-connection: Keep-Alive
-content-length: 0
-server: ArangoDB
-x-arango-async-id: 81809
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/all
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 15
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
-{
- "result" : true
-}
-
-
Hide response body
-
-
-shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
-
-HTTP/1.1 202 Accepted
-content-type: text/plain
-connection: Keep-Alive
-content-length: 0
-server: ArangoDB
-x-arango-async-id: 81809
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/all
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 15
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
Show response body
-
-
-
-
-
-
-Deleting expired jobs:
-
-
-
-
-
-shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
-
-HTTP/1.1 202 Accepted
-content-type: text/plain
-connection: Keep-Alive
-content-length: 0
-server: ArangoDB
-x-arango-async-id: 81811
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/time
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 55
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
-{
- "error" : false,
- "code" : 200,
- "time" : 1687621381.4327047
-}
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/expired?stamp=1687621381.4327047
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 15
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
-{
- "result" : true
-}
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 2
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
-[ ]
-
-
Hide response body
-
-
-shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
-
-HTTP/1.1 202 Accepted
-content-type: text/plain
-connection: Keep-Alive
-content-length: 0
-server: ArangoDB
-x-arango-async-id: 81811
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/time
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 55
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/expired?stamp=1687621381.4327047
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 15
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
-
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 2
+content-length: 1709
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -32840,57 +33911,188 @@ x-content-type-options: nosniff
-
-Deleting the result of a specific job:
+A query that produces a warning
-
-
+
+
-shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
-
-HTTP/1.1 202 Accepted
-content-type: text/plain
-connection: Keep-Alive
-content-length: 0
-server: ArangoDB
-x-arango-async-id: 81813
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81813
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
+{
+ "query" : "FOR i IN 1..10 RETURN 1 / 0"
+}
+EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 15
+content-length: 1686
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "result" : true
+ "plan" : {
+ "nodes" : [
+ {
+ "type" : "SingletonNode",
+ "dependencies" : [ ],
+ "id" : 1,
+ "estimatedCost" : 1,
+ "estimatedNrItems" : 1
+ },
+ {
+ "type" : "CalculationNode",
+ "dependencies" : [
+ 1
+ ],
+ "id" : 2,
+ "estimatedCost" : 2,
+ "estimatedNrItems" : 1,
+ "expression" : {
+ "type" : "range",
+ "typeID" : 49,
+ "subNodes" : [
+ {
+ "type" : "value",
+ "typeID" : 40,
+ "value" : 1,
+ "vType" : "int",
+ "vTypeID" : 2
+ },
+ {
+ "type" : "value",
+ "typeID" : 40,
+ "value" : 10,
+ "vType" : "int",
+ "vTypeID" : 2
+ }
+ ]
+ },
+ "outVariable" : {
+ "id" : 2,
+ "name" : "1",
+ "isDataFromCollection" : false
+ },
+ "canThrow" : false,
+ "expressionType" : "simple"
+ },
+ {
+ "type" : "CalculationNode",
+ "dependencies" : [
+ 2
+ ],
+ "id" : 4,
+ "estimatedCost" : 3,
+ "estimatedNrItems" : 1,
+ "expression" : {
+ "type" : "value",
+ "typeID" : 40,
+ "value" : null,
+ "vType" : "null",
+ "vTypeID" : 0
+ },
+ "outVariable" : {
+ "id" : 4,
+ "name" : "3",
+ "isDataFromCollection" : false,
+ "constantValue" : null
+ },
+ "canThrow" : false,
+ "expressionType" : "json"
+ },
+ {
+ "type" : "EnumerateListNode",
+ "dependencies" : [
+ 4
+ ],
+ "id" : 3,
+ "estimatedCost" : 13,
+ "estimatedNrItems" : 10,
+ "inVariable" : {
+ "id" : 2,
+ "name" : "1",
+ "isDataFromCollection" : false
+ },
+ "outVariable" : {
+ "id" : 0,
+ "name" : "i",
+ "isDataFromCollection" : false
+ }
+ },
+ {
+ "type" : "ReturnNode",
+ "dependencies" : [
+ 3
+ ],
+ "id" : 5,
+ "estimatedCost" : 23,
+ "estimatedNrItems" : 10,
+ "inVariable" : {
+ "id" : 4,
+ "name" : "3",
+ "isDataFromCollection" : false,
+ "constantValue" : null
+ },
+ "count" : true
+ }
+ ],
+ "rules" : [
+ "move-calculations-up",
+ "move-calculations-up-2"
+ ],
+ "collections" : [ ],
+ "variables" : [
+ {
+ "id" : 4,
+ "name" : "3",
+ "isDataFromCollection" : false,
+ "constantValue" : null
+ },
+ {
+ "id" : 2,
+ "name" : "1",
+ "isDataFromCollection" : false
+ },
+ {
+ "id" : 0,
+ "name" : "i",
+ "isDataFromCollection" : false
+ }
+ ],
+ "estimatedCost" : 23,
+ "estimatedNrItems" : 10,
+ "isModificationQuery" : false
+ },
+ "cacheable" : false,
+ "warnings" : [
+ {
+ "code" : 1562,
+ "message" : "division by zero"
+ }
+ ],
+ "stats" : {
+ "rulesExecuted" : 41,
+ "rulesSkipped" : 0,
+ "plansCreated" : 1
+ },
+ "error" : false,
+ "code" : 200
}
-
Hide response body
-
+
-shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
-
-HTTP/1.1 202 Accepted
-content-type: text/plain
-connection: Keep-Alive
-content-length: 0
-server: ArangoDB
-x-arango-async-id: 81813
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81813
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
+{
+ "query" : "FOR i IN 1..10 RETURN 1 / 0"
+}
+EOF
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 15
+content-length: 1686
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -32901,38 +34103,47 @@ x-content-type-options: nosniff
-Deleting the result of a non-existing job:
+Invalid query (missing bind parameter)
-
-
+
+
+
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/AreYouThere
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
+{
+ "query" : "FOR p IN products FILTER p.id == @id LIMIT 2 RETURN p.n"
+}
+EOF
-HTTP/1.1 404 Not Found
+HTTP/1.1 400 Bad Request
content-type: application/json
connection: Keep-Alive
-content-length: 67
+content-length: 126
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "code" : 404,
+ "code" : 400,
"error" : true,
- "errorMessage" : "not found",
- "errorNum" : 404
+ "errorMessage" : "no value specified for declared bind parameter 'id' (while parsing)",
+ "errorNum" : 1551
}
-
Hide response body
-
+
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/AreYouThere
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
+{
+ "query" : "FOR p IN products FILTER p.id == @id LIMIT 2 RETURN p.n"
+}
+EOF
-HTTP/1.1 404 Not Found
+HTTP/1.1 400 Bad Request
content-type: application/json
connection: Keep-Alive
-content-length: 67
+content-length: 126
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -32940,81 +34151,185 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-
-
-@startDocuBlock job_fetch_result
-
-@brief fetches a job result and removes it from the queue
-
-@RESTHEADER{PUT /_api/job/{job-id}, Return result of an async job, getJobResult}
-
-@RESTURLPARAMETERS
-
-@RESTURLPARAM{job-id,string,required}
-The async job id.
-
-@RESTDESCRIPTION
-Returns the result of an async job identified by job-id. If the async job
-result is present on the server, the result will be removed from the list of
-result. That means this method can be called for each job-id once.
-The method will return the original job result's headers and body, plus the
-additional HTTP header x-arango-async-job-id. If this header is present,
-then
-the job was found and the response contains the original job's result. If
-the header is not present, the job was not found and the response contains
-status information from the job manager.
-@RESTRETURNCODES
-@RESTRETURNCODE{204}
-is returned if the job requested via job-id is still in the queue of pending
-(or not yet finished) jobs. In this case, no x-arango-async-id HTTP header
-will be returned.
-@RESTRETURNCODE{400}
-is returned if no job-id was specified in the request. In this case,
-no x-arango-async-id HTTP header will be returned.
-@RESTRETURNCODE{404}
-is returned if the job was not found or already deleted or fetched from
-the job result list. In this case, no x-arango-async-id HTTP header will
-be returned.
+The data returned in the **plan** attribute of the result contains one element per AQL top-level statement
+(i.e. `FOR`, `RETURN`, `FILTER` etc.). If the query optimizer removed some unnecessary statements,
+the result might also contain less elements than there were top-level statements in the AQL query.
-@EXAMPLES
-Not providing a job-id:
+The following example shows a query with a non-sensible filter condition that
+the optimizer has removed so that there are less top-level statements.
-
-
+
+
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
+{ "query" : "FOR i IN [ 1, 2, 3 ] FILTER 1 == 2 RETURN i" }
+EOF
-HTTP/1.1 400 Bad Request
+HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 71
+content-length: 1430
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "code" : 400,
- "error" : true,
- "errorMessage" : "bad parameter",
- "errorNum" : 400
+ "plan" : {
+ "nodes" : [
+ {
+ "type" : "SingletonNode",
+ "dependencies" : [ ],
+ "id" : 1,
+ "estimatedCost" : 1,
+ "estimatedNrItems" : 1
+ },
+ {
+ "type" : "CalculationNode",
+ "dependencies" : [
+ 1
+ ],
+ "id" : 2,
+ "estimatedCost" : 2,
+ "estimatedNrItems" : 1,
+ "expression" : {
+ "type" : "array",
+ "typeID" : 41,
+ "subNodes" : [
+ {
+ "type" : "value",
+ "typeID" : 40,
+ "value" : 1,
+ "vType" : "int",
+ "vTypeID" : 2
+ },
+ {
+ "type" : "value",
+ "typeID" : 40,
+ "value" : 2,
+ "vType" : "int",
+ "vTypeID" : 2
+ },
+ {
+ "type" : "value",
+ "typeID" : 40,
+ "value" : 3,
+ "vType" : "int",
+ "vTypeID" : 2
+ }
+ ]
+ },
+ "outVariable" : {
+ "id" : 2,
+ "name" : "1",
+ "isDataFromCollection" : false,
+ "constantValue" : [
+ 1,
+ 2,
+ 3
+ ]
+ },
+ "canThrow" : false,
+ "expressionType" : "json"
+ },
+ {
+ "type" : "EnumerateListNode",
+ "dependencies" : [
+ 2
+ ],
+ "id" : 3,
+ "estimatedCost" : 5,
+ "estimatedNrItems" : 3,
+ "inVariable" : {
+ "id" : 2,
+ "name" : "1",
+ "isDataFromCollection" : false,
+ "constantValue" : [
+ 1,
+ 2,
+ 3
+ ]
+ },
+ "outVariable" : {
+ "id" : 0,
+ "name" : "i",
+ "isDataFromCollection" : false
+ }
+ },
+ {
+ "type" : "NoResultsNode",
+ "dependencies" : [
+ 3
+ ],
+ "id" : 4,
+ "estimatedCost" : 0.5,
+ "estimatedNrItems" : 0
+ },
+ {
+ "type" : "ReturnNode",
+ "dependencies" : [
+ 4
+ ],
+ "id" : 5,
+ "estimatedCost" : 0.5,
+ "estimatedNrItems" : 0,
+ "inVariable" : {
+ "id" : 0,
+ "name" : "i",
+ "isDataFromCollection" : false
+ },
+ "count" : true
+ }
+ ],
+ "rules" : [ ],
+ "collections" : [ ],
+ "variables" : [
+ {
+ "id" : 2,
+ "name" : "1",
+ "isDataFromCollection" : false,
+ "constantValue" : [
+ 1,
+ 2,
+ 3
+ ]
+ },
+ {
+ "id" : 0,
+ "name" : "i",
+ "isDataFromCollection" : false
+ }
+ ],
+ "estimatedCost" : 0.5,
+ "estimatedNrItems" : 0,
+ "isModificationQuery" : false
+ },
+ "cacheable" : true,
+ "warnings" : [ ],
+ "stats" : {
+ "rulesExecuted" : 41,
+ "rulesSkipped" : 0,
+ "plansCreated" : 1
+ },
+ "error" : false,
+ "code" : 200
}
-
Hide response body
-
+
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/explain <<EOF
+{ "query" : "FOR i IN [ 1, 2, 3 ] FILTER 1 == 2 RETURN i" }
+EOF
-HTTP/1.1 400 Bad Request
+HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 71
+content-length: 1430
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -33025,121 +34340,106 @@ x-content-type-options: nosniff
-Providing a job-id for a non-existing job:
+@endDocuBlock
-
-
-
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/notthere
+
+@startDocuBlock job_cancel
-HTTP/1.1 404 Not Found
-content-type: application/json
-connection: Keep-Alive
-content-length: 67
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
+@brief cancels an async job
-{
- "code" : 404,
- "error" : true,
- "errorMessage" : "not found",
- "errorNum" : 404
-}
-
-
Hide response body
-
-
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/notthere
+@RESTHEADER{PUT /_api/job/{job-id}/cancel, Cancel async job, putJobMethod:cancel}
-HTTP/1.1 404 Not Found
-content-type: application/json
-connection: Keep-Alive
-content-length: 67
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-Show response body
-
-
-
+@RESTRETURNCODE{404}
+is returned if the job was not found or already deleted or fetched from
+the job result list. In this case, no x-arango-async-id HTTP header will
+be returned.
+
+@EXAMPLES
+
+
+
+
-shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
+shell> curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/cursor <<EOF
+{
+ "query" : "FOR i IN 1..10 FOR j IN 1..10 LET x = sleep(1.0) FILTER i == 5 && j == 5 RETURN 42"
+}
+EOF
HTTP/1.1 202 Accepted
content-type: text/plain
connection: Keep-Alive
content-length: 0
server: ArangoDB
-x-arango-async-id: 81818
+x-arango-async-id: 81805
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81818
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 61
+content-length: 9
server: ArangoDB
-x-arango-async-id: 81818
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-{
- "server" : "arango",
- "license" : "enterprise",
- "version" : "3.9.12"
-}
-
-
Hide response body
-
-
-shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
+[
+ "81805"
+]
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81805/cancel
-HTTP/1.1 202 Accepted
-content-type: text/plain
+HTTP/1.1 200 OK
+content-type: application/json
connection: Keep-Alive
-content-length: 0
+content-length: 15
server: ArangoDB
-x-arango-async-id: 81818
-x-arango-queue-time-seconds: 0.000000
+x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81818
+
+{
+ "result" : true
+}
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 61
+content-length: 9
server: ArangoDB
-x-arango-async-id: 81818
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-Show response body
-
-
-
-
-
-
-Fetching the result of an HTTP POST job that failed:
-
-
-
+[
+
"81805"
+]
+
+
Hide response body
+
-shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection <<EOF
+shell> curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/cursor <<EOF
{
- "name" : " this name is invalid "
+ "query" : "FOR i IN 1..10 FOR j IN 1..10 LET x = sleep(1.0) FILTER i == 5 && j == 5 RETURN 42"
}
EOF
@@ -33148,53 +34448,34 @@ content-type: text/plain
connection: Keep-Alive
content-length: 0
server: ArangoDB
-x-arango-async-id: 81820
+x-arango-async-id: 81805
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81820
-
-HTTP/1.1 400 Bad Request
+HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 114
+content-length: 9
server: ArangoDB
-x-arango-async-id: 81820
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81805/cancel
-{
- "code" : 400,
- "error" : true,
- "errorMessage" : "expected PUT /_api/collection/<collection-name>/<action>",
- "errorNum" : 400
-}
-
-
Hide response body
-
-
-shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection <<EOF
-{
- "name" : " this name is invalid "
-}
-EOF
-
-HTTP/1.1 202 Accepted
-content-type: text/plain
+HTTP/1.1 200 OK
+content-type: application/json
connection: Keep-Alive
-content-length: 0
+content-length: 15
server: ArangoDB
-x-arango-async-id: 81820
-x-arango-queue-time-seconds: 0.000000
+x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81820
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
-HTTP/1.1 400 Bad Request
+HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 114
+content-length: 9
server: ArangoDB
-x-arango-async-id: 81820
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body
@@ -33203,56 +34484,62 @@ x-content-type-options: nosniff
+
+
@endDocuBlock
-
-@startDocuBlock job_getByType
+
+@startDocuBlock job_delete
-@brief Returns the ids of job results with a specific status
+@brief deletes an async job result
-@RESTHEADER{GET /_api/job/{type}#by-type, Returns list of async jobs, getJob}
+@RESTHEADER{DELETE /_api/job/{type}#by-type, Deletes async job, deleteJob:byType}
@RESTURLPARAMETERS
@RESTURLPARAM{type,string,required}
-The type of jobs to return. The type can be either done or pending. Setting
-the type to done will make the method return the ids of already completed
-async
-jobs for which results can be fetched. Setting the type to pending will
-return
-the ids of not yet finished async jobs.
+The type of jobs to delete. type can be:
+* *all*: Deletes all jobs results. Currently executing or queued async
+ jobs will not be stopped by this call.
+* *expired*: Deletes expired results. To determine the expiration status of a
+ result, pass the stamp query parameter. stamp needs to be a UNIX timestamp,
+ and all async job results created at a lower timestamp will be deleted.
+* *an actual job-id*: In this case, the call will remove the result of the
+ specified async job. If the job is currently executing or queued, it will
+ not be aborted.
@RESTQUERYPARAMETERS
-@RESTQUERYPARAM{count,number,optional}
-
-The maximum number of ids to return per call. If not specified, a
-server-defined maximum value will be used.
+@RESTQUERYPARAM{stamp,number,optional}
+A UNIX timestamp specifying the expiration threshold when type is expired.
@RESTDESCRIPTION
-Returns the list of ids of async jobs with a specific status (either done or
-pending).
-The list can be used by the client to get an overview of the job system
-status and
-to retrieve completed job results later.
+Deletes either all job results, expired job results, or the result of a
+specific job.
+Clients can use this method to perform an eventual garbage collection of job
+results.
@RESTRETURNCODES
@RESTRETURNCODE{200}
-is returned if the list can be compiled successfully. Note: the list might
-be empty.
+is returned if the deletion operation was carried out successfully.
+This code will also be returned if no results were deleted.
@RESTRETURNCODE{400}
is returned if type is not specified or has an invalid value.
+@RESTRETURNCODE{404}
+is returned if type is a job-id but no async job with the specified id was
+found.
+
@EXAMPLES
-Fetching the list of done jobs:
+Deleting all jobs:
-
-
+
+
shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
@@ -33261,26 +34548,26 @@ content-type: text/plain
connection: Keep-Alive
content-length: 0
server: ArangoDB
-x-arango-async-id: 81822
+x-arango-async-id: 81809
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/done
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/all
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 9
+content-length: 15
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-[
- "81822"
-]
+{
+ "result" : true
+}
-
Hide response body
-
+
shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
@@ -33289,15 +34576,15 @@ content-type: text/plain
connection: Keep-Alive
content-length: 0
server: ArangoDB
-x-arango-async-id: 81822
+x-arango-async-id: 81809
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/done
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/all
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 9
+content-length: 15
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -33308,11 +34595,11 @@ x-content-type-options: nosniff
-Fetching the list of pending jobs:
+Deleting expired jobs:
-
-
+
+
shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
@@ -33321,114 +34608,73 @@ content-type: text/plain
connection: Keep-Alive
content-length: 0
server: ArangoDB
-x-arango-async-id: 81824
+x-arango-async-id: 81811
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/time
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 2
+content-length: 55
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-[ ]
-
-
-
-
-
-
-
-Querying the status of a pending job:
-(we create a sleep job therefore...)
-
-
-
-
-
-shell> curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
{
- "collections" : {
- "read" : [
- "_frontend"
- ]
- },
- "action" : "function () {require('internal').sleep(15.0);}"
+ "error" : false,
+ "code" : 200,
+ "time" : 1693580485.3359842
}
-EOF
-
-HTTP/1.1 202 Accepted
-content-type: text/plain
-connection: Keep-Alive
-content-length: 0
-server: ArangoDB
-x-arango-async-id: 81826
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/expired?stamp=1693580485.3359842
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 9
+content-length: 15
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-[
- "81826"
-]
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81826
+{
+ "result" : true
+}
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 15
+content-length: 2
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-{
- "result" : true
-}
+[ ]
-
Hide response body
-
+
-shell> curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
-{
- "collections" : {
- "read" : [
- "_frontend"
- ]
- },
- "action" : "function () {require('internal').sleep(15.0);}"
-}
-EOF
+shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
HTTP/1.1 202 Accepted
content-type: text/plain
connection: Keep-Alive
content-length: 0
server: ArangoDB
-x-arango-async-id: 81826
+x-arango-async-id: 81811
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/time
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 9
+content-length: 55
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81826
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/expired?stamp=1693580485.3359842
HTTP/1.1 200 OK
content-type: application/json
@@ -33437,6 +34683,15 @@ content-length: 15
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
+
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 2
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
Show response body
@@ -33444,47 +34699,13 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-
-
-@startDocuBlock job_getStatusById
-
-@brief Returns the status of a specific job
-
-@RESTHEADER{GET /_api/job/{job-id}, Returns async job, getJobById}
-
-@RESTURLPARAMETERS
-
-@RESTURLPARAM{job-id,string,required}
-The async job id.
-
-@RESTDESCRIPTION
-Returns the processing status of the specified job. The processing status
-can be
-determined by peeking into the HTTP response code of the response.
-
-@RESTRETURNCODES
-
-@RESTRETURNCODE{200}
-is returned if the job requested via job-id has been executed
-and its result is ready to fetch.
-
-@RESTRETURNCODE{204}
-is returned if the job requested via job-id is still in the queue of pending
-(or not yet finished) jobs.
-
-@RESTRETURNCODE{404}
-is returned if the job was not found or already deleted or fetched from the
-job result list.
-@EXAMPLES
-Querying the status of a done job:
+Deleting the result of a specific job:
-
-
+
+
shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
@@ -33493,29 +34714,26 @@ content-type: text/plain
connection: Keep-Alive
content-length: 0
server: ArangoDB
-x-arango-async-id: 81829
+x-arango-async-id: 81813
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81829
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81813
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 61
+content-length: 15
server: ArangoDB
-x-arango-async-id: 81829
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "server" : "arango",
- "license" : "enterprise",
- "version" : "3.9.12"
+ "result" : true
}
-
Hide response body
-
+
shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
@@ -33524,17 +34742,16 @@ content-type: text/plain
connection: Keep-Alive
content-length: 0
server: ArangoDB
-x-arango-async-id: 81829
+x-arango-async-id: 81813
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81829
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81813
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 61
+content-length: 15
server: ArangoDB
-x-arango-async-id: 81829
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body
@@ -33544,272 +34761,120 @@ x-content-type-options: nosniff
-Querying the status of a pending job:
-(therefore we create a long runnging job...)
+Deleting the result of a non-existing job:
-
-
+
+
-shell> curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
-{
- "collections" : {
- "read" : [
- "_aqlfunctions"
- ]
- },
- "action" : "function () {require('internal').sleep(15.0);}"
-}
-EOF
-
-HTTP/1.1 202 Accepted
-content-type: text/plain
-connection: Keep-Alive
-content-length: 0
-server: ArangoDB
-x-arango-async-id: 81831
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81831
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/AreYouThere
-HTTP/1.1 204 No Content
-content-type: text/plain
+HTTP/1.1 404 Not Found
+content-type: application/json
connection: Keep-Alive
-content-length: 0
+content-length: 67
server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
+x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
+{
+ "code" : 404,
+ "error" : true,
+ "errorMessage" : "not found",
+ "errorNum" : 404
+}
-
-
-
-
-
-@endDocuBlock
-
-
-
-@startDocuBlock delete_batch_replication
-
-@brief handle a dump batch command
-
-@RESTHEADER{DELETE /_api/replication/batch/{id}, Deletes an existing dump batch,handleCommandBatch:DELETE}
-
-**Note**: These calls are uninteresting to users.
-
-@RESTURLPARAMETERS
-
-@RESTURLPARAM{id,string,required}
-The id of the batch.
-
-@RESTDESCRIPTION
-Deletes the existing dump batch, allowing compaction and cleanup to resume.
-
-**Note**: on a Coordinator, this request must have the query parameter
-*DBserver* which must be an ID of a DB-Server.
-The very same request is forwarded synchronously to that DB-Server.
-It is an error if this attribute is not bound in the Coordinator case.
-
-@RESTRETURNCODES
-
-@RESTRETURNCODE{204}
-is returned if the batch was deleted successfully.
-
-@RESTRETURNCODE{400}
-is returned if the batch was not found.
-
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
-@endDocuBlock
-
-
-
-@startDocuBlock get_api_replication_applier_state
-
-@brief output the current status of the replication
-
-@RESTHEADER{GET /_api/replication/applier-state, State of the replication applier,handleCommandApplierGetState}
-
-@RESTQUERYPARAMETERS
-
-@RESTQUERYPARAM{global,boolean,optional}
-If set to *true*, returns the state of the global replication applier for all
-databases. If set to *false*, returns the state of the replication applier in the
-selected database.
-
-@RESTDESCRIPTION
-Returns the state of the replication applier, regardless of whether the
-applier is currently running or not.
-
-The response is a JSON object with the following attributes:
-
-- *state*: a JSON object with the following sub-attributes:
-
- - *running*: whether or not the applier is active and running
-
- - *lastAppliedContinuousTick*: the last tick value from the continuous
- replication log the applier has applied.
-
- - *lastProcessedContinuousTick*: the last tick value from the continuous
- replication log the applier has processed.
-
- Regularly, the last applied and last processed tick values should be
- identical. For transactional operations, the replication applier will first
- process incoming log events before applying them, so the processed tick
- value might be higher than the applied tick value. This will be the case
- until the applier encounters the *transaction commit* log event for the
- transaction.
-
- - *lastAvailableContinuousTick*: the last tick value the remote server can
- provide, for all databases.
-
- - *ticksBehind*: this attribute will be present only if the applier is currently
- running. It will provide the number of log ticks between what the applier
- has applied/seen and the last log tick value provided by the remote server.
- If this value is zero, then both servers are in sync. If this is non-zero,
- then the remote server has additional data that the applier has not yet
- fetched and processed, or the remote server may have more data that is not
- applicable to the applier.
-
- Client applications can use it to determine approximately how far the applier
- is behind the remote server, and can periodically check if the value is
- increasing (applier is falling behind) or decreasing (applier is catching up).
-
- Please note that as the remote server will only keep one last log tick value
- for all of its databases, but replication may be restricted to just certain
- databases on the applier, this value is more meaningful when the global applier
- is used.
- Additionally, the last log tick provided by the remote server may increase
- due to writes into system collections that are not replicated due to replication
- configuration. So the reported value may exaggerate the reality a bit for
- some scenarios.
-
- - *time*: the time on the applier server.
-
- - *totalRequests*: the total number of requests the applier has made to the
- endpoint.
-
- - *totalFailedConnects*: the total number of failed connection attempts the
- applier has made.
-
- - *totalEvents*: the total number of log events the applier has processed.
-
- - *totalOperationsExcluded*: the total number of log events excluded because
- of *restrictCollections*.
-
- - *progress*: a JSON object with details about the replication applier progress.
- It contains the following sub-attributes if there is progress to report:
-
- - *message*: a textual description of the progress
-
- - *time*: the date and time the progress was logged
-
- - *failedConnects*: the current number of failed connection attempts
-
- - *lastError*: a JSON object with details about the last error that happened on
- the applier. It contains the following sub-attributes if there was an error:
+
Hide response body
+
+
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/AreYouThere
- - *errorNum*: a numerical error code
+HTTP/1.1 404 Not Found
+content-type: application/json
+connection: Keep-Alive
+content-length: 67
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
Show response body
+
+
- - *errorMessage*: a textual error description
+@endDocuBlock
- - *time*: the date and time the error occurred
- In case no error has occurred, *lastError* will be empty.
+
+@startDocuBlock job_fetch_result
-- *server*: a JSON object with the following sub-attributes:
+@brief fetches a job result and removes it from the queue
- - *version*: the applier server's version
+@RESTHEADER{PUT /_api/job/{job-id}, Return result of an async job, getJobResult}
- - *serverId*: the applier server's id
+@RESTURLPARAMETERS
-- *endpoint*: the endpoint the applier is connected to (if applier is
- active) or will connect to (if applier is currently inactive)
+@RESTURLPARAM{job-id,string,required}
+The async job id.
-- *database*: the name of the database the applier is connected to (if applier is
- active) or will connect to (if applier is currently inactive)
+@RESTDESCRIPTION
+Returns the result of an async job identified by job-id. If the async job
+result is present on the server, the result will be removed from the list of
+result. That means this method can be called for each job-id once.
+The method will return the original job result's headers and body, plus the
+additional HTTP header x-arango-async-job-id. If this header is present,
+then
+the job was found and the response contains the original job's result. If
+the header is not present, the job was not found and the response contains
+status information from the job manager.
-Please note that all "tick" values returned do not have a specific unit. Tick
-values are only meaningful when compared to each other. Higher tick values mean
-"later in time" than lower tick values.
@RESTRETURNCODES
-@RESTRETURNCODE{200}
-is returned if the request was executed successfully.
+@RESTRETURNCODE{204}
+is returned if the job requested via job-id is still in the queue of pending
+(or not yet finished) jobs. In this case, no x-arango-async-id HTTP header
+will be returned.
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
+@RESTRETURNCODE{400}
+is returned if no job-id was specified in the request. In this case,
+no x-arango-async-id HTTP header will be returned.
-@RESTRETURNCODE{500}
-is returned if an error occurred while assembling the response.
+@RESTRETURNCODE{404}
+is returned if the job was not found or already deleted or fetched from
+the job result list. In this case, no x-arango-async-id HTTP header will
+be returned.
@EXAMPLES
-
-Fetching the state of an inactive applier:
+Not providing a job-id:
-
-
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/applier-state
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job
-HTTP/1.1 200 OK
+HTTP/1.1 400 Bad Request
content-type: application/json
connection: Keep-Alive
-content-length: 686
+content-length: 71
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "state" : {
- "started" : "2023-06-24T15:42:52Z",
- "running" : false,
- "phase" : "inactive",
- "lastAppliedContinuousTick" : null,
- "lastProcessedContinuousTick" : null,
- "lastAvailableContinuousTick" : null,
- "safeResumeTick" : null,
- "progress" : {
- "time" : "2023-06-24T15:42:53Z",
- "message" : "applier shut down",
- "failedConnects" : 1
- },
- "totalRequests" : 2,
- "totalFailedConnects" : 1,
- "totalEvents" : 0,
- "totalDocuments" : 0,
- "totalRemovals" : 0,
- "totalResyncs" : 0,
- "totalOperationsExcluded" : 0,
- "totalApplyTime" : 0,
- "averageApplyTime" : 0,
- "totalFetchTime" : 0,
- "averageFetchTime" : 0,
- "lastError" : {
- "errorNum" : 0
- },
- "time" : "2023-06-24T15:42:53Z"
- },
- "server" : {
- "version" : "3.9.12",
- "serverId" : "82519733153206"
- },
- "endpoint" : "tcp://127.0.0.1:8529",
- "database" : "_system"
+ "code" : 400,
+ "error" : true,
+ "errorMessage" : "bad parameter",
+ "errorNum" : 400
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/applier-state
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job
-HTTP/1.1 200 OK
+HTTP/1.1 400 Bad Request
content-type: application/json
connection: Keep-Alive
-content-length: 686
+content-length: 71
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -33820,70 +34885,38 @@ x-content-type-options: nosniff
-Fetching the state of an active applier:
+Providing a job-id for a non-existing job:
-
-
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/applier-state
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/notthere
-HTTP/1.1 200 OK
+HTTP/1.1 404 Not Found
content-type: application/json
connection: Keep-Alive
-content-length: 716
+content-length: 67
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "state" : {
- "started" : "2023-06-24T15:42:52Z",
- "running" : true,
- "phase" : "running",
- "lastAppliedContinuousTick" : null,
- "lastProcessedContinuousTick" : null,
- "lastAvailableContinuousTick" : null,
- "safeResumeTick" : null,
- "ticksBehind" : 0,
- "progress" : {
- "time" : "2023-06-24T15:42:53Z",
- "message" : "fetching leader state information",
- "failedConnects" : 0
- },
- "totalRequests" : 2,
- "totalFailedConnects" : 1,
- "totalEvents" : 0,
- "totalDocuments" : 0,
- "totalRemovals" : 0,
- "totalResyncs" : 0,
- "totalOperationsExcluded" : 0,
- "totalApplyTime" : 0,
- "averageApplyTime" : 0,
- "totalFetchTime" : 0,
- "averageFetchTime" : 0,
- "lastError" : {
- "errorNum" : 0
- },
- "time" : "2023-06-24T15:42:53Z"
- },
- "server" : {
- "version" : "3.9.12",
- "serverId" : "82519733153206"
- },
- "endpoint" : "tcp://127.0.0.1:8529",
- "database" : "_system"
+ "code" : 404,
+ "error" : true,
+ "errorMessage" : "not found",
+ "errorNum" : 404
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/applier-state
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/notthere
-HTTP/1.1 200 OK
+HTTP/1.1 404 Not Found
content-type: application/json
connection: Keep-Alive
-content-length: 716
+content-length: 67
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -33893,390 +34926,519 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-
-@startDocuBlock get_api_replication_cluster_inventory
+Fetching the result of an HTTP GET job:
-@brief returs an overview of collections and indexes in a cluster
-@RESTHEADER{GET /_api/replication/clusterInventory, Return cluster inventory of collections and indexes, handleCommandClusterInventory}
+
+
+
+shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
-@RESTQUERYPARAMETERS
+HTTP/1.1 202 Accepted
+content-type: text/plain
+connection: Keep-Alive
+content-length: 0
+server: ArangoDB
+x-arango-async-id: 81818
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTQUERYPARAM{includeSystem,boolean,optional}
-Include system collections in the result. The default value is *true*.
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81818
-@RESTDESCRIPTION
-Returns the array of collections and indexes available on the cluster.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 61
+server: ArangoDB
+x-arango-async-id: 81818
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-The response will be an array of JSON objects, one for each collection.
-Each collection containscontains exactly two keys "parameters" and
-"indexes". This
-information comes from Plan/Collections/{DB-Name}/* in the Agency,
-just that the *indexes* attribute there is relocated to adjust it to
-the data format of arangodump.
+{
+ "server" : "arango",
+ "license" : "enterprise",
+ "version" : "3.9.12"
+}
+
+
Hide response body
+
+
+shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
-@RESTRETURNCODES
+HTTP/1.1 202 Accepted
+content-type: text/plain
+connection: Keep-Alive
+content-length: 0
+server: ArangoDB
+x-arango-async-id: 81818
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81818
-@RESTRETURNCODE{200}
-is returned if the request was executed successfully.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 61
+server: ArangoDB
+x-arango-async-id: 81818
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection <<EOF
+{
+ "name" : " this name is invalid "
+}
+EOF
-@RESTQUERYPARAMETERS
+HTTP/1.1 202 Accepted
+content-type: text/plain
+connection: Keep-Alive
+content-length: 0
+server: ArangoDB
+x-arango-async-id: 81820
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTQUERYPARAM{collection,string,required}
-The name or id of the collection to dump.
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81820
-@RESTQUERYPARAM{chunkSize,number,optional}
-Approximate maximum size of the returned result.
+HTTP/1.1 400 Bad Request
+content-type: application/json
+connection: Keep-Alive
+content-length: 114
+server: ArangoDB
+x-arango-async-id: 81820
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTQUERYPARAM{batchId,number,required}
-The id of the snapshot to use
+{
+ "code" : 400,
+ "error" : true,
+ "errorMessage" : "expected PUT /_api/collection/<collection-name>/<action>",
+ "errorNum" : 400
+}
+
+
Hide response body
+
+
+shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection <<EOF
+{
+ "name" : " this name is invalid "
+}
+EOF
-@RESTDESCRIPTION
-Returns the data from the collection for the requested range.
+HTTP/1.1 202 Accepted
+content-type: text/plain
+connection: Keep-Alive
+content-length: 0
+server: ArangoDB
+x-arango-async-id: 81820
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81820
+HTTP/1.1 400 Bad Request
+content-type: application/json
+connection: Keep-Alive
+content-length: 114
+server: ArangoDB
+x-arango-async-id: 81820
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
-@brief Return the first available tick value from the server
+HTTP/1.1 202 Accepted
+content-type: text/plain
+connection: Keep-Alive
+content-length: 0
+server: ArangoDB
+x-arango-async-id: 81822
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTHEADER{GET /_api/replication/logger-first-tick, Returns the first available tick value, handleCommandLoggerFirstTick}
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/done
-@RESTDESCRIPTION
-Returns the first available tick value that can be served from the server's
-replication log. This method can be called by replication clients after to
-determine if certain data (identified by a tick value) is still available
-for replication.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 9
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-The result is a JSON object containing the attribute *firstTick*. This
-attribute contains the minimum tick value available in the server's
-replication
-log.
+[
+ "81822"
+]
+
+
Hide response body
+
+
+shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
-**Note**: this method is not supported on a Coordinator in a cluster.
+HTTP/1.1 202 Accepted
+content-type: text/plain
+connection: Keep-Alive
+content-length: 0
+server: ArangoDB
+x-arango-async-id: 81822
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/done
-@RESTRETURNCODES
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 9
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
Show response body
+
+
+
+
+shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
+HTTP/1.1 202 Accepted
+content-type: text/plain
+connection: Keep-Alive
+content-length: 0
+server: ArangoDB
+x-arango-async-id: 81824
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-
-
-
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-first-tick
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 22
+content-length: 2
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-{
- "firstTick" : "175570"
-}
+[ ]
+
+
+shell> curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
+{
+ "collections" : {
+ "read" : [
+ "_frontend"
+ ]
+ },
+ "action" : "function () {require('internal').sleep(15.0);}"
+}
+EOF
-@RESTHEADER{GET /_api/replication/logger-follow, Returns log entries, handleCommandLoggerFollow}
+HTTP/1.1 202 Accepted
+content-type: text/plain
+connection: Keep-Alive
+content-length: 0
+server: ArangoDB
+x-arango-async-id: 81826
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@HINTS
-{% hint 'warning' %}
-This route should no longer be used.
-It is considered as deprecated from version 3.4.0 on. Client applications
-should use the REST API endpoint `/_api/wal/tail` instead.
-{% endhint %}
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
-@RESTQUERYPARAMETERS
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 9
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTQUERYPARAM{from,number,optional}
-Exclusive lower bound tick value for results.
+[
+ "81826"
+]
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81826
-@RESTQUERYPARAM{to,number,optional}
-Inclusive upper bound tick value for results.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 15
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTQUERYPARAM{chunkSize,number,optional}
-Approximate maximum size of the returned result.
+{
+ "result" : true
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
+{
+ "collections" : {
+ "read" : [
+ "_frontend"
+ ]
+ },
+ "action" : "function () {require('internal').sleep(15.0);}"
+}
+EOF
-@RESTQUERYPARAM{includeSystem,boolean,optional}
-Include system collections in the result. The default value is *true*.
+HTTP/1.1 202 Accepted
+content-type: text/plain
+connection: Keep-Alive
+content-length: 0
+server: ArangoDB
+x-arango-async-id: 81826
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/pending
-@RESTDESCRIPTION
-Returns data from the server's replication log. This method can be called
-by replication clients after an initial synchronization of data. The method
-will return all "recent" log entries from the logger server, and the clients
-can replay and apply these entries locally so they get to the same data
-state as the logger server.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 9
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81826
-Clients can call this method repeatedly to incrementally fetch all changes
-from the logger server. In this case, they should provide the *from* value so
-they will only get returned the log events since their last fetch.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 15
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
-**Note**: this method is not supported on a Coordinator in a cluster.
+HTTP/1.1 202 Accepted
+content-type: text/plain
+connection: Keep-Alive
+content-length: 0
+server: ArangoDB
+x-arango-async-id: 81829
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTRETURNCODES
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81829
-@RESTRETURNCODE{200}
-is returned if the request was executed successfully, and there are log
-events available for the requested range. The response body will not be empty
-in this case.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 61
+server: ArangoDB
+x-arango-async-id: 81829
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTRETURNCODE{204}
-is returned if the request was executed successfully, but there are no log
-events available for the requested range. The response body will be empty
-in this case.
+{
+ "server" : "arango",
+ "license" : "enterprise",
+ "version" : "3.9.12"
+}
+
+
Hide response body
+
+
+shell> curl -X PUT --header 'x-arango-async: store' --header 'accept: application/json' --dump - http://localhost:8529/_api/version
-@RESTRETURNCODE{400}
-is returned if either the *from* or *to* values are invalid.
+HTTP/1.1 202 Accepted
+content-type: text/plain
+connection: Keep-Alive
+content-length: 0
+server: ArangoDB
+x-arango-async-id: 81829
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81829
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 61
+server: ArangoDB
+x-arango-async-id: 81829
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
-
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-follow?from=180303
+shell> curl -X POST --header 'x-arango-async: store' --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
+{
+ "collections" : {
+ "read" : [
+ "_aqlfunctions"
+ ]
+ },
+ "action" : "function () {require('internal').sleep(15.0);}"
+}
+EOF
+
+HTTP/1.1 202 Accepted
+content-type: text/plain
+connection: Keep-Alive
+content-length: 0
+server: ArangoDB
+x-arango-async-id: 81831
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/job/81831
HTTP/1.1 204 No Content
-content-type: application/x-arango-dump
+content-type: text/plain
connection: Keep-Alive
content-length: 0
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
-x-arango-replication-active: true
-x-arango-replication-checkmore: false
-x-arango-replication-frompresent: true
-x-arango-replication-lastincluded: 0
-x-arango-replication-lastscanned: 180303
-x-arango-replication-lasttick: 180303
x-content-type-options: nosniff
@@ -34285,207 +35447,89 @@ x-content-type-options: nosniff
+@endDocuBlock
-A few log events *(One JSON document per line)*
+
+@startDocuBlock delete_api_analyzer
+@brief removes an Analyzer configuration
-
-
-
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-follow?from=180303
+@RESTHEADER{DELETE /_api/analyzer/{analyzer-name}, Remove an Analyzer, RestAnalyzerHandler:Delete}
-HTTP/1.1 200 OK
-content-type: application/x-arango-dump
-connection: Keep-Alive
-content-length: 1612
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-arango-replication-active: true
-x-arango-replication-checkmore: false
-x-arango-replication-frompresent: true
-x-arango-replication-lastincluded: 180329
-x-arango-replication-lastscanned: 180326
-x-arango-replication-lasttick: 180329
-x-content-type-options: nosniff
+@RESTURLPARAMETERS
-{
- "tick" : "180306",
- "type" : 2300,
- "database" : "1",
- "tid" : "0",
- "cid" : "4",
- "cname" : "_users",
- "data" : {
- "_key" : "89",
- "_id" : "_users/89",
- "_rev" : "_gM2QjUC---",
- "user" : "root",
- "source" : "LOCAL",
- "authData" : {
- "active" : true,
- "simple" : {
- "hash" : "20a54bb107469df1982a6912605eba448b494794f218315fdf34aa928c19b1f4",
- "salt" : "1c976c9e",
- "method" : "sha256"
- }
- },
- "databases" : {
- "*" : {
- "permissions" : {
- "read" : true,
- "write" : true
- },
- "collections" : {
- "*" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- }
- }
- },
- "_system" : {
- "permissions" : {
- "read" : true,
- "write" : true
- },
- "collections" : {
- "products" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- },
- "products1" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- },
- "animals" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- },
- "*" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- },
- "demo" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- }
- }
- }
- }
- }
-}↩
-{
- "tick" : "180319",
- "type" : 2001,
- "database" : "1",
- "cuid" : "h4B0D1F61ADB6/68894",
- "cid" : "68894",
- "data" : {
- "id" : "68894",
- "name" : ""
- }
-}↩
-{
- "tick" : "180327",
- "type" : 2300,
- "database" : "1",
- "tid" : "0",
- "cid" : "4",
- "cname" : "_users",
- "data" : {
- "_key" : "89",
- "_id" : "_users/89",
- "_rev" : "_gM2QjUK---",
- "user" : "root",
- "source" : "LOCAL",
- "authData" : {
- "active" : true,
- "simple" : {
- "hash" : "20a54bb107469df1982a6912605eba448b494794f218315fdf34aa928c19b1f4",
- "salt" : "1c976c9e",
- "method" : "sha256"
- }
- },
- "databases" : {
- "_system" : {
- "permissions" : {
- "read" : true,
- "write" : true
- },
- "collections" : {
- "demo" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- },
- "*" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- },
- "animals" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- },
- "products1" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- }
- }
- },
- "*" : {
- "permissions" : {
- "read" : true,
- "write" : true
- },
- "collections" : {
- "*" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- }
- }
- }
- }
- }
-}↩
+@RESTURLPARAM{analyzer-name,string,required}
+The name of the Analyzer to remove.
+
+@RESTQUERYPARAMETERS
+
+@RESTQUERYPARAM{force,boolean,optional}
+The Analyzer configuration should be removed even if it is in-use.
+The default value is *false*.
+
+@RESTDESCRIPTION
+Removes an Analyzer configuration identified by *analyzer-name*.
+
+If the Analyzer definition was successfully dropped, an object is returned with
+the following attributes:
+- *error*: *false*
+- *name*: The name of the removed Analyzer
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+The Analyzer configuration was removed successfully.
+
+@RESTRETURNCODE{400}
+The *analyzer-name* was not supplied or another request parameter was not
+valid.
+
+@RESTRETURNCODE{403}
+The user does not have permission to remove this Analyzer configuration.
+
+@RESTRETURNCODE{404}
+Such an Analyzer configuration does not exist.
+
+@RESTRETURNCODE{409}
+The specified Analyzer configuration is still in use and *force* was omitted or
+*false* specified.
+
+@EXAMPLES
+
+Removing without *force*:
+
+
+
+
+
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/analyzer/testAnalyzer
+
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 57
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
+{
+ "error" : false,
+ "code" : 200,
+ "name" : "_system::testAnalyzer"
+}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-follow?from=180303
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/analyzer/testAnalyzer
-HTTP/1.1 200 OK
-content-type: application/x-arango-dump
+HTTP/1.1 200 OK
+content-type: application/json
connection: Keep-Alive
-content-length: 1612
+content-length: 57
server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-arango-replication-active: true
-x-arango-replication-checkmore: false
-x-arango-replication-frompresent: true
-x-arango-replication-lastincluded: 180329
-x-arango-replication-lastscanned: 180326
-x-arango-replication-lasttick: 180329
+x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body
@@ -34494,126 +35538,83 @@ x-content-type-options: nosniff
+Removing with *force*:
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection <<EOF
+{
+ "name" : "testCollection"
+}
+EOF
-More events than would fit into the response
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view <<EOF
+{
+ "name" : "testView",
+ "type" : "arangosearch",
+ "links" : {
+ "testCollection" : {
+ "analyzers" : [
+ "testAnalyzer"
+ ]
+ }
+ }
+}
+EOF
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/analyzer/testAnalyzer?force=false
-
-
-
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-follow?from=180271&chunkSize=400
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/analyzer/testAnalyzer?force=true
HTTP/1.1 200 OK
-content-type: application/x-arango-dump
+content-type: application/json
connection: Keep-Alive
-content-length: 773
+content-length: 57
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
-x-arango-replication-active: true
-x-arango-replication-checkmore: true
-x-arango-replication-frompresent: true
-x-arango-replication-lastincluded: 180276
-x-arango-replication-lastscanned: 180273
-x-arango-replication-lasttick: 180303
x-content-type-options: nosniff
{
- "tick" : "180274",
- "type" : 2300,
- "database" : "1",
- "tid" : "0",
- "cid" : "4",
- "cname" : "_users",
- "data" : {
- "_key" : "89",
- "_id" : "_users/89",
- "_rev" : "_gM2QiTa---",
- "user" : "root",
- "source" : "LOCAL",
- "authData" : {
- "active" : true,
- "simple" : {
- "hash" : "20a54bb107469df1982a6912605eba448b494794f218315fdf34aa928c19b1f4",
- "salt" : "1c976c9e",
- "method" : "sha256"
- }
- },
- "databases" : {
- "*" : {
- "permissions" : {
- "read" : true,
- "write" : true
- },
- "collections" : {
- "*" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- }
- }
- },
- "_system" : {
- "permissions" : {
- "read" : true,
- "write" : true
- },
- "collections" : {
- "products" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- },
- "products1" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- },
- "animals" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- },
- "*" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- },
- "demo" : {
- "permissions" : {
- "read" : true,
- "write" : true
- }
- }
- }
- }
- }
- }
+ "error" : false,
+ "code" : 200,
+ "name" : "_system::testAnalyzer"
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-follow?from=180271&chunkSize=400
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection <<EOF
+{
+ "name" : "testCollection"
+}
+EOF
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view <<EOF
+{
+ "name" : "testView",
+ "type" : "arangosearch",
+ "links" : {
+ "testCollection" : {
+ "analyzers" : [
+ "testAnalyzer"
+ ]
+ }
+ }
+}
+EOF
+
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/analyzer/testAnalyzer?force=false
+
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/analyzer/testAnalyzer?force=true
HTTP/1.1 200 OK
-content-type: application/x-arango-dump
+content-type: application/json
connection: Keep-Alive
-content-length: 773
+content-length: 57
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
-x-arango-replication-active: true
-x-arango-replication-checkmore: true
-x-arango-replication-frompresent: true
-x-arango-replication-lastincluded: 180276
-x-arango-replication-lastscanned: 180273
-x-arango-replication-lasttick: 180303
x-content-type-options: nosniff
Show response body
@@ -34624,109 +35625,345 @@ x-content-type-options: nosniff
+
@endDocuBlock
-
-@startDocuBlock get_api_replication_logger_return_state
+
+@startDocuBlock get_api_analyzer
-@brief returns the state of the replication logger
+@brief returns an Analyzer definition
-@RESTHEADER{GET /_api/replication/logger-state, Return replication logger state, handleCommandLoggerState}
+@RESTHEADER{GET /_api/analyzer/{analyzer-name}, Return the Analyzer definition, RestAnalyzerHandler:GetDefinition}
+
+@RESTURLPARAMETERS
+
+@RESTURLPARAM{analyzer-name,string,required}
+The name of the Analyzer to retrieve.
@RESTDESCRIPTION
-Returns the current state of the server's replication logger. The state will
-include information about whether the logger is running and about the last
-logged tick value. This tick value is important for incremental fetching of
-data.
+Retrieves the full definition for the specified Analyzer name.
+The resulting object contains the following attributes:
+- *name*: the Analyzer name
+- *type*: the Analyzer type
+- *properties*: the properties used to configure the specified type
+- *features*: the set of features to set on the Analyzer generated fields
-The body of the response contains a JSON object with the following
-attributes:
+@RESTRETURNCODES
-- *state*: the current logger state as a JSON object with the following
- sub-attributes:
+@RESTRETURNCODE{200}
+The Analyzer definition was retrieved successfully.
- - *running*: whether or not the logger is running
+@RESTRETURNCODE{404}
+Such an Analyzer configuration does not exist.
- - *lastLogTick*: the tick value of the latest tick the logger has logged.
- This value can be used for incremental fetching of log data.
+@EXAMPLES
- - *totalEvents*: total number of events logged since the server was started.
- The value is not reset between multiple stops and re-starts of the logger.
+Retrieve an Analyzer definition:
- - *time*: the current date and time on the logger server
-- *server*: a JSON object with the following sub-attributes:
+
+
+
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/analyzer/testAnalyzer
- - *version*: the logger server's version
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 105
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
- - *serverId*: the logger server's id
+{
+ "error" : false,
+ "code" : 200,
+ "type" : "identity",
+ "properties" : {
+ },
+ "name" : "_system::testAnalyzer",
+ "features" : [ ]
+}
+
+
Hide response body
+
+
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/analyzer/testAnalyzer
-- *clients*: returns the last fetch status by replication clients connected to
- the logger. Each client is returned as a JSON object with the following attributes:
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 105
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
Show response body
+
+
- - *syncerId*: id of the client syncer
- - *serverId*: server id of client
- - *lastServedTick*: last tick value served to this client via the WAL tailing API
- - *time*: date and time when this client last called the WAL tailing API
-@RESTRETURNCODES
+@endDocuBlock
-@RESTRETURNCODE{200}
-is returned if the logger state could be determined successfully.
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
+
+@startDocuBlock get_api_analyzers
-@RESTRETURNCODE{500}
-is returned if the logger state could not be determined.
+@brief returns a listing of available Analyzer definitions
+
+@RESTHEADER{GET /_api/analyzer, List all Analyzers, RestAnalyzerHandler:List}
+
+@RESTDESCRIPTION
+Retrieves a an array of all Analyzer definitions.
+The resulting array contains objects with the following attributes:
+- *name*: the Analyzer name
+- *type*: the Analyzer type
+- *properties*: the properties used to configure the specified type
+- *features*: the set of features to set on the Analyzer generated fields
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+The Analyzer definitions was retrieved successfully.
@EXAMPLES
-Returns the state of the replication logger.
+Retrieve all Analyzer definitions:
-
-
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-state
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/analyzer
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 224
+content-length: 2116
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "state" : {
- "running" : true,
- "lastLogTick" : "180329",
- "lastUncommittedLogTick" : "180329",
- "totalEvents" : 180329,
- "time" : "2023-06-24T15:42:56Z"
- },
- "server" : {
- "version" : "3.9.12",
- "serverId" : "82519733153206",
- "engine" : "rocksdb"
- },
- "clients" : [ ]
+ "error" : false,
+ "code" : 200,
+ "result" : [
+ {
+ "name" : "text_zh",
+ "type" : "text",
+ "properties" : {
+ "locale" : "zh",
+ "case" : "lower",
+ "stopwords" : [ ],
+ "accent" : false,
+ "stemming" : false
+ },
+ "features" : [
+ "frequency",
+ "position",
+ "norm"
+ ]
+ },
+ {
+ "name" : "text_sv",
+ "type" : "text",
+ "properties" : {
+ "locale" : "sv",
+ "case" : "lower",
+ "stopwords" : [ ],
+ "accent" : false,
+ "stemming" : true
+ },
+ "features" : [
+ "frequency",
+ "position",
+ "norm"
+ ]
+ },
+ {
+ "name" : "text_nl",
+ "type" : "text",
+ "properties" : {
+ "locale" : "nl",
+ "case" : "lower",
+ "stopwords" : [ ],
+ "accent" : false,
+ "stemming" : true
+ },
+ "features" : [
+ "frequency",
+ "position",
+ "norm"
+ ]
+ },
+ {
+ "name" : "text_it",
+ "type" : "text",
+ "properties" : {
+ "locale" : "it",
+ "case" : "lower",
+ "stopwords" : [ ],
+ "accent" : false,
+ "stemming" : true
+ },
+ "features" : [
+ "frequency",
+ "position",
+ "norm"
+ ]
+ },
+ {
+ "name" : "text_fr",
+ "type" : "text",
+ "properties" : {
+ "locale" : "fr",
+ "case" : "lower",
+ "stopwords" : [ ],
+ "accent" : false,
+ "stemming" : true
+ },
+ "features" : [
+ "frequency",
+ "position",
+ "norm"
+ ]
+ },
+ {
+ "name" : "text_pt",
+ "type" : "text",
+ "properties" : {
+ "locale" : "pt",
+ "case" : "lower",
+ "stopwords" : [ ],
+ "accent" : false,
+ "stemming" : true
+ },
+ "features" : [
+ "frequency",
+ "position",
+ "norm"
+ ]
+ },
+ {
+ "name" : "text_no",
+ "type" : "text",
+ "properties" : {
+ "locale" : "no",
+ "case" : "lower",
+ "stopwords" : [ ],
+ "accent" : false,
+ "stemming" : true
+ },
+ "features" : [
+ "frequency",
+ "position",
+ "norm"
+ ]
+ },
+ {
+ "name" : "text_fi",
+ "type" : "text",
+ "properties" : {
+ "locale" : "fi",
+ "case" : "lower",
+ "stopwords" : [ ],
+ "accent" : false,
+ "stemming" : true
+ },
+ "features" : [
+ "frequency",
+ "position",
+ "norm"
+ ]
+ },
+ {
+ "name" : "text_es",
+ "type" : "text",
+ "properties" : {
+ "locale" : "es",
+ "case" : "lower",
+ "stopwords" : [ ],
+ "accent" : false,
+ "stemming" : true
+ },
+ "features" : [
+ "frequency",
+ "position",
+ "norm"
+ ]
+ },
+ {
+ "name" : "text_en",
+ "type" : "text",
+ "properties" : {
+ "locale" : "en",
+ "case" : "lower",
+ "stopwords" : [ ],
+ "accent" : false,
+ "stemming" : true
+ },
+ "features" : [
+ "frequency",
+ "position",
+ "norm"
+ ]
+ },
+ {
+ "name" : "text_ru",
+ "type" : "text",
+ "properties" : {
+ "locale" : "ru",
+ "case" : "lower",
+ "stopwords" : [ ],
+ "accent" : false,
+ "stemming" : true
+ },
+ "features" : [
+ "frequency",
+ "position",
+ "norm"
+ ]
+ },
+ {
+ "name" : "text_de",
+ "type" : "text",
+ "properties" : {
+ "locale" : "de",
+ "case" : "lower",
+ "stopwords" : [ ],
+ "accent" : false,
+ "stemming" : true
+ },
+ "features" : [
+ "frequency",
+ "position",
+ "norm"
+ ]
+ },
+ {
+ "name" : "identity",
+ "type" : "identity",
+ "properties" : {
+ },
+ "features" : [
+ "frequency",
+ "norm"
+ ]
+ }
+ ]
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-state
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/analyzer
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 224
+content-length: 2116
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -34736,109 +35973,90 @@ x-content-type-options: nosniff
-
-
@endDocuBlock
-
-@startDocuBlock get_api_replication_logger_tick_ranges
-
-@brief returns the tick value ranges available in the logfiles
+
+@startDocuBlock post_api_analyzer
-@RESTHEADER{GET /_api/replication/logger-tick-ranges, Return the tick ranges available in the WAL logfiles,handleCommandLoggerTickRanges}
+@brief creates a new Analyzer based on the provided definition
-@RESTDESCRIPTION
-Returns the currently available ranges of tick values for all currently
-available WAL logfiles. The tick values can be used to determine if certain
-data (identified by tick value) are still available for replication.
+@RESTHEADER{POST /_api/analyzer, Create an Analyzer with the supplied definition, RestAnalyzerHandler:Create}
-The body of the response contains a JSON array. Each array member is an
-object
-that describes a single logfile. Each object has the following attributes:
+@RESTBODYPARAM{name,string,required,string}
+The Analyzer name.
-* *datafile*: name of the logfile
+@RESTBODYPARAM{type,string,required,string}
+The Analyzer type.
-* *status*: status of the datafile, in textual form (e.g. "sealed", "open")
+@RESTBODYPARAM{properties,object,optional,}
+The properties used to configure the specified Analyzer type.
-* *tickMin*: minimum tick value contained in logfile
+@RESTBODYPARAM{features,array,optional,string}
+The set of features to set on the Analyzer generated fields.
+The default value is an empty array.
-* *tickMax*: maximum tick value contained in logfile
+@RESTDESCRIPTION
+Creates a new Analyzer based on the provided configuration.
@RESTRETURNCODES
@RESTRETURNCODE{200}
-is returned if the tick ranges could be determined successfully.
+An Analyzer with a matching name and definition already exists.
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
+@RESTRETURNCODE{201}
+A new Analyzer definition was successfully created.
-@RESTRETURNCODE{500}
-is returned if the logger state could not be determined.
+@RESTRETURNCODE{400}
+One or more of the required parameters is missing or one or more of the parameters
+is not valid.
-@RESTRETURNCODE{501}
-is returned when this operation is called on a Coordinator in a cluster.
+@RESTRETURNCODE{403}
+The user does not have permission to create and Analyzer with this configuration.
@EXAMPLES
-Returns the available tick ranges.
-
-
-
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-tick-ranges
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/analyzer <<EOF
+{
+ "name" : "testAnalyzer",
+ "type" : "identity"
+}
+EOF
-HTTP/1.1 200 OK
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 458
+content-length: 80
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
-[
- {
- "datafile" : "/archive/000087.log",
- "status" : "collected",
- "tickMin" : "175570",
- "tickMax" : "175666"
- },
- {
- "datafile" : "/archive/000110.log",
- "status" : "collected",
- "tickMin" : "175666",
- "tickMax" : "175709"
- },
- {
- "datafile" : "/archive/000119.log",
- "status" : "collected",
- "tickMin" : "175709",
- "tickMax" : "176272"
- },
- {
- "datafile" : "/archive/000121.log",
- "status" : "collected",
- "tickMin" : "176272",
- "tickMax" : "176291"
+{
+ "name" : "_system::testAnalyzer",
+ "type" : "identity",
+ "properties" : {
},
- {
- "datafile" : "/000128.log",
- "status" : "open",
- "tickMin" : "176291",
- "tickMax" : "180329"
- }
-]
+ "features" : [ ]
+}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/logger-tick-ranges
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/analyzer <<EOF
+{
+ "name" : "testAnalyzer",
+ "type" : "identity"
+}
+EOF
-HTTP/1.1 200 OK
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 458
+content-length: 80
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -34849,155 +36067,107 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-
-@startDocuBlock get_api_replication_revisions_tree
+@endDocuBlock
-@brief retrieves the Merkle tree associated with the collection
-@RESTHEADER{GET /_api/replication/revisions/tree, Return Merkle tree for a collection,handleCommandRevisionTree}
+
+@startDocuBlock delete_api_transaction
-@HINTS
-{% hint 'warning' %}
-This revision-based replication endpoint will only work with collections
-created in ArangoDB v3.8.0 or later.
-{% endhint %}
+@brief abort a server-side transaction
-@RESTQUERYPARAMETERS
+@RESTHEADER{DELETE /_api/transaction/{transaction-id}, Abort transaction, executeAbort:transaction}
-@RESTQUERYPARAM{collection,string,required}
-The name or id of the collection to query.
+@RESTURLPARAMETERS
-@RESTQUERYPARAM{batchId,number,required}
-The id of the snapshot to use
+@RESTURLPARAM{transaction-id,string,required}
+The transaction identifier,
@RESTDESCRIPTION
-Returns the Merkle tree from the collection.
-
-The result will be JSON/VelocyPack in the following format:
-```
-{
- version: ,
- branchingFactor:
- maxDepth: ,
- rangeMin: ,
- rangeMax: ,
- nodes: [
- { count: , hash: },
- { count: , hash: },
- ...
- { count: , hash: }
- ]
-}
-```
-
-At the moment, there is only one version, 1, so this can safely be ignored for
-now.
-
-Each `` value type is a 64-bit value encoded as a string of
-11 characters, using the same encoding as our document `_rev` values. The
-reason for this is that 64-bit values cannot necessarily be represented in full
-in JavaScript, as it handles all numbers as floating point, and can only
-represent up to `2^53-1` faithfully.
-
-The node count should correspond to a full tree with the given `maxDepth` and
-`branchingFactor`. The nodes are laid out in level-order tree traversal, so the
-root is at index `0`, its children at indices `[1, branchingFactor]`, and so
-on.
-
-@RESTRETURNCODES
-
-@RESTRETURNCODE{200}
-is returned if the request was executed successfully and data was returned.
-
-@RESTRETURNCODE{401}
-is returned if necessary parameters are missing
-
-@RESTRETURNCODE{404}
-is returned when the collection or snapshot could not be found.
-
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
+Abort a running server-side transaction. Aborting is an idempotent operation.
+It is not an error to abort a transaction more than once.
-@RESTRETURNCODE{500}
-is returned if an error occurred while assembling the response.
+If the transaction can be aborted, *HTTP 200* will be returned.
+The returned JSON object has the following properties:
-@RESTRETURNCODE{501}
-is returned if called on a collection which doesn't support sync-by-revision
+- *error*: boolean flag to indicate if an error occurred (*false*
+ in this case)
-@endDocuBlock
+- *code*: the HTTP status code
+- *result*: result containing
+ - *id*: the identifier of the transaction
+ - *status*: containing the string 'aborted'
-
-@startDocuBlock get_api_wal_access_last_tick
+If the transaction cannot be found, aborting is not allowed or the
+transaction was already committed, the server
+will respond with *HTTP 400*, *HTTP 404* or *HTTP 409*.
-@brief Return last available tick value
+The body of the response will then contain a JSON object with additional error
+details. The object has the following attributes:
-@RESTHEADER{GET /_api/wal/lastTick, Return last available tick value, handleCommandLastTick}
+- *error*: boolean flag to indicate that an error occurred (*true* in this case)
-@RESTDESCRIPTION
-Returns the last available tick value that can be served from the server's
-replication log. This corresponds to the tick of the latest successfull operation.
+- *code*: the HTTP status code
-The result is a JSON object containing the attributes *tick*, *time* and *server*.
-* *tick*: contains the last available tick, *time*
-* *time*: the server time as string in format "YYYY-MM-DDTHH:MM:SSZ"
-* *server*: An object with fields *version* and *serverId*
+- *errorNum*: the server error number
-**Note**: this method is not supported on a Coordinator in a cluster.
+- *errorMessage*: a descriptive error message
@RESTRETURNCODES
@RESTRETURNCODE{200}
-is returned if the request was executed successfully.
+If the transaction was aborted,
+*HTTP 200* will be returned.
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
+@RESTRETURNCODE{400}
+If the transaction cannot be aborted, the server
+will respond with *HTTP 400*.
-@RESTRETURNCODE{500}
-is returned if an error occurred while assembling the response.
+@RESTRETURNCODE{404}
+If the transaction was not found, the server
+will respond with *HTTP 404*.
-@RESTRETURNCODE{501}
-is returned when this operation is called on a Coordinator in a cluster.
+@RESTRETURNCODE{409}
+If the transaction was already committed, the server
+will respond with *HTTP 409*.
@EXAMPLES
-Returning the first available tick
+Aborting a transaction:
-
-
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/wal/lastTick
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction/68965
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 105
+content-length: 69
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "time" : "2023-06-24T15:42:56Z",
- "tick" : "180619",
- "server" : {
- "version" : "3.9.12",
- "serverId" : "82519733153206"
+ "code" : 200,
+ "error" : false,
+ "result" : {
+ "id" : "68965",
+ "status" : "aborted"
}
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/wal/lastTick
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction/68965
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 105
+content-length: 69
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -35007,338 +36177,83 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-
-
-@startDocuBlock get_api_wal_access_range
-
-@brief returns the tick ranges available in the write-ahead-log
-
-@RESTHEADER{GET /_api/wal/range, Return tick ranges available in the operations of WAL, handleCommandTickRange}
-
-@RESTDESCRIPTION
-Returns the currently available ranges of tick values for all WAL files.
-The tick values can be used to determine if certain
-data (identified by tick value) are still available for replication.
-
-The body of the response contains a JSON object.
-* *tickMin*: minimum tick available
-* *tickMax*: maximum tick available
-* *time*: the server time as string in format "YYYY-MM-DDTHH:MM:SSZ"
-* *server*: An object with fields *version* and *serverId*
-
-@RESTRETURNCODES
-
-@RESTRETURNCODE{200}
-is returned if the tick ranges could be determined successfully.
-
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
-
-@RESTRETURNCODE{500}
-is returned if the server operations state could not be determined.
-
-@RESTRETURNCODE{501}
-is returned when this operation is called on a Coordinator in a cluster.
-
-@EXAMPLES
-
-Returns the available tick ranges.
-
-
-
-
-
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/wal/range
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 127
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
-{
- "time" : "2023-06-24T15:42:58Z",
- "tickMin" : "175570",
- "tickMax" : "180680",
- "server" : {
- "version" : "3.9.12",
- "serverId" : "82519733153206"
- }
-}
-
-
Hide response body
-
-
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/wal/range
-
-HTTP/1.1 200 OK
-content-type: application/json
-connection: Keep-Alive
-content-length: 127
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-content-type-options: nosniff
-
Show response body
-
-
-
-
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/wal/tail?from=180654
+- *id*: the identifier of the transaction
-HTTP/1.1 204 No Content
-content-type: application/x-arango-dump
-connection: Keep-Alive
-content-length: 0
-server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-arango-replication-checkmore: false
-x-arango-replication-frompresent: true
-x-arango-replication-lastincluded: 0
-x-arango-replication-lastscanned: 180652
-x-arango-replication-lasttick: 180654
-x-content-type-options: nosniff
+- *status*: the status of the transaction. One of "running", "committed" or "aborted".
-
-
-
-
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/wal/tail?from=180654
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction/68983
-HTTP/1.1 200 OK
-content-type: application/x-arango-dump
+HTTP/1.1 200 OK
+content-type: application/json
connection: Keep-Alive
-content-length: 74
+content-length: 69
server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-arango-replication-checkmore: true
-x-arango-replication-frompresent: true
-x-arango-replication-lastincluded: 180670
-x-arango-replication-lastscanned: 180680
-x-arango-replication-lasttick: 180680
+x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "tick" : "180670",
- "type" : 2001,
- "db" : "_system",
- "cuid" : "h4B0D1F61ADB6/69137"
-}↩
+ "code" : 200,
+ "error" : false,
+ "result" : {
+ "id" : "68983",
+ "status" : "running"
+ }
+}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/wal/tail?from=180654
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction/68983
-HTTP/1.1 200 OK
-content-type: application/x-arango-dump
+HTTP/1.1 200 OK
+content-type: application/json
connection: Keep-Alive
-content-length: 74
+content-length: 69
server: ArangoDB
-x-arango-queue-time-seconds: 0.000000
-x-arango-replication-checkmore: true
-x-arango-replication-frompresent: true
-x-arango-replication-lastincluded: 180670
-x-arango-replication-lastscanned: 180680
-x-arango-replication-lasttick: 180680
+x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body
@@ -35348,52 +36263,69 @@ x-content-type-options: nosniff
+@endDocuBlock
-More events than would fit into the response
+
+@startDocuBlock get_api_transactions
+@brief Return the currently running server-side transactions
-
-
+@RESTHEADER{GET /_api/transaction, Get currently running transactions, executeGetState:transactions}
+
+@RESTDESCRIPTION
+The result is an object with the attribute *transactions*, which contains
+an array of transactions.
+In a cluster the array will contain the transactions from all Coordinators.
+
+Each array entry contains an object with the following attributes:
+
+- *id*: the transaction's id
+- *state*: the transaction's status
+
+@RESTRETURNCODES
+
+@RESTRETURNCODE{200}
+If the list of transactions can be retrieved successfully, *HTTP 200* will be returned.
+
+@EXAMPLES
+
+Get currently running transactions
+
+
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/wal/tail?from=180619&chunkSize=400
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction
HTTP/1.1 200 OK
-content-type: application/x-arango-dump
+content-type: application/json
connection: Keep-Alive
-content-length: 74
+content-length: 51
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
-x-arango-replication-checkmore: true
-x-arango-replication-frompresent: true
-x-arango-replication-lastincluded: 180635
-x-arango-replication-lastscanned: 180654
-x-arango-replication-lasttick: 180654
x-content-type-options: nosniff
{
- "tick" : "180635",
- "type" : 2001,
- "db" : "_system",
- "cuid" : "h4B0D1F61ADB6/69121"
+ "transactions" : [
+ {
+ "id" : "69022",
+ "state" : "running"
+ }
+ ]
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/wal/tail?from=180619&chunkSize=400
+shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction
HTTP/1.1 200 OK
-content-type: application/x-arango-dump
+content-type: application/json
connection: Keep-Alive
-content-length: 74
+content-length: 51
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
-x-arango-replication-checkmore: true
-x-arango-replication-frompresent: true
-x-arango-replication-lastincluded: 180635
-x-arango-replication-lastscanned: 180654
-x-arango-replication-lasttick: 180654
x-content-type-options: nosniff
Show response body
@@ -35403,278 +36335,331 @@ x-content-type-options: nosniff
-
@endDocuBlock
-
-@startDocuBlock post_api_replication_revisions_tree
-
-@brief rebuilds the Merkle tree associated with the collection
-
-@RESTHEADER{POST /_api/replication/revisions/tree, Rebuild Merkle tree for a collection,handleCommandRebuildRevisionTree}
-
-@HINTS
-{% hint 'warning' %}
-This revision-based replication endpoint will only work with collections
-created in ArangoDB v3.8.0 or later.
-{% endhint %}
-
-@RESTQUERYPARAMETERS
-
-@RESTQUERYPARAM{collection,string,required}
-The name or id of the collection to query.
+
+@startDocuBlock post_api_transaction
-@RESTDESCRIPTION
-Rebuilds the Merkle tree for the collection.
+@brief execute a server-side transaction
-If successful, there will be no return body.
+@RESTHEADER{POST /_api/transaction, Execute transaction, executeCommit}
-@RESTRETURNCODES
+@RESTBODYPARAM{collections,string,required,string}
+*collections* must be a JSON object that can have one or all sub-attributes
+*read*, *write* or *exclusive*, each being an array of collection names or a
+single collection name as string. Collections that will be written to in the
+transaction must be declared with the *write* or *exclusive* attribute or it
+will fail, whereas non-declared collections from which is solely read will be
+added lazily. The optional sub-attribute *allowImplicit* can be set to *false*
+to let transactions fail in case of undeclared collections for reading.
+Collections for reading should be fully declared if possible, to avoid
+deadlocks.
-@RESTRETURNCODE{204}
-is returned if the request was executed successfully.
+@RESTBODYPARAM{action,string,required,string}
+the actual transaction operations to be executed, in the
+form of stringified JavaScript code. The code will be executed on server
+side, with late binding. It is thus critical that the code specified in
+*action* properly sets up all the variables it needs.
+If the code specified in *action* ends with a return statement, the
+value returned will also be returned by the REST API in the *result*
+attribute if the transaction committed successfully.
-@RESTRETURNCODE{401}
-is returned if necessary parameters are missing
+@RESTBODYPARAM{waitForSync,boolean,optional,}
+an optional boolean flag that, if set, will force the
+transaction to write all data to disk before returning.
-@RESTRETURNCODE{404}
-is returned when the collection or could not be found.
+@RESTBODYPARAM{allowImplicit,boolean,optional,}
+Allow reading from undeclared collections.
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
+@RESTBODYPARAM{lockTimeout,integer,optional,int64}
+an optional numeric value that can be used to set a
+timeout in seconds for waiting on collection locks. This option is only
+meaningful when using exclusive locks. If not specified, a default value of
+900 seconds will be used. Setting *lockTimeout* to *0* will make ArangoDB
+not time out waiting for a lock.
-@RESTRETURNCODE{500}
-is returned if an error occurred while assembling the response.
+@RESTBODYPARAM{params,string,optional,string}
+optional arguments passed to *action*.
-@RESTRETURNCODE{501}
-is returned if called on a collection which doesn't support sync-by-revision
+@RESTBODYPARAM{maxTransactionSize,integer,optional,int64}
+Transaction size limit in bytes.
-@endDocuBlock
+@RESTDESCRIPTION
+The transaction description must be passed in the body of the POST request.
+If the transaction is fully executed and committed on the server,
+*HTTP 200* will be returned. Additionally, the return value of the
+code defined in *action* will be returned in the *result* attribute.
-
-@startDocuBlock post_batch_replication
+For successfully committed transactions, the returned JSON object has the
+following properties:
-@brief handle a dump batch command
+- *error*: boolean flag to indicate if an error occurred (*false*
+ in this case)
-@RESTHEADER{POST /_api/replication/batch, Create new dump batch, handleCommandBatch:Create}
+- *code*: the HTTP status code
-**Note**: These calls are uninteresting to users.
+- *result*: the return value of the transaction
-@RESTQUERYPARAMETERS
+If the transaction specification is either missing or malformed, the server
+will respond with *HTTP 400*.
-@RESTQUERYPARAM{state,boolean,optional}
-setting `state` to true will make the response also contain
-a `state` attribute with information about the leader state.
-This is used only internally during the replication process
-and should not be used by client applications.
+The body of the response will then contain a JSON object with additional error
+details. The object has the following attributes:
-@RESTBODYPARAM{ttl,integer,required,int64}
-the time-to-live for the new batch (in seconds)
-A JSON object with the batch configuration.
+- *error*: boolean flag to indicate that an error occurred (*true* in this case)
-@RESTDESCRIPTION
-Creates a new dump batch and returns the batch's id.
+- *code*: the HTTP status code
-The response is a JSON object with the following attributes:
+- *errorNum*: the server error number
-- *id*: the id of the batch
-- *lastTick*: snapshot tick value using when creating the batch
-- *state*: additional leader state information (only present if the
- `state` URL parameter was set to `true` in the request)
+- *errorMessage*: a descriptive error message
-**Note**: on a Coordinator, this request must have the query parameter
-*DBserver* which must be an ID of a DB-Server.
-The very same request is forwarded synchronously to that DB-Server.
-It is an error if this attribute is not bound in the Coordinator case.
+If a transaction fails to commit, either by an exception thrown in the
+*action* code, or by an internal error, the server will respond with
+an error.
+Any other errors will be returned with any of the return codes
+*HTTP 400*, *HTTP 409*, or *HTTP 500*.
@RESTRETURNCODES
@RESTRETURNCODE{200}
-is returned if the batch was created successfully.
+If the transaction is fully executed and committed on the server,
+*HTTP 200* will be returned.
@RESTRETURNCODE{400}
-is returned if the ttl value is invalid or if *DBserver* attribute
-is not specified or illegal on a Coordinator.
-
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
-@endDocuBlock
-
-
-
-@startDocuBlock put_api_replication_applier
-
-@brief fetch the current replication configuration
+If the transaction specification is either missing or malformed, the server
+will respond with *HTTP 400*.
-@RESTHEADER{GET /_api/replication/applier-config, Return configuration of replication applier, handleCommandApplierGetConfig}
+@RESTRETURNCODE{404}
+If the transaction specification contains an unknown collection, the server
+will respond with *HTTP 404*.
-@RESTQUERYPARAMETERS
+@RESTRETURNCODE{500}
+Exceptions thrown by users will make the server respond with a return code of
+*HTTP 500*
-@RESTQUERYPARAM{global,boolean,optional}
-If set to *true*, returns the configuration of the global replication applier for all
-databases. If set to *false*, returns the configuration of the replication applier in the
-selected database.
+@EXAMPLES
-@RESTDESCRIPTION
-Returns the configuration of the replication applier.
+Executing a transaction on a single collection
-The body of the response is a JSON object with the configuration. The
-following attributes may be present in the configuration:
-- *endpoint*: the logger server to connect to (e.g. "tcp://192.168.173.13:8529").
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
+{
+ "collections" : {
+ "write" : "products"
+ },
+ "action" : "function () { var db = require('@arangodb').db; db.products.save({}); return db.products.count(); }"
+}
+EOF
-- *database*: the name of the database to connect to (e.g. "_system").
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 37
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-- *username*: an optional ArangoDB username to use when connecting to the endpoint.
+{
+ "error" : false,
+ "code" : 200,
+ "result" : 1
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
+{
+ "collections" : {
+ "write" : "products"
+ },
+ "action" : "function () { var db = require('@arangodb').db; db.products.save({}); return db.products.count(); }"
+}
+EOF
-- *password*: the password to use when connecting to the endpoint.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 37
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
-- *maxConnectRetries*: the maximum number of connection attempts the applier
- will make in a row. If the applier cannot establish a connection to the
- endpoint in this number of attempts, it will stop itself.
-- *connectTimeout*: the timeout (in seconds) when attempting to connect to the
- endpoint. This value is used for each connection attempt.
-- *requestTimeout*: the timeout (in seconds) for individual requests to the endpoint.
-- *chunkSize*: the requested maximum size for log transfer packets that
- is used when the endpoint is contacted.
+Executing a transaction using multiple collections
-- *autoStart*: whether or not to auto-start the replication applier on
- (next and following) server starts
-- *adaptivePolling*: whether or not the replication applier will use
- adaptive polling.
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
+{
+ "collections" : {
+ "write" : [
+ "products",
+ "materials"
+ ]
+ },
+ "action" : "function () {var db = require('@arangodb').db;db.products.save({});db.materials.save({});return 'worked!';}"
+}
+EOF
-- *includeSystem*: whether or not system collection operations will be applied
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 45
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-- *autoResync*: whether or not the follower should perform a full automatic
- resynchronization with the leader in case the leader cannot serve log data
- requested by the follower, or when the replication is started and no tick
- value
- can be found.
+{
+ "error" : false,
+ "code" : 200,
+ "result" : "worked!"
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
+{
+ "collections" : {
+ "write" : [
+ "products",
+ "materials"
+ ]
+ },
+ "action" : "function () {var db = require('@arangodb').db;db.products.save({});db.materials.save({});return 'worked!';}"
+}
+EOF
-- *autoResyncRetries*: number of resynchronization retries that will be performed
- in a row when automatic resynchronization is enabled and kicks in. Setting this
- to *0* will effectively disable *autoResync*. Setting it to some other value
- will limit the number of retries that are performed. This helps preventing endless
- retries in case resynchronizations always fail.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 45
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
-- *initialSyncMaxWaitTime*: the maximum wait time (in seconds) that the initial
- synchronization will wait for a response from the leader when fetching initial
- collection data.
- This wait time can be used to control after what time the initial synchronization
- will give up waiting for a response and fail. This value is relevant even
- for continuous replication when *autoResync* is set to *true* because this
- may re-start the initial synchronization when the leader cannot provide
- log data the follwer requires.
- This value will be ignored if set to *0*.
-- *connectionRetryWaitTime*: the time (in seconds) that the applier will
- intentionally idle before it retries connecting to the leader in case of
- connection problems.
- This value will be ignored if set to *0*.
-- *idleMinWaitTime*: the minimum wait time (in seconds) that the applier will
- intentionally idle before fetching more log data from the leader in case
- the leader has already sent all its log data. This wait time can be used
- to control the frequency with which the replication applier sends HTTP log
- fetch requests to the leader in case there is no write activity on the leader.
- This value will be ignored if set to *0*.
-- *idleMaxWaitTime*: the maximum wait time (in seconds) that the applier will
- intentionally idle before fetching more log data from the leader in case the
- leader has already sent all its log data and there have been previous log
- fetch attempts that resulted in no more log data. This wait time can be used
- to control the maximum frequency with which the replication applier sends HTTP
- log fetch requests to the leader in case there is no write activity on the
- leader for longer periods. This configuration value will only be used if the
- option *adaptivePolling* is set to *true*.
- This value will be ignored if set to *0*.
+Aborting a transaction due to an internal error
-- *requireFromPresent*: if set to *true*, then the replication applier will check
- at start whether the start tick from which it starts or resumes replication is
- still present on the leader. If not, then there would be data loss. If
- *requireFromPresent* is *true*, the replication applier will abort with an
- appropriate error message. If set to *false*, then the replication applier will
- still start, and ignore the data loss.
-- *verbose*: if set to *true*, then a log line will be emitted for all operations
- performed by the replication applier. This should be used for debugging
- replication
- problems only.
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
+{
+ "collections" : {
+ "write" : "products"
+ },
+ "action" : "function () {var db = require('@arangodb').db;db.products.save({ _key: 'abc'});db.products.save({ _key: 'abc'});}"
+}
+EOF
-- *restrictType*: the configuration for *restrictCollections*
+HTTP/1.1 409 Conflict
+content-type: application/json
+connection: Keep-Alive
+content-length: 154
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-- *restrictCollections*: the optional array of collections to include or exclude,
- based on the setting of *restrictType*
+{
+ "code" : 409,
+ "error" : true,
+ "errorMessage" : "unique constraint violated - in index primary of type primary over '_key'; conflicting key: abc",
+ "errorNum" : 1210
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
+{
+ "collections" : {
+ "write" : "products"
+ },
+ "action" : "function () {var db = require('@arangodb').db;db.products.save({ _key: 'abc'});db.products.save({ _key: 'abc'});}"
+}
+EOF
-@RESTRETURNCODES
+HTTP/1.1 409 Conflict
+content-type: application/json
+connection: Keep-Alive
+content-length: 154
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
-@RESTRETURNCODE{200}
-is returned if the request was executed successfully.
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
-@RESTRETURNCODE{500}
-is returned if an error occurred while assembling the response.
-@EXAMPLES
+Aborting a transaction by explicitly throwing an exception
-
-
+
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/applier-config
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
+{
+ "collections" : {
+ "read" : "products"
+ },
+ "action" : "function () { throw 'doh!'; }"
+}
+EOF
-HTTP/1.1 200 OK
+HTTP/1.1 500 Internal Server Error
content-type: application/json
connection: Keep-Alive
-content-length: 519
+content-length: 63
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "requestTimeout" : 600,
- "connectTimeout" : 10,
- "ignoreErrors" : 0,
- "maxConnectRetries" : 100,
- "lockTimeoutRetries" : 0,
- "sslProtocol" : 0,
- "chunkSize" : 0,
- "skipCreateDrop" : false,
- "autoStart" : false,
- "adaptivePolling" : true,
- "autoResync" : false,
- "autoResyncRetries" : 2,
- "maxPacketSize" : 536870912,
- "includeSystem" : true,
- "includeFoxxQueues" : false,
- "requireFromPresent" : true,
- "verbose" : false,
- "incremental" : false,
- "restrictType" : "",
- "restrictCollections" : [ ],
- "connectionRetryWaitTime" : 15,
- "initialSyncMaxWaitTime" : 300,
- "idleMinWaitTime" : 1,
- "idleMaxWaitTime" : 2.5
+ "code" : 500,
+ "error" : true,
+ "errorMessage" : "doh!",
+ "errorNum" : 1650
}
-
Hide response body
-
+
-shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/applier-config
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
+{
+ "collections" : {
+ "read" : "products"
+ },
+ "action" : "function () { throw 'doh!'; }"
+}
+EOF
-HTTP/1.1 200 OK
+HTTP/1.1 500 Internal Server Error
content-type: application/json
connection: Keep-Alive
-content-length: 519
+content-length: 63
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -35683,237 +36668,190 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-@startDocuBlock put_api_replication_applier_adjust
+Referring to a non-existing collection
-@brief set configuration values of an applier
-@RESTHEADER{PUT /_api/replication/applier-config, Adjust configuration of replication applier,handleCommandApplierSetConfig}
+
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
+{
+ "collections" : {
+ "read" : "products"
+ },
+ "action" : "function () { return true; }"
+}
+EOF
-@RESTQUERYPARAMETERS
+HTTP/1.1 404 Not Found
+content-type: application/json
+connection: Keep-Alive
+content-length: 97
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTQUERYPARAM{global,boolean,optional}
-If set to *true*, adjusts the configuration of the global replication applier for all
-databases. If set to *false*, adjusts the configuration of the replication applier in the
-selected database.
+{
+ "code" : 404,
+ "error" : true,
+ "errorMessage" : "collection or view not found: products",
+ "errorNum" : 1203
+}
+
+
Hide response body
+
+
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction <<EOF
+{
+ "collections" : {
+ "read" : "products"
+ },
+ "action" : "function () { return true; }"
+}
+EOF
-@RESTBODYPARAM{endpoint,string,required,string}
-the logger server to connect to (e.g. "tcp://192.168.173.13:8529"). The endpoint must be specified.
+HTTP/1.1 404 Not Found
+content-type: application/json
+connection: Keep-Alive
+content-length: 97
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
-@RESTBODYPARAM{database,string,required,string}
-the name of the database on the endpoint. If not specified, defaults to the current local database name.
-@RESTBODYPARAM{username,string,optional,string}
-an optional ArangoDB username to use when connecting to the endpoint.
-@RESTBODYPARAM{password,string,required,string}
-the password to use when connecting to the endpoint.
+@endDocuBlock
-@RESTBODYPARAM{maxConnectRetries,integer,required,int64}
-the maximum number of connection attempts the applier
-will make in a row. If the applier cannot establish a connection to the
-endpoint in this number of attempts, it will stop itself.
-@RESTBODYPARAM{connectTimeout,integer,required,int64}
-the timeout (in seconds) when attempting to connect to the
-endpoint. This value is used for each connection attempt.
+
+@startDocuBlock post_api_transaction_begin
-@RESTBODYPARAM{requestTimeout,integer,required,int64}
-the timeout (in seconds) for individual requests to the endpoint.
+@brief begin a server-side transaction
-@RESTBODYPARAM{chunkSize,integer,required,int64}
-the requested maximum size for log transfer packets that
-is used when the endpoint is contacted.
+@RESTHEADER{POST /_api/transaction/begin, Begin transaction, executeBegin}
-@RESTBODYPARAM{autoStart,boolean,required,}
-whether or not to auto-start the replication applier on
-(next and following) server starts
+@RESTBODYPARAM{collections,string,required,string}
+*collections* must be a JSON object that can have one or all sub-attributes
+*read*, *write* or *exclusive*, each being an array of collection names or a
+single collection name as string. Collections that will be written to in the
+transaction must be declared with the *write* or *exclusive* attribute or it
+will fail, whereas non-declared collections from which is solely read will be
+added lazily.
-@RESTBODYPARAM{adaptivePolling,boolean,required,}
-if set to *true*, the replication applier will fall
-to sleep for an increasingly long period in case the logger server at the
-endpoint does not have any more replication events to apply. Using
-adaptive polling is thus useful to reduce the amount of work for both the
-applier and the logger server for cases when there are only infrequent
-changes. The downside is that when using adaptive polling, it might take
-longer for the replication applier to detect that there are new replication
-events on the logger server.
-Setting *adaptivePolling* to false will make the replication applier
-contact the logger server in a constant interval, regardless of whether
-the logger server provides updates frequently or seldom.
+@RESTBODYPARAM{waitForSync,boolean,optional,}
+an optional boolean flag that, if set, will force the
+transaction to write all data to disk before returning.
-@RESTBODYPARAM{includeSystem,boolean,required,}
-whether or not system collection operations will be applied
+@RESTBODYPARAM{allowImplicit,boolean,optional,}
+Allow reading from undeclared collections.
-@RESTBODYPARAM{autoResync,boolean,optional,}
-whether or not the follower should perform a full automatic resynchronization
-with the leader in case the leader cannot serve log data requested by the
-follower, or when the replication is started and no tick value can be found.
+@RESTBODYPARAM{lockTimeout,integer,optional,int64}
+an optional numeric value that can be used to set a
+timeout in seconds for waiting on collection locks. This option is only
+meaningful when using exclusive locks. If not specified, a default
+value will be used. Setting *lockTimeout* to *0* will make ArangoDB
+not time out waiting for a lock.
-@RESTBODYPARAM{autoResyncRetries,integer,optional,int64}
-number of resynchronization retries that will be performed in a row when
-automatic resynchronization is enabled and kicks in. Setting this to *0*
-will
-effectively disable *autoResync*. Setting it to some other value will limit
-the number of retries that are performed. This helps preventing endless
-retries
-in case resynchronizations always fail.
+@RESTBODYPARAM{maxTransactionSize,integer,optional,int64}
+Transaction size limit in bytes.
-@RESTBODYPARAM{initialSyncMaxWaitTime,integer,optional,int64}
-the maximum wait time (in seconds) that the initial synchronization will
-wait for a response from the leader when fetching initial collection data.
-This wait time can be used to control after what time the initial
-synchronization
-will give up waiting for a response and fail. This value is relevant even
-for continuous replication when *autoResync* is set to *true* because this
-may re-start the initial synchronization when the leader cannot provide
-log data the follower requires.
-This value will be ignored if set to *0*.
+@RESTDESCRIPTION
+The transaction description must be passed in the body of the POST request.
+If the transaction can be started on the server, *HTTP 201* will be returned.
-@RESTBODYPARAM{connectionRetryWaitTime,integer,optional,int64}
-the time (in seconds) that the applier will intentionally idle before
-it retries connecting to the leader in case of connection problems.
-This value will be ignored if set to *0*.
+For successfully started transactions, the returned JSON object has the
+following properties:
-@RESTBODYPARAM{idleMinWaitTime,integer,optional,int64}
-the minimum wait time (in seconds) that the applier will intentionally idle
-before fetching more log data from the leader in case the leader has
-already sent all its log data. This wait time can be used to control the
-frequency with which the replication applier sends HTTP log fetch requests
-to the leader in case there is no write activity on the leader.
-This value will be ignored if set to *0*.
+- *error*: boolean flag to indicate if an error occurred (*false*
+ in this case)
-@RESTBODYPARAM{idleMaxWaitTime,integer,optional,int64}
-the maximum wait time (in seconds) that the applier will intentionally idle
-before fetching more log data from the leader in case the leader has
-already sent all its log data and there have been previous log fetch attempts
-that resulted in no more log data. This wait time can be used to control the
-maximum frequency with which the replication applier sends HTTP log fetch
-requests to the leader in case there is no write activity on the leader for
-longer periods. This configuration value will only be used if the option
-*adaptivePolling* is set to *true*.
-This value will be ignored if set to *0*.
+- *code*: the HTTP status code
-@RESTBODYPARAM{requireFromPresent,boolean,required,}
-if set to *true*, then the replication applier will check
-at start whether the start tick from which it starts or resumes replication is
-still present on the leader. If not, then there would be data loss. If
-*requireFromPresent* is *true*, the replication applier will abort with an
-appropriate error message. If set to *false*, then the replication applier will
-still start, and ignore the data loss.
+- *result*: result containing
+ - *id*: the identifier of the transaction
+ - *status*: containing the string 'running'
-@RESTBODYPARAM{verbose,boolean,required,}
-if set to *true*, then a log line will be emitted for all operations
-performed by the replication applier. This should be used for debugging replication
-problems only.
+If the transaction specification is either missing or malformed, the server
+will respond with *HTTP 400* or *HTTP 404*.
-@RESTBODYPARAM{restrictType,string,required,string}
-the configuration for *restrictCollections*; Has to be either *include* or *exclude*
+The body of the response will then contain a JSON object with additional error
+details. The object has the following attributes:
-@RESTBODYPARAM{restrictCollections,array,optional,string}
-the array of collections to include or exclude,
-based on the setting of *restrictType*
+- *error*: boolean flag to indicate that an error occurred (*true* in this case)
-@RESTDESCRIPTION
-Sets the configuration of the replication applier. The configuration can
-only be changed while the applier is not running. The updated configuration
-will be saved immediately but only become active with the next start of the
-applier.
+- *code*: the HTTP status code
-In case of success, the body of the response is a JSON object with the updated
-configuration.
+- *errorNum*: the server error number
+
+- *errorMessage*: a descriptive error message
@RESTRETURNCODES
-@RESTRETURNCODE{200}
-is returned if the request was executed successfully.
+@RESTRETURNCODE{201}
+If the transaction is running on the server,
+*HTTP 201* will be returned.
@RESTRETURNCODE{400}
-is returned if the configuration is incomplete or malformed, or if the
-replication applier is currently running.
-
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
+If the transaction specification is either missing or malformed, the server
+will respond with *HTTP 400*.
-@RESTRETURNCODE{500}
-is returned if an error occurred while assembling the response.
+@RESTRETURNCODE{404}
+If the transaction specification contains an unknown collection, the server
+will respond with *HTTP 404*.
@EXAMPLES
+Executing a transaction on a single collection
+
-
-
+
+
-shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/replication/applier-config <<EOF
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction/begin <<EOF
{
- "endpoint" : "tcp://127.0.0.1:8529",
- "username" : "replicationApplier",
- "password" : "applier1234@foxx",
- "chunkSize" : 4194304,
- "autoStart" : false,
- "adaptivePolling" : true
+ "collections" : {
+ "write" : "products"
+ }
}
EOF
-HTTP/1.1 200 OK
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 612
+content-length: 69
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "endpoint" : "tcp://127.0.0.1:8529",
- "database" : "_system",
- "username" : "replicationApplier",
- "requestTimeout" : 600,
- "connectTimeout" : 10,
- "ignoreErrors" : 0,
- "maxConnectRetries" : 100,
- "lockTimeoutRetries" : 0,
- "sslProtocol" : 0,
- "chunkSize" : 4194304,
- "skipCreateDrop" : false,
- "autoStart" : false,
- "adaptivePolling" : true,
- "autoResync" : false,
- "autoResyncRetries" : 2,
- "maxPacketSize" : 536870912,
- "includeSystem" : true,
- "includeFoxxQueues" : false,
- "requireFromPresent" : true,
- "verbose" : false,
- "incremental" : false,
- "restrictType" : "",
- "restrictCollections" : [ ],
- "connectionRetryWaitTime" : 15,
- "initialSyncMaxWaitTime" : 300,
- "idleMinWaitTime" : 1,
- "idleMaxWaitTime" : 2.5
+ "code" : 201,
+ "error" : false,
+ "result" : {
+ "id" : "68975",
+ "status" : "running"
+ }
}
-
Hide response body
-
+
-shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/replication/applier-config <<EOF
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction/begin <<EOF
{
- "endpoint" : "tcp://127.0.0.1:8529",
- "username" : "replicationApplier",
- "password" : "applier1234@foxx",
- "chunkSize" : 4194304,
- "autoStart" : false,
- "adaptivePolling" : true
+ "collections" : {
+ "write" : "products"
+ }
}
EOF
-HTTP/1.1 200 OK
+HTTP/1.1 201 Created
content-type: application/json
connection: Keep-Alive
-content-length: 612
+content-length: 69
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -35924,121 +36862,50 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-
-
-@startDocuBlock put_api_replication_applier_start
-
-@brief start the replication applier
-
-@RESTHEADER{PUT /_api/replication/applier-start, Start replication applier,handleCommandApplierStart}
-
-@RESTQUERYPARAMETERS
-
-@RESTQUERYPARAM{global,boolean,optional}
-If set to *true*, starts the global replication applier for all
-databases. If set to *false*, starts the replication applier in the
-selected database.
-
-@RESTQUERYPARAM{from,string,optional}
-The remote *lastLogTick* value from which to start applying. If not specified,
-the last saved tick from the previous applier run is used. If there is no
-previous applier state saved, the applier will start at the beginning of the
-logger server's log.
-
-@RESTDESCRIPTION
-Starts the replication applier. This will return immediately if the
-replication applier is already running.
-
-If the replication applier is not already running, the applier configuration
-will be checked, and if it is complete, the applier will be started in a
-background thread. This means that even if the applier will encounter any
-errors while running, they will not be reported in the response to this
-method.
-
-To detect replication applier errors after the applier was started, use the
-*/_api/replication/applier-state* API instead.
-
-@RESTRETURNCODES
-
-@RESTRETURNCODE{200}
-is returned if the request was executed successfully.
-
-@RESTRETURNCODE{400}
-is returned if the replication applier is not fully configured or the
-configuration is invalid.
-
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
-
-@RESTRETURNCODE{500}
-is returned if an error occurred while assembling the response.
-
-@EXAMPLES
+Referring to a non-existing collection
-
-
+
+
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/applier-start
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction/begin <<EOF
+{
+ "collections" : {
+ "read" : "products"
+ }
+}
+EOF
-HTTP/1.1 200 OK
+HTTP/1.1 404 Not Found
content-type: application/json
connection: Keep-Alive
-content-length: 711
+content-length: 97
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "state" : {
- "started" : "",
- "running" : true,
- "phase" : "running",
- "lastAppliedContinuousTick" : null,
- "lastProcessedContinuousTick" : null,
- "lastAvailableContinuousTick" : null,
- "safeResumeTick" : null,
- "ticksBehind" : 0,
- "progress" : {
- "time" : "2023-06-24T15:42:41Z",
- "message" : "applier initially created for database '_system'",
- "failedConnects" : 0
- },
- "totalRequests" : 0,
- "totalFailedConnects" : 0,
- "totalEvents" : 0,
- "totalDocuments" : 0,
- "totalRemovals" : 0,
- "totalResyncs" : 0,
- "totalOperationsExcluded" : 0,
- "totalApplyTime" : 0,
- "averageApplyTime" : 0,
- "totalFetchTime" : 0,
- "averageFetchTime" : 0,
- "lastError" : {
- "errorNum" : 0
- },
- "time" : "2023-06-24T15:42:52Z"
- },
- "server" : {
- "version" : "3.9.12",
- "serverId" : "82519733153206"
- },
- "endpoint" : "tcp://127.0.0.1:8529",
- "database" : "_system"
+ "code" : 404,
+ "error" : true,
+ "errorMessage" : "collection or view not found: products",
+ "errorNum" : 1203
}
-
Hide response body
-
+
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/applier-start
+shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/transaction/begin <<EOF
+{
+ "collections" : {
+ "read" : "products"
+ }
+}
+EOF
-HTTP/1.1 200 OK
+HTTP/1.1 404 Not Found
content-type: application/json
connection: Keep-Alive
-content-length: 711
+content-length: 97
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -36048,101 +36915,106 @@ x-content-type-options: nosniff
-@endDocuBlock
+@endDocuBlock
+
+
+
+@startDocuBlock put_api_transaction
+
+@brief commit a server-side transaction
+
+@RESTHEADER{PUT /_api/transaction/{transaction-id}, Commit transaction, executeCommit:Transaction}
+
+@RESTURLPARAMETERS
+
+@RESTURLPARAM{transaction-id,string,required}
+The transaction identifier,
+
+@RESTDESCRIPTION
+Commit a running server-side transaction. Committing is an idempotent operation.
+It is not an error to commit a transaction more than once.
+
+If the transaction can be committed, *HTTP 200* will be returned.
+The returned JSON object has the following properties:
+
+- *error*: boolean flag to indicate if an error occurred (*false*
+ in this case)
+
+- *code*: the HTTP status code
+- *result*: result containing
+ - *id*: the identifier of the transaction
+ - *status*: containing the string 'committed'
-
-@startDocuBlock put_api_replication_applier_stop
+If the transaction cannot be found, committing is not allowed or the
+transaction was aborted, the server
+will respond with *HTTP 400*, *HTTP 404* or *HTTP 409*.
-@brief stop the replication
+The body of the response will then contain a JSON object with additional error
+details. The object has the following attributes:
-@RESTHEADER{PUT /_api/replication/applier-stop, Stop replication applier,handleCommandApplierStop}
+- *error*: boolean flag to indicate that an error occurred (*true* in this case)
-@RESTQUERYPARAMETERS
+- *code*: the HTTP status code
-@RESTQUERYPARAM{global,boolean,optional}
-If set to *true*, stops the global replication applier for all
-databases. If set to *false*, stops the replication applier in the
-selected database.
+- *errorNum*: the server error number
-@RESTDESCRIPTION
-Stops the replication applier. This will return immediately if the
-replication applier is not running.
+- *errorMessage*: a descriptive error message
@RESTRETURNCODES
@RESTRETURNCODE{200}
-is returned if the request was executed successfully.
+If the transaction was committed,
+*HTTP 200* will be returned.
-@RESTRETURNCODE{405}
-is returned when an invalid HTTP method is used.
+@RESTRETURNCODE{400}
+If the transaction cannot be committed, the server
+will respond with *HTTP 400*.
-@RESTRETURNCODE{500}
-is returned if an error occurred while assembling the response.
+@RESTRETURNCODE{404}
+If the transaction was not found, the server
+will respond with *HTTP 404*.
+
+@RESTRETURNCODE{409}
+If the transaction was already aborted, the server
+will respond with *HTTP 409*.
@EXAMPLES
+Committing a transaction:
-
-
+
+
+
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/applier-stop
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction/68957
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 686
+content-length: 71
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
- "state" : {
- "started" : "2023-06-24T15:42:52Z",
- "running" : false,
- "phase" : "inactive",
- "lastAppliedContinuousTick" : null,
- "lastProcessedContinuousTick" : null,
- "lastAvailableContinuousTick" : null,
- "safeResumeTick" : null,
- "progress" : {
- "time" : "2023-06-24T15:42:54Z",
- "message" : "applier shut down",
- "failedConnects" : 0
- },
- "totalRequests" : 6,
- "totalFailedConnects" : 3,
- "totalEvents" : 0,
- "totalDocuments" : 0,
- "totalRemovals" : 0,
- "totalResyncs" : 0,
- "totalOperationsExcluded" : 0,
- "totalApplyTime" : 0,
- "averageApplyTime" : 0,
- "totalFetchTime" : 0,
- "averageFetchTime" : 0,
- "lastError" : {
- "errorNum" : 0
- },
- "time" : "2023-06-24T15:42:54Z"
- },
- "server" : {
- "version" : "3.9.12",
- "serverId" : "82519733153206"
- },
- "endpoint" : "tcp://127.0.0.1:8529",
- "database" : "_system"
+ "code" : 200,
+ "error" : false,
+ "result" : {
+ "id" : "68957",
+ "status" : "committed"
+ }
}
-
Hide response body
-
+
-shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/replication/applier-stop
+shell> curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/transaction/68957
HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
-content-length: 686
+content-length: 71
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
@@ -36152,902 +37024,982 @@ x-content-type-options: nosniff
-@endDocuBlock
-
-@startDocuBlock put_api_replication_inventory
+@endDocuBlock
-@brief Returns an overview of collections and their indexes
-@RESTHEADER{GET /_api/replication/inventory, Return inventory of collections and indexes, handleCommandInventory}
+
+@startDocuBlock delete_remove_document_MULTI
-@RESTQUERYPARAMETERS
+@brief removes multiple document
-@RESTQUERYPARAM{includeSystem,boolean,optional}
-Include system collections in the result. The default value is *true*.
+@RESTHEADER{DELETE /_api/document/{collection},Removes multiple documents,removeDocuments}
-@RESTQUERYPARAM{global,boolean,optional}
-Include all databases in the response. Only works on `_system` The default value is *false*.
+@RESTALLBODYPARAM{array,json,required}
+A JSON array of strings or documents.
-@RESTQUERYPARAM{batchId,number,required}
-A valid batchId is required for this API call
+@RESTURLPARAMETERS
-@RESTQUERYPARAM{collection,string,optional}
-If this parameter is set, the response will be restricted to a single collection (the one
-specified), and no views will be returned. This can be used as an optimization to reduce
-the size of the response.
+@RESTURLPARAM{collection,string,required}
+Collection from which documents are removed.
-@RESTDESCRIPTION
-Returns the array of collections and their indexes, and the array of views available. These
-arrays can be used by replication clients to initiate an initial synchronization with the
-server.
-The response will contain all collections, their indexes and views in the requested database
-if *global* is not set, and all collections, indexes and views in all databases if *global*
-is set.
-In case *global* is not set, it is possible to restrict the response to a single collection
-by setting the *collection* parameter. In this case the response will contain only information
-about the requested collection in the *collections* array, and no information about views
-(i.e. the *views* response attribute will be an empty array).
+@RESTQUERYPARAMETERS
-The response will contain a JSON object with the *collections*, *views*, *state* and
-*tick* attributes.
+@RESTQUERYPARAM{waitForSync,boolean,optional}
+Wait until deletion operation has been synced to disk.
-*collections* is an array of collections with the following sub-attributes:
+@RESTQUERYPARAM{returnOld,boolean,optional}
+Return additionally the complete previous revision of the changed
+document under the attribute *old* in the result.
-- *parameters*: the collection properties
+@RESTQUERYPARAM{ignoreRevs,boolean,optional}
+If set to *true*, ignore any *_rev* attribute in the selectors. No
+revision check is performed. If set to *false* then revisions are checked.
+The default is *true*.
-- *indexes*: an array of the indexes of a the collection. Primary indexes and edge indexes
- are not included in this array.
+@RESTQUERYPARAM{refillIndexCaches,boolean,optional}
+Whether to delete existing entries from the in-memory edge cache and refill it
+with other edges if edge documents are removed.
-The *state* attribute contains the current state of the replication logger. It
-contains the following sub-attributes:
+@RESTDESCRIPTION
+The body of the request is an array consisting of selectors for
+documents. A selector can either be a string with a key or a string
+with a document identifier or an object with a *_key* attribute. This
+API call removes all specified documents from *collection*.
+If the *ignoreRevs* query parameter is *false* and the
+selector is an object and has a *_rev* attribute, it is a
+precondition that the actual revision of the removed document in the
+collection is the specified one.
-- *running*: whether or not the replication logger is currently active. Note:
- since ArangoDB 2.2, the value will always be *true*
+The body of the response is an array of the same length as the input
+array. For each input selector, the output contains a JSON object
+with the information about the outcome of the operation. If no error
+occurred, an object is built in which the attribute *_id* contains
+the known *document-id* of the removed document, *_key* contains
+the key which uniquely identifies a document in a given collection,
+and the attribute *_rev* contains the document revision. In case of
+an error, an object with the attribute *error* set to *true* and
+*errorCode* set to the error code is built.
-- *lastLogTick*: the value of the last tick the replication logger has written
+If the *waitForSync* parameter is not specified or set to *false*,
+then the collection's default *waitForSync* behavior is applied.
+The *waitForSync* query parameter cannot be used to disable
+synchronization for collections that have a default *waitForSync*
+value of *true*.
-- *time*: the current time on the server
+If the query parameter *returnOld* is *true*, then
+the complete previous revision of the document
+is returned under the *old* attribute in the result.
-*views* is an array of available views.
+Note that if any precondition is violated or an error occurred with
+some of the documents, the return code is still 200 or 202, but
+the additional HTTP header *X-Arango-Error-Codes* is set, which
+contains a map of the error codes that occurred together with their
+multiplicities, as in: *1200:17,1205:10* which means that in 17
+cases the error 1200 "revision conflict" and in 10 cases the error
+1205 "illegal document handle" has happened.
-Replication clients should note the *lastLogTick* value returned. They can then
-fetch collections' data using the dump method up to the value of lastLogTick, and
-query the continuous replication log for log events after this tick value.
+@RESTRETURNCODES
-To create a full copy of the collections on the server, a replication client
-can execute these steps:
+@RESTRETURNCODE{200}
+is returned if *waitForSync* was *true*.
-- call the */inventory* API method. This returns the *lastLogTick* value and the
- array of collections and indexes from the server.
+@RESTRETURNCODE{202}
+is returned if *waitForSync* was *false*.
-- for each collection returned by */inventory*, create the collection locally and
- call */dump* to stream the collection data to the client, up to the value of
- *lastLogTick*.
- After that, the client can create the indexes on the collections as they were
- reported by */inventory*.
+@RESTRETURNCODE{404}
+is returned if the collection was not found.
+The response body contains an error document in this case.
-If the clients wants to continuously stream replication log events from the logger
-server, the following additional steps need to be carried out:
+@EXAMPLES
-- the client should call */_api/wal/tail* initially to fetch the first batch of
- replication events that were logged after the client's call to */inventory*.
+Using document keys:
- The call to */_api/wal/tail* should use a *from* parameter with the value of the
- *lastLogTick* as reported by */inventory*. The call to */_api/wal/tail* will
- return the *x-arango-replication-lastincluded* header which will contain the
- last tick value included in the response.
-- the client can then continuously call */_api/wal/tail* to incrementally fetch new
- replication events that occurred after the last transfer.
+
+
+
+shell> curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
+[
+ "1",
+ "2"
+]
+EOF
- Calls should use a *from* parameter with the value of the *x-arango-replication-lastincluded*
- header of the previous response. If there are no more replication events, the
- response will be empty and clients can go to sleep for a while and try again
- later.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 107
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-**Note**: on a Coordinator, this request must have the query parameter
-*DBserver* which must be an ID of a DB-Server.
-The very same request is forwarded synchronously to that DB-Server.
-It is an error if this attribute is not bound in the Coordinator case.
+[
+ {
+ "_id" : "products/1",
+ "_key" : "1",
+ "_rev" : "_gjDBOQS--_"
+ },
+ {
+ "_id" : "products/2",
+ "_key" : "2",
+ "_rev" : "_gjDBOQS--A"
+ }
+]
+
+
Hide response body
+
+
+shell> curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
+[
+ "1",
+ "2"
+]
+EOF
-**Note**: Using the `global` parameter the top-level object contains a key `databases`
-under which each key represents a database name, and the value conforms to the above description.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 107
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
Show response body
+
+
+
+
+shell> curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
+[
+ {
+ "_key" : "1"
+ },
+ {
+ "_key" : "2"
+ }
+]
+EOF
-@RESTBODYPARAM{password,string,required,string}
-the password to use when connecting to the leader.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 107
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTBODYPARAM{includeSystem,boolean,required,}
-whether or not system collection operations will be applied
+[
+ {
+ "_id" : "products/1",
+ "_key" : "1",
+ "_rev" : "_gjDBOQq--_"
+ },
+ {
+ "_id" : "products/2",
+ "_key" : "2",
+ "_rev" : "_gjDBOQq--A"
+ }
+]
+
+
Hide response body
+
+
+shell> curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
+[
+ {
+ "_key" : "1"
+ },
+ {
+ "_key" : "2"
+ }
+]
+EOF
-@RESTBODYPARAM{restrictType,string,optional,string}
-an optional string value for collection filtering. When
-specified, the allowed values are *include* or *exclude*.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 107
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+shell> curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
+[
+ "1",
+ "other/2"
+]
+EOF
-@RESTBODYPARAM{connectionRetryWaitTime,integer,optional,int64}
-the time (in seconds) that the applier will intentionally idle before
-it retries connecting to the leader in case of connection problems.
-This value will be ignored if set to *0*.
+HTTP/1.1 202 Accepted
+content-type: application/json
+connection: Keep-Alive
+content-length: 135
+server: ArangoDB
+x-arango-error-codes: {"1202":2}
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@RESTBODYPARAM{idleMinWaitTime,integer,optional,int64}
-the minimum wait time (in seconds) that the applier will intentionally idle
-before fetching more log data from the leader in case the leader has
-already sent all its log data. This wait time can be used to control the
-frequency with which the replication applier sends HTTP log fetch requests
-to the leader in case there is no write activity on the leader.
-This value will be ignored if set to *0*.
+[
+ {
+ "error" : true,
+ "errorNum" : 1202,
+ "errorMessage" : "document not found"
+ },
+ {
+ "error" : true,
+ "errorNum" : 1202,
+ "errorMessage" : "document not found"
+ }
+]
+
+
Hide response body
+
+
+shell> curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/document/products <<EOF
+[
+ "1",
+ "other/2"
+]
+EOF
-@RESTBODYPARAM{idleMaxWaitTime,integer,optional,int64}
-the maximum wait time (in seconds) that the applier will intentionally idle
-before fetching more log data from the leader in case the leader has
-already sent all its log data and there have been previous log fetch attempts
-that resulted in no more log data. This wait time can be used to control the
-maximum frequency with which the replication applier sends HTTP log fetch
-requests to the leader in case there is no write activity on the leader for
-longer periods. This configuration value will only be used if the option
-*adaptivePolling* is set to *true*.
-This value will be ignored if set to *0*.
+HTTP/1.1 202 Accepted
+content-type: application/json
+connection: Keep-Alive
+content-length: 135
+server: ArangoDB
+x-arango-error-codes: {"1202":2}
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+shell> curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/document/products?ignoreRevs=false <<EOF
+[
+ {
+ "_key" : "1",
+ "_rev" : "_gjDBORW--_"
+ },
+ {
+ "_key" : "2",
+ "_rev" : "_gjDBORW--A"
+ }
+]
+EOF
- Regularly, the last applied and last processed tick values should be
- identical. For transactional operations, the replication applier will first
- process incoming log events before applying them, so the processed tick
- value might be higher than the applied tick value. This will be the case
- until the applier encounters the *transaction commit* log event for the
- transaction.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 107
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
- - *lastAvailableContinuousTick*: the last tick value the remote server can
- provide.
+[
+ {
+ "_id" : "products/1",
+ "_key" : "1",
+ "_rev" : "_gjDBORW--_"
+ },
+ {
+ "_id" : "products/2",
+ "_key" : "2",
+ "_rev" : "_gjDBORW--A"
+ }
+]
+
+
Hide response body
+
+
+shell> curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/document/products?ignoreRevs=false <<EOF
+[
+ {
+ "_key" : "1",
+ "_rev" : "_gjDBORW--_"
+ },
+ {
+ "_key" : "2",
+ "_rev" : "_gjDBORW--A"
+ }
+]
+EOF
- - *ticksBehind*: this attribute will be present only if the applier is currently
- running. It will provide the number of log ticks between what the applier
- has applied/seen and the last log tick value provided by the remote server.
- If this value is zero, then both servers are in sync. If this is non-zero,
- then the remote server has additional data that the applier has not yet
- fetched and processed, or the remote server may have more data that is not
- applicable to the applier.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 107
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+shell> curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/document/products?ignoreRevs=false <<EOF
+[
+ {
+ "_key" : "1",
+ "_rev" : "non-matching revision"
+ },
+ {
+ "_key" : "2",
+ "_rev" : "non-matching revision"
+ }
+]
+EOF
- - *time*: the date and time the progress was logged
+HTTP/1.1 202 Accepted
+content-type: application/json
+connection: Keep-Alive
+content-length: 167
+server: ArangoDB
+x-arango-error-codes: {"1200":2}
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
- - *failedConnects*: the current number of failed connection attempts
+[
+ {
+ "error" : true,
+ "errorNum" : 1200,
+ "errorMessage" : "conflict, _rev values do not match"
+ },
+ {
+ "error" : true,
+ "errorNum" : 1200,
+ "errorMessage" : "conflict, _rev values do not match"
+ }
+]
+
+
Hide response body
+
+
+shell> curl -X DELETE --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/document/products?ignoreRevs=false <<EOF
+[
+ {
+ "_key" : "1",
+ "_rev" : "non-matching revision"
+ },
+ {
+ "_key" : "2",
+ "_rev" : "non-matching revision"
+ }
+]
+EOF
- - *lastError*: a JSON object with details about the last error that happened on
- the applier. It contains the following sub-attributes if there was an error:
+HTTP/1.1 202 Accepted
+content-type: application/json
+connection: Keep-Alive
+content-length: 167
+server: ArangoDB
+x-arango-error-codes: {"1200":2}
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/document/products/67583
-The response may be truncated if it would be very long. In this case, the
-response array length will be less than the request array length, and
-subsequent requests can be made for the omitted documents.
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 60
+etag: "_gjDBOPO--_"
+location: /_db/_system/_api/document/products/67583
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-Each `` value type is a 64-bit value encoded as a string of
-11 characters, using the same encoding as our document `_rev` values. The
-reason for this is that 64-bit values cannot necessarily be represented in full
-in JavaScript, as it handles all numbers as floating point, and can only
-represent up to `2^53-1` faithfully.
+{
+ "_id" : "products/67583",
+ "_key" : "67583",
+ "_rev" : "_gjDBOPO--_"
+}
+
+
Hide response body
+
+
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/document/products/67583
-@RESTRETURNCODES
+HTTP/1.1 200 OK
+content-type: application/json
+connection: Keep-Alive
+content-length: 60
+etag: "_gjDBOPO--_"
+location: /_db/_system/_api/document/products/67583
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+
Show response body
+
+
+
+
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/document/products/67651
-
-@startDocuBlock put_api_replication_revisions_ranges
+HTTP/1.1 404 Not Found
+content-type: application/json
+connection: Keep-Alive
+content-length: 77
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
-@brief retrieves the revision IDs of documents within requested ranges
+{
+ "code" : 404,
+ "error" : true,
+ "errorMessage" : "document not found",
+ "errorNum" : 1202
+}
+
+
Hide response body
+
+
+shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/document/products/67651
-@RESTHEADER{PUT /_api/replication/revisions/ranges, Return revision IDs within requested ranges,handleCommandRevisionRanges}
+HTTP/1.1 404 Not Found
+content-type: application/json
+connection: Keep-Alive
+content-length: 77
+server: ArangoDB
+x-arango-queue-time-seconds: 0.000000
+x-content-type-options: nosniff
+Show response body
+
+
+
+
+shell> curl -X DELETE --header