HTTP interface for collections
The HTTP API for collections lets you create and delete collections, get information about collections, and modify certain properties of existing collections
Addresses of collections
All collections in ArangoDB have a unique identifier and a unique
name. To access a collection, use the collection name to refer to it:
http://server:port/_api/collection/<collection-name>
For example, assume that the collection identifier is 7254820
and
the collection name is demo
, then the URL of that collection is:
http://localhost:8529/_api/collection/demo
List all collections
get
/_api/collection
Returns an object with a result
attribute containing an array with the
descriptions of all collections in the current database.
By providing the optional excludeSystem
query parameter with a value of
true
, all system collections are excluded from the response.
Query Parameters
excludeSystem boolean
Whether or not system collections should be excluded from the result.
Examples
Return information about all collections:
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 1641
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"result" : [
{
"id" : "9",
"name" : "_aqlfunctions",
"status" : 3,
"type" : 2,
"isSystem" : true,
"globallyUniqueId" : "_aqlfunctions"
},
{
"id" : "141",
"name" : "demo",
"status" : 3,
"type" : 2,
"isSystem" : false,
"globallyUniqueId" : "hED60CCAA6F22/141"
},
{
"id" : "147",
"name" : "animals",
"status" : 3,
"type" : 2,
"isSystem" : false,
"globallyUniqueId" : "hED60CCAA6F22/147"
},
{
"id" : "68023",
"name" : "mycollection",
"status" : 3,
"type" : 2,
"isSystem" : false,
"globallyUniqueId" : "hED60CCAA6F22/68023"
},
{
"id" : "3",
"name" : "_users",
"status" : 3,
"type" : 2,
"isSystem" : true,
"globallyUniqueId" : "_users"
},
{
"id" : "7",
"name" : "_graphs",
"status" : 3,
"type" : 2,
"isSystem" : true,
"globallyUniqueId" : "_graphs"
},
{
"id" : "13",
"name" : "_appbundles",
"status" : 3,
"type" : 2,
"isSystem" : true,
"globallyUniqueId" : "_appbundles"
},
{
"id" : "8",
"name" : "_analyzers",
"status" : 3,
"type" : 2,
"isSystem" : true,
"globallyUniqueId" : "_analyzers"
},
{
"id" : "14",
"name" : "_frontend",
"status" : 3,
"type" : 2,
"isSystem" : true,
"globallyUniqueId" : "_frontend"
},
{
"id" : "6",
"name" : "_statisticsRaw",
"status" : 3,
"type" : 2,
"isSystem" : true,
"globallyUniqueId" : "_statisticsRaw"
},
{
"id" : "12",
"name" : "_apps",
"status" : 3,
"type" : 2,
"isSystem" : true,
"globallyUniqueId" : "_apps"
},
{
"id" : "136",
"name" : "ignore",
"status" : 3,
"type" : 2,
"isSystem" : false,
"globallyUniqueId" : "hED60CCAA6F22/136"
},
{
"id" : "4",
"name" : "_statistics",
"status" : 3,
"type" : 2,
"isSystem" : true,
"globallyUniqueId" : "_statistics"
},
{
"id" : "10",
"name" : "_queues",
"status" : 3,
"type" : 2,
"isSystem" : true,
"globallyUniqueId" : "_queues"
},
{
"id" : "5",
"name" : "_statistics15",
"status" : 3,
"type" : 2,
"isSystem" : true,
"globallyUniqueId" : "_statistics15"
},
{
"id" : "11",
"name" : "_jobs",
"status" : 3,
"type" : 2,
"isSystem" : true,
"globallyUniqueId" : "_jobs"
}
]
}
get
/_api/collection/{collection-name}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
The result is an object describing the collection with the following
attributes:
id
: The identifier of the collection.
name
: The name of the collection.
status
: The status of the collection as number.
Every other status indicates a corrupted collection.
Path Parameters
collection-name* string
The name of the collection.
Responses
404
If the collection-name
is unknown, then a HTTP 404 is
returned.
Get the properties of a collection
get
/_api/collection/{collection-name}/properties
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
Returns all properties of the specified collection.
Path Parameters
collection-name* string
The name of the collection.
Responses
200
Response Body
cacheEnabled* boolean
Whether the in-memory hash cache for documents is enabled for this
collection.
computedValues array of objects
A list of objects, each representing a computed value.
computeOn array of strings
An array of strings that defines on which write operations the value is
computed. The possible values are "insert"
, "update"
, and "replace"
.
expression string
An AQL RETURN
operation with an expression that computes the desired value.
failOnWarning boolean
Whether the write operation fails if the expression produces a warning.
keepNull boolean
Whether the target attribute is set if the expression evaluates to null
.
name string
The name of the target attribute.
overwrite boolean
Whether the computed value takes precedence over a user-provided or
existing attribute.
distributeShardsLike string
The name of another collection. This collection uses the replicationFactor
,
numberOfShards
and shardingStrategy
properties of the other collection and
the shards of this collection are distributed in the same way as the shards of
the other collection.
globallyUniqueId string
A unique identifier of the collection. This is an internal property.
id string
A unique identifier of the collection (deprecated).
isDisjoint boolean
Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint
(Enterprise Edition only). This is an internal property. (cluster only)
isSmart boolean
Whether the collection is used in a SmartGraph or EnterpriseGraph (Enterprise Edition only).
This is an internal property. (cluster only)
isSystem boolean
Whether the collection is a system collection. Collection names that starts with
an underscore are usually system collections.
keyOptions* object
An object which contains key generation options.
allowUserKeys* boolean
If set to true
, then you are allowed to supply
own key values in the _key
attribute of a document. If set to
false
, then the key generator is solely responsible for
generating keys and an error is raised if you supply own key values in the
_key
attribute of documents.
You should not use both user-specified and automatically generated document keys
in the same collection in cluster deployments for collections with more than a
single shard. Mixing the two can lead to conflicts because Coordinators that
auto-generate keys in this case are not aware of all keys which are already used.
increment* integer
The increment value for the autoincrement
key generator.
Not used for other key generator types.
lastValue* integer
The current offset value of the autoincrement
or padded
key generator.
This is an internal property for restoring dumps properly.
offset* integer
The initial offset value for the autoincrement
key generator.
Not used for other key generator types.
type* string
Specifies the type of the key generator. Possible values:
"traditional"
"autoincrement"
"uuid"
"padded"
name string
The name of this collection.
numberOfShards integer
The number of shards of the collection. (cluster only)
replicationFactor integer
Contains how many copies of each shard are kept on different DB-Servers.
It is an integer number in the range of 1-10 or the string "satellite"
for SatelliteCollections (Enterprise Edition only). (cluster only)
schema object
An object that specifies the collection-level schema for documents.
shardKeys array of strings
Contains the names of document attributes that are used to
determine the target shard for documents. (cluster only)
shardingStrategy string
The sharding strategy selected for the collection. (cluster only)
Possible values:
"community-compat"
"enterprise-compat"
"enterprise-smart-edge-compat"
"hash"
"enterprise-hash-smart-edge"
"enterprise-hex-smart-vertex"
smartGraphAttribute string
The attribute that is used for sharding: vertices with the same value of
this attribute are placed in the same shard. All vertices are required to
have this attribute set and it has to be a string. Edges derive the
attribute from their connected vertices (Enterprise Edition only). (cluster only)
smartJoinAttribute string
Determines an attribute of the collection that must contain the shard key value
of the referred-to SmartJoin collection (Enterprise Edition only). (cluster only)
syncByRevision* boolean
Whether the newer revision-based replication protocol is
enabled for this collection. This is an internal property.
type integer
The type of the collection:
0
: “unknown”2
: regular document collection3
: edge collection
waitForSync* boolean
If true
, creating, changing, or removing
documents waits until the data has been synchronized to disk.
writeConcern integer
Determines how many copies of each shard are required to be
in-sync on the different DB-Servers. If there are less than these many copies
in the cluster, a shard refuses to write. Writes to shards with enough
up-to-date copies succeed at the same time, however. The value of
writeConcern
cannot be greater than replicationFactor
.
If distributeShardsLike
is set, the default writeConcern
is that of the prototype collection.
For SatelliteCollections, the writeConcern
is automatically controlled to
equal the number of DB-Servers and has a value of 0
.
Otherwise, the default value is controlled by the current database’s
default writeConcern
, which uses the --cluster.write-concern
startup option as default, which defaults to 1
. (cluster only)
400
If the collection-name
is missing, then a HTTP 400 is
returned.
404
If the collection-name
is unknown, then a HTTP 404
is returned.
Examples
Using an identifier:
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/68434/properties
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 445
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/68434/properties
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"writeConcern" : 1,
"waitForSync" : true,
"usesRevisionsAsDocumentIds" : true,
"syncByRevision" : true,
"statusString" : "loaded",
"id" : "68434",
"isSmartChild" : false,
"schema" : null,
"name" : "products",
"type" : 2,
"status" : 3,
"cacheEnabled" : false,
"isSystem" : false,
"internalValidatorType" : 0,
"globallyUniqueId" : "hED60CCAA6F22/68434",
"keyOptions" : {
"allowUserKeys" : true,
"type" : "traditional",
"lastValue" : 0
},
"computedValues" : null,
"objectId" : "68435"
}
Using a name:
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/properties
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 445
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/properties
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"writeConcern" : 1,
"waitForSync" : true,
"usesRevisionsAsDocumentIds" : true,
"syncByRevision" : true,
"statusString" : "loaded",
"id" : "68444",
"isSmartChild" : false,
"schema" : null,
"name" : "products",
"type" : 2,
"status" : 3,
"cacheEnabled" : false,
"isSystem" : false,
"internalValidatorType" : 0,
"globallyUniqueId" : "hED60CCAA6F22/68444",
"keyOptions" : {
"allowUserKeys" : true,
"type" : "traditional",
"lastValue" : 0
},
"computedValues" : null,
"objectId" : "68445"
}
Get the document count of a collection
get
/_api/collection/{collection-name}/count
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
Get the number of documents in a collection.
count
: The number of documents stored in the specified collection.
Path Parameters
collection-name* string
The name of the collection.
Responses
400
If the collection-name
is missing, then a HTTP 400 is
returned.
404
If the collection-name
is unknown, then a HTTP 404
is returned.
Examples
Requesting the number of documents:
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/count
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 461
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/count
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"writeConcern" : 1,
"waitForSync" : true,
"usesRevisionsAsDocumentIds" : true,
"syncByRevision" : true,
"statusString" : "loaded",
"id" : "68454",
"isSmartChild" : false,
"schema" : null,
"name" : "products",
"type" : 2,
"status" : 3,
"count" : 100,
"cacheEnabled" : false,
"isSystem" : false,
"internalValidatorType" : 0,
"globallyUniqueId" : "hED60CCAA6F22/68454",
"keyOptions" : {
"allowUserKeys" : true,
"type" : "traditional",
"lastValue" : 68658
},
"computedValues" : null,
"objectId" : "68455"
}
Get the collection statistics
get
/_api/collection/{collection-name}/figures
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
In addition to the above, the result also contains the number of documents
and additional statistical information about the collection.
Path Parameters
collection-name* string
The name of the collection.
Query Parameters
details boolean
Setting details
to true
will return extended storage engine-specific
details to the figures. The details are intended for debugging ArangoDB itself
and their format is subject to change. By default, details
is set to false
,
so no details are returned and the behavior is identical to previous versions
of ArangoDB.
Please note that requesting details
may cause additional load and thus have
an impact on performance.
Responses
200
Returns information about the collection:
Response Body
count* integer
The number of documents currently present in the collection.
figures* object
The metrics of the collection.
indexes* object
The index metrics.
count* integer
The total number of indexes defined for the collection, including the pre-defined
indexes (e.g. primary index).
size* integer
The total memory allocated for indexes in bytes.
400
If the collection-name
is missing, then a HTTP 400 is
returned.
404
If the collection-name
is unknown, then a HTTP 404
is returned.
Examples
Using an identifier and requesting the figures of the collection:
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/figures
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 575
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/figures
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"figures" : {
"indexes" : {
"count" : 1,
"size" : 2696
},
"documentsSize" : 3484,
"cacheInUse" : false,
"cacheSize" : 0,
"cacheUsage" : 0
},
"writeConcern" : 1,
"waitForSync" : false,
"usesRevisionsAsDocumentIds" : true,
"syncByRevision" : true,
"statusString" : "loaded",
"id" : "68664",
"isSmartChild" : false,
"schema" : null,
"name" : "products",
"type" : 2,
"status" : 3,
"count" : 1,
"cacheEnabled" : false,
"isSystem" : false,
"internalValidatorType" : 0,
"globallyUniqueId" : "hED60CCAA6F22/68664",
"keyOptions" : {
"allowUserKeys" : true,
"type" : "traditional",
"lastValue" : 68670
},
"computedValues" : null,
"objectId" : "68665"
}
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/figures?details=true
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 648
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/figures
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"figures" : {
"indexes" : {
"count" : 1,
"size" : 1233
},
"documentsSize" : 5352,
"cacheInUse" : false,
"cacheSize" : 0,
"cacheUsage" : 0,
"engine" : {
"documents" : 1,
"indexes" : [
{
"type" : "primary",
"id" : 0,
"count" : 1
}
]
}
},
"writeConcern" : 1,
"waitForSync" : false,
"usesRevisionsAsDocumentIds" : true,
"syncByRevision" : true,
"statusString" : "loaded",
"id" : "68676",
"isSmartChild" : false,
"schema" : null,
"name" : "products",
"type" : 2,
"status" : 3,
"count" : 1,
"cacheEnabled" : false,
"isSystem" : false,
"internalValidatorType" : 0,
"globallyUniqueId" : "hED60CCAA6F22/68676",
"keyOptions" : {
"allowUserKeys" : true,
"type" : "traditional",
"lastValue" : 68682
},
"computedValues" : null,
"objectId" : "68677"
}
Get the responsible shard for a document
put
/_api/collection/{collection-name}/responsibleShard
Returns the ID of the shard that is responsible for the given document
(if the document exists) or that would be responsible if such document
existed.
The request must body must contain a JSON document with at least the
collection’s shard key attributes set to some values.
The response is a JSON object with a shardId
attribute, which will
contain the ID of the responsible shard.
This method is only available in cluster deployments on Coordinators.
Path Parameters
collection-name* string
The name of the collection.
Request Body application/json
document* object
The request body must be a JSON object with at least the shard key
attributes set to some values, but it may also be a full document.
Responses
200
Returns the ID of the responsible shard.
400
If the collection-name
is missing, then a HTTP 400 is
returned.
Additionally, if not all of the collection’s shard key
attributes are present in the input document, then a
HTTP 400 is returned as well.
404
If the collection-name
is unknown, then an HTTP 404
is returned.
501
HTTP 501 is returned if the method is called on a single server.
Examples
curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection/testCollection/responsibleShard
"{\"_key\":\"testkey\",\"value\":23}"
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 45
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/testCollection/responsibleShard
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"shardId" : "s10064"
}
Get the shard IDs of a collection
get
/_api/collection/{collection-name}/shards
By default returns a JSON array with the shard IDs of the collection.
If the details
parameter is set to true
, it will return a JSON object with the
shard IDs as object attribute keys, and the responsible servers for each shard mapped to them.
In the detailed response, the leader shards will be first in the arrays.
This method is only available in cluster deployments on Coordinators.
Path Parameters
collection-name* string
The name of the collection.
Query Parameters
details boolean
If set to true, the return value will also contain the responsible servers for the collections’ shards.
Responses
200
Returns the collection’s shards.
400
If the collection-name
is missing, then a HTTP 400 is
returned.
404
If the collection-name
is unknown, then an HTTP 404
is returned.
501
HTTP 501 is returned if the method is called on a single server.
Examples
Retrieves the list of shards:
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/testCollection/shards
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 593
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/testCollection/shards
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
"{\"error\":false,\"code\":200,\"shards\":[\"s10069\",\"s10070\",\"s10071\"],\"writeConcern\":1,\"waitForSync\":false,\"usesRevisionsAsDocumentIds\":true,\"syncByRevision\":true,\"shardingStrategy\":\"hash\",\"schema\":null,\"numberOfShards\":3,\"minReplicationFactor\":1,\"id\":\"10068\",\"isSmartChild\":false,\"name\":\"testCollection\",\"statusString\":\"loaded\",\"isSmart\":false,\"replicationFactor\":1,\"type\":2,\"status\":3,\"cacheEnabled\":false,\"isSystem\":false,\"computedValues\":null,\"internalValidatorType\":0,\"globallyUniqueId\":\"c10068/\",\"shardKeys\":[\"_key\"],\"isDisjoint\":false,\"keyOptions\":{\"allowUserKeys\":true,\"type\":\"traditional\"}}"
Retrieves the list of shards with the responsible servers:
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/testCollection/shards?details=true
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 731
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/testCollection/shards
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
"{\"error\":false,\"code\":200,\"shards\":{\"s10078\":[\"PRMR-9d3e15b3-dc6b-45b9-b84c-7c13dd065c8a\"],\"s10076\":[\"PRMR-46de0332-b6f8-434a-8627-a5d7e659826f\"],\"s10077\":[\"PRMR-96488cfb-50a3-45f1-9d4e-ee3186d7ff05\"]},\"writeConcern\":1,\"waitForSync\":false,\"usesRevisionsAsDocumentIds\":true,\"syncByRevision\":true,\"shardingStrategy\":\"hash\",\"schema\":null,\"numberOfShards\":3,\"minReplicationFactor\":1,\"id\":\"10075\",\"isSmartChild\":false,\"name\":\"testCollection\",\"statusString\":\"loaded\",\"isSmart\":false,\"replicationFactor\":1,\"type\":2,\"status\":3,\"cacheEnabled\":false,\"isSystem\":false,\"computedValues\":null,\"internalValidatorType\":0,\"globallyUniqueId\":\"c10075/\",\"shardKeys\":[\"_key\"],\"isDisjoint\":false,\"keyOptions\":{\"allowUserKeys\":true,\"type\":\"traditional\"}}"
Get the collection revision ID
get
/_api/collection/{collection-name}/revision
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
The response will contain the collection’s latest used revision id.
The revision id is a server-generated string that clients can use to
check whether data in a collection has changed since the last revision check.
revision
: The collection revision id as a string.
Path Parameters
collection-name* string
The name of the collection.
Responses
400
If the collection-name
is missing, then a HTTP 400 is
returned.
404
If the collection-name
is unknown, then a HTTP 404
is returned.
Examples
Retrieving the revision of a collection
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/revision
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 462
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/revision
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"writeConcern" : 1,
"waitForSync" : false,
"usesRevisionsAsDocumentIds" : true,
"syncByRevision" : true,
"statusString" : "loaded",
"schema" : null,
"revision" : "54",
"id" : "68688",
"isSmartChild" : false,
"name" : "products",
"type" : 2,
"status" : 3,
"cacheEnabled" : false,
"isSystem" : false,
"objectId" : "68689",
"computedValues" : null,
"internalValidatorType" : 0,
"globallyUniqueId" : "hED60CCAA6F22/68688",
"keyOptions" : {
"allowUserKeys" : true,
"type" : "traditional",
"lastValue" : 0
}
}
Get the collection checksum
get
/_api/collection/{collection-name}/checksum
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
Will calculate a checksum of the meta-data (keys and optionally revision ids) and
optionally the document data in the collection.
The checksum can be used to compare if two collections on different ArangoDB
instances contain the same contents. The current revision of the collection is
returned too so one can make sure the checksums are calculated for the same
state of data.
By default, the checksum will only be calculated on the _key
system attribute
of the documents contained in the collection. For edge collections, the system
attributes _from
and _to
will also be included in the calculation.
By setting the optional query parameter withRevisions
to true
, then revision
ids (_rev
system attributes) are included in the checksumming.
By providing the optional query parameter withData
with a value of true
,
the user-defined document attributes will be included in the calculation too.
Including user-defined attributes will make the checksumming slower.
The response is a JSON object with the following attributes:
Path Parameters
collection-name* string
The name of the collection.
Query Parameters
withRevisions boolean
Whether or not to include document revision ids in the checksum calculation.
withData boolean
Whether or not to include document body data in the checksum calculation.
Responses
400
If the collection-name
is missing, then a HTTP 400 is
returned.
404
If the collection-name
is unknown, then a HTTP 404
is returned.
Examples
Retrieving the checksum of a collection:
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/checksum
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 194
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/checksum
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"isSystem" : false,
"status" : 3,
"type" : 2,
"name" : "products",
"id" : "68698",
"revision" : "_hlWqSW6--_",
"globallyUniqueId" : "hED60CCAA6F22/68698",
"checksum" : "11542004467624430538"
}
Retrieving the checksum of a collection including the collection data,
but not the revisions:
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/checksum?withRevisions=false&withData=true
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 193
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/checksum
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"isSystem" : false,
"status" : 3,
"type" : 2,
"name" : "products",
"id" : "68710",
"revision" : "_hlWqSXW--_",
"globallyUniqueId" : "hED60CCAA6F22/68710",
"checksum" : "2093507711476238367"
}
Get the available key generators
get
/_api/key-generators
Returns the available key generators for collections.
Responses
200
An object that contains a list of the available generators for document keys:
"padded"
"uuid"
"autoincrement"
"traditional"
Response Body
keyGenerators* array of strings
The available document key generators.
Examples:
Retrieving the key generators for collections:
curl --header 'accept: application/json' --dump - http://localhost:8529/_api/key-generators
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 65
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"keyGenerators" : [
"padded",
"uuid",
"autoincrement",
"traditional"
]
}
Create and delete collections
Create a collection
post
/_api/collection
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
Creates a new collection with a given name. The request must contain an
object with the following attributes.
Query Parameters
waitForSyncReplication boolean
The default is true
, which means the server only reports success back to the
client when all replicas have created the collection. Set it to false
if you want
faster server responses and don’t care about full replication.
enforceReplicationFactor boolean
The default is true
, which means the server checks if there are enough replicas
available at creation time and bail out otherwise. Set it to false
to disable
this extra check.
Request Body application/json
cacheEnabled boolean
Whether the in-memory hash cache for documents should be enabled for this
collection (default: false
). Can be controlled globally with the --cache.size
startup option. The cache can speed up repeated reads of the same documents via
their document keys. If the same documents are not fetched often or are
modified frequently, then you may disable the cache to avoid the maintenance
costs.
computedValues array of objects
An optional list of objects, each representing a computed value.
computeOn array of strings
An array of strings to define on which write operations the value shall be
computed. The possible values are "insert"
, "update"
, and "replace"
.
The default is ["insert", "update", "replace"]
.
expression string
An AQL RETURN
operation with an expression that computes the desired value.
See Computed Value Expressions for details.
failOnWarning boolean
Whether to let the write operation fail if the expression produces a warning.
The default is false
.
keepNull boolean
Whether the target attribute shall be set if the expression evaluates to null
.
You can set the option to false
to not set (or unset) the target attribute if
the expression returns null
. The default is true
.
name string
The name of the target attribute. Can only be a top-level attribute, but you
may return a nested object. Cannot be _key
, _id
, _rev
, _from
, _to
,
or a shard key attribute.
overwrite boolean
Whether the computed value shall take precedence over a user-provided or
existing attribute.
distributeShardsLike string
The name of another collection. If this property is set in a cluster, the
collection copies the replicationFactor
, numberOfShards
and shardingStrategy
properties from the specified collection (referred to as the prototype collection)
and distributes the shards of this collection in the same way as the shards of
the other collection. In an Enterprise Edition cluster, this data co-location is
utilized to optimize queries.
You need to use the same number of shardKeys
as the prototype collection, but
you can use different attributes.
The default is ""
.
Using this parameter has consequences for the prototype
collection. It can no longer be dropped, before the sharding-imitating
collections are dropped. Equally, backups and restores of imitating
collections alone generate warnings (which can be overridden)
about a missing sharding prototype.
isDisjoint boolean
Whether the collection is for a Disjoint SmartGraph
(Enterprise Edition only). This is an internal property.
isSmart boolean
Whether the collection is for a SmartGraph or EnterpriseGraph
(Enterprise Edition only). This is an internal property.
isSystem boolean
If true
, create a system collection. In this case, the collection-name
should start with an underscore. End-users should normally create non-system
collections only. API implementors may be required to create system
collections in very special occasions, but normally a regular collection will do.
(The default is false
)
keyOptions object
additional options for key generation. If specified, then keyOptions
should be a JSON object containing the following attributes:
allowUserKeys boolean
If set to true
, then you are allowed to supply own key values in the
_key
attribute of documents. If set to false
, then the key generator
is solely be responsible for generating keys and an error is raised if you
supply own key values in the _key
attribute of documents.
You should not use both user-specified and automatically generated document keys
in the same collection in cluster deployments for collections with more than a
single shard. Mixing the two can lead to conflicts because Coordinators that
auto-generate keys in this case are not aware of all keys which are already used.
increment integer
increment value for autoincrement
key generator. Not used for other key
generator types.
offset integer
Initial offset value for autoincrement
key generator.
Not used for other key generator types.
type string
specifies the type of the key generator. The currently available generators are
traditional
, autoincrement
, uuid
and padded
.
The traditional
key generator generates numerical keys in ascending order.
The sequence of keys is not guaranteed to be gap-free.
The autoincrement
key generator generates numerical keys in ascending order,
the initial offset and the spacing can be configured (note: autoincrement
is currently only supported for non-sharded collections).
The sequence of generated keys is not guaranteed to be gap-free, because a new key
will be generated on every document insert attempt, not just for successful
inserts.
The padded
key generator generates keys of a fixed length (16 bytes) in
ascending lexicographical sort order. This is ideal for the RocksDB storage engine,
which will slightly benefit keys that are inserted in lexicographically
ascending order. The key generator can be used in a single-server or cluster.
The sequence of generated keys is not guaranteed to be gap-free.
The uuid
key generator generates universally unique 128 bit keys, which
are stored in hexadecimal human-readable format. This key generator can be used
in a single-server or cluster to generate “seemingly random” keys. The keys
produced by this key generator are not lexicographically sorted.
Please note that keys are only guaranteed to be truly ascending in single
server deployments and for collections that only have a single shard (that includes
collections in a OneShard database).
The reason is that for collections with more than a single shard, document keys
are generated on Coordinator(s). For collections with a single shard, the document
keys are generated on the leader DB-Server, which has full control over the key
sequence.
name* string
The name of the collection.
numberOfShards integer
(The default is 1
): in a cluster, this value determines the
number of shards to create for the collection.
replicationFactor integer
(The default is 1
): in a cluster, this attribute determines how many copies
of each shard are kept on different DB-Servers. The value 1 means that only one
copy (no synchronous replication) is kept. A value of k means that k-1 replicas
are kept. For SatelliteCollections, it needs to be the string "satellite"
,
which matches the replication factor to the number of DB-Servers
(Enterprise Edition only).
Any two copies reside on different DB-Servers. Replication between them is
synchronous, that is, every write operation to the “leader” copy will be replicated
to all “follower” replicas, before the write operation is reported successful.
If a server fails, this is detected automatically and one of the servers holding
copies take over, usually without an error being reported.
schema object
Optional object that specifies the collection level schema for
documents. The attribute keys rule
, level
and message
must follow the
rules documented in Document Schema Validation
shardKeys string
(The default is [ "_key" ]
): in a cluster, this attribute determines
which document attributes are used to determine the target shard for documents.
Documents are sent to shards based on the values of their shard key attributes.
The values of all shard key attributes in a document are hashed,
and the hash value is used to determine the target shard.
Values of shard key attributes cannot be changed once set.
shardingStrategy string
This attribute specifies the name of the sharding strategy to use for
the collection. There are different sharding strategies
to select from when creating a new collection. The selected shardingStrategy
value remains fixed for the collection and cannot be changed afterwards.
This is important to make the collection keep its sharding settings and
always find documents already distributed to shards using the same
initial sharding algorithm.
The available sharding strategies are:
community-compat
: default sharding used by ArangoDB
Community Edition before version 3.4enterprise-compat
: default sharding used by ArangoDB
Enterprise Edition before version 3.4enterprise-smart-edge-compat
: default sharding used by smart edge
collections in ArangoDB Enterprise Edition before version 3.4hash
: default sharding used for new collections starting from version 3.4
(excluding smart edge collections)enterprise-hash-smart-edge
: default sharding used for new
smart edge collections starting from version 3.4enterprise-hex-smart-vertex
: sharding used for vertex collections of
EnterpriseGraphs
If no sharding strategy is specified, the default is hash
for
all normal collections, enterprise-hash-smart-edge
for all smart edge
collections, and enterprise-hex-smart-vertex
for EnterpriseGraph
vertex collections (the latter two require the Enterprise Edition of ArangoDB).
Manually overriding the sharding strategy does not yet provide a
benefit, but it may later in case other sharding strategies are added.
smartGraphAttribute string
The attribute that is used for sharding: vertices with the same value of
this attribute are placed in the same shard. All vertices are required to
have this attribute set and it has to be a string. Edges derive the
attribute from their connected vertices.
This feature can only be used in the Enterprise Edition.
smartJoinAttribute string
In an Enterprise Edition cluster, this attribute determines an attribute
of the collection that must contain the shard key value of the referred-to
SmartJoin collection. Additionally, the shard key for a document in this
collection must contain the value of this attribute, followed by a colon,
followed by the actual primary key of the document.
This feature can only be used in the Enterprise Edition and requires the
distributeShardsLike
attribute of the collection to be set to the name
of another collection. It also requires the shardKeys
attribute of the
collection to be set to a single shard key attribute, with an additional ‘:’
at the end.
A further restriction is that whenever documents are stored or updated in the
collection, the value stored in the smartJoinAttribute
must be a string.
type integer
(The default is 2
): the type of the collection to create.
The following values for type
are valid:
2
: document collection3
: edge collection
waitForSync boolean
If true
then the data is synchronized to disk before returning from a
document create, update, replace or removal operation. (Default: false
)
writeConcern integer
Determines how many copies of each shard are required to be
in sync on the different DB-Servers. If there are less than these many copies
in the cluster, a shard refuses to write. Writes to shards with enough
up-to-date copies succeed at the same time, however. The value of
writeConcern
cannot be greater than replicationFactor
.
If distributeShardsLike
is set, the default writeConcern
is that of the prototype collection.
For SatelliteCollections, the writeConcern
is automatically controlled to
equal the number of DB-Servers and has a value of 0
.
Otherwise, the default value is controlled by the current database’s
default writeConcern
, which uses the --cluster.write-concern
startup option as default, which defaults to 1
. (cluster only)
Responses
200
Response Body
cacheEnabled* boolean
Whether the in-memory hash cache for documents is enabled for this
collection.
computedValues array of objects
A list of objects, each representing a computed value.
computeOn array of strings
An array of strings that defines on which write operations the value is
computed. The possible values are "insert"
, "update"
, and "replace"
.
expression string
An AQL RETURN
operation with an expression that computes the desired value.
failOnWarning boolean
Whether the write operation fails if the expression produces a warning.
keepNull boolean
Whether the target attribute is set if the expression evaluates to null
.
name string
The name of the target attribute.
overwrite boolean
Whether the computed value takes precedence over a user-provided or
existing attribute.
distributeShardsLike string
The name of another collection. This collection uses the replicationFactor
,
numberOfShards
and shardingStrategy
properties of the other collection and
the shards of this collection are distributed in the same way as the shards of
the other collection.
globallyUniqueId string
A unique identifier of the collection. This is an internal property.
id string
A unique identifier of the collection (deprecated).
isDisjoint boolean
Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint
(Enterprise Edition only). This is an internal property. (cluster only)
isSmart boolean
Whether the collection is used in a SmartGraph or EnterpriseGraph (Enterprise Edition only).
This is an internal property. (cluster only)
isSystem boolean
Whether the collection is a system collection. Collection names that starts with
an underscore are usually system collections.
keyOptions* object
An object which contains key generation options.
allowUserKeys* boolean
If set to true
, then you are allowed to supply
own key values in the _key
attribute of a document. If set to
false
, then the key generator is solely responsible for
generating keys and an error is raised if you supply own key values in the
_key
attribute of documents.
You should not use both user-specified and automatically generated document keys
in the same collection in cluster deployments for collections with more than a
single shard. Mixing the two can lead to conflicts because Coordinators that
auto-generate keys in this case are not aware of all keys which are already used.
increment* integer
The increment value for the autoincrement
key generator.
Not used for other key generator types.
lastValue* integer
The current offset value of the autoincrement
or padded
key generator.
This is an internal property for restoring dumps properly.
offset* integer
The initial offset value for the autoincrement
key generator.
Not used for other key generator types.
type* string
Specifies the type of the key generator. Possible values:
"traditional"
"autoincrement"
"uuid"
"padded"
name string
The name of this collection.
numberOfShards integer
The number of shards of the collection. (cluster only)
replicationFactor integer
Contains how many copies of each shard are kept on different DB-Servers.
It is an integer number in the range of 1-10 or the string "satellite"
for SatelliteCollections (Enterprise Edition only). (cluster only)
schema object
An object that specifies the collection-level schema for documents.
shardKeys array of strings
Contains the names of document attributes that are used to
determine the target shard for documents. (cluster only)
shardingStrategy string
The sharding strategy selected for the collection. (cluster only)
Possible values:
"community-compat"
"enterprise-compat"
"enterprise-smart-edge-compat"
"hash"
"enterprise-hash-smart-edge"
"enterprise-hex-smart-vertex"
smartGraphAttribute string
The attribute that is used for sharding: vertices with the same value of
this attribute are placed in the same shard. All vertices are required to
have this attribute set and it has to be a string. Edges derive the
attribute from their connected vertices (Enterprise Edition only). (cluster only)
smartJoinAttribute string
Determines an attribute of the collection that must contain the shard key value
of the referred-to SmartJoin collection (Enterprise Edition only). (cluster only)
syncByRevision* boolean
Whether the newer revision-based replication protocol is
enabled for this collection. This is an internal property.
type integer
The type of the collection:
0
: “unknown”2
: regular document collection3
: edge collection
waitForSync* boolean
If true
, creating, changing, or removing
documents waits until the data has been synchronized to disk.
writeConcern integer
Determines how many copies of each shard are required to be
in-sync on the different DB-Servers. If there are less than these many copies
in the cluster, a shard refuses to write. Writes to shards with enough
up-to-date copies succeed at the same time, however. The value of
writeConcern
cannot be greater than replicationFactor
.
If distributeShardsLike
is set, the default writeConcern
is that of the prototype collection.
For SatelliteCollections, the writeConcern
is automatically controlled to
equal the number of DB-Servers and has a value of 0
.
Otherwise, the default value is controlled by the current database’s
default writeConcern
, which uses the --cluster.write-concern
startup option as default, which defaults to 1
. (cluster only)
400
If the collection-name
is missing, then an HTTP 400 is
returned.
404
If the collection-name
is unknown, then an HTTP 404 is returned.
Examples
curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection
{
"name": "testCollectionBasics"
}
curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection
{
"name": "testCollectionEdges",
"type": 3
}
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 458
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"writeConcern" : 1,
"waitForSync" : false,
"usesRevisionsAsDocumentIds" : true,
"syncByRevision" : true,
"statusString" : "loaded",
"id" : "68722",
"isSmartChild" : false,
"schema" : null,
"name" : "testCollectionBasics",
"type" : 2,
"status" : 3,
"cacheEnabled" : false,
"isSystem" : false,
"internalValidatorType" : 0,
"globallyUniqueId" : "hED60CCAA6F22/68722",
"keyOptions" : {
"allowUserKeys" : true,
"type" : "traditional",
"lastValue" : 0
},
"computedValues" : null,
"objectId" : "68723"
}
HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 457
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"writeConcern" : 1,
"waitForSync" : false,
"usesRevisionsAsDocumentIds" : true,
"syncByRevision" : true,
"statusString" : "loaded",
"id" : "68727",
"isSmartChild" : false,
"schema" : null,
"name" : "testCollectionEdges",
"type" : 3,
"status" : 3,
"cacheEnabled" : false,
"isSystem" : false,
"internalValidatorType" : 0,
"globallyUniqueId" : "hED60CCAA6F22/68727",
"keyOptions" : {
"allowUserKeys" : true,
"type" : "traditional",
"lastValue" : 0
},
"computedValues" : null,
"objectId" : "68728"
}
curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection
{
"name": "testCollectionUsers",
"keyOptions": {
"type": "autoincrement",
"increment": 5,
"allowUserKeys": true
}
}
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 484
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"writeConcern" : 1,
"waitForSync" : false,
"usesRevisionsAsDocumentIds" : true,
"syncByRevision" : true,
"statusString" : "loaded",
"id" : "68742",
"isSmartChild" : false,
"schema" : null,
"name" : "testCollectionUsers",
"type" : 2,
"status" : 3,
"cacheEnabled" : false,
"isSystem" : false,
"internalValidatorType" : 0,
"globallyUniqueId" : "hED60CCAA6F22/68742",
"keyOptions" : {
"allowUserKeys" : true,
"type" : "autoincrement",
"offset" : 0,
"increment" : 5,
"lastValue" : 0
},
"computedValues" : null,
"objectId" : "68743"
}
Drop a collection
delete
/_api/collection/{collection-name}
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
Drops the collection identified by collection-name
.
If the collection was successfully dropped, an object is returned with
the following attributes:
Path Parameters
collection-name* string
The name of the collection to drop.
Query Parameters
isSystem boolean
Whether or not the collection to drop is a system collection. This parameter
must be set to true
in order to drop a system collection.
Responses
400
If the collection-name
is missing, then a HTTP 400 is
returned.
404
If the collection-name
is unknown, then a HTTP 404 is returned.
Examples
Using an identifier:
curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/68751
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 39
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"id" : "68751"
}
Using a name:
curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products1
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 39
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"id" : "68760"
}
Dropping a system collection
curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/_example?isSystem=true
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 39
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"id" : "68769"
}
Truncate a collection
put
/_api/collection/{collection-name}/truncate
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
Removes all documents from the collection, but leaves the indexes intact.
Path Parameters
collection-name* string
The name of the collection.
Query Parameters
waitForSync boolean
If true
then the data is synchronized to disk before returning from the
truncate operation (default: false
)
compact boolean
If true
(default) then the storage engine is told to start a compaction
in order to free up disk space. This can be resource intensive. If the only
intention is to start over with an empty collection, specify false
.
Responses
400
If the collection-name
is missing, then a HTTP 400 is
returned.
404
If the collection-name
is unknown, then a HTTP 404
is returned.
Examples
curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/truncate
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 135
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/truncate
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"globallyUniqueId" : "hED60CCAA6F22/68777",
"isSystem" : false,
"status" : 3,
"type" : 2,
"name" : "products",
"id" : "68777"
}
Modify collections
Load a collection
put
/_api/collection/{collection-name}/load
The load function is deprecated from version 3.8.0 onwards and is a no-op
from version 3.9.0 onwards. It should no longer be used, as it may be removed
in a future version of ArangoDB.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
Since ArangoDB version 3.9.0 this API does nothing. Previously it used to
load a collection into memory.
The request body object might optionally contain the following attribute:
count
: If set, this controls whether the return value should include
the number of documents in the collection. Setting count
to
false
may speed up loading a collection. The default value for
count
is true
.
A call to this API returns an object with the following attributes for
compatibility reasons:
id
: The identifier of the collection.
name
: The name of the collection.
count
: The number of documents inside the collection. This is only
returned if the count
input parameters is set to true
or has
not been specified.
status
: The status of the collection as number.
type
: The collection type. Valid types are:
- 2: document collection
- 3: edge collection
isSystem
: If true
then the collection is a system collection.
Path Parameters
collection-name* string
The name of the collection.
Responses
400
If the collection-name
is missing, then a HTTP 400 is
returned.
404
If the collection-name
is unknown, then a HTTP 404
is returned.
Examples
curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/load
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 145
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/load
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"count" : 0,
"globallyUniqueId" : "hED60CCAA6F22/68787",
"isSystem" : false,
"status" : 3,
"type" : 2,
"name" : "products",
"id" : "68787"
}
Unload a collection
put
/_api/collection/{collection-name}/unload
The unload function is deprecated from version 3.8.0 onwards and is a no-op
from version 3.9.0 onwards. It should no longer be used, as it may be removed
in a future version of ArangoDB.
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
Since ArangoDB version 3.9.0 this API does nothing. Previously it used to
unload a collection from memory, while preserving all documents.
When calling the API an object with the following attributes is
returned for compatibility reasons:
id
: The identifier of the collection.
name
: The name of the collection.
status
: The status of the collection as number.
type
: The collection type. Valid types are:
- 2: document collection
- 3: edges collection
isSystem
: If true
then the collection is a system collection.
Path Parameters
collection-name* string
The name of the collection.
Responses
400
If the collection-name
is missing, then a HTTP 400 is
returned.
404
If the collection-name
is unknown, then a HTTP 404 is returned.
Examples
curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/unload
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 135
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/unload
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"globallyUniqueId" : "hED60CCAA6F22/68797",
"isSystem" : false,
"status" : 3,
"type" : 2,
"name" : "products",
"id" : "68797"
}
Load collection indexes into memory
put
/_api/collection/{collection-name}/loadIndexesIntoMemory
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
You can call this endpoint to try to cache this collection’s index entries in
the main memory. Index lookups served from the memory cache can be much faster
than lookups not stored in the cache, resulting in a performance boost.
The endpoint iterates over suitable indexes of the collection and stores the
indexed values (not the entire document data) in memory. This is implemented for
edge indexes only.
The endpoint returns as soon as the index warmup has been scheduled. The index
warmup may still be ongoing in the background, even after the return value has
already been sent. As all suitable indexes are scanned, it may cause significant
I/O activity and background load.
This feature honors memory limits. If the indexes you want to load are smaller
than your memory limit, this feature guarantees that most index values are
cached. If the index is greater than your memory limit, this feature fills
up values up to this limit. You cannot control which indexes of the collection
should have priority over others.
It is guaranteed that the in-memory cache data is consistent with the stored
index data at all times.
On success, this endpoint returns an object with attribute result
set to true
.
Path Parameters
collection-name* string
The name of the collection.
Responses
200
If the index loading has been scheduled for all suitable indexes.
400
If the collection-name
is missing, then a HTTP 400 is
returned.
404
If the collection-name
is unknown, then a HTTP 404 is returned.
Examples
curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/products/loadIndexesIntoMemory
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 40
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/loadIndexesIntoMemory
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"result" : true
}
Change the properties of a collection
put
/_api/collection/{collection-name}/properties
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
Changes the properties of a collection. Only the provided attributes are
updated. Collection properties cannot be changed once a collection is
created except for the listed properties, as well as the collection name via
the rename endpoint (but not in clusters).
Path Parameters
collection-name* string
The name of the collection.
Request Body application/json
cacheEnabled boolean
Whether the in-memory hash cache for documents should be enabled for this
collection (default: false
). Can be controlled globally with the --cache.size
startup option. The cache can speed up repeated reads of the same documents via
their document keys. If the same documents are not fetched often or are
modified frequently, then you may disable the cache to avoid the maintenance
costs.
computedValues array of objects
An optional list of objects, each representing a computed value.
computeOn array of strings
An array of strings to define on which write operations the value shall be
computed. The possible values are "insert"
, "update"
, and "replace"
.
The default is ["insert", "update", "replace"]
.
expression string
An AQL RETURN
operation with an expression that computes the desired value.
See Computed Value Expressions for details.
failOnWarning boolean
Whether to let the write operation fail if the expression produces a warning.
The default is false
.
keepNull boolean
Whether the target attribute shall be set if the expression evaluates to null
.
You can set the option to false
to not set (or unset) the target attribute if
the expression returns null
. The default is true
.
name string
The name of the target attribute. Can only be a top-level attribute, but you
may return a nested object. Cannot be _key
, _id
, _rev
, _from
, _to
,
or a shard key attribute.
overwrite boolean
Whether the computed value shall take precedence over a user-provided or
existing attribute.
replicationFactor integer
(The default is 1
): in a cluster, this attribute determines how many copies
of each shard are kept on different DB-Servers. The value 1 means that only one
copy (no synchronous replication) is kept. A value of k means that k-1 replicas
are kept. For SatelliteCollections, it needs to be the string "satellite"
,
which matches the replication factor to the number of DB-Servers
(Enterprise Edition only).
Any two copies reside on different DB-Servers. Replication between them is
synchronous, that is, every write operation to the “leader” copy will be replicated
to all “follower” replicas, before the write operation is reported successful.
If a server fails, this is detected automatically and one of the servers holding
copies take over, usually without an error being reported.
schema object
Optional object that specifies the collection level schema for
documents. The attribute keys rule
, level
and message
must follow the
rules documented in Document Schema Validation
waitForSync boolean
If true
then the data is synchronized to disk before returning from a
document create, update, replace or removal operation. (default: false)
writeConcern integer
Determines how many copies of each shard are required to be
in sync on the different DB-Servers. If there are less than these many copies
in the cluster, a shard refuses to write. Writes to shards with enough
up-to-date copies succeed at the same time, however. The value of
writeConcern
cannot be greater than replicationFactor
.
If distributeShardsLike
is set, the default writeConcern
is that of the prototype collection.
For SatelliteCollections, the writeConcern
is automatically controlled to
equal the number of DB-Servers and has a value of 0
.
Otherwise, the default value is controlled by the current database’s
default writeConcern
, which uses the --cluster.write-concern
startup option as default, which defaults to 1
. (cluster only)
Responses
400
If the collection-name
is missing, then a HTTP 400 is
returned.
404
If the collection-name
is unknown, then a HTTP 404
is returned.
Examples
curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection/products/properties
{
"waitForSync": true
}
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 445
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products/properties
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"writeConcern" : 1,
"waitForSync" : true,
"usesRevisionsAsDocumentIds" : true,
"syncByRevision" : true,
"statusString" : "loaded",
"id" : "68815",
"isSmartChild" : false,
"schema" : null,
"name" : "products",
"type" : 2,
"status" : 3,
"cacheEnabled" : false,
"isSystem" : false,
"internalValidatorType" : 0,
"globallyUniqueId" : "hED60CCAA6F22/68815",
"keyOptions" : {
"allowUserKeys" : true,
"type" : "traditional",
"lastValue" : 0
},
"computedValues" : null,
"objectId" : "68816"
}
Rename a collection
put
/_api/collection/{collection-name}/rename
Accessing collections by their numeric ID is deprecated from version 3.4.0 on.
You should reference them via their names instead.
Renames a collection. Expects an object with the attribute(s)
It returns an object with the attributes
id
: The identifier of the collection.
name
: The new name of the collection.
status
: The status of the collection as number.
type
: The collection type. Valid types are:
- 2: document collection
- 3: edges collection
isSystem
: If true
then the collection is a system collection.
If renaming the collection succeeds, then the collection is also renamed in
all graph definitions inside the _graphs
collection in the current database.
Renaming collections is not supported in cluster deployments.
Path Parameters
collection-name* string
The name of the collection to rename.
Responses
400
If the collection-name
is missing, then a HTTP 400 is
returned.
404
If the collection-name
is unknown, then a HTTP 404
is returned.
Examples
curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/collection/products1/rename
{
"name": "newname"
}
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 134
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/products1/rename
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"globallyUniqueId" : "hED60CCAA6F22/68826",
"isSystem" : false,
"status" : 3,
"type" : 2,
"name" : "newname",
"id" : "68826"
}
Recalculate the document count of a collection
put
/_api/collection/{collection-name}/recalculateCount
Recalculates the document count of a collection, if it ever becomes inconsistent.
It returns an object with the attributes
result
: will be true
if recalculating the document count succeeded.
Path Parameters
collection-name* string
The name of the collection.
Responses
200
If the document count was recalculated successfully, HTTP 200 is returned.
404
If the collection-name
is unknown, then a HTTP 404 is returned.
Compact a collection
put
/_api/collection/{collection-name}/compact
Compacts the data of a collection in order to reclaim disk space.
The operation will compact the document and index data by rewriting the
underlying .sst files and only keeping the relevant entries.
Under normal circumstances, running a compact operation is not necessary, as
the collection data will eventually get compacted anyway. However, in some
situations, e.g. after running lots of update/replace or remove operations,
the disk data for a collection may contain a lot of outdated data for which the
space shall be reclaimed. In this case the compaction operation can be used.
Path Parameters
collection-name* string
Name of the collection to compact
Responses
200
Compaction started successfully
401
if the request was not authenticated as a user with sufficient rights
Examples
curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_api/collection/testCollection/compact
Show outputHTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 141
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
location: /_db/_system/_api/collection/testCollection/compact
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
{
"error" : false,
"code" : 200,
"globallyUniqueId" : "hED60CCAA6F22/68838",
"isSystem" : false,
"status" : 3,
"type" : 2,
"name" : "testCollection",
"id" : "68838"
}