Merge pull request #19180 from tlrx/doc-version-number-zero-with-dbq-and-ubq

[Doc] Document Update/Delete-By-Query with version number zero

docs/reference/docs/delete-by-query.asciidoc

@@ -54,6 +54,10 @@ conflict if the document changes between the time when the snapshot was taken
 and when the delete request is processed. When the versions match the document
 is deleted.
 
+NOTE: Since `internal` versioning does not support the value 0 as a valid
+version number, documents with version equal to zero cannot be deleted using
+`_delete_by_query` and will fail the request.
+
 During the `_delete_by_query` execution, multiple search requests are sequentially
 executed in order to find all the matching documents to delete. Every time a batch
 of documents is found, a corresponding bulk request is executed to delete all

docs/reference/docs/index_.asciidoc

@@ -119,6 +119,14 @@ indexed and the new version number used. If the value provided is less
 than or equal to the stored document's version number, a version
 conflict will occur and the index operation will fail.
 
+WARNING: External versioning supports the value 0 as a valid version number.
+This allows the version to be in sync with an external versioning system
+where version numbers start from zero instead of one. It has the side effect
+that documents with version number equal to zero cannot neither be updated
+using the <<docs-update-by-query,Update-By-Query API>> nor be deleted
+using the <<docs-delete-by-query,Delete By Query API>> as long as their
+version number is equal to zero.
+
 A nice side effect is that there is no need to maintain strict ordering
 of async indexing operations executed as a result of changes to a source
 database, as long as version numbers from the source database are used.

docs/reference/docs/update-by-query.asciidoc

@@ -46,6 +46,10 @@ conflict if the document changes between the time when the snapshot was taken
 and when the index request is processed. When the versions match the document
 is updated and the version number is incremented.
 
+NOTE: Since `internal` versioning does not support the value 0 as a valid
+version number, documents with version equal to zero cannot be updated using
+`_update_by_query` and will fail the request.
+
 All update and query failures cause the `_update_by_query` to abort and are
 returned in the `failures` of the response. The updates that have been
 performed still stick. In other words, the process is not rolled back, only

modules/reindex/src/test/resources/rest-api-spec/test/delete_by_query/40_versioning.yaml

@@ -0,0 +1,29 @@
+---
+"delete_by_query fails to delete documents with version number equal to zero":
+  - do:
+      index:
+        index:        index1
+        type:         type1
+        id:           1
+        version:      0 # Starting version is zero
+        version_type: external
+        body:    {"delete": 0}
+  - do:
+      indices.refresh: {}
+
+  # Delete by query uses internal versioning and will fail here
+  # because zero is not allowed as a valid version number
+  - do:
+      catch: /illegal version value \[0\] for version type \[INTERNAL\]./
+      delete_by_query:
+        index: index1
+        refresh: true
+        body:
+          query:
+            match_all: {}
+  - do:
+      get:
+        index: index1
+        type:  type1
+        id:    1
+  - match: {_version: 0}

modules/reindex/src/test/resources/rest-api-spec/test/update_by_query/40_versioning.yaml

@@ -21,3 +21,30 @@
         type:  test
         id:    1
   - match: {_version: 2}
+
+---
+"update_by_query fails to update documents with version number equal to zero":
+  - do:
+      index:
+        index:        index1
+        type:         type1
+        id:           1
+        version:      0 # Starting version is zero
+        version_type: external
+        body:    {"update": 0}
+  - do:
+      indices.refresh: {}
+
+  # Update by query uses internal versioning and will fail here
+  # because zero is not allowed as a valid version number
+  - do:
+      catch: /illegal version value \[0\] for version type \[INTERNAL\]./
+      update_by_query:
+        index: index1
+        refresh: true
+  - do:
+      get:
+        index: index1
+        type:  type1
+        id:    1
+  - match: {_version: 0}