Exploring Collections and Documents

ArangoDB is a database that serves documents to clients.

• A document contains zero or more attributes, each one of these attributes has a value. A value can either be an atomic type, i. e. integer, strings, boolean, an array or an embedded document. Documents are normally represented as JSON objects
• Documents are grouped into collections. A collection contains zero or more documents
• Queries are used to filter documents based on certain criteria. Queries can be as simple as a “query by example” or as complex as “joins” using many collections or graph structures
• Cursors are used to iterate over the result of a query
• Indexes are used to speed up searches. There are various types of indexes such as hash indexes and geo indexes

If you are familiar with RDBMS then it is safe to compare collections to tables and documents to rows. However, bringing structure to the “rows” has many advantages - as you will see later.

Starting the JavaScript shell

The easiest way to connect to the database is the JavaScript shell arangosh. You can either start it from the command-line or as an embedded version in the browser. Using the command-line tool has the advantage that you can use autocompletion.

unix> arangosh --server.password ""
                                       _ 
  __ _ _ __ __ _ _ __   __ _  ___  ___| |__ 
 / _` | '__/ _` | '_ \ / _` |/ _ \/ __| '_ \ 
| (_| | | | (_| | | | | (_| | (_) \__ \ | | |
 \__,_|_|  \__,_|_| |_|\__, |\___/|___/_| |_|
                       |___/

Welcome to arangosh 2.x.y. Copyright (c) 2012 triAGENS GmbH.
Using Google V8 4.1.0.27 JavaScript engine.
Using READLINE 6.1.

Connected to Arango DB 127.0.0.1:8529 Version 2.2.0

arangosh> help
------------------------------------- Help -------------------------------------
Predefined objects:                                                 
  arango:                               ArangoConnection           
  db:                                   ArangoDatabase             
  fm:                                   FoxxManager  
Example:                                                            
 > db._collections();                   list all collections       
 > db._create(<name>)                   create a new collection    
 > db._drop(<name>)                     drop a collection         
 > db.<name>.toArray()                  list all documents         
 > id = db.<name>.save({ ... })         save a document            
 > db.<name>.remove(<_id>)              delete a document          
 > db.<name>.document(<_id>)            retrieve a document        
 > db.<name>.replace(<_id>, {...})      overwrite a document       
 > db.<name>.update(<_id>, {...})       partially update a document
 > db.<name>.exists(<_id>)              check if document exists   
 > db._query(<query>).toArray()         execute an AQL query       
 > db._useDatabase(<name>)              switch database            
 > db._createDatabase(<name>)           create a new database      
 > db._listDatabases()                  list existing databases    
 > help                                 show help pages            
 > exit                                         
arangosh>

This gives you a prompt where you can issue JavaScript commands.

The standard setup does not require a password. Depending on your setup you might need to specify the endpoint, username and password in order to run the shell on your system. You can use the options --server.endpoint, --server.username and --server.password for this.

unix> arangosh --server.endpoint tcp://127.0.0.1:8529 --server.username root

A default configuration is normally installed under /etc/arangodb/arangosh.conf. It contains a default endpoint and an empty password.

Querying for Documents

All documents are stored in collections. All collections are stored in a database. The database object is accessible via the variable db.

Creating a collection is simple. You can use the _create method of the db variable.

arangosh> db._create("example");

[ArangoCollection 447105153, "example" (type document, status loaded)]

After the collection has been created you can easily access it using the path db.example. The collection currently shows as loaded, meaning that it’s loaded into memory. If you restart the server and access the collection again it will now show as unloaded. You can also manually unload a collection.

arangosh> db.example.unload();
arangosh> db.example;

[ArangoCollection 447105153, "example" (type document, status unloaded)]

Whenever you use a collection ArangoDB will automatically load it into memory for you.

In order to create new documents in a collection use the save operation.

arangosh> db.example.save({ Hello : "World" });
arangosh> db.example.save({ "name" : "John Doe", "age" : 29 });
arangosh> db.example.save({ "name" : "Jane Smith", "age" : 31 });

{ 
  "_id" : "example/460998785", 
  "_rev" : "460998785", 
  "_key" : "460998785" 
}
{ 
  "_id" : "example/461392001", 
  "_rev" : "461392001", 
  "_key" : "461392001" 
}
{ 
  "_id" : "example/461588609", 
  "_rev" : "461588609", 
  "_key" : "461588609" 
}

Just storing documents would be no fun. We now want to select some of the stored documents again. In order to select all elements of a collection, one can use the toArray method:

arangosh> db.example.toArray()

[ 
  { 
    "Hello" : "World", 
    "_id" : "example/460998785", 
    "_rev" : "460998785", 
    "_key" : "460998785" 
  }, 
  { 
    "age" : 31, 
    "name" : "Jane Smith", 
    "_id" : "example/461588609", 
    "_rev" : "461588609", 
    "_key" : "461588609" 
  }, 
  { 
    "age" : 29, 
    "name" : "John Doe", 
    "_id" : "example/461392001", 
    "_rev" : "461392001", 
    "_key" : "461392001" 
  } 
]

Now we want to look for a person with a given name. We can use byExample for this. The method returns an array of documents matching a given example.

arangosh> db.example.byExample({ name: "Jane Smith" }).toArray()

[ 
  { 
    "_id" : "example/461588609", 
    "_key" : "461588609", 
    "_rev" : "461588609", 
    "age" : 31, 
    "name" : "Jane Smith" 
  } 
]

While the byExample works very well for simple queries where you combine the conditions with an and. The syntax above becomes messy for joins and or conditions. Therefore ArangoDB also supports a full-blown query language, AQL. To run an AQL query, use the db._query method:.

arangosh> db._query('FOR user IN example FILTER user.name == "Jane Smith" RETURN user').toArray()

[ 
  { 
    "age" : 31, 
    "name" : "Jane Smith", 
    "_id" : "example/461588609", 
    "_rev" : "461588609", 
    "_key" : "461588609" 
  } 
]

Searching for all persons with an age above 30:

arangosh> db._query('FOR user IN example FILTER user.age > 30 RETURN user').toArray()

[ 
  { 
    "age" : 31, 
    "name" : "Jane Smith", 
    "_id" : "example/461588609", 
    "_rev" : "461588609", 
    "_key" : "461588609" 
  } 
]

John was put in there by mistake – so let’s delete him again; We fetch the _id using byExample:

arangosh> db.example.remove(db.example.byExample({ name: "John Doe" }).toArray()[0]._id)
arangosh> db.example.toArray()

true
[ 
  { 
    "Hello" : "World", 
    "_id" : "example/460998785", 
    "_rev" : "460998785", 
    "_key" : "460998785" 
  }, 
  { 
    "age" : 31, 
    "name" : "Jane Smith", 
    "_id" : "example/461588609", 
    "_rev" : "461588609", 
    "_key" : "461588609" 
  } 
]

You can learn all about the query language Aql. Note that _query is a short-cut for _createStatement and execute. We will come back to these functions when we talk about cursors.

ArangoDB’s Front-End

The ArangoDB server has a graphical front-end, which allows you to inspect the current state of the server from within your browser. You can use the front-end using the following URL:

http://localhost:8529/

The front-end allows you to browse through the collections and documents. If you need to administrate the database, please use the ArangoDB shell described in the next section.