DOC-614 | Versioning support for document operations

site/content/3.12/about-arangodb/features/highlights-by-version.md

@@ -17,6 +17,10 @@ aliases:
   Accelerate wildcard searches against Views and inverted indexes with _n_-grams
   to quickly find candidate matches.
 
+- [**External versioning**](../../release-notes/version-3.12/whats-new-in-3-12.md#external-versioning-support):
+  Specify any top-level attribute to compare whether the version number is higher
+  than the currently stored one when updating or replacing documents.
+
 **Enterprise Edition**
 
 - [**ArangoSearch WAND optimization**](../../index-and-search/arangosearch/performance.md#wand-optimization):

site/content/3.12/aql/high-level-operations/insert.md

@@ -175,6 +175,39 @@ INSERT { _from: "vert/A", _to: "vert/B" } INTO coll
   OPTIONS { refillIndexCaches: true }
 ```
 
+### `versionAttribute`
+
+Only applicable if `overwrite` is set to `true` or `overwriteMode`
+is set to `update` or `replace`.
+
+You can use the `versionAttribute` option for external versioning support.
+If set, the attribute with the name specified by the option is looked up in the
+stored document and the attribute value is compared numerically to the value of
+the versioning attribute in the supplied document that is supposed to update/replace it.
+
+If the version number in the new document is higher (rounded down to a whole number)
+than in the document that already exists in the database, then the update/replace
+operation is performed normally. This is also the case if the new versioning
+attribute has a non-numeric value, if it is a negative number, or if the
+attribute doesn't exist in the supplied or stored document.
+
+If the version number in the new document is lower or equal to what exists in
+the database, the operation is not performed and the existing document thus not
+changed. No error is returned in this case.
+
+The attribute can only be a top-level attribute.
+
+For example, the following query conditionally replaces an existing document with
+the key `"123"` if the attribute `externalVersion` currently has a value below `5`:
+
+```aql
+INSERT { _key: "123", externalVersion: 5, anotherAttribute: true } IN coll
+  OPTIONS { overwriteMode: "replace", versionAttribute: "externalVersion" }
+```
+
+You can check if `OLD._rev` (if not `null`) and `NEW._rev` are different to determine if the
+document has been changed.
+
 ## Returning the inserted documents
 
 The inserted documents can also be returned by the query. In this case, the `INSERT` 

site/content/3.12/aql/high-level-operations/replace.md

@@ -252,6 +252,36 @@ REPLACE { _key: "123", _from: "vert/C", _to: "vert/D" } IN edgeColl
   OPTIONS { refillIndexCaches: true }
 ```
 
+### `versionAttribute`
+
+You can use the `versionAttribute` option for external versioning support.
+If set, the attribute with the name specified by the option is looked up in the
+stored document and the attribute value is compared numerically to the value of
+the versioning attribute in the supplied document that is supposed to replace it.
+
+If the version number in the new document is higher (rounded down to a whole number)
+than in the document that already exists in the database, then the replace
+operation is performed normally. This is also the case if the new versioning
+attribute has a non-numeric value, if it is a negative number, or if the
+attribute doesn't exist in the supplied or stored document.
+
+If the version number in the new document is lower or equal to what exists in
+the database, the operation is not performed and the existing document thus not
+changed. No error is returned in this case.
+
+The attribute can only be a top-level attribute.
+
+For example, the following query conditionally replaces an existing document with
+the key `"123"` if the attribute `externalVersion` currently has a value below `5`:
+
+```aql
+REPLACE { _key: "123", externalVersion: 5, anotherAttribute: true } IN coll
+  OPTIONS { versionAttribute: "externalVersion" }
+```
+
+You can check if `OLD._rev` and `NEW._rev` are different to determine if the
+document has been changed.
+
 ## Returning the modified documents
 
 You can optionally return the documents modified by the query. In this case, the `REPLACE` 

site/content/3.12/aql/high-level-operations/update.md

@@ -368,6 +368,36 @@ UPDATE { _key: "123", _from: "vert/C", _to: "vert/D" } IN edgeColl
   OPTIONS { refillIndexCaches: true }
 ```
 
+### `versionAttribute`
+
+You can use the `versionAttribute` option for external versioning support.
+If set, the attribute with the name specified by the option is looked up in the
+stored document and the attribute value is compared numerically to the value of
+the versioning attribute in the supplied document that is supposed to update it.
+
+If the version number in the new document is higher (rounded down to a whole number)
+than in the document that already exists in the database, then the update
+operation is performed normally. This is also the case if the new versioning
+attribute has a non-numeric value, if it is a negative number, or if the
+attribute doesn't exist in the supplied or stored document.
+
+If the version number in the new document is lower or equal to what exists in
+the database, the operation is not performed and the existing document thus not
+changed. No error is returned in this case.
+
+The attribute can only be a top-level attribute.
+
+For example, the following query conditionally updates an existing document with
+the key `"123"` if the attribute `externalVersion` currently has a value below `5`:
+
+```aql
+UPDATE { _key: "123", externalVersion: 5, anotherAttribute: true } IN coll
+  OPTIONS { versionAttribute: "externalVersion" }
+```
+
+You can check if `OLD._rev` and `NEW._rev` are different to determine if the
+document has been changed.
+
 ## Returning the modified documents
 
 You can optionally return the documents modified by the query. In this case, the `UPDATE` 

site/content/3.12/develop/http-api/documents.md

@@ -476,6 +476,34 @@ paths:
             affect the edge index or cache-enabled persistent indexes.
           schema:
             type: boolean
+        - name: versionAttribute
+          in: query
+          required: false
+          description: |
+            Only applicable if `overwrite` is set to `true` or `overwriteMode`
+            is set to `update` or `replace`.
+
+            You can use the `versionAttribute` option for external versioning support.
+            If set, the attribute with the name specified by the option is looked up in the
+            stored document and the attribute value is compared numerically to the value of
+            the versioning attribute in the supplied document that is supposed to update/replace it.
+
+            If the version number in the new document is higher (rounded down to a whole number)
+            than in the document that already exists in the database, then the update/replace
+            operation is performed normally. This is also the case if the new versioning
+            attribute has a non-numeric value, if it is a negative number, or if the
+            attribute doesn't exist in the supplied or stored document.
+
+            If the version number in the new document is lower or equal to what exists in
+            the database, the operation is not performed and the existing document thus not
+            changed. No error is returned in this case.
+
+            The attribute can only be a top-level attribute.
+
+            You can check if `_oldRev` (if present) and `_rev` are different to determine if the
+            document has been changed.
+          schema:
+            type: string
         - name: x-arango-trx-id
           in: header
           required: false
@@ -856,6 +884,31 @@ paths:
             replacements affect the edge index or cache-enabled persistent indexes.
           schema:
             type: boolean
+        - name: versionAttribute
+          in: query
+          required: false
+          description: |
+            You can use the `versionAttribute` option for external versioning support.
+            If set, the attribute with the name specified by the option is looked up in the
+            stored document and the attribute value is compared numerically to the value of
+            the versioning attribute in the supplied document that is supposed to replace it.
+
+            If the version number in the new document is higher (rounded down to a whole number)
+            than in the document that already exists in the database, then the replace
+            operation is performed normally. This is also the case if the new versioning
+            attribute has a non-numeric value, if it is a negative number, or if the
+            attribute doesn't exist in the supplied or stored document.
+
+            If the version number in the new document is lower or equal to what exists in
+            the database, the operation is not performed and the existing document thus not
+            changed. No error is returned in this case.
+
+            The attribute can only be a top-level attribute.
+
+            You can check if `_oldRev` and `_rev` are different to determine if the
+            document has been changed.
+          schema:
+            type: string
         - name: If-Match
           in: header
           required: false
@@ -1178,6 +1231,31 @@ paths:
             affect the edge index or cache-enabled persistent indexes.
           schema:
             type: boolean
+        - name: versionAttribute
+          in: query
+          required: false
+          description: |
+            You can use the `versionAttribute` option for external versioning support.
+            If set, the attribute with the name specified by the option is looked up in the
+            stored document and the attribute value is compared numerically to the value of
+            the versioning attribute in the supplied document that is supposed to update it.
+
+            If the version number in the new document is higher (rounded down to a whole number)
+            than in the document that already exists in the database, then the update
+            operation is performed normally. This is also the case if the new versioning
+            attribute has a non-numeric value, if it is a negative number, or if the
+            attribute doesn't exist in the supplied or stored document.
+
+            If the version number in the new document is lower or equal to what exists in
+            the database, the operation is not performed and the existing document thus not
+            changed. No error is returned in this case.
+
+            The attribute can only be a top-level attribute.
+
+            You can check if `_oldRev` and `_rev` are different to determine if the
+            document has been changed.
+          schema:
+            type: string
         - name: If-Match
           in: header
           required: false
@@ -1875,6 +1953,34 @@ paths:
             affect the edge index or cache-enabled persistent indexes.
           schema:
             type: boolean
+        - name: versionAttribute
+          in: query
+          required: false
+          description: |
+            Only applicable if `overwrite` is set to `true` or `overwriteMode`
+            is set to `update` or `replace`.
+
+            You can use the `versionAttribute` option for external versioning support.
+            If set, the attribute with the name specified by the option is looked up in the
+            stored document and the attribute value is compared numerically to the value of
+            the versioning attribute in the supplied document that is supposed to update/replace it.
+
+            If the version number in the new document is higher (rounded down to a whole number)
+            than in the document that already exists in the database, then the update/replace
+            operation is performed normally. This is also the case if the new versioning
+            attribute has a non-numeric value, if it is a negative number, or if the
+            attribute doesn't exist in the supplied or stored document.
+
+            If the version number in the new document is lower or equal to what exists in
+            the database, the operation is not performed and the existing document thus not
+            changed. No error is returned in this case.
+
+            The attribute can only be a top-level attribute.
+
+            You can check if `_oldRev` (if present) and `_rev` are different to determine if the
+            document has been changed.
+          schema:
+            type: string
         - name: x-arango-trx-id
           in: header
           required: false
@@ -2146,6 +2252,31 @@ paths:
             replacements affect the edge index or cache-enabled persistent indexes.
           schema:
             type: boolean
+        - name: versionAttribute
+          in: query
+          required: false
+          description: |
+            You can use the `versionAttribute` option for external versioning support.
+            If set, the attribute with the name specified by the option is looked up in the
+            stored document and the attribute value is compared numerically to the value of
+            the versioning attribute in the supplied document that is supposed to replace it.
+
+            If the version number in the new document is higher (rounded down to a whole number)
+            than in the document that already exists in the database, then the replace
+            operation is performed normally. This is also the case if the new versioning
+            attribute has a non-numeric value, if it is a negative number, or if the
+            attribute doesn't exist in the supplied or stored document.
+
+            If the version number in the new document is lower or equal to what exists in
+            the database, the operation is not performed and the existing document thus not
+            changed. No error is returned in this case.
+
+            The attribute can only be a top-level attribute.
+
+            You can check if `_oldRev` and `_rev` are different to determine if the
+            document has been changed.
+          schema:
+            type: string
         - name: x-arango-trx-id
           in: header
           required: false
@@ -2368,6 +2499,31 @@ paths:
             affect the edge index or cache-enabled persistent indexes.
           schema:
             type: boolean
+        - name: versionAttribute
+          in: query
+          required: false
+          description: |
+            You can use the `versionAttribute` option for external versioning support.
+            If set, the attribute with the name specified by the option is looked up in the
+            stored document and the attribute value is compared numerically to the value of
+            the versioning attribute in the supplied document that is supposed to update it.
+
+            If the version number in the new document is higher (rounded down to a whole number)
+            than in the document that already exists in the database, then the update
+            operation is performed normally. This is also the case if the new versioning
+            attribute has a non-numeric value, if it is a negative number, or if the
+            attribute doesn't exist in the supplied or stored document.
+
+            If the version number in the new document is lower or equal to what exists in
+            the database, the operation is not performed and the existing document thus not
+            changed. No error is returned in this case.
+
+            The attribute can only be a top-level attribute.
+
+            You can check if `_oldRev` and `_rev` are different to determine if the
+            document has been changed.
+          schema:
+            type: string
         - name: x-arango-trx-id
           in: header
           required: false