ArangoDB in 10 Minutes: CRUD

This is a short tutorial to get started with ArangoDB. In less than 10 minutes, you can learn how to do a Document CRUD (Create, Read, Update, Delete) with AQL and HTTP API in ArangoDB.

Note: This tutorial was written for ArangoDB 3.0 and may not work with older versions.

Note: Install ArangoDB for your environment.

Create a Document

With the following command you can create a document: POST /_api/document/{collection}

Post Body data (required): A JSON representation of a single document or of an array of documents.

Note: The following examples lean on the assumption that a collection named “users” is already created.

Curl Example

Create a document in a collection named users. The revision identifier is auto-generated by the server and might or might not be different than displayed in the examples.

Note: In case the authentication in your system is enabled you need to specify --user (username):(password) in the curl commands.

curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document/users <<EOF
{
    "_key": "FirstUser",
    "firstName": "Anna",
    "name": "Pavlova",
    "profession": "artist"
}

You should see something like this as a result:

HTTP/1.1 202 Accepted
Location: /_db/_system/_api/document/users/FirstUser
Etag: "99790"
Server: ArangoDB
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
Content-Length: 59

{"_id":"users/FirstUser","_key":"FirstUser","_rev":"99790"}

AQL Example

For creating a document in a collection, AQL supports the following data-modification operation:

• INSERT: insert new documents into a collection.

Note: You can use the Queries tab in the ArangoDB web-interface to execute the query.

Here is an example that insert a document in an existing collection named “users”:

INSERT {
    _key: "SecondUser",
    firstName: "Jana",
    name: "Volkova",
    profession: "Avocado farmer"
} IN users

Read a Document

The following command reads a single document: GET /_api/document/{document-handle} .

Path Parameters – document-handle (required): The handle of the document.

Curl Example

Use a document handle:

curl --dump - http://localhost:8529/_api/document/users/FirstUser

The result should look approximately like this:

HTTP/1.1 200 OK
Etag: "99790"
Server: ArangoDB
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
Content-Length: 117

{"_key":"FirstUser","_id":"users/FirstUser","_rev":"99790","firstName":"Anna","name":"Pavlova","profession":"artist"}

AQL Example

The result of an AQL query is an array of values. The individual values in the result array may or may not have a homogeneous structure, depending on what is actually queried.

FOR u IN users
    RETURN u

The result should look like something like this:

[
  {
    "_key": "SecondUser",
    "_id": "users/SecondUser",
    "_rev": "99878",
    "firstName": "Jana",
    "name": "Volkova",
    "profession": "Avocado farmer"
  },
  {
    "_key": "FirstUser",
    "_id": "users/FirstUser",
    "_rev": "99790",
    "firstName": "Anna",
    "name": "Pavlova",
    "profession": "artist"
  }
]

Update a Document

With the following command, you can update a document:  PATCH /_api/document/{document-handle} .

Post Body document (required): A JSON representation of a document update as an object.

Path Parameters – document-handle (required): This URL parameter must be a document handle.

Curl Example

Patches an existing document with new content.

curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/document/users/FirstUser <<EOF
{
"profession" : "singer"
}
EOF

The result should look like something like this:

HTTP/1.1 202 Accepted
Location: /_db/_system/_api/document/users/FirstUser
Etag: "100621"
Server: ArangoDB
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
Content-Length: 78

{"_id":"users/FirstUser","_key":"FirstUser","_rev":"100621","_oldRev":"99790"}

Read a document again to see the results:

curl --dump - http://localhost:8529/_api/document/users/FirstUser

The result is the following:

HTTP/1.1 200 OK
Etag: "100621"
Server: ArangoDB
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
Content-Length: 118

{"_key":"FirstUser","_id":"users/FirstUser","_rev":"100621","firstName":"Anna","name":"Pavlova","profession":"singer"}

Or check out the ArangoDB web-interface to see that the update in a document took place:

AQL Example

Update is quite simple. The following AQL statement will add or change the attributes status and location:

UPDATE "SecondUser" WITH {
    profession: "database expert"
} IN users

Read the document again to see the results:

FOR u IN users
    RETURN u

The results:

[
  {
    "_key": "SecondUser",
    "_id": "users/SecondUser",
    "_rev": "101463",
    "firstName": "Jana",
    "name": "Volkova",
    "profession": "database expert"
  },
  {
    "_key": "FirstUser",
    "_id": "users/FirstUser",
    "_rev": "100621",
    "firstName": "Anna",
    "name": "Pavlova",
    "profession": "singer"
  }
]

Delete a Document

This command removes a document: DELETE /_api/document/{document-handle}

Path Parameters – document-handle (required): Removes the document identified by document-handle.

Curl Example

Using document handle:

curl -X DELETE --dump - http://localhost:8529/_api/document/users/FirstUser

The results will look approximately like this:

HTTP/1.1 202 Accepted
Location: /_db/_system/_api/document/users/FirstUser
Etag: "100621"
Server: ArangoDB
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
Content-Length: 60

{"_id":"users/FirstUser","_key":"FirstUser","_rev":"100621"}

AQL Example

Removing a document if you know its key is simple as well:

REMOVE "SecondUser" IN users

Learn More

By now you should have a sound understanding of how to run the basic operations in ArangoDB. But there is much more to know and so much more you can do:

• Dive into AQL to learn more about the query language
• A detailed overview on how to work with Documents using REST in ArangoDB can be found here
• Explore the ArangoDB Cookbook for practical solutions to common problems
• Confused by the jargon? There’s a glossary that can help you
• Have questions? Ask on StackOverflow and find answers
• Made a cool thing? Tell us more about it!
• Want to get involved? ArangoDB is Open Source with many ways to contribute
• Still wondering? Get in touch via our Slack Community Channel or on Twitter @arangodb