Document Keys

Users can define their own keys for documents they save. The document key willbe saved along with a document in the _key attribute. Users can pick keyvalues as required, provided that the values conform to the followingrestrictions:

  • The key must be a string value. Numeric keys are not allowed, but any numericvalue can be put into a string and can then be used as document key.
  • The key must be at least 1 byte and at most 254 bytes long. Empty keys are disallowed when specified (though it may be valid to completely omit the_key attribute from a document)
  • It must consist of the letters a-z (lower or upper case), the digits 0-9or any of the following punctuation characters:_ - : . @ ( ) + , = ; $ ! * ' %
  • Any other characters, especially multi-byte UTF-8 sequences, whitespace or punctuation characters cannot be used inside key values
  • The key must be unique within the collection it is used

Keys are case-sensitive, i.e. myKey and MyKEY are considered to bedifferent keys.

Specifying a document key is optional when creating new documents. If nodocument key is specified by the user, ArangoDB will create the document keyitself as each document is required to have a key.

There are no guarantees about the format and pattern of auto-generated documentkeys other than the above restrictions. Clients should therefore treatauto-generated document keys as opaque values and not rely on their format.

The current format for generated keys is a string containing numeric digits.The numeric values reflect chronological time in the sense that _key valuesgenerated later will contain higher numbers than _key values generated earlier.But the exact value that will be generated by the server is not predictable.Note that if you sort on the _key attribute, string comparison will be used,which means "100" is less than "99" etc.