ArangoDB 1.2: Simplifications Overview | ArangoDB 2013

The upcoming 1.2 version of ArangoDB will provide several improvements and fixes.
Apart from the additional features the new version provides, the following changes might also be very interesting for users and driver maintainers:

User-defined keys

ArangoDB 1.2 allows users to determine their own document keys to uniquely identify documents.
In previous versions of ArangoDB, each document automatically got an “_id” value determined by the server. The document id part of this “_id” value was an ever-increasing integer number that users could not change or preselect, and that was hard to memoize.

ArangoDB 1.2 now allows specifying own id values by providing a “_key” attribute when creating documents. The value specified in “_key” will automatically become part of a document’s “_id” value.

Creating a document with a user-defined key is simple. The “_key” value will automatically become a document meta-attribute, that is returned for every document:

arangod> db.mycollection.save({ 
  _key: "mytest", 
  someValue: 1 
});

{
  "_id" : "mycollection/mytest",           
  "_rev" : "317015507519",                         
  "_key" : "mytest"            
}

The “_key” attribute can also be used to easily address and access documents later:

arangod> db.mycollection.document("mytest");

{ 
  "_key" : "mytest", 
  "_id" : "mycollection/mytest", 
  "_rev" : "316961300786" 
}

arangod> db.mycollection.update("mytest", { 
  someValue: 2 
}); 

{ 
  "_id" : "mycollection/mytest", 
  "_rev" : "317015704127", 
  "_oldRev" : "317015507519", 
  "_key" : "mytest" 
}

arangod> db.mycollection.remove("mytest");
true

Note: if no value is specified for “_key”, then the server will generate a “_key” value itself. So there is no need to use user-defined keys immediately, though it will eventually make sense to use them.

Usage of collection names

ArangoDB 1.1 and earlier versions required the user to use collection ids instead of collection names in several places. The collection ids were unique integers generated by the server.

To make ArangoDB easier to use, ArangoDB 1.2 allows the usage of collection names instead of collection ids.

This is especially handy when using referencing vertexes in an edge collection, e.g.

arangod> db.myvertexcollection.save({ 
  _key: "vertex1", 
  someValue: 1 
});

{ 
  "_id" : "myvertexcollection/vertex1", 
  "_rev" : "317019177535", 
  "_key" : "vertex1" 
}

arangod> db.myvertexcollection.save({ 
  _key: "vertex2", 
  someValue: 2 
});

{ 
  "_id" : "myvertexcollection/vertex2", 
  "_rev" : "317019243071", 
  "_key" : "vertex2" 
}

arangod> db.myedgecollection.save(
  "myvertexcollection/vertex1", 
  "myvertexcollection/vertex2", { 
    someEdgeValue: "..." 
  });

{ 
  "_id" : "myedgecollection/317019439679", 
  "_rev" : "317019439679", 
  "_key" : "317019439679" 
}

It also makes composing AQL statements much easier than filter on specific documents:

arangod> stmt = db._createStatement({ 
  query: "FOR e IN myedgecollection 
          FILTER e._from == 'myvertexcollection/vertex1' 
          RETURN e" 
}); 
cursor = stmt.execute().toArray(); 

[ 
  { 
    "_id" : "myedgecollection/317019439679", 
    "_rev" : "317019439679", 
    "_key" : "317019439679", 
    "_from" : "myvertexcollection/vertex1", 
    "_to" : "myvertexcollection/vertex2", 
    "someEdgeValue" : "..." 
  } 
]

Overall, these two changes should make using ArangoDB much more intuitive and easier than before.

Using user-defined deys and collection names instead of the server-generated ids might also save a few roundtrips that were necessary in previous versions to look up collection and document ids.