!CHAPTER Document functions AQL supports the following functions to operate on document values: - *MATCHES(document, examples, return-index)*: Compares the document *document* against each example document provided in the array *examples*. If *document* matches one of the examples, *true* is returned, and if there is no match *false* will be returned. The default return value type can be changed by passing *true* as the third function parameter *return-index*. Setting this flag will return the index of the example that matched (starting at offset 0), or *-1* if there was no match. The comparisons will be started with the first example. All attributes of the example will be compared against the attributes of *document*. If all attributes match, the comparison stops and the result is returned. If there is a mismatch, the function will continue the comparison with the next example until there are no more examples left. The *examples* must be an array of 1..n example documents, with any number of attributes each. Note: specifying an empty array of examples is not allowed. @EXAMPLES MATCHES( { "test" : 1 }, [ { "test" : 1, "foo" : "bar" }, { "foo" : 1 }, { "test : 1 } ], true) This will return *2*, because the third example matches, and because the *return-index* flag is set to *true*. - *MERGE(document1, document2, ... documentn)*: Merges the documents in *document1* to *documentn* into a single document. If document attribute keys are ambiguous, the merged result will contain the values of the documents contained later in the argument list. For example, two documents with distinct attribute names can easily be merged into one: /* { "user1" : { "name" : "J" }, "user2" : { "name" : "T" } } */ MERGE( { "user1" : { "name" : "J" } }, { "user2" : { "name" : "T" } } ) When merging documents with identical attribute names, the attribute values of the latter documents will be used in the end result: /* { "users" : { "name" : "T" } } */ MERGE( { "users" : { "name" : "J" } }, { "users" : { "name" : "T" } } ) Please note that merging will only be done for top-level attributes. If you wish to merge sub-attributes, you should consider using *MERGE_RECURSIVE* instead. - *MERGE_RECURSIVE(document1, document2, ... documentn)*: Recursively merges the documents in *document1* to *documentn* into a single document. If document attribute keys are ambiguous, the merged result will contain the values of the documents contained later in the argument list. For example, two documents with distinct attribute names can easily be merged into one: /* { "user-1" : { "name" : "J", "livesIn" : { "city" : "LA", "state" : "CA" }, "age" : 42 } } */ MERGE_RECURSIVE( { "user-1" : { "name" : "J", "livesIn" : { "city" : "LA" } } }, { "user-1" : { "age" : 42, "livesIn" : { "state" : "CA" } } } ) - *TRANSLATE(value, lookup, defaultValue)*: Looks up the value *value* in the *lookup* document. If *value* is a key in *lookup*, then *value* will be replaced with the lookup value found. If *value* is not present in *lookup*, then *defaultValue* will be returned if specified. If no *defaultValue* is specified, *value* will be returned: /* "France" */ TRANSLATE("FR", { US: "United States", UK: "United Kingdom", FR: "France" }) /* "not found!" */ TRANSLATE(42, { foo: "bar", bar: "baz" }, "not found!") - *HAS(document, attributename)*: Returns *true* if *document* has an attribute named *attributename*, and *false* otherwise. - *ATTRIBUTES(document, removeInternal, sort)*: Returns the attribute names of the *document* as an array. If *removeInternal* is set to *true*, then all internal attributes (such as *_id*, *_key* etc.) are removed from the result. If *sort* is set to *true*, then the attribute names in the result will be sorted. Otherwise they will be returned in any order. - *VALUES(document, removeInternal)*: Returns the attribute values of the *document* as an array. If *removeInternal* is set to *true*, then all internal attributes (such as *_id*, *_key* etc.) are removed from the result. - *ZIP(attributes, values)*: Returns a document object assembled from the separate parameters *attributes* and *values*. *attributes* and *values* must be arrays and must have the same length. The items in *attributes* will be used for naming the attributes in the result. The items in *values* will be used as the actual values of the result. /* { "name" : "some user", "active" : true, "hobbies" : [ "swimming", "riding" ] } */ ZIP([ 'name', 'active', 'hobbies' ], [ 'some user', true, [ 'swimming', 'riding' ] ]) - *UNSET(document, attributename, ...)*: Removes the attributes *attributename* (can be one or many) from *document*. All other attributes will be preserved. Multiple attribute names can be specified by either passing multiple individual string argument names, or by passing an array of attribute names: UNSET(doc, '_id', '_key', [ 'foo', 'bar' ]) UNSET(doc, [ '_id', '_key', 'foo', 'bar' ]) - *KEEP(document, attributename, ...)*: Keeps only the attributes *attributename* (can be one or many) from *document*. All other attributes will be removed from the result. Multiple attribute names can be specified by either passing multiple individual string argument names, or by passing an array of attribute names: KEEP(doc, 'firstname', 'name', 'likes') KEEP(doc, [ 'firstname', 'name', 'likes' ]) - *PARSE_IDENTIFIER(document-handle)*: Parses the [document handle](../Glossary/index.html#document_handle) specified in *document-handle* and returns a the handle's individual parts a separate attributes. This function can be used to easily determine the [collection name](../Glossary/index.html#collection_name) and key from a given document. The *document-handle* can either be a regular document from a collection, or a document identifier string (e.g. *_users/1234*). Passing either a non-string or a non-document or a document without an *_id* attribute will result in an error. /* { "collection" : "_users", "key" : "my-user" } */ PARSE_IDENTIFIER('_users/my-user') /* { "collection" : "mycollection", "key" : "mykey" } */ PARSE_IDENTIFIER({ "_id" : "mycollection/mykey", "value" : "some value" })