mirror of https://gitee.com/bigwinds/arangodb
134 lines
5.7 KiB
Plaintext
134 lines
5.7 KiB
Plaintext
!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 list *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 a list of 1..n example documents, with any number of attributes
|
|
each. Note: specifying an empty list of examples is not allowed.
|
|
|
|
@EXAMPLES
|
|
|
|
RETURN 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:
|
|
|
|
RETURN MERGE(
|
|
{ "user1" : { "name" : "J" } },
|
|
{ "user2" : { "name" : "T" } }
|
|
)
|
|
|
|
[
|
|
{ "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:
|
|
|
|
RETURN MERGE(
|
|
{ "users" : { "name" : "J" } },
|
|
{ "users" : { "name" : "T" } }
|
|
)
|
|
|
|
[
|
|
{ "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:
|
|
|
|
RETURN MERGE_RECURSIVE(
|
|
{ "user-1" : { "name" : "J", "livesIn" : { "city" : "LA" } } },
|
|
{ "user-1" : { "age" : 42, "livesIn" : { "state" : "CA" } } }
|
|
)
|
|
|
|
[
|
|
{ "user-1" : { "name" : "J", "livesIn" : { "city" : "LA", "state" : "CA" }, "age" : 42 } }
|
|
]
|
|
|
|
- *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:
|
|
|
|
RETURN TRANSLATE("FR", { US: "United States", UK: "United Kingdom", FR: "France" })
|
|
|
|
"France"
|
|
|
|
RETURN TRANSLATE(42, { foo: "bar", bar: "baz" }, "not found!")
|
|
|
|
"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 *document as a list.
|
|
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.
|
|
|
|
- *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 a list of attribute names:
|
|
|
|
RETURN 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 a list of attribute names:
|
|
|
|
RETURN KEEP(doc, 'firstname', 'name', 'likes')
|
|
|
|
- *PARSE_IDENTIFIER(document-handle)*: Parses the [document handle](../Glossary/README.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/README.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.
|
|
|
|
RETURN PARSE_IDENTIFIER('_users/my-user')
|
|
|
|
[
|
|
{ "collection" : "_users", "key" : "my-user" }
|
|
]
|
|
|
|
RETURN PARSE_IDENTIFIER({ "_id" : "mycollection/mykey", "value" : "some value" })
|
|
|
|
[
|
|
{ "collection" : "mycollection", "key" : "mykey" }
|
|
] |