ArangoDB 2013: Simplify Database Management with Auto-Increment

The most recent versions of ArangoDB offer more detailed control over what values will be auto-generated for the _key and _id attributes of documents. They also allow using predictable auto-increment sequences.

ArangoDB 1.1 and before always auto-generated the values for the _id attribute of documents, and since ArangoDB 1.2 there was the possibility to provide user-defined document keys in the _key attribute.

ArangoDB 1.2.2 extends this a bit more: each collection now has a set of so-called “key options”, which control if and how document keys are generated, and if users are allowed to provide their own _key values.

“Traditional” key generator

When no “key options” are specified on collection creation, ArangoDB will use the “traditional” key generator by default.

This key generator will work in the same ways as ArangoDB 1.2 previously did. Each collection will happily accept user-defined _key values. If the user doesn’t specify any _key value, the server will auto-generate the value. The auto-generated _key values will be ever-increasing numbers, with a non-deterministic increment:

arangosh> db._create("users");
arangosh> db.users.save({ name: "John" });
{ "_id" : "users/1533108862550", "_key" : "1533108862550", ... }
arangosh> db.users.save({ name: "Jane" }); 
{ "_id" : "users/1533108993622", "_key" : "1533108993622", ... }

“Autoincrement” key generator

To get better control over the generated _key values, there is the “autoincrement” key generator. This key generator will generate much “nicer” and predictable keys. It can activated as follows when a collection is created:

arangosh> db._create("users", { 
  keyOptions: { 
    type: "autoincrement" 
  } 
});

arangosh> db.users.save({ name: "John" });
{ "_id" : "users/1", "_key" : "1", ... }
arangosh> db.users.save({ name: "Jane" });
{ "_id" : "users/2", "_key" : "2", ... }

The start value and the actual increment values for the sequence can optionally be adjusted when the collection is first created:

arangosh> db._create("users", { 
  keyOptions: { 
    type: "autoincrement", 
    offset: 5, 
    increment: 12 
  } 
});

arangosh> db.users.save({ name: "John" });
{ "_id" : "users/5", "_key" : "5", ... }
arangosh> db.users.save({ name: "Jane" });
{ "_id" : "users/17", "_key" : "17", ... }

Auto-generated and user-specified keys can also be mixed. We’ll now create a document using our own key, and after that create a document and let the server generate the next _key value:

arangosh> db.users.save({ name: "James", _key: "18" });
{ "_id" : "users/18", "_key" : "18", ... }
arangosh> db.users.save({ name: "Jack" });
{ "_id" : "users/29", "_key" : "29", ... }

Note that the auto-generated _key value of “29” is in line with the auto-increment rules initially specified (offset 5, increment 12).

Disallowing user-defined keys

In some cases it may make sense to give the server the sole responsibility for generating the _key values, and to disallow user-supplied keys completely. This is supported in ArangoDB by creating a collection and setting the “allowUserKeys” attribute to false. Whenever there is an attempt then to insert a document with a user-defined key, the server will reject it:

arangosh> db._create("users", { 
  keyOptions: { 
    type: "autoincrement", 
    allowUserKeys: false 
  } 
});

arangosh> db.users.save({ name: "Jack" });
{ "_id" : "users/1", "_key" : "1", ... }
arangosh> db.users.save({ name: "James", _key: "18" });
JavaScript exception in file '/org/arangodb/arangosh' at 104,11: 
[ArangoError 1222: collection does not allow using user-defined keys]
!    throw new ArangoError(requestResult)

As noted above, the feature has been made available in recent versions of ArangoDB 1.2, and is thus contained in the ArangoDB 1.2.2 builds, which are available for download here. Enjoy!