ArangoDB Manual

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

HTTP Interface for Collections

Collections

Collection: A collection consists of documents. It is uniquely identified by it's collection identifier. It also has a unique name.

Collection Identifier: A collection identifier identifies a collection in a database. It is an integer and is unique within the database.

Collection Name: A collection name identifies a collection in a database. It is an string and is unique within the database. Unlike the collection identifier it is supplied by the creator of the collection. The collection name can consist of letters, digits and the characters _ (underscore) and - (dash). However, the first character must be a letter.

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. This collection identifier identifies a collection and is managed by ArangoDB. All collections are found under the URI

http://server:port/_api/collection/collection-identifier

For example: Assume that the collection identifier is 7254820, then the URL of that collection is:

http://localhost:8529/_api/collection/7254820

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.

Examples

> curl --data @- -X POST --dump - http://localhost:8529/_api/collection
{ "name" : "UnitTestsCollectionBasics" }

HTTP/1.1 200 OK
content-type: application/json
location: /_api/collection/179665369

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

DELETE /_api/collection (deletes a collection)

DELETE /_api/collection/collection-identifier

Deletes a collection identified by collection-identified.

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-identifier is missing, then a HTTP 400 is returned. If the collection-identifier is unknown, then a HTTP 404 is returned.

It is possible to specify a name instead of an identifier.

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-identifier/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,
  "error": false
}

Getting Information about a Collection

GET /_api/collection (reads a collection)

GET /_api/collection/collection-identifier

The result is an objects 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-identifier is unknown, then a HTTP 404 is returned.

It is possible to specify a name instead of an identifier. In this case the response will contain a field "Location" which contains the correct location.

GET /_api/collection/collection-identifier/properties

In addition to the above, the result will always contain the waitForSync and the journalSize 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.

GET /_api/collection/collection-identifier/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-identifier/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.

journalSize: The maximal size of the journal in bytes.

Note: the filesizes of shapes and compactor files are not reported.

Examples

Using an identifier:

> curl -X GET --dump - http://localhost:8529/_api/collection/73482

HTTP/1.1 200 OK
content-type: application/json
location: /_api/collection/73482

{
  "name": "UnitTestsCollectionBasics",
  "code": 200,
  "waitForSync": true,
  "id": 73482,
  "status": 3,
  "error": false
}

Using a name:

> curl -X GET --dump - http://localhost:8529/_api/collection/UnitTestsCollectionBasics

HTTP/1.1 200 OK
content-type: application/json
location: /_api/collection/73482

{
  "name": "UnitTestsCollectionBasics",
  "code": 200,
  "waitForSync": true,
  "id": 73482,
  "status": 3,
  "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
location: /_api/collection/73482/count

{
  "name": "UnitTestsCollectionBasics",
  "code": 200,
  "waitForSync": true,
  "id": 73482,
  "count": 0,
  "status": 3,
  "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
location: /_api/collection/73482/figures

{
  "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
    }
  },
  "waitForSync": true,
  "id": 73482,
  "journalSize": 134217728,
  "count": 0,
  "status": 3,
  "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.

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",
      "waitForSync": true,
      "id": 64091684,
      "status": 3
    },
    {
      "name": "units",
      "waitForSync": true,
      "id": 63043108,
      "status": 3
    }
  ],
  "code": 200,
  "names": {
    "units": {
      "name": "units",
      "waitForSync": true,
      "id": 63043108,
      "status": 3
    },
    "employees": {
      "name": "employees",
      "waitForSync": true,
      "id": 64091684,
      "status": 3
    }
  },
  "error": false
}

Modifying a Collection

PUT /_api/collection/.../load (loads a collection)

PUT /_api/collection/collection-identifier/load

Loads a collection into memory. On success an object with the following

id: The identifier of the collection.

name: The name of the collection.

count: The number of documents inside the collection.

status: The status of the collection as number.

If the collection-identifier is missing, then a HTTP 400 is returned. If the collection-identifier is unknown, then a HTTP 404 is returned.

It is possible to specify a name instead of an identifier.

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,
  "error": false
}

PUT /_api/collection/.../unload (unloads a collection)

PUT /_api/collection/collection-identifier/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

id: The identifier of the collection.

name: The name of the collection.

status: The status of the collection as number.

If the collection-identifier is missing, then a HTTP 400 is returned. If the collection-identifier 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,
  "error": false
}

PUT /_api/collection/.../properties (changes the properties of a collection)

PUT /_api/collection/collection-identifier/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.

If returns an object with the attributes

id: The identifier of the collection.

name: The name of the collection.

waitForSync: The new value.

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,
  "id": 70109828,
  "journalSize": 134217728,
  "status": 3,
  "error": false
}

PUT /_api/collection/.../rename (renames a collection)

PUT /_api/collection/collection-identifier/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.

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,
  "error": false
}

HTTP Interface for Collections

Collections

Address of a Collection

Working with Collections using HTTP

Creating and Deleting Collections

Getting Information about a Collection

Modifying a Collection