Add PARSE_KEY() and PARSE_COLLECTION() functions (#386)

* Add PARSE_KEY() and PARSE_COLLECTION() functions

* [skip ci] Automatic commit of generated files from CircleCI

---------

Co-authored-by: CircleCI <[email protected]>
Co-authored-by: CircleCI Job <[email protected]>

Author: 3 people

site/content/3.12/aql/functions/document-object.md

@@ -632,24 +632,56 @@ RETURN MERGE_RECURSIVE(
 )
 ```
 
-## PARSE_IDENTIFIER()
+## PARSE_COLLECTION()
 
-`PARSE_IDENTIFIER(documentIdentifier) → parts`
+`PARSE_COLLECTION(documentIdentifier) → collectionName`
 
 Parse a [document ID](../../concepts/data-structure/documents/_index.md#document-identifiers) and
-return its individual parts as separate attributes.
+return the collection name.
+
+- **documentIdentifier** (string\|object): a document identifier string (e.g. `_users/1234`)
+  or a regular document from a collection. Passing either a non-string or a non-document
+  or a document without an `_id` attribute results in an error.
+- returns **collectionName** (string): the name of the collection
+
+**Examples**
+
+Parse a document identifier string and extract the collection name:
+
+```aql
+---
+name: aqlParseCollection_1
+description: ''
+---
+RETURN PARSE_COLLECTION("_users/my-user")
+```
+
+Parse the `_id` attribute of a document to extract the collection name:
+
+```aql
+---
+name: aqlParseCollection_2
+description: ''
+---
+RETURN PARSE_COLLECTION( { "_id": "mycollection/mykey", "value": "some value" } )
+```
+
+## PARSE_IDENTIFIER()
+
+`PARSE_IDENTIFIER(documentIdentifier) → parts`
 
-This function can be used to easily determine the
-[collection name](../../concepts/data-structure/collections.md#collection-names) and key of a given document.
+Parse a [document ID](../../concepts/data-structure/documents/_index.md#document-identifiers)
+and separately return the collection name and the document key.
 
 - **documentIdentifier** (string\|object): a document identifier string (e.g. `_users/1234`)
   or a regular document from a collection. Passing either a non-string or a non-document
-  or a document without an `_id` attribute will result in an error.
-- returns **parts** (object): an object with the attributes *collection* and *key*
+  or a document without an `_id` attribute results in an error.
+- returns **parts** (object): an object with the attributes `collection` and `key`
 
 **Examples**
 
-Parse a document identifier string:
+Parse a document identifier string and extract both the collection name and the
+document key:
 
 ```aql
 ---
@@ -659,7 +691,8 @@ description: ''
 RETURN PARSE_IDENTIFIER("_users/my-user")
 ```
 
-Parse the document identifier string of a document (`_id` attribute):
+Parse the `_id` attribute of a document to extract both the collection name and
+the document key:
 
 ```aql
 ---
@@ -669,6 +702,40 @@ description: ''
 RETURN PARSE_IDENTIFIER( { "_id": "mycollection/mykey", "value": "some value" } )
 ```
 
+## PARSE_KEY()
+
+`PARSE_KEY(documentIdentifier) → key`
+
+Parse a [document ID](../../concepts/data-structure/documents/_index.md#document-identifiers) and
+return the document key.
+
+- **documentIdentifier** (string\|object): a document identifier string (e.g. `_users/1234`)
+  or a regular document from a collection. Passing either a non-string or a non-document
+  or a document without an `_id` attribute results in an error.
+- returns **key** (string): the document key
+
+**Examples**
+
+Parse a document identifier string and extract the document key:
+
+```aql
+---
+name: aqlParseKey_1
+description: ''
+---
+RETURN PARSE_KEY("_users/my-user")
+```
+
+Parse the `_id` attribute of a document to extract the document key:
+
+```aql
+---
+name: aqlParseKey_2
+description: ''
+---
+RETURN PARSE_KEY( { "_id": "mycollection/mykey", "value": "some value" } )
+```
+
 ## TRANSLATE()
 
 `TRANSLATE(value, lookupDocument, defaultValue) → mappedValue`

site/content/3.12/aql/functions/string.md

@@ -1429,7 +1429,9 @@ Split the given string `value` into a list of strings, using the `separator`.
 
 To split a document identifier (`_id`) into the collection name and document key
 (`_key`), you should use the more optimized
-[`PARSE_IDENTIFIER()` function](document-object.md#parse_identifier).
+[`PARSE_IDENTIFIER()` function](document-object.md#parse_identifier), respectively
+[`PARSE_COLLECTION()`](document-object.md#parse_collection) or
+[`PARSE_KEY()`](document-object.md#parse_key) to only extract the name or key.
 
 - **value** (string): a string
 - **separator** (string): either a string or a list of strings. If `separator` is

site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md

@@ -174,6 +174,14 @@ UPDATE { logins: OLD.logins + 1 } IN users
 
 Read more about [`UPSERT` operations](../../aql/high-level-operations/upsert.md) in AQL.
 
+### Added AQL functions
+
+The new `PARSE_COLLECTION()` and `PARSE_KEY()` let you more extract the
+collection name respectively the document key from a document identifier with
+less overhead.
+
+See [Document and object functions in AQL](../../aql/functions/document-object.md#parse_collection).
+
 ## Indexing
 
 ### Stored values can contain the `_id` attribute