Skip to content

Commit 9507d94

Browse files
bleskesbleskes
authored
Deprecate support for internal versioning for concurrency control (#38451)
Relates #38254 Relates #10708
1 parent aa9816c commit 9507d94

File tree

18 files changed

+149
-10
lines changed

18 files changed

+149
-10
lines changed

‎client/rest-high-level/src/test/java/org/elasticsearch/client/CrudIT.java

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,8 @@ public void testDelete() throws IOException {
105105
IndexResponse indexResponse = highLevelClient().index(
106106
new IndexRequest("index", "type", docId).source(Collections.singletonMap("foo", "bar")), RequestOptions.DEFAULT);
107107
DeleteRequest deleteRequest = new DeleteRequest("index", "type", docId);
108-
if (randomBoolean()) {
108+
final boolean useSeqNo = randomBoolean();
109+
if (useSeqNo) {
109110
deleteRequest.setIfSeqNo(indexResponse.getSeqNo());
110111
deleteRequest.setIfPrimaryTerm(indexResponse.getPrimaryTerm());
111112
} else {
@@ -117,6 +118,11 @@ public void testDelete() throws IOException {
117118
assertEquals("type", deleteResponse.getType());
118119
assertEquals(docId, deleteResponse.getId());
119120
assertEquals(DocWriteResponse.Result.DELETED, deleteResponse.getResult());
121+
if (useSeqNo == false) {
122+
assertWarnings("Usage of internal versioning for optimistic concurrency control is deprecated and will be removed." +
123+
" Please use the `if_seq_no` and `if_primary_term` parameters instead." +
124+
" (request for index [index], type [type], id [id])");
125+
}
120126
}
121127
{
122128
// Testing non existing document
@@ -153,6 +159,9 @@ public void testDelete() throws IOException {
153159
} else {
154160
assertEquals("Elasticsearch exception [type=version_conflict_engine_exception, reason=[type][" + docId + "]: " +
155161
"version conflict, current version [1] is different than the one provided [2]]", exception.getMessage());
162+
assertWarnings("Usage of internal versioning for optimistic concurrency control is deprecated and will be removed." +
163+
" Please use the `if_seq_no` and `if_primary_term` parameters instead." +
164+
" (request for index [index], type [type], id [version_conflict])");
156165
}
157166
assertEquals("index", exception.getMetadata("es.index").get(0));
158167
}
@@ -430,6 +439,9 @@ public void testMultiGet() throws IOException {
430439
@AwaitsFix(bugUrl = "https://github.com/elastic/elasticsearch/pull/38451 contains a fix. sliencing for now")
431440
public void testIndex() throws IOException {
432441
final XContentType xContentType = randomFrom(XContentType.values());
442+
highLevelClient().indices().create(
443+
new CreateIndexRequest("index").settings(Collections.singletonMap("index.number_of_shards", "1")),
444+
RequestOptions.DEFAULT);
433445
{
434446
IndexRequest indexRequest = new IndexRequest("index", "type");
435447
indexRequest.source(XContentBuilder.builder(xContentType.xContent()).startObject().field("test", "test").endObject());
@@ -480,7 +492,7 @@ public void testIndex() throws IOException {
480492
IndexRequest wrongRequest = new IndexRequest("index", "type", "id");
481493
wrongRequest.source(XContentBuilder.builder(xContentType.xContent()).startObject().field("field", "test").endObject());
482494
if (seqNosForConflict) {
483-
wrongRequest.setIfSeqNo(2).setIfPrimaryTerm(2);
495+
wrongRequest.setIfSeqNo(5).setIfPrimaryTerm(2);
484496
} else {
485497
wrongRequest.version(5);
486498
}
@@ -491,11 +503,14 @@ public void testIndex() throws IOException {
491503
assertEquals(RestStatus.CONFLICT, exception.status());
492504
if (seqNosForConflict) {
493505
assertEquals("Elasticsearch exception [type=version_conflict_engine_exception, reason=[type][id]: " +
494-
"version conflict, required seqNo [1], primary term [5]. current document has seqNo [2] and primary term [1]]",
506+
"version conflict, required seqNo [5], primary term [2]. current document has seqNo [2] and primary term [1]]",
495507
exception.getMessage());
496508
} else {
497509
assertEquals("Elasticsearch exception [type=version_conflict_engine_exception, reason=[type][id]: " +
498510
"version conflict, current version [2] is different than the one provided [5]]", exception.getMessage());
511+
assertWarnings("Usage of internal versioning for optimistic concurrency control is deprecated and will be removed. " +
512+
"Please use the `if_seq_no` and `if_primary_term` parameters instead. " +
513+
"(request for index [index], type [type], id [id])");
499514
}
500515
assertEquals("index", exception.getMetadata("es.index").get(0));
501516
}

‎client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/CRUDDocumentationIT.java

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -224,7 +224,8 @@ public void testIndex() throws Exception {
224224
// tag::index-conflict
225225
IndexRequest request = new IndexRequest("posts", "doc", "1")
226226
.source("field", "value")
227-
.version(1);
227+
.setIfSeqNo(100L)
228+
.setIfPrimaryTerm(1L);
228229
try {
229230
IndexResponse response = client.index(request, RequestOptions.DEFAULT);
230231
} catch(ElasticsearchException e) {
@@ -434,7 +435,8 @@ public void testUpdate() throws Exception {
434435
// tag::update-conflict
435436
UpdateRequest request = new UpdateRequest("posts", "doc", "1")
436437
.doc("field", "value")
437-
.version(1);
438+
.setIfSeqNo(100L)
439+
.setIfPrimaryTerm(1L);
438440
try {
439441
UpdateResponse updateResponse = client.update(
440442
request, RequestOptions.DEFAULT);
@@ -639,8 +641,9 @@ public void testDelete() throws Exception {
639641
// tag::delete-conflict
640642
try {
641643
DeleteResponse deleteResponse = client.delete(
642-
new DeleteRequest("posts", "doc", "1").version(2),
643-
RequestOptions.DEFAULT);
644+
new DeleteRequest("posts", "doc", "1")
645+
.setIfSeqNo(100L).setIfPrimaryTerm(2L),
646+
RequestOptions.DEFAULT);
644647
} catch (ElasticsearchException exception) {
645648
if (exception.status() == RestStatus.CONFLICT) {
646649
// <1>

‎docs/reference/docs/index_.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -389,6 +389,8 @@ the different version types and their semantics.
389389

390390
`internal`:: only index the document if the given version is identical to the version
391391
of the stored document.
392+
deprecated[6.7.0, Please use `if_seq_no` & `if_primary_term` instead. See <<optimistic-concurrency-control>> for more details.]
393+
392394

393395
`external` or `external_gt`:: only index the document if the given version is strictly higher
394396
than the version of the stored document *or* if there is no existing document. The given

‎docs/reference/docs/update.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -338,6 +338,8 @@ The update API uses the Elasticsearch's versioning support internally to make
338338
sure the document doesn't change during the update. You can use the `version`
339339
parameter to specify that the document should only be updated if its version
340340
matches the one specified.
341+
deprecated[6.7.0, Please use `if_seq_no` & `if_primary_term` instead. See <<optimistic-concurrency-control>> for more details.]
342+
341343

342344
[NOTE]
343345
.The update API does not support versioning other than internal

‎docs/reference/migration/migrate_6_7.asciidoc

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,25 @@
77
This section discusses the changes that you need to be aware of when migrating
88
your application to Elasticsearch 6.7.
99

10+
* <<breaking_67_indexing_changes>>
1011
* <<breaking_67_plugin_changes>>
1112
* <<breaking_67_settings_changes>>
1213

1314
See also <<release-highlights>> and <<es-release-notes>>.
1415

16+
[float]
17+
[[breaking_67_indexing_changes]]
18+
=== Indexing changes
19+
20+
[float]
21+
==== Deprecated usage of `internal` versioning for optimistic concurrency control
22+
23+
`internal` version may not uniquely identify a document's version if an indexed document
24+
wasn't fully replicated when a primary fails. As such it is unsafe to use for
25+
optimistic concurrency control, is deprecated and the option will no longer be available
26+
in Elasticsearch 7.0.0. Please use the `if_seq_no` and `if_primary_term` parameters instead.
27+
See <<optimistic-concurrency-control>> for more details.
28+
1529
[float]
1630
[[breaking_67_plugin_changes]]
1731
=== Plugin changes

‎rest-api-spec/src/main/resources/rest-api-spec/test/bulk/60_deprecated.yml

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
"Deprecated parameters should produce warning in Bulk query":
44

55
- skip:
6-
version: " - 6.0.99"
7-
reason: some parameters are deprecated starting from 6.1, their equivalents without underscore are used instead
6+
version: " - 6.6.99"
7+
reason: versioned operations were deprecated in 6.7
88
features: "warnings"
99

1010
- do:
@@ -16,6 +16,8 @@
1616
{ "doc": { "f1": "v2" } }
1717
warnings:
1818
- "Deprecated field [_version] used, expected [version] instead"
19+
- "Usage of internal versioning for optimistic concurrency control is deprecated and will be removed. Please use the `if_seq_no` and `if_primary_term` parameters instead. (request for index [test_index], type [test_type], id [test_id_1])"
20+
- "Usage of internal versioning for optimistic concurrency control is deprecated and will be removed. Please use the `if_seq_no` and `if_primary_term` parameters instead. (request for index [test_index], type [test_type], id [test_id_2])"
1921

2022
- do:
2123
bulk:

‎rest-api-spec/src/main/resources/rest-api-spec/test/delete/20_internal_version.yml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
---
22
"Internal version":
3+
- skip:
4+
version: " - 6.6.99"
5+
reason: versioned operations were deprecated in 6.7
6+
features: warnings
37

48
- do:
59
index:
@@ -17,12 +21,16 @@
1721
type: test
1822
id: 1
1923
version: 2
24+
warnings:
25+
- "Usage of internal versioning for optimistic concurrency control is deprecated and will be removed. Please use the `if_seq_no` and `if_primary_term` parameters instead. (request for index [test_1], type [test], id [1])"
2026

2127
- do:
2228
delete:
2329
index: test_1
2430
type: test
2531
id: 1
2632
version: 1
33+
warnings:
34+
- "Usage of internal versioning for optimistic concurrency control is deprecated and will be removed. Please use the `if_seq_no` and `if_primary_term` parameters instead. (request for index [test_1], type [test], id [1])"
2735

2836
- match: { _version: 2 }

‎rest-api-spec/src/main/resources/rest-api-spec/test/delete/21_cas.yml

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
"Compare and set with sequence numbers":
3+
- skip:
4+
version: " - 6.5.99"
5+
reason: sequence numbers can be used for CAS as of 6.6.0
6+
7+
- do:
8+
index:
9+
index: test_1
10+
type: test
11+
id: 1
12+
body: { foo: bar }
13+
14+
- match: { _seq_no: 0 }
15+
16+
- do:
17+
catch: conflict
18+
delete:
19+
index: test_1
20+
type: test
21+
id: 1
22+
if_seq_no: 2
23+
if_primary_term: 1
24+
25+
- do:
26+
delete:
27+
index: test_1
28+
type: test
29+
id: 1
30+
if_seq_no: 0
31+
if_primary_term: 1
32+
33+
- match: { _seq_no: 1 }

‎rest-api-spec/src/main/resources/rest-api-spec/test/index/30_internal_version.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
---
22
"Internal version":
3+
- skip:
4+
version: " - 6.6.99"
5+
reason: versioned operations were deprecated in 6.7
6+
features: warnings
37

48
- do:
59
index:
@@ -15,6 +19,7 @@
1519
type: test
1620
id: 1
1721
body: { foo: bar }
22+
1823
- match: { _version: 2}
1924

2025
- do:
@@ -25,12 +30,17 @@
2530
id: 1
2631
body: { foo: bar }
2732
version: 1
33+
warnings:
34+
- "Usage of internal versioning for optimistic concurrency control is deprecated and will be removed. Please use the `if_seq_no` and `if_primary_term` parameters instead. (request for index [test_1], type [test], id [1])"
35+
2836
- do:
2937
index:
3038
index: test_1
3139
type: test
3240
id: 1
3341
body: { foo: bar }
3442
version: 2
43+
warnings:
44+
- "Usage of internal versioning for optimistic concurrency control is deprecated and will be removed. Please use the `if_seq_no` and `if_primary_term` parameters instead. (request for index [test_1], type [test], id [1])"
3545

3646
- match: { _version: 3 }

‎rest-api-spec/src/main/resources/rest-api-spec/test/update/30_internal_version.yml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
---
22
"Internal version":
3+
- skip:
4+
version: " - 6.6.99"
5+
reason: versioned operations were deprecated in 6.7
6+
features: warnings
37

48
- do:
59
catch: missing
@@ -10,6 +14,8 @@
1014
version: 1
1115
body:
1216
doc: { foo: baz }
17+
warnings:
18+
- "Usage of internal versioning for optimistic concurrency control is deprecated and will be removed. Please use the `if_seq_no` and `if_primary_term` parameters instead. (request for index [test_1], type [test], id [1])"
1319

1420
- do:
1521
index:
@@ -28,3 +34,5 @@
2834
version: 2
2935
body:
3036
doc: { foo: baz }
37+
warnings:
38+
- "Usage of internal versioning for optimistic concurrency control is deprecated and will be removed. Please use the `if_seq_no` and `if_primary_term` parameters instead. (request for index [test_1], type [test], id [1])"

‎server/src/main/java/org/elasticsearch/action/DocWriteRequest.java

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
import org.elasticsearch.action.update.UpdateRequest;
2525
import org.elasticsearch.common.io.stream.StreamInput;
2626
import org.elasticsearch.common.io.stream.StreamOutput;
27+
import org.elasticsearch.common.logging.DeprecationLogger;
2728
import org.elasticsearch.common.lucene.uid.Versions;
2829
import org.elasticsearch.index.VersionType;
2930

@@ -252,6 +253,17 @@ static void writeDocumentRequest(StreamOutput out, DocWriteRequest request) thr
252253
}
253254
}
254255

256+
static void logDeprecationWarnings(DocWriteRequest request, DeprecationLogger logger) {
257+
if (request.versionType() == VersionType.INTERNAL &&
258+
request.version() != Versions.MATCH_ANY &&
259+
request.version() != Versions.MATCH_DELETED) {
260+
logger.deprecatedAndMaybeLog("occ_internal_version",
261+
"Usage of internal versioning for optimistic concurrency control is deprecated and will be removed. Please use" +
262+
" the `if_seq_no` and `if_primary_term` parameters instead. (request for index [{}], type [{}], id [{}])",
263+
request.index(), request.type(), request.id());
264+
}
265+
}
266+
255267
static ActionRequestValidationException validateSeqNoBasedCASParams(
256268
DocWriteRequest request, ActionRequestValidationException validationException) {
257269
if (request.versionType().validateVersionForWrites(request.version()) == false) {

‎server/src/main/java/org/elasticsearch/action/delete/DeleteRequest.java

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919

2020
package org.elasticsearch.action.delete;
2121

22+
import org.apache.logging.log4j.LogManager;
2223
import org.elasticsearch.Version;
2324
import org.elasticsearch.action.ActionRequestValidationException;
2425
import org.elasticsearch.action.CompositeIndicesRequest;
@@ -28,6 +29,7 @@
2829
import org.elasticsearch.common.Strings;
2930
import org.elasticsearch.common.io.stream.StreamInput;
3031
import org.elasticsearch.common.io.stream.StreamOutput;
32+
import org.elasticsearch.common.logging.DeprecationLogger;
3133
import org.elasticsearch.common.lucene.uid.Versions;
3234
import org.elasticsearch.index.VersionType;
3335
import org.elasticsearch.index.shard.ShardId;
@@ -51,6 +53,7 @@
5153
*/
5254
public class DeleteRequest extends ReplicatedWriteRequest<DeleteRequest>
5355
implements DocWriteRequest<DeleteRequest>, CompositeIndicesRequest {
56+
private static final DeprecationLogger DEPRECATION_LOGGER = new DeprecationLogger(LogManager.getLogger(DeleteRequest.class));
5457

5558
private String type;
5659
private String id;
@@ -99,6 +102,8 @@ public ActionRequestValidationException validate() {
99102

100103
validationException = DocWriteRequest.validateSeqNoBasedCASParams(this, validationException);
101104

105+
DocWriteRequest.logDeprecationWarnings(this, DEPRECATION_LOGGER);
106+
102107
return validationException;
103108
}
104109

‎server/src/main/java/org/elasticsearch/action/index/IndexRequest.java

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919

2020
package org.elasticsearch.action.index;
2121

22+
import org.apache.logging.log4j.LogManager;
2223
import org.elasticsearch.ElasticsearchGenerationException;
2324
import org.elasticsearch.Version;
2425
import org.elasticsearch.action.ActionRequestValidationException;
@@ -36,6 +37,7 @@
3637
import org.elasticsearch.common.bytes.BytesReference;
3738
import org.elasticsearch.common.io.stream.StreamInput;
3839
import org.elasticsearch.common.io.stream.StreamOutput;
40+
import org.elasticsearch.common.logging.DeprecationLogger;
3941
import org.elasticsearch.common.lucene.uid.Versions;
4042
import org.elasticsearch.common.unit.ByteSizeValue;
4143
import org.elasticsearch.common.xcontent.XContentBuilder;
@@ -73,6 +75,7 @@
7375
* @see org.elasticsearch.client.Client#index(IndexRequest)
7476
*/
7577
public class IndexRequest extends ReplicatedWriteRequest<IndexRequest> implements DocWriteRequest<IndexRequest>, CompositeIndicesRequest {
78+
private static final DeprecationLogger DEPRECATION_LOGGER = new DeprecationLogger(LogManager.getLogger(IndexRequest.class));
7679

7780
/**
7881
* Max length of the source document to include into string()
@@ -198,6 +201,8 @@ public ActionRequestValidationException validate() {
198201
}
199202

200203

204+
DocWriteRequest.logDeprecationWarnings(this, DEPRECATION_LOGGER);
205+
201206
return validationException;
202207
}
203208

‎server/src/main/java/org/elasticsearch/action/update/UpdateRequest.java

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,9 @@ public ActionRequestValidationException validate() {
160160
if (doc == null && docAsUpsert) {
161161
validationException = addValidationError("doc must be specified if doc_as_upsert is enabled", validationException);
162162
}
163+
164+
DocWriteRequest.logDeprecationWarnings(this, DEPRECATION_LOGGER);
165+
163166
return validationException;
164167
}
165168

‎server/src/test/java/org/elasticsearch/action/bulk/BulkRequestTests.java

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -316,6 +316,8 @@ public void testToValidateUpsertRequestAndVersionInBulkRequest() throws IOExcept
316316
bulkRequest.add(data, null, null, xContentType);
317317
assertThat(bulkRequest.validate().validationErrors(), contains("can't provide both upsert request and a version",
318318
"can't provide version in upsert request"));
319+
assertWarnings("Usage of internal versioning for optimistic concurrency control is deprecated and will be removed. " +
320+
"Please use the `if_seq_no` and `if_primary_term` parameters instead. (request for index [index], type [type], id [id])");
319321
}
320322

321323
public void testBulkTerminatedByNewline() throws Exception {

0 commit comments

Comments
 (0)