Skip to content

Commit 1920efe

Browse files
nerpaulaSimran-B
nerpaula
and
Simran-B
authored
DOC-614 | Versioning support for document operations (#453)
* versioning support for document operations * add http api changes * Review --------- Co-authored-by: Simran Spiller <[email protected]>
1 parent 848f1e4 commit 1920efe

File tree

8 files changed

+426
-1
lines changed

8 files changed

+426
-1
lines changed

Diff for: ‎site/content/3.12/about-arangodb/features/highlights-by-version.md

+4
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@ aliases:
1717
Accelerate wildcard searches against Views and inverted indexes with _n_-grams
1818
to quickly find candidate matches.
1919

20+
- [**External versioning**](../../release-notes/version-3.12/whats-new-in-3-12.md#external-versioning-support):
21+
Specify any top-level attribute to compare whether the version number is higher
22+
than the currently stored one when updating or replacing documents.
23+
2024
**Enterprise Edition**
2125

2226
- [**ArangoSearch WAND optimization**](../../index-and-search/arangosearch/performance.md#wand-optimization):

Diff for: ‎site/content/3.12/aql/high-level-operations/insert.md

+33
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,39 @@ INSERT { _from: "vert/A", _to: "vert/B" } INTO coll
175175
OPTIONS { refillIndexCaches: true }
176176
```
177177

178+
### `versionAttribute`
179+
180+
Only applicable if `overwrite` is set to `true` or `overwriteMode`
181+
is set to `update` or `replace`.
182+
183+
You can use the `versionAttribute` option for external versioning support.
184+
If set, the attribute with the name specified by the option is looked up in the
185+
stored document and the attribute value is compared numerically to the value of
186+
the versioning attribute in the supplied document that is supposed to update/replace it.
187+
188+
If the version number in the new document is higher (rounded down to a whole number)
189+
than in the document that already exists in the database, then the update/replace
190+
operation is performed normally. This is also the case if the new versioning
191+
attribute has a non-numeric value, if it is a negative number, or if the
192+
attribute doesn't exist in the supplied or stored document.
193+
194+
If the version number in the new document is lower or equal to what exists in
195+
the database, the operation is not performed and the existing document thus not
196+
changed. No error is returned in this case.
197+
198+
The attribute can only be a top-level attribute.
199+
200+
For example, the following query conditionally replaces an existing document with
201+
the key `"123"` if the attribute `externalVersion` currently has a value below `5`:
202+
203+
```aql
204+
INSERT { _key: "123", externalVersion: 5, anotherAttribute: true } IN coll
205+
OPTIONS { overwriteMode: "replace", versionAttribute: "externalVersion" }
206+
```
207+
208+
You can check if `OLD._rev` (if not `null`) and `NEW._rev` are different to determine if the
209+
document has been changed.
210+
178211
## Returning the inserted documents
179212

180213
The inserted documents can also be returned by the query. In this case, the `INSERT`

Diff for: ‎site/content/3.12/aql/high-level-operations/replace.md

+30
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,36 @@ REPLACE { _key: "123", _from: "vert/C", _to: "vert/D" } IN edgeColl
252252
OPTIONS { refillIndexCaches: true }
253253
```
254254

255+
### `versionAttribute`
256+
257+
You can use the `versionAttribute` option for external versioning support.
258+
If set, the attribute with the name specified by the option is looked up in the
259+
stored document and the attribute value is compared numerically to the value of
260+
the versioning attribute in the supplied document that is supposed to replace it.
261+
262+
If the version number in the new document is higher (rounded down to a whole number)
263+
than in the document that already exists in the database, then the replace
264+
operation is performed normally. This is also the case if the new versioning
265+
attribute has a non-numeric value, if it is a negative number, or if the
266+
attribute doesn't exist in the supplied or stored document.
267+
268+
If the version number in the new document is lower or equal to what exists in
269+
the database, the operation is not performed and the existing document thus not
270+
changed. No error is returned in this case.
271+
272+
The attribute can only be a top-level attribute.
273+
274+
For example, the following query conditionally replaces an existing document with
275+
the key `"123"` if the attribute `externalVersion` currently has a value below `5`:
276+
277+
```aql
278+
REPLACE { _key: "123", externalVersion: 5, anotherAttribute: true } IN coll
279+
OPTIONS { versionAttribute: "externalVersion" }
280+
```
281+
282+
You can check if `OLD._rev` and `NEW._rev` are different to determine if the
283+
document has been changed.
284+
255285
## Returning the modified documents
256286

257287
You can optionally return the documents modified by the query. In this case, the `REPLACE`

Diff for: ‎site/content/3.12/aql/high-level-operations/update.md

+30
Original file line numberDiff line numberDiff line change
@@ -368,6 +368,36 @@ UPDATE { _key: "123", _from: "vert/C", _to: "vert/D" } IN edgeColl
368368
OPTIONS { refillIndexCaches: true }
369369
```
370370

371+
### `versionAttribute`
372+
373+
You can use the `versionAttribute` option for external versioning support.
374+
If set, the attribute with the name specified by the option is looked up in the
375+
stored document and the attribute value is compared numerically to the value of
376+
the versioning attribute in the supplied document that is supposed to update it.
377+
378+
If the version number in the new document is higher (rounded down to a whole number)
379+
than in the document that already exists in the database, then the update
380+
operation is performed normally. This is also the case if the new versioning
381+
attribute has a non-numeric value, if it is a negative number, or if the
382+
attribute doesn't exist in the supplied or stored document.
383+
384+
If the version number in the new document is lower or equal to what exists in
385+
the database, the operation is not performed and the existing document thus not
386+
changed. No error is returned in this case.
387+
388+
The attribute can only be a top-level attribute.
389+
390+
For example, the following query conditionally updates an existing document with
391+
the key `"123"` if the attribute `externalVersion` currently has a value below `5`:
392+
393+
```aql
394+
UPDATE { _key: "123", externalVersion: 5, anotherAttribute: true } IN coll
395+
OPTIONS { versionAttribute: "externalVersion" }
396+
```
397+
398+
You can check if `OLD._rev` and `NEW._rev` are different to determine if the
399+
document has been changed.
400+
371401
## Returning the modified documents
372402

373403
You can optionally return the documents modified by the query. In this case, the `UPDATE`

Diff for: ‎site/content/3.12/develop/http-api/documents.md

+156
Original file line numberDiff line numberDiff line change
@@ -476,6 +476,34 @@ paths:
476476
affect the edge index or cache-enabled persistent indexes.
477477
schema:
478478
type: boolean
479+
- name: versionAttribute
480+
in: query
481+
required: false
482+
description: |
483+
Only applicable if `overwrite` is set to `true` or `overwriteMode`
484+
is set to `update` or `replace`.
485+
486+
You can use the `versionAttribute` option for external versioning support.
487+
If set, the attribute with the name specified by the option is looked up in the
488+
stored document and the attribute value is compared numerically to the value of
489+
the versioning attribute in the supplied document that is supposed to update/replace it.
490+
491+
If the version number in the new document is higher (rounded down to a whole number)
492+
than in the document that already exists in the database, then the update/replace
493+
operation is performed normally. This is also the case if the new versioning
494+
attribute has a non-numeric value, if it is a negative number, or if the
495+
attribute doesn't exist in the supplied or stored document.
496+
497+
If the version number in the new document is lower or equal to what exists in
498+
the database, the operation is not performed and the existing document thus not
499+
changed. No error is returned in this case.
500+
501+
The attribute can only be a top-level attribute.
502+
503+
You can check if `_oldRev` (if present) and `_rev` are different to determine if the
504+
document has been changed.
505+
schema:
506+
type: string
479507
- name: x-arango-trx-id
480508
in: header
481509
required: false
@@ -856,6 +884,31 @@ paths:
856884
replacements affect the edge index or cache-enabled persistent indexes.
857885
schema:
858886
type: boolean
887+
- name: versionAttribute
888+
in: query
889+
required: false
890+
description: |
891+
You can use the `versionAttribute` option for external versioning support.
892+
If set, the attribute with the name specified by the option is looked up in the
893+
stored document and the attribute value is compared numerically to the value of
894+
the versioning attribute in the supplied document that is supposed to replace it.
895+
896+
If the version number in the new document is higher (rounded down to a whole number)
897+
than in the document that already exists in the database, then the replace
898+
operation is performed normally. This is also the case if the new versioning
899+
attribute has a non-numeric value, if it is a negative number, or if the
900+
attribute doesn't exist in the supplied or stored document.
901+
902+
If the version number in the new document is lower or equal to what exists in
903+
the database, the operation is not performed and the existing document thus not
904+
changed. No error is returned in this case.
905+
906+
The attribute can only be a top-level attribute.
907+
908+
You can check if `_oldRev` and `_rev` are different to determine if the
909+
document has been changed.
910+
schema:
911+
type: string
859912
- name: If-Match
860913
in: header
861914
required: false
@@ -1178,6 +1231,31 @@ paths:
11781231
affect the edge index or cache-enabled persistent indexes.
11791232
schema:
11801233
type: boolean
1234+
- name: versionAttribute
1235+
in: query
1236+
required: false
1237+
description: |
1238+
You can use the `versionAttribute` option for external versioning support.
1239+
If set, the attribute with the name specified by the option is looked up in the
1240+
stored document and the attribute value is compared numerically to the value of
1241+
the versioning attribute in the supplied document that is supposed to update it.
1242+
1243+
If the version number in the new document is higher (rounded down to a whole number)
1244+
than in the document that already exists in the database, then the update
1245+
operation is performed normally. This is also the case if the new versioning
1246+
attribute has a non-numeric value, if it is a negative number, or if the
1247+
attribute doesn't exist in the supplied or stored document.
1248+
1249+
If the version number in the new document is lower or equal to what exists in
1250+
the database, the operation is not performed and the existing document thus not
1251+
changed. No error is returned in this case.
1252+
1253+
The attribute can only be a top-level attribute.
1254+
1255+
You can check if `_oldRev` and `_rev` are different to determine if the
1256+
document has been changed.
1257+
schema:
1258+
type: string
11811259
- name: If-Match
11821260
in: header
11831261
required: false
@@ -1875,6 +1953,34 @@ paths:
18751953
affect the edge index or cache-enabled persistent indexes.
18761954
schema:
18771955
type: boolean
1956+
- name: versionAttribute
1957+
in: query
1958+
required: false
1959+
description: |
1960+
Only applicable if `overwrite` is set to `true` or `overwriteMode`
1961+
is set to `update` or `replace`.
1962+
1963+
You can use the `versionAttribute` option for external versioning support.
1964+
If set, the attribute with the name specified by the option is looked up in the
1965+
stored document and the attribute value is compared numerically to the value of
1966+
the versioning attribute in the supplied document that is supposed to update/replace it.
1967+
1968+
If the version number in the new document is higher (rounded down to a whole number)
1969+
than in the document that already exists in the database, then the update/replace
1970+
operation is performed normally. This is also the case if the new versioning
1971+
attribute has a non-numeric value, if it is a negative number, or if the
1972+
attribute doesn't exist in the supplied or stored document.
1973+
1974+
If the version number in the new document is lower or equal to what exists in
1975+
the database, the operation is not performed and the existing document thus not
1976+
changed. No error is returned in this case.
1977+
1978+
The attribute can only be a top-level attribute.
1979+
1980+
You can check if `_oldRev` (if present) and `_rev` are different to determine if the
1981+
document has been changed.
1982+
schema:
1983+
type: string
18781984
- name: x-arango-trx-id
18791985
in: header
18801986
required: false
@@ -2146,6 +2252,31 @@ paths:
21462252
replacements affect the edge index or cache-enabled persistent indexes.
21472253
schema:
21482254
type: boolean
2255+
- name: versionAttribute
2256+
in: query
2257+
required: false
2258+
description: |
2259+
You can use the `versionAttribute` option for external versioning support.
2260+
If set, the attribute with the name specified by the option is looked up in the
2261+
stored document and the attribute value is compared numerically to the value of
2262+
the versioning attribute in the supplied document that is supposed to replace it.
2263+
2264+
If the version number in the new document is higher (rounded down to a whole number)
2265+
than in the document that already exists in the database, then the replace
2266+
operation is performed normally. This is also the case if the new versioning
2267+
attribute has a non-numeric value, if it is a negative number, or if the
2268+
attribute doesn't exist in the supplied or stored document.
2269+
2270+
If the version number in the new document is lower or equal to what exists in
2271+
the database, the operation is not performed and the existing document thus not
2272+
changed. No error is returned in this case.
2273+
2274+
The attribute can only be a top-level attribute.
2275+
2276+
You can check if `_oldRev` and `_rev` are different to determine if the
2277+
document has been changed.
2278+
schema:
2279+
type: string
21492280
- name: x-arango-trx-id
21502281
in: header
21512282
required: false
@@ -2368,6 +2499,31 @@ paths:
23682499
affect the edge index or cache-enabled persistent indexes.
23692500
schema:
23702501
type: boolean
2502+
- name: versionAttribute
2503+
in: query
2504+
required: false
2505+
description: |
2506+
You can use the `versionAttribute` option for external versioning support.
2507+
If set, the attribute with the name specified by the option is looked up in the
2508+
stored document and the attribute value is compared numerically to the value of
2509+
the versioning attribute in the supplied document that is supposed to update it.
2510+
2511+
If the version number in the new document is higher (rounded down to a whole number)
2512+
than in the document that already exists in the database, then the update
2513+
operation is performed normally. This is also the case if the new versioning
2514+
attribute has a non-numeric value, if it is a negative number, or if the
2515+
attribute doesn't exist in the supplied or stored document.
2516+
2517+
If the version number in the new document is lower or equal to what exists in
2518+
the database, the operation is not performed and the existing document thus not
2519+
changed. No error is returned in this case.
2520+
2521+
The attribute can only be a top-level attribute.
2522+
2523+
You can check if `_oldRev` and `_rev` are different to determine if the
2524+
document has been changed.
2525+
schema:
2526+
type: string
23712527
- name: x-arango-trx-id
23722528
in: header
23732529
required: false

0 commit comments

Comments
 (0)