ArangoDB Manual Pages


HTTP Interface for Collections

Collections

This is an introduction to ArangoDB's Http interface for collections.

Collection: A collection consists of documents. It is uniquely identified by the server via its collection identifier. It also has a unique name that clients should use to identify and access it. Collections have a type that is specified by the user when the collection is created. There currently are document and edge collections. The default type is document.

Collection Identifier: A collection identifier identifies a collection in a database. It is a string value and is unique within the database. Up to including ArangoDB 1.1, the collection identifier has been a client's primary means to access collections. Starting with ArangoDB 1.2, clients should instead use a collection's unique name to access a collection instead of its identifier.ArangoDB currently uses 64bit unsigned integer values to maintain collection ids internally. When returning collection ids to clients, ArangoDB will put them into a string to ensure the collection id is not clipped by clients that do not support big integers. Clients should treat the collection ids returned by ArangoDB as opaque strings when they store or use it locally.Note: collection ids have been returned as integers up to including ArangoDB 1.1

Collection Name: A collection name identifies a collection in a database. It is a string and is unique within the database. Unlike the collection identifier it is supplied by the creator of the collection. The collection name must consist of letters, digits and the characters _ (underscore), - (dash), and : (colon). Please refer to Naming Conventions in ArangoDB for more information on valid collection names.

Key Generator: ArangoDB allows using key generators for each collection. Key generators have the purpose of auto-generating values for the _key attribute of a document if none was specified by the user.By default, ArangoDB will use the traditional key generator. The traditional key generator will auto-generate key values that are strings with ever-increasing numbers. The increment values it uses are non-deterministic.Contrary, the autoincrement key generator will auto-generate deterministic key values. Both the start value and the increment value can be defined when the collection is created. The default start value is 0 and the default increment is 1, meaning the key values it will create by default are:

1, 2, 3, 4, 5, ...
When creating a collection with the autoincrement key generator and an increment of 5, the generated keys would be:

1, 6, 11, 16, 21, ...

The basic operations (create, read, update, delete) for documents are mapped to the standard HTTP methods (POST, GET, PUT, DELETE).

Address of a Collection

All collections in ArangoDB have an unique identifier and a unique name. ArangoDB internally uses the collection's unique identifier to look up collections. This identifier however is managed by ArangoDB and the user has no control over it. In order to allow users use their own names, each collection also has a unique name, which is specified by the user. To access a collection from the user perspective, the collection name should be used, i.e.:

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

Working with Collections using HTTP

Creating and Deleting Collections

POST /_api/collection
(creates a collection)
POST /_api/collection
Creates an new collection with a given name. The request must contain an object with the following attributes.
  • name: The name of the collection.
  • waitForSync (optional, default: false): If true then the data is synchronised to disk before returning from a create or update of an document.
  • journalSize (optional, default is a configuration parameter): The maximal size of a journal or datafile. Note that this also limits the maximal size of a single object. Must be at least 1MB.
  • isSystem (optional, default is false): If true, create a system collection. In this case 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.
  • isVolatile (optional, default is false): If true then the collection data is kept in-memory only and not made persistent. Unloading the collection will cause the collection data to be discarded. Stopping or re-starting the server will also cause full loss of data in the collection. Setting this option will make the resulting collection be slightly faster than regular collections because ArangoDB does not enforce any synchronisation to disk and does not calculate any CRC checksums for datafiles (as there are no datafiles).

    This option should threrefore be used for cache-type collections only, and not for data that cannot be re-created otherwise.

  • keyOptions (optional) additional options for key generation. If specified, then keyOptions should be a JSON array containing the following attributes (note: some of them are optional):
    • type: specifies the type of the key generator. The currently available generators are traditional and autoincrement.
    • allowUserKeys: if set to true, then it is allowed to supply own key values in the _key attribute of a document. If set to false, then the key generator will solely be responsible for generating keys and supplying own key values in the _key attribute of documents is considered an error.
    • increment: increment value for autoincrement key generator. Not used for other key generator types.
    • offset: initial offset value for autoincrement key generator. Not used for other key generator types.
  • options (optional) Additional collection options
  • type (optional, default is 2): the type of the collection to create. The following values for type are valid:
    • 2: document collection
    • 3: edges collection
Examples
> curl --data @- -X POST --dump - http://localhost:8529/_api/collection
{ "name" : "UnitTestsCollectionBasics" }

HTTP/1.1 200 OK
content-type: application/json

{
  "name": "UnitTestsCollectionBasics",
  "code": 200,
  "waitForSync": false,
  "isVolatile": false,
  "id": 179665369,
  "status": 3,
  "type" : 2,
  "error": false
}

> curl --data @- -X POST --dump - http://localhost:8529/_api/collection
{ "name" : "UnitTestsCollectionEdges", "type" : 3 }

HTTP/1.1 200 OK
content-type: application/json

{
  "name": "UnitTestsCollectionEdges",
  "code": 200,
  "waitForSync": false,
  "isVolatile": false,
  "id": 184354432,
  "status": 3,
  "type": 3,
  "error": false
}
> curl --data @- -X POST --dump - http://localhost:8529/_api/collection
{ "name" : "users", "keyOptions" : { "type" : "autoincrement", "increment" : 5, "allowUserKeys" : true } }

HTTP/1.1 200 OK
location: /_api/collection/users
content-type: application/json; charset=utf-8

{
  "name" : "users", 
  "waitForSync" : false,
  "isVolatile" : false,
  "isSystem" : false,
  "status" : 3,
  "type" : 2,
  "error" : false,
  "code": 200
}

DELETE /_api/collection
(deletes a collection)
DELETE /_api/collection/collection-name
Deletes a collection identified by collection-name.If the collection was successfully deleted then, an object is returned with the following attributes:
  • error: false
  • id: The identifier of the deleted collection.
If the collection-name is missing, then a HTTP 400 is returned. If the collection-name is unknown, then a HTTP 404 is returned.
Examples
Using an identifier:
> curl -X DELETE --dump - http://localhost:8529/_api/collection/101711425

HTTP/1.1 200 OK
content-type: application/json

{
  "code": 200,
  "id": 101711425,
  "error": false
}
Using a name:
> curl -X DELETE --dump - http://localhost:8529/_api/collection/UnitTestsCollectionBasics

HTTP/1.1 200 OK
content-type: application/json

{
  "code": 200,
  "id": 103022145,
  "error": false
}

PUT /_api/collection/.../truncate
(truncates a collection)
PUT /_api/collection/collection-name/truncate
Removes all documents from the collection, but leaves the indexes intact.
Examples
> curl -X PUT --dump - http://localhost:8529/_api/collection/56478340/truncate

HTTP/1.1 200 OK
content-type: application/json

{
  "name": "UnitTestsCollectionBasics",
  "code": 200,
  "id": 56478340,
  "status": 3,
  "type": 2,
  "error": false
}

Getting Information about a Collection

GET /_api/collection
(reads a collection)
GET /_api/collection/collection-name
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.
    • 1: new born collection
    • 2: unloaded
    • 3: loaded
    • 4: in the process of being unloaded
    • 5: deleted
Every other status indicates a corrupted collection.
  • type: The type of the collection as number.
    • 2: document collection (normal case)
    • 3: edges collection
If the collection-name is unknown, then a HTTP 404 is returned.
GET /_api/collection/collection-name/properties
In addition to the above, the result will always contain the waitForSync, journalSize, and isVolatile properties. This is achieved by forcing a load of the underlying collection.
  • waitForSync: If true then creating or changing a document will wait until the data has been synchronised to disk.
  • journalSize: The maximal size of a journal / datafile.
  • isVolatile: If true then the collection data will be kept in memory only and ArangoDB will not write or sync the data to disk.
GET /_api/collection/collection-name/count
In addition to the above, the result also contains the number of documents. Note that this will always load the collection into memory.
  • count: The number of documents inside the collection.
GET /_api/collection/collection-name/figures
In addition to the above, the result also contains the number of documents and additional statistical information about the collection. Note that this will always load the collection into memory.
  • count: The number of documents inside the collection.
  • figures.alive.count: The number of living documents.
  • figures.alive.size: The total size in bytes used by all living documents.
  • figures.dead.count: The number of dead documents.
  • figures.dead.size: The total size in bytes used by all dead documents.
  • figures.dead.deletion: The total number of deletion markers.
  • figures.datafiles.count: The number of active datafiles.
  • figures.datafiles.fileSize: The total filesize of datafiles.
  • figures.journals.count: The number of journal files.
  • figures.journals.fileSize: The total filesize of journal files.
  • figures.shapes.count: The total number of shapes used in the collection (this includes shapes that are not in use anymore)
  • journalSize: The maximal size of the journal in bytes.
Note: the filesizes of shapes and compactor files are not reported.
GET /_api/collection/collection-name/revision
In addition to the above, the result will also contain the collection's 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.
Examples
Using an identifier:
> curl -X GET --dump - http://localhost:8529/_api/collection/73482

HTTP/1.1 200 OK
content-type: application/json

{
  "name": "UnitTestsCollectionBasics",
  "code": 200,
  "id": 73482,
  "status": 3,
  "type": 2,
  "error": false
}
Using a name:
> curl -X GET --dump - http://localhost:8529/_api/collection/UnitTestsCollectionBasics

HTTP/1.1 200 OK
content-type: application/json

{
  "name": "UnitTestsCollectionBasics",
  "code": 200,
  "id": 73482,
  "status": 3,
  "type": 2,
  "error": false
}
Using an identifier and requesting the number of documents:
> curl -X GET --dump - http://localhost:8529/_api/collection/73482/count

HTTP/1.1 200 OK
content-type: application/json

{
  "name": "UnitTestsCollectionBasics",
  "code": 200,
  "waitForSync": true,
  "isVolatile": false,
  "id": 73482,
  "journalSize": 33554432,
  "count": 0,
  "status": 3,
  "type": 2,
  "error": false
}
Using an identifier and requesting the figures of the collection:
> curl -X GET --dump - http://localhost:8529/_api/collection/73482/figures

HTTP/1.1 200 OK
content-type: application/json

{
  "name": "UnitTestsCollectionBasics",
  "code": 200,
  "figures": {
    "datafiles": {
      "count": 0,
      "fileSize": 0
    },
    "journals": {
      "count": 0,
      "fileSize": 33554432 
    },
    "alive": {
      "size": 0,
      "count": 0
    },
    "dead": {
      "size": 2384,
      "count": 149
    },
    "shapes": {
      "count": 59
    },
  },
  "waitForSync": true,
  "isVolatile": false,
  "id": 73482,
  "journalSize": 134217728,
  "count": 0,
  "status": 3,
  "type": 2,
  "error": false
}

GET /_api/collection
(reads all collections)
GET /_api/collection
Returns an object with an attribute collections containing a list of all collection descriptions. The same information is also available in the names as hash map with the collection names as keys.By providing the optional URL parameter excludeSystem with a value of true, all system collections will be excluded from the response.
Examples
Return information about all collections:
> curl -X GET --dump - http://localhost:8529/_api/collection

HTTP/1.1 200 OK
content-type: application/json

{
  "collections": [
    {
      "name": "employees",
      "id": 64091684,
      "status": 3,
      "type": 2
    },
    {
      "name": "units",
      "id": 63043108,
      "status": 3,
      "type": 2
    }
  ],
  "code": 200,
  "names": {
    "units": {
      "name": "units",
      "id": 63043108,
      "status": 3,
      "type": 2
    },
    "employees": {
      "name": "employees",
      "id": 64091684,
      "status": 3,
      "type": 2
    }
  },
  "error": false
}

Modifying a Collection

PUT /_api/collection/.../load
(loads a collection)
PUT /_api/collection/collection-name/load
Loads a collection into memory. Returns the collection on success.The request 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.
On success an object with the following attributes is returned:
  • 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: edges collection
If the collection-name is missing, then a HTTP 400 is returned. If the collection-name is unknown, then a HTTP 404 is returned.
Examples
> curl -X PUT --dump - http://localhost:8529/_api/collection/55144253/load

HTTP/1.1 200 OK
content-type: application/json

{
  "name": "UnitTestsCollectionBasics",
  "code": 200,
  "id": 55144253,
  "count": 0,
  "status": 3,
  "type": 2,
  "error": false
}

PUT /_api/collection/.../unload
(unloads a collection)
PUT /_api/collection/collection-name/unload
Removes a collection from memory. This call does not delete any documents. You can use the collection afterwards; in which case it will be loaded into memory, again. On success an object with the following attributes is returned:
  • 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
If the collection-name is missing, then a HTTP 400 is returned. If the collection-name is unknown, then a HTTP 404 is returned.
Examples
> curl -X PUT --dump - http://localhost:8529/_api/collection/57765693/unload

HTTP/1.1 200 OK
content-type: application/json

{
  "name": "UnitTestsCollectionBasics",
  "code": 200,
  "id": 57765693,
  "status": 4,
  "type": 2,
  "error": false
}

PUT /_api/collection/.../properties
(changes the properties of a collection)
PUT /_api/collection/collection-name/properties
Changes the properties of a collection. Expects an object with the attribute(s)
  • waitForSync: If true then creating or changing a document will wait until the data has been synchronised to disk.
  • journalSize: Size (in bytes) for new journal files that are created for the collection.
If returns an object with the attributes
  • id: The identifier of the collection.
  • name: The name of the collection.
  • waitForSync: The new value.
  • journalSize: The new value.
  • status: The status of the collection as number.
  • type: The collection type. Valid types are:
    • 2: document collection
    • 3: edges collection
Note: some other collection properties, such as type or isVolatile cannot be changed once the collection is created.
Examples
> curl --data @- -X PUT --dump - http://localhost:8529/_api/collection/70109828/properties
{ "waitForSync" : true }

HTTP/1.1 200 OK
content-type: application/json

{
  "name": "UnitTestsCollectionBasics",
  "code": 200,
  "waitForSync": true,
  "isVolatile": false,
  "id": 70109828,
  "journalSize": 134217728,
  "status": 3,
  "type": 2,
  "error": false
}

PUT /_api/collection/.../rename
(renames a collection)
PUT /_api/collection/collection-name/rename
Renames a collection. Expects an object with the attribute(s)
  • name: The new name.
If 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
Examples
> curl --data @- -X PUT --dump - http://localhost:8529/_api/collection/59230852/rename
{ "name" : "UnitTestsCollectionBasics2" }

HTTP/1.1 200 OK
content-type: application/json

{
  "name": "UnitTestsCollectionBasics2",
  "code": 200,
  "id": 59230852,
  "status": 3,
  "type": 2,
  "error": false
}