Skip to content

Commit 6df1c9e

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 42b4f23 commit 6df1c9e

File tree

26 files changed

+118
-63
lines changed

26 files changed

+118
-63
lines changed

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -705,10 +705,10 @@ Params withFetchSourceContext(FetchSourceContext fetchSourceContext) {
705705
putParam("_source", Boolean.FALSE.toString());
706706
}
707707
if (fetchSourceContext.includes() != null && fetchSourceContext.includes().length > 0) {
708-
putParam("_source_include", String.join(",", fetchSourceContext.includes()));
708+
putParam("_source_includes", String.join(",", fetchSourceContext.includes()));
709709
}
710710
if (fetchSourceContext.excludes() != null && fetchSourceContext.excludes().length > 0) {
711-
putParam("_source_exclude", String.join(",", fetchSourceContext.excludes()));
711+
putParam("_source_excludes", String.join(",", fetchSourceContext.excludes()));
712712
}
713713
}
714714
return this;

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1514,13 +1514,13 @@ private static void randomizeFetchSourceContextParams(Consumer<FetchSourceContex
15141514
String[] includes = new String[numIncludes];
15151515
String includesParam = randomFields(includes);
15161516
if (numIncludes > 0) {
1517-
expectedParams.put("_source_include", includesParam);
1517+
expectedParams.put("_source_includes", includesParam);
15181518
}
15191519
int numExcludes = randomIntBetween(0, 5);
15201520
String[] excludes = new String[numExcludes];
15211521
String excludesParam = randomFields(excludes);
15221522
if (numExcludes > 0) {
1523-
expectedParams.put("_source_exclude", excludesParam);
1523+
expectedParams.put("_source_excludes", excludesParam);
15241524
}
15251525
consumer.accept(new FetchSourceContext(true, includes, excludes));
15261526
}

‎docs/reference/docs/get.asciidoc

Lines changed: 4 additions & 4 deletions
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

Lines changed: 1 addition & 1 deletion
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/search/explain.asciidoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@ This will yield the same result as the previous request.
122122
`_source`::
123123

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

127127
`stored_fields`::
128128
Allows to control which stored fields to return as part of the

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

Lines changed: 1 addition & 1 deletion
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

Lines changed: 2 additions & 2 deletions
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

Lines changed: 2 additions & 2 deletions
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

Lines changed: 2 additions & 2 deletions
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

Lines changed: 2 additions & 2 deletions
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

Lines changed: 2 additions & 2 deletions
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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,14 @@
5454
"type" : "list",
5555
"description" : "True or false to return the _source field or not, or a list of fields to return"
5656
},
57+
"_source_excludes": {
58+
"type" : "list",
59+
"description" : "A list of fields to exclude from the returned _source field"
60+
},
61+
"_source_includes": {
62+
"type" : "list",
63+
"description" : "A list of fields to extract and return from the _source field"
64+
},
5765
"_source_exclude": {
5866
"type" : "list",
5967
"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

Lines changed: 2 additions & 2 deletions
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

Lines changed: 2 additions & 2 deletions
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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -105,11 +105,11 @@
105105
"type" : "list",
106106
"description" : "True or false to return the _source field or not, or a list of fields to return"
107107
},
108-
"_source_exclude": {
108+
"_source_excludes": {
109109
"type" : "list",
110110
"description" : "A list of fields to exclude from the returned _source field"
111111
},
112-
"_source_include": {
112+
"_source_includes": {
113113
"type" : "list",
114114
"description" : "A list of fields to extract and return from the _source field"
115115
},

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,11 +34,11 @@
3434
"type" : "list",
3535
"description" : "True or false to return the _source field or not, or a list of fields to return"
3636
},
37-
"_source_exclude": {
37+
"_source_excludes": {
3838
"type" : "list",
3939
"description" : "A list of fields to exclude from the returned _source field"
4040
},
41-
"_source_include": {
41+
"_source_includes": {
4242
"type" : "list",
4343
"description" : "A list of fields to extract and return from the _source field"
4444
},

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

Lines changed: 2 additions & 2 deletions
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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@
7373
bulk:
7474
include_type_name: false
7575
index: test_index
76-
_source_include: foo
76+
_source_includes: foo
7777
body: |
7878
{ "update": { "_id": "test_id_3" } }
7979
{ "doc": { "foo": "garply" } }

‎rest-api-spec/src/main/resources/rest-api-spec/test/bulk/41_source_with_types.yml

Lines changed: 1 addition & 1 deletion
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

Lines changed: 3 additions & 3 deletions
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

Lines changed: 37 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,18 +40,18 @@
4040
- is_false: _source.include.field2
4141

4242
- do:
43-
get: { include_type_name: false, index: test_1, id: 1, _source_include: include.field1 }
43+
get: { include_type_name: false, index: test_1, id: 1, _source_includes: include.field1 }
4444
- match: { _source.include.field1: v1 }
4545
- is_false: _source.include.field2
4646

4747
- do:
48-
get: { include_type_name: false, index: test_1, id: 1, _source_include: "include.field1,include.field2" }
48+
get: { include_type_name: false, index: test_1, id: 1, _source_includes: "include.field1,include.field2" }
4949
- match: { _source.include.field1: v1 }
5050
- match: { _source.include.field2: v2 }
5151
- is_false: _source.count
5252

5353
- do:
54-
get: { include_type_name: false, index: test_1, id: 1, _source_include: include, _source_exclude: "*.field2" }
54+
get: { include_type_name: false, index: test_1, id: 1, _source_includes: include, _source_excludes: "*.field2" }
5555
- match: { _source.include.field1: v1 }
5656
- is_false: _source.include.field2
5757
- is_false: _source.count
@@ -70,3 +70,37 @@
7070
- match: { _id: "1" }
7171
- match: { fields.count: [1] }
7272
- match: { _source.include.field1: v1 }
73+
74+
---
75+
"Deprecated _source_include and _source_exclude":
76+
77+
- skip:
78+
version: " - 6.99.99"
79+
reason: _source_include and _source_exclude are deprecated from 6.6.0
80+
features: "warnings"
81+
82+
- do:
83+
indices.create:
84+
index: test_1
85+
body:
86+
mappings:
87+
_doc:
88+
properties:
89+
count:
90+
type: integer
91+
store: true
92+
93+
- do:
94+
index:
95+
index: test_1
96+
type: _doc
97+
id: 1
98+
body: { "include": { "field1": "v1", "field2": "v2" }, "count": 1 }
99+
- do:
100+
get: { index: test_1, type: _doc, id: 1, _source_include: include.field1 }
101+
warnings:
102+
- "Deprecated parameter [_source_include] used, expected [_source_includes] instead"
103+
- do:
104+
get: { index: test_1, type: _doc, id: 1, _source_includes: include, _source_exclude: "*.field2" }
105+
warnings:
106+
- "Deprecated parameter [_source_exclude] used, expected [_source_excludes] instead"

‎rest-api-spec/src/main/resources/rest-api-spec/test/get/71_source_filtering_with_types.yml

Lines changed: 3 additions & 3 deletions
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

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

Lines changed: 3 additions & 3 deletions
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

0 commit comments

Comments
 (0)