ArangoDB

Handling Collections

This is an introduction to ArangoDB's interface for collections and how handle collections from the JavaScript shell arangosh. For other languages see the corresponding language API.

The most import call is the call to create a new collection, see _create.

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.

Address of a Collection

All collections in ArangoDB have an unique identifier. This collection identifier identifies a collection and is managed by ArangoDB. Each collection, in addition, has a unique name. This name is managed by the user. The interface allows you to access the collections as:

db._collection(collection-identifier)

or

db._collection(collection-name)

A collection is created by a db._create call, see _create.

For example: Assume that the collection identifier is 7254820 and the name is demo, then the collection can be accessed as:

db._collection("demo")

or

db._collection(7254820)

If no collection with such a name or identifier exists, then null is returned.

There is a short-cut

db.collection-name

This call will either return the collection named collection-name or create a new one with that name and a set of default properties.

Working with Collections

Collection Methods

collection.drop()
Drops a collection and all its indexes.

Examples

Drops a collection:

arango> col = db.examples;
[ArangoCollection 109757, "examples" (status unloaded)]
arango> col.drop()
arango> col;
[ArangoCollection 109757, "examples" (status deleted)]

collection.truncate()
Truncates a collection, removing all documents but keeping all its indexes.

Examples

Truncates a collection:

arango> col = db.examples;
[ArangoCollection 91022, "examples" (status new born)]
arango> col.save({ "Hallo" : "World" });
{ "_id" : "91022/1532814", "_rev" : 1532814 }
arango> col.count();
1
arango> col.truncate();
arango> col.count();
0

collection.properties()
Returns an object containing all collection properties.

  • waitForSync: If true creating a document will only return after the data was synced to disk.
  • journalSize : The size of the journal in bytes.
collection.properties(properties)
Changes the collection properties. properties must be a object with one or more of the following attribute(s):

  • waitForSync: If true creating a document will only return after the data was synced to disk.
  • journalSize : The size of the journal in bytes.

Note that it is not possible to change the journal size after the journal or datafile has been created. Changing this parameter will only effect newly created journals. Also note that you cannot lower the journal size to less then size of the largest document already stored in the collection.

Examples

Read all properties

arango> db.examples.properties()
{ "waitForSync" : false, "journalSize" : 33554432 }

Change a property

arango> db.examples.properties({ waitForSync : false })
{ "waitForSync" : false, "journalSize" : 33554432 }

collection.figures()
Returns an object containing all collection figures.

  • alive.count: The number of living documents.
  • alive.size: The total size in bytes used by all living documents.
  • dead.count: The number of dead documents.
  • dead.size: The total size in bytes used by all dead documents.
  • dead.deletion: The total number of deletion markers.
  • datafiles.count: The number of active datafiles.
  • datafiles.fileSize: The total filesize of the active datafiles.
  • journals.count: The number of journal files.
  • journals.fileSize: The total filesize of the journal files.

Examples

arango> db.demo.figures()
{ "numberDatafiles" : 1, "numberAlive" : 1, "numberDead" : 1, "sizeAlive" : 24, "sizeDead" : 24, "numberDeletion" : 1 }

collection.load()
Loads a collection into memory.

Examples

arango> col = db.example;
[ArangoCollection 164208316, "example" (status unloading)]
arango> col.load();
arango> col;
[ArangoCollection 164208316, "example" (status loaded)]

collection.unload()
Starts unloading a collection from memory. Note that unloading is deferred until all query have finished.

Examples

arango> col = db.example;
[ArangoCollection 164208316, "example" (status loaded)]
arango> col.unload();
arango> col;
[ArangoCollection 164208316, "example" (status unloaded)]

collection.rename(new-name)
Renames a collection using the new-name. The new-name must not already be used for a different collection. If it is an error is thrown.

Examples

arango> c = db.example;
[ArangoCollection 68519, "example" (status new born)]
arango> c.rename("better-example");
arango> c;
[ArangoCollection 68519, "better-example" (status new born)]

Database Methods

db._collection(collection-identifier)
Returns the collection with the given identifier or null if no such collection exists.

db._collection(collection-name)
Returns the collection with the given name or null if no such collection exists.

Examples

Get a collection by name:

arango> db._collection("demo");
[ArangoCollection 145387, "demo" (status loaded)]

Get a collection by id:

arango> db._collection(145387);
[ArangoCollection 145387, "demo" (status loaded)]

Unknown collection:

arango> db._collection("unknown")
null

db._create(collection-name)
Creates a new document collection named collection-name. If the collection name already exists, then an error is thrown. The default value for waitForSync is false.

db._create(collection-name, properties)
properties must be an object, with the following attribues:

  • waitForSync (optional, default false): If true creating a document will only return after the data was synced to disk.
  • 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.

Examples

With defaults:

arango> c = db._create("cars");
[ArangoCollection 111137, "cars" (status loaded)]
arango> c.properties()
{ "waitForSync" : false, "journalSize" : 33554432 }

With properties:

arango> c = db._create("cars", { waitForSync : true, journalSize : 1024 * 1204 });
[ArangoCollection 96384, "cars" (status loaded)]
arango> c.properties()
{ "waitForSync" : true, "journalSize" : 1232896 }

db._collections()
Returns all collections of the given database.

Examples

arango> db.examples.load();
arango> var d = db.demo;
arango> db._collections();
[[ArangoCollection 96393, "examples" (status loaded)], [ArangoCollection 1407113, "demo" (status new born)]]

db.collection-name
Returns the collection with the given collection-name. If no such collection exists, create a collection named collection-name with the default properties.

Examples

arango> db.examples;
[ArangoCollection 110371, "examples" (status new born)]

db._drop(collection)
Drops a collection and all its indexes.

db._drop(collection-identifier)
Drops a collection identified by collection-identifier and all its indexes. No error is thrown if there is no such collection.

db._drop(collection-name)
Drops a collection named collection-name and all its indexes. No error is thrown if there is no such collection.

Examples

Drops a collection:

arango> col = db.examples;
[ArangoCollection 109757, "examples" (status unloaded)]
arango> db._drop(col)
arango> col;
[ArangoCollection 109757, "examples" (status deleted)]

Drops a collection identified by name:

arango> col = db.examples;
[ArangoCollection 85198, "examples" (status new born)]
arango> db._drop("examples");
arango> col;
[ArangoCollection 85198, "examples" (status deleted)]

db._truncate(collection)
Truncates a collection, removing all documents but keeping all its indexes.

db._truncate(collection-identifier)
Truncates a collection identified by collection-identified. No error is thrown if there is no such collection.

db._truncate(collection-name)
Truncates a collection named collection-name. No error is thrown if there is no such collection.

Examples

Truncates a collection:

arango> col = db.examples;
[ArangoCollection 91022, "examples" (status new born)]
arango> col.save({ "Hallo" : "World" });
{ "_id" : "91022/1532814", "_rev" : 1532814 }
arango> col.count();
1
arango> db._truncate(col);
arango> col.count();
0

Truncates a collection identified by name:

arango> col = db.examples;
[ArangoCollection 91022, "examples" (status new born)]
arango> col.save({ "Hallo" : "World" });
{ "_id" : "91022/1532814", "_rev" : 1532814 }
arango> col.count();
1
arango> db._truncate("examples");
arango> col.count();
0