Skip to content

Commit c45ff27

Browse files
lipsillnik9000
lipsill
authored and
nik9000
committed
Deprecate _source_include and _source_exclude url parameters (#33475)
Deprecates `_source_include` and `_source_exclude` url parameters in favor of `_source_inclues` and `_source_excludes` because those are consistent with the rest of Elasticsearch's APIs. Relates to #22792
1 parent 547a16d commit c45ff27

File tree

25 files changed

+123
-59
lines changed

25 files changed

+123
-59
lines changed

‎client/rest-high-level/src/main/java/org/elasticsearch/client/RequestConverters.java

+2-2
Original file line numberDiff line numberDiff line change
@@ -747,10 +747,10 @@ Params withFetchSourceContext(FetchSourceContext fetchSourceContext) {
747747
putParam("_source", Boolean.FALSE.toString());
748748
}
749749
if (fetchSourceContext.includes() != null && fetchSourceContext.includes().length > 0) {
750-
putParam("_source_include", String.join(",", fetchSourceContext.includes()));
750+
putParam("_source_includes", String.join(",", fetchSourceContext.includes()));
751751
}
752752
if (fetchSourceContext.excludes() != null && fetchSourceContext.excludes().length > 0) {
753-
putParam("_source_exclude", String.join(",", fetchSourceContext.excludes()));
753+
putParam("_source_excludes", String.join(",", fetchSourceContext.excludes()));
754754
}
755755
}
756756
return this;

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

+2-2
Original file line numberDiff line numberDiff line change
@@ -1589,13 +1589,13 @@ private static void randomizeFetchSourceContextParams(Consumer<FetchSourceContex
15891589
String[] includes = new String[numIncludes];
15901590
String includesParam = randomFields(includes);
15911591
if (numIncludes > 0) {
1592-
expectedParams.put("_source_include", includesParam);
1592+
expectedParams.put("_source_includes", includesParam);
15931593
}
15941594
int numExcludes = randomIntBetween(0, 5);
15951595
String[] excludes = new String[numExcludes];
15961596
String excludesParam = randomFields(excludes);
15971597
if (numExcludes > 0) {
1598-
expectedParams.put("_source_exclude", excludesParam);
1598+
expectedParams.put("_source_excludes", excludesParam);
15991599
}
16001600
consumer.accept(new FetchSourceContext(true, includes, excludes));
16011601
}

‎docs/reference/docs/get.asciidoc

+4-4
Original file line numberDiff line numberDiff line change
@@ -73,14 +73,14 @@ GET twitter/_doc/0?_source=false
7373
// CONSOLE
7474
// TEST[setup:twitter]
7575

76-
If you only need one or two fields from the complete `_source`, you can use the `_source_include`
77-
& `_source_exclude` parameters to include or filter out that parts you need. This can be especially helpful
76+
If you only need one or two fields from the complete `_source`, you can use the `_source_includes`
77+
& `_source_excludes` parameters to include or filter out that parts you need. This can be especially helpful
7878
with large documents where partial retrieval can save on network overhead. Both parameters take a comma separated list
7979
of fields or wildcard expressions. Example:
8080

8181
[source,js]
8282
--------------------------------------------------
83-
GET twitter/_doc/0?_source_include=*.id&_source_exclude=entities
83+
GET twitter/_doc/0?_source_includes=*.id&_source_excludes=entities
8484
--------------------------------------------------
8585
// CONSOLE
8686
// TEST[setup:twitter]
@@ -232,7 +232,7 @@ You can also use the same source filtering parameters to control which parts of
232232

233233
[source,js]
234234
--------------------------------------------------
235-
GET twitter/_doc/1/_source?_source_include=*.id&_source_exclude=entities'
235+
GET twitter/_doc/1/_source?_source_includes=*.id&_source_excludes=entities'
236236
--------------------------------------------------
237237
// CONSOLE
238238
// TEST[continued]

‎docs/reference/docs/multi-get.asciidoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ GET /test/_doc/_mget
8989
By default, the `_source` field will be returned for every document (if stored).
9090
Similar to the <<get-source-filtering,get>> API, you can retrieve only parts of
9191
the `_source` (or not at all) by using the `_source` parameter. You can also use
92-
the url parameters `_source`,`_source_include` & `_source_exclude` to specify defaults,
92+
the url parameters `_source`,`_source_includes` & `_source_excludes` to specify defaults,
9393
which will be used when there are no per-document instructions.
9494

9595
For example:

‎docs/reference/migration/migrate_6_6.asciidoc

+9
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,12 @@ Using automatically expanded fields for the "all fields" mode ("default_field":
2222
for the `query_string`, `multi_match` and `simple_query_string` now raises a warning and
2323
a deprecation notice to be logged for queries beyond 1024 fields. This limit will be
2424
enforced with a hard error starting in 7.0.
25+
26+
[float]
27+
==== Deprecate `_source_exclude` and `_source_include` URL Parameters
28+
29+
`_source_exclude` and `_source_include` are deprecated in favor of
30+
`_source_excludes` and `_source_includes` because those line up better with the
31+
rest of Elasticsearc's APIs and Elasticsearch will raise a deprecation warning
32+
if those are used on any APIs. We plan to drop support for `_source_exclude` and
33+
`_source_include` in 7.0.

‎docs/reference/search/explain.asciidoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ This will yield the same result as the previous request.
117117
`_source`::
118118

119119
Set to `true` to retrieve the `_source` of the document explained. You can also
120-
retrieve part of the document by using `_source_include` & `_source_exclude` (see <<get-source-filtering,Get API>> for more details)
120+
retrieve part of the document by using `_source_includes` & `_source_excludes` (see <<get-source-filtering,Get API>> for more details)
121121

122122
`stored_fields`::
123123
Allows to control which stored fields to return as part of the

‎docs/reference/search/uri-request.asciidoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ providing text to a numeric field) to be ignored. Defaults to false.
8383
hits was computed.
8484

8585
|`_source`|Set to `false` to disable retrieval of the `_source` field. You can also retrieve
86-
part of the document by using `_source_include` & `_source_exclude` (see the <<search-request-source-filtering, request body>>
86+
part of the document by using `_source_includes` & `_source_excludes` (see the <<search-request-source-filtering, request body>>
8787
documentation for more details)
8888

8989
|`stored_fields` |The selective stored fields of the document to return for each hit,

‎rest-api-spec/src/main/resources/rest-api-spec/api/bulk.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,11 @@
4545
"type" : "list",
4646
"description" : "True or false to return the _source field or not, or default list of fields to return, can be overridden on each sub-request"
4747
},
48-
"_source_exclude": {
48+
"_source_excludes": {
4949
"type" : "list",
5050
"description" : "Default list of fields to exclude from the returned _source field, can be overridden on each sub-request"
5151
},
52-
"_source_include": {
52+
"_source_includes": {
5353
"type" : "list",
5454
"description" : "Default list of fields to extract and return from the _source field, can be overridden on each sub-request"
5555
},

‎rest-api-spec/src/main/resources/rest-api-spec/api/delete_by_query.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -102,11 +102,11 @@
102102
"type" : "list",
103103
"description" : "True or false to return the _source field or not, or a list of fields to return"
104104
},
105-
"_source_exclude": {
105+
"_source_excludes": {
106106
"type" : "list",
107107
"description" : "A list of fields to exclude from the returned _source field"
108108
},
109-
"_source_include": {
109+
"_source_includes": {
110110
"type" : "list",
111111
"description" : "A list of fields to extract and return from the _source field"
112112
},

‎rest-api-spec/src/main/resources/rest-api-spec/api/exists.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -51,11 +51,11 @@
5151
"type" : "list",
5252
"description" : "True or false to return the _source field or not, or a list of fields to return"
5353
},
54-
"_source_exclude": {
54+
"_source_excludes": {
5555
"type" : "list",
5656
"description" : "A list of fields to exclude from the returned _source field"
5757
},
58-
"_source_include": {
58+
"_source_includes": {
5959
"type" : "list",
6060
"description" : "A list of fields to extract and return from the _source field"
6161
},

‎rest-api-spec/src/main/resources/rest-api-spec/api/exists_source.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -47,11 +47,11 @@
4747
"type" : "list",
4848
"description" : "True or false to return the _source field or not, or a list of fields to return"
4949
},
50-
"_source_exclude": {
50+
"_source_excludes": {
5151
"type" : "list",
5252
"description" : "A list of fields to exclude from the returned _source field"
5353
},
54-
"_source_include": {
54+
"_source_includes": {
5555
"type" : "list",
5656
"description" : "A list of fields to extract and return from the _source field"
5757
},

‎rest-api-spec/src/main/resources/rest-api-spec/api/explain.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -69,11 +69,11 @@
6969
"type" : "list",
7070
"description" : "True or false to return the _source field or not, or a list of fields to return"
7171
},
72-
"_source_exclude": {
72+
"_source_excludes": {
7373
"type" : "list",
7474
"description" : "A list of fields to exclude from the returned _source field"
7575
},
76-
"_source_include": {
76+
"_source_includes": {
7777
"type" : "list",
7878
"description" : "A list of fields to extract and return from the _source field"
7979
}

‎rest-api-spec/src/main/resources/rest-api-spec/api/get.json

+8
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,14 @@
5151
"type" : "list",
5252
"description" : "True or false to return the _source field or not, or a list of fields to return"
5353
},
54+
"_source_excludes": {
55+
"type" : "list",
56+
"description" : "A list of fields to exclude from the returned _source field"
57+
},
58+
"_source_includes": {
59+
"type" : "list",
60+
"description" : "A list of fields to extract and return from the _source field"
61+
},
5462
"_source_exclude": {
5563
"type" : "list",
5664
"description" : "A list of fields to exclude from the returned _source field"

‎rest-api-spec/src/main/resources/rest-api-spec/api/get_source.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -47,11 +47,11 @@
4747
"type" : "list",
4848
"description" : "True or false to return the _source field or not, or a list of fields to return"
4949
},
50-
"_source_exclude": {
50+
"_source_excludes": {
5151
"type" : "list",
5252
"description" : "A list of fields to exclude from the returned _source field"
5353
},
54-
"_source_include": {
54+
"_source_includes": {
5555
"type" : "list",
5656
"description" : "A list of fields to extract and return from the _source field"
5757
},

‎rest-api-spec/src/main/resources/rest-api-spec/api/mget.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -40,11 +40,11 @@
4040
"type" : "list",
4141
"description" : "True or false to return the _source field or not, or a list of fields to return"
4242
},
43-
"_source_exclude": {
43+
"_source_excludes": {
4444
"type" : "list",
4545
"description" : "A list of fields to exclude from the returned _source field"
4646
},
47-
"_source_include": {
47+
"_source_includes": {
4848
"type" : "list",
4949
"description" : "A list of fields to extract and return from the _source field"
5050
}

‎rest-api-spec/src/main/resources/rest-api-spec/api/search.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -101,11 +101,11 @@
101101
"type" : "list",
102102
"description" : "True or false to return the _source field or not, or a list of fields to return"
103103
},
104-
"_source_exclude": {
104+
"_source_excludes": {
105105
"type" : "list",
106106
"description" : "A list of fields to exclude from the returned _source field"
107107
},
108-
"_source_include": {
108+
"_source_includes": {
109109
"type" : "list",
110110
"description" : "A list of fields to extract and return from the _source field"
111111
},

‎rest-api-spec/src/main/resources/rest-api-spec/api/update.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,11 @@
3535
"type" : "list",
3636
"description" : "True or false to return the _source field or not, or a list of fields to return"
3737
},
38-
"_source_exclude": {
38+
"_source_excludes": {
3939
"type" : "list",
4040
"description" : "A list of fields to exclude from the returned _source field"
4141
},
42-
"_source_include": {
42+
"_source_includes": {
4343
"type" : "list",
4444
"description" : "A list of fields to extract and return from the _source field"
4545
},

‎rest-api-spec/src/main/resources/rest-api-spec/api/update_by_query.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -106,11 +106,11 @@
106106
"type" : "list",
107107
"description" : "True or false to return the _source field or not, or a list of fields to return"
108108
},
109-
"_source_exclude": {
109+
"_source_excludes": {
110110
"type" : "list",
111111
"description" : "A list of fields to exclude from the returned _source field"
112112
},
113-
"_source_include": {
113+
"_source_includes": {
114114
"type" : "list",
115115
"description" : "A list of fields to extract and return from the _source field"
116116
},

‎rest-api-spec/src/main/resources/rest-api-spec/test/bulk/40_source.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@
6666
bulk:
6767
index: test_index
6868
type: test_type
69-
_source_include: foo
69+
_source_includes: foo
7070
body: |
7171
{ "update": { "_id": "test_id_3" } }
7272
{ "doc": { "foo": "garply" } }

‎rest-api-spec/src/main/resources/rest-api-spec/test/explain/20_source_filtering.yml

+3-3
Original file line numberDiff line numberDiff line change
@@ -27,18 +27,18 @@
2727
- is_false: get._source.include.field2
2828

2929
- do:
30-
explain: { index: test_1, type: test, id: 1, _source_include: include.field1, body: { query: { match_all: {}} } }
30+
explain: { index: test_1, type: test, id: 1, _source_includes: include.field1, body: { query: { match_all: {}} } }
3131
- match: { get._source.include.field1: v1 }
3232
- is_false: get._source.include.field2
3333

3434
- do:
35-
explain: { index: test_1, type: test, id: 1, _source_include: "include.field1,include.field2", body: { query: { match_all: {}} } }
35+
explain: { index: test_1, type: test, id: 1, _source_includes: "include.field1,include.field2", body: { query: { match_all: {}} } }
3636
- match: { get._source.include.field1: v1 }
3737
- match: { get._source.include.field2: v2 }
3838
- is_false: get._source.count
3939

4040
- do:
41-
explain: { index: test_1, type: test, id: 1, _source_include: include, _source_exclude: "*.field2", body: { query: { match_all: {}} } }
41+
explain: { index: test_1, type: test, id: 1, _source_includes: include, _source_excludes: "*.field2", body: { query: { match_all: {}} } }
4242
- match: { get._source.include.field1: v1 }
4343
- is_false: get._source.include.field2
4444
- is_false: get._source.count

‎rest-api-spec/src/main/resources/rest-api-spec/test/get/70_source_filtering.yml

+37-3
Original file line numberDiff line numberDiff line change
@@ -36,18 +36,18 @@
3636
- is_false: _source.include.field2
3737

3838
- do:
39-
get: { index: test_1, type: test, id: 1, _source_include: include.field1 }
39+
get: { index: test_1, type: test, id: 1, _source_includes: include.field1 }
4040
- match: { _source.include.field1: v1 }
4141
- is_false: _source.include.field2
4242

4343
- do:
44-
get: { index: test_1, type: test, id: 1, _source_include: "include.field1,include.field2" }
44+
get: { index: test_1, type: test, id: 1, _source_includes: "include.field1,include.field2" }
4545
- match: { _source.include.field1: v1 }
4646
- match: { _source.include.field2: v2 }
4747
- is_false: _source.count
4848

4949
- do:
50-
get: { index: test_1, type: test, id: 1, _source_include: include, _source_exclude: "*.field2" }
50+
get: { index: test_1, type: test, id: 1, _source_includes: include, _source_excludes: "*.field2" }
5151
- match: { _source.include.field1: v1 }
5252
- is_false: _source.include.field2
5353
- is_false: _source.count
@@ -66,3 +66,37 @@
6666
- match: { _id: "1" }
6767
- match: { fields.count: [1] }
6868
- match: { _source.include.field1: v1 }
69+
70+
---
71+
"Deprecated _source_include and _source_exclude":
72+
73+
- skip:
74+
version: " - 6.99.99"
75+
reason: _source_include and _source_exclude are deprecated from 6.6.0
76+
features: "warnings"
77+
78+
- do:
79+
indices.create:
80+
index: test_1
81+
body:
82+
mappings:
83+
_doc:
84+
properties:
85+
count:
86+
type: integer
87+
store: true
88+
89+
- do:
90+
index:
91+
index: test_1
92+
type: _doc
93+
id: 1
94+
body: { "include": { "field1": "v1", "field2": "v2" }, "count": 1 }
95+
- do:
96+
get: { index: test_1, type: _doc, id: 1, _source_include: include.field1 }
97+
warnings:
98+
- "Deprecated parameter [_source_include] used, expected [_source_includes] instead"
99+
- do:
100+
get: { index: test_1, type: _doc, id: 1, _source_includes: include, _source_exclude: "*.field2" }
101+
warnings:
102+
- "Deprecated parameter [_source_exclude] used, expected [_source_excludes] instead"

‎rest-api-spec/src/main/resources/rest-api-spec/test/get_source/70_source_filtering.yml

+3-3
Original file line numberDiff line numberDiff line change
@@ -9,18 +9,18 @@
99
body: { "include": { "field1": "v1", "field2": "v2" }, "count": 1 }
1010

1111
- do:
12-
get_source: { index: test_1, type: test, id: 1, _source_include: include.field1 }
12+
get_source: { index: test_1, type: test, id: 1, _source_includes: include.field1 }
1313
- match: { include.field1: v1 }
1414
- is_false: include.field2
1515

1616
- do:
17-
get_source: { index: test_1, type: test, id: 1, _source_include: "include.field1,include.field2" }
17+
get_source: { index: test_1, type: test, id: 1, _source_includes: "include.field1,include.field2" }
1818
- match: { include.field1: v1 }
1919
- match: { include.field2: v2 }
2020
- is_false: count
2121

2222
- do:
23-
get_source: { index: test_1, type: test, id: 1, _source_include: include, _source_exclude: "*.field2" }
23+
get_source: { index: test_1, type: test, id: 1, _source_includes: include, _source_excludes: "*.field2" }
2424
- match: { include.field1: v1 }
2525
- is_false: include.field2
2626
- is_false: count

‎rest-api-spec/src/main/resources/rest-api-spec/test/mget/70_source_filtering.yml

+3-3
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ setup:
100100

101101
- do:
102102
mget:
103-
_source_include: "include.field1,count"
103+
_source_includes: "include.field1,count"
104104
index: test_1
105105
body: { ids: [ 1,2 ] }
106106
- match: { docs.0._source: { include: { field1: v1 }, count: 1} }
@@ -111,8 +111,8 @@ setup:
111111

112112
- do:
113113
mget:
114-
_source_include: include
115-
_source_exclude: "*.field2"
114+
_source_includes: include
115+
_source_excludes: "*.field2"
116116
index: test_1
117117
body: { ids: [ 1,2 ] }
118118
- match: { docs.0._source: { include: { field1: v1 } } }

0 commit comments

Comments
 (0)