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
elastic · Oct 29, 2018 · 6df1c9e · 6df1c9e
1 parent 42b4f23
commit 6df1c9e
Show file tree

Hide file tree

Showing 26 changed files with 118 additions and 63 deletions.
diff --git a/client/rest-high-level/src/main/java/org/elasticsearch/client/RequestConverters.java b/client/rest-high-level/src/main/java/org/elasticsearch/client/RequestConverters.java
@@ -705,10 +705,10 @@ Params withFetchSourceContext(FetchSourceContext fetchSourceContext) {
                     putParam("_source", Boolean.FALSE.toString());
                 }
                 if (fetchSourceContext.includes() != null && fetchSourceContext.includes().length > 0) {
-                    putParam("_source_include", String.join(",", fetchSourceContext.includes()));
+                    putParam("_source_includes", String.join(",", fetchSourceContext.includes()));
                 }
                 if (fetchSourceContext.excludes() != null && fetchSourceContext.excludes().length > 0) {
-                    putParam("_source_exclude", String.join(",", fetchSourceContext.excludes()));
+                    putParam("_source_excludes", String.join(",", fetchSourceContext.excludes()));
                 }
             }
             return this;

diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/RequestConvertersTests.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/RequestConvertersTests.java
@@ -1514,13 +1514,13 @@ private static void randomizeFetchSourceContextParams(Consumer<FetchSourceContex
                 String[] includes = new String[numIncludes];
                 String includesParam = randomFields(includes);
                 if (numIncludes > 0) {
-                    expectedParams.put("_source_include", includesParam);
+                    expectedParams.put("_source_includes", includesParam);
                 }
                 int numExcludes = randomIntBetween(0, 5);
                 String[] excludes = new String[numExcludes];
                 String excludesParam = randomFields(excludes);
                 if (numExcludes > 0) {
-                    expectedParams.put("_source_exclude", excludesParam);
+                    expectedParams.put("_source_excludes", excludesParam);
                 }
                 consumer.accept(new FetchSourceContext(true, includes, excludes));
             }

diff --git a/docs/reference/docs/get.asciidoc b/docs/reference/docs/get.asciidoc
@@ -73,14 +73,14 @@ GET twitter/_doc/0?_source=false
 // CONSOLE
 // TEST[setup:twitter]
 
-If you only need one or two fields from the complete `_source`, you can use the `_source_include`
-& `_source_exclude` parameters to include or filter out that parts you need. This can be especially helpful
+If you only need one or two fields from the complete `_source`, you can use the `_source_includes`
+& `_source_excludes` parameters to include or filter out that parts you need. This can be especially helpful
 with large documents where partial retrieval can save on network overhead. Both parameters take a comma separated list
 of fields or wildcard expressions. Example:
 
 [source,js]
 --------------------------------------------------
-GET twitter/_doc/0?_source_include=*.id&_source_exclude=entities
+GET twitter/_doc/0?_source_includes=*.id&_source_excludes=entities
 --------------------------------------------------
 // CONSOLE
 // TEST[setup:twitter]
@@ -232,7 +232,7 @@ You can also use the same source filtering parameters to control which parts of
 
 [source,js]
 --------------------------------------------------
-GET twitter/_doc/1/_source?_source_include=*.id&_source_exclude=entities'
+GET twitter/_doc/1/_source?_source_includes=*.id&_source_excludes=entities'
 --------------------------------------------------
 // CONSOLE
 // TEST[continued]

diff --git a/docs/reference/docs/multi-get.asciidoc b/docs/reference/docs/multi-get.asciidoc
@@ -89,7 +89,7 @@ GET /test/_doc/_mget
 By default, the `_source` field will be returned for every document (if stored).
 Similar to the <<get-source-filtering,get>> API, you can retrieve only parts of
 the `_source` (or not at all) by using the `_source` parameter. You can also use
-the url parameters `_source`,`_source_include` & `_source_exclude` to specify defaults,
+the url parameters `_source`,`_source_includes` & `_source_excludes` to specify defaults,
 which will be used when there are no per-document instructions.
 
 For example:

diff --git a/docs/reference/search/explain.asciidoc b/docs/reference/search/explain.asciidoc
@@ -122,7 +122,7 @@ This will yield the same result as the previous request.
 `_source`::
 
     Set to `true` to retrieve the `_source` of the document explained. You can also
-    retrieve part of the document by using `_source_include` & `_source_exclude` (see <<get-source-filtering,Get API>> for more details)
+    retrieve part of the document by using `_source_includes` & `_source_excludes` (see <<get-source-filtering,Get API>> for more details)
 
 `stored_fields`::
     Allows to control which stored fields to return as part of the

diff --git a/docs/reference/search/uri-request.asciidoc b/docs/reference/search/uri-request.asciidoc
@@ -83,7 +83,7 @@ providing text to a numeric field) to be ignored. Defaults to false.
 hits was computed.
 
 |`_source`|Set to `false` to disable retrieval of the `_source` field. You can also retrieve
-part of the document by using `_source_include` & `_source_exclude` (see the <<search-request-source-filtering, request body>>
+part of the document by using `_source_includes` & `_source_excludes` (see the <<search-request-source-filtering, request body>>
 documentation for more details)
 
 |`stored_fields` |The selective stored fields of the document to return for each hit,

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/bulk.json b/rest-api-spec/src/main/resources/rest-api-spec/api/bulk.json
@@ -45,11 +45,11 @@
           "type" : "list",
           "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"
         },
-        "_source_exclude": {
+        "_source_excludes": {
           "type" : "list",
           "description" : "Default list of fields to exclude from the returned _source field, can be overridden on each sub-request"
         },
-        "_source_include": {
+        "_source_includes": {
           "type" : "list",
           "description" : "Default list of fields to extract and return from the _source field, can be overridden on each sub-request"
         },

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/delete_by_query.json b/rest-api-spec/src/main/resources/rest-api-spec/api/delete_by_query.json
@@ -102,11 +102,11 @@
           "type" : "list",
           "description" : "True or false to return the _source field or not, or a list of fields to return"
         },
-        "_source_exclude": {
+        "_source_excludes": {
           "type" : "list",
           "description" : "A list of fields to exclude from the returned _source field"
         },
-        "_source_include": {
+        "_source_includes": {
           "type" : "list",
           "description" : "A list of fields to extract and return from the _source field"
         },

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/exists.json b/rest-api-spec/src/main/resources/rest-api-spec/api/exists.json
@@ -51,11 +51,11 @@
           "type" : "list",
           "description" : "True or false to return the _source field or not, or a list of fields to return"
         },
-        "_source_exclude": {
+        "_source_excludes": {
           "type" : "list",
           "description" : "A list of fields to exclude from the returned _source field"
         },
-        "_source_include": {
+        "_source_includes": {
           "type" : "list",
           "description" : "A list of fields to extract and return from the _source field"
         },

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/exists_source.json b/rest-api-spec/src/main/resources/rest-api-spec/api/exists_source.json
@@ -47,11 +47,11 @@
           "type" : "list",
           "description" : "True or false to return the _source field or not, or a list of fields to return"
         },
-        "_source_exclude": {
+        "_source_excludes": {
           "type" : "list",
           "description" : "A list of fields to exclude from the returned _source field"
         },
-        "_source_include": {
+        "_source_includes": {
           "type" : "list",
           "description" : "A list of fields to extract and return from the _source field"
         },

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/explain.json b/rest-api-spec/src/main/resources/rest-api-spec/api/explain.json
@@ -69,11 +69,11 @@
           "type" : "list",
           "description" : "True or false to return the _source field or not, or a list of fields to return"
         },
-        "_source_exclude": {
+        "_source_excludes": {
           "type" : "list",
           "description" : "A list of fields to exclude from the returned _source field"
         },
-        "_source_include": {
+        "_source_includes": {
           "type" : "list",
           "description" : "A list of fields to extract and return from the _source field"
         }

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/get.json b/rest-api-spec/src/main/resources/rest-api-spec/api/get.json
@@ -54,6 +54,14 @@
           "type" : "list",
           "description" : "True or false to return the _source field or not, or a list of fields to return"
         },
+        "_source_excludes": {
+          "type" : "list",
+          "description" : "A list of fields to exclude from the returned _source field"
+        },
+        "_source_includes": {
+          "type" : "list",
+          "description" : "A list of fields to extract and return from the _source field"
+        },
         "_source_exclude": {
           "type" : "list",
           "description" : "A list of fields to exclude from the returned _source field"

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/get_source.json b/rest-api-spec/src/main/resources/rest-api-spec/api/get_source.json
@@ -47,11 +47,11 @@
           "type" : "list",
           "description" : "True or false to return the _source field or not, or a list of fields to return"
         },
-        "_source_exclude": {
+        "_source_excludes": {
           "type" : "list",
           "description" : "A list of fields to exclude from the returned _source field"
         },
-        "_source_include": {
+        "_source_includes": {
           "type" : "list",
           "description" : "A list of fields to extract and return from the _source field"
         },

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/mget.json b/rest-api-spec/src/main/resources/rest-api-spec/api/mget.json
@@ -40,11 +40,11 @@
           "type" : "list",
           "description" : "True or false to return the _source field or not, or a list of fields to return"
         },
-        "_source_exclude": {
+        "_source_excludes": {
           "type" : "list",
           "description" : "A list of fields to exclude from the returned _source field"
         },
-        "_source_include": {
+        "_source_includes": {
           "type" : "list",
           "description" : "A list of fields to extract and return from the _source field"
         }

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/search.json b/rest-api-spec/src/main/resources/rest-api-spec/api/search.json
@@ -105,11 +105,11 @@
           "type" : "list",
           "description" : "True or false to return the _source field or not, or a list of fields to return"
         },
-        "_source_exclude": {
+        "_source_excludes": {
           "type" : "list",
           "description" : "A list of fields to exclude from the returned _source field"
         },
-        "_source_include": {
+        "_source_includes": {
           "type" : "list",
           "description" : "A list of fields to extract and return from the _source field"
         },

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/update.json b/rest-api-spec/src/main/resources/rest-api-spec/api/update.json
@@ -34,11 +34,11 @@
           "type" : "list",
           "description" : "True or false to return the _source field or not, or a list of fields to return"
         },
-        "_source_exclude": {
+        "_source_excludes": {
           "type" : "list",
           "description" : "A list of fields to exclude from the returned _source field"
         },
-        "_source_include": {
+        "_source_includes": {
           "type" : "list",
           "description" : "A list of fields to extract and return from the _source field"
         },

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/update_by_query.json b/rest-api-spec/src/main/resources/rest-api-spec/api/update_by_query.json
@@ -106,11 +106,11 @@
           "type" : "list",
           "description" : "True or false to return the _source field or not, or a list of fields to return"
         },
-        "_source_exclude": {
+        "_source_excludes": {
           "type" : "list",
           "description" : "A list of fields to exclude from the returned _source field"
         },
-        "_source_include": {
+        "_source_includes": {
           "type" : "list",
           "description" : "A list of fields to extract and return from the _source field"
         },

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/test/bulk/40_source.yml b/rest-api-spec/src/main/resources/rest-api-spec/test/bulk/40_source.yml
@@ -73,7 +73,7 @@
       bulk:
         include_type_name: false
         index: test_index
-        _source_include: foo
+        _source_includes: foo
         body: |
           { "update": { "_id": "test_id_3" } }
           { "doc": { "foo": "garply" } }

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/test/bulk/41_source_with_types.yml b/rest-api-spec/src/main/resources/rest-api-spec/test/bulk/41_source_with_types.yml
@@ -66,7 +66,7 @@
       bulk:
         index: test_index
         type: test_type
-        _source_include: foo
+        _source_includes: foo
         body: |
           { "update": { "_id": "test_id_3" } }
           { "doc": { "foo": "garply" } }

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/test/explain/20_source_filtering.yml b/rest-api-spec/src/main/resources/rest-api-spec/test/explain/20_source_filtering.yml
@@ -27,18 +27,18 @@
   - is_false: get._source.include.field2
 
   - do:
-      explain: { index:  test_1, type: test, id: 1, _source_include: include.field1, body: { query: { match_all: {}} } }
+      explain: { index:  test_1, type: test, id: 1, _source_includes: include.field1, body: { query: { match_all: {}} } }
   - match:  { get._source.include.field1: v1 }
   - is_false: get._source.include.field2
 
   - do:
-      explain: { index:  test_1, type: test, id: 1, _source_include: "include.field1,include.field2", body: { query: { match_all: {}} } }
+      explain: { index:  test_1, type: test, id: 1, _source_includes: "include.field1,include.field2", body: { query: { match_all: {}} } }
   - match:  { get._source.include.field1: v1 }
   - match:  { get._source.include.field2: v2 }
   - is_false: get._source.count
 
   - do:
-      explain: { index:  test_1, type: test, id: 1, _source_include: include, _source_exclude: "*.field2", body: { query: { match_all: {}} } }
+      explain: { index:  test_1, type: test, id: 1, _source_includes: include, _source_excludes: "*.field2", body: { query: { match_all: {}} } }
   - match:  { get._source.include.field1: v1 }
   - is_false: get._source.include.field2
   - is_false: get._source.count
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/test/get/70_source_filtering.yml b/rest-api-spec/src/main/resources/rest-api-spec/test/get/70_source_filtering.yml
@@ -40,18 +40,18 @@
   - is_false: _source.include.field2
 
   - do:
-      get: { include_type_name: false, index:  test_1, id: 1, _source_include: include.field1 }
+      get: { include_type_name: false, index:  test_1, id: 1, _source_includes: include.field1 }
   - match:  { _source.include.field1: v1 }
   - is_false: _source.include.field2
 
   - do:
-      get: { include_type_name: false, index:  test_1, id: 1, _source_include: "include.field1,include.field2" }
+      get: { include_type_name: false, index:  test_1, id: 1, _source_includes: "include.field1,include.field2" }
   - match:  { _source.include.field1: v1 }
   - match:  { _source.include.field2: v2 }
   - is_false: _source.count
 
   - do:
-      get: { include_type_name: false, index:  test_1, id: 1, _source_include: include, _source_exclude: "*.field2" }
+      get: { include_type_name: false, index:  test_1, id: 1, _source_includes: include, _source_excludes: "*.field2" }
   - match:  { _source.include.field1: v1 }
   - is_false: _source.include.field2
   - is_false: _source.count
@@ -70,3 +70,37 @@
   - match:   { _id:      "1"       }
   - match:   { fields.count:  [1] }
   - match:   { _source.include.field1: v1 }
+
+---
+"Deprecated _source_include and _source_exclude":
+
+  - skip:
+      version: " - 6.99.99"
+      reason: _source_include and _source_exclude are deprecated from 6.6.0
+      features: "warnings"
+
+  - do:
+      indices.create:
+        index: test_1
+        body:
+          mappings:
+            _doc:
+              properties:
+                count:
+                  type: integer
+                  store: true
+
+  - do:
+      index:
+        index:  test_1
+        type:   _doc
+        id:     1
+        body:   { "include": { "field1": "v1", "field2": "v2" }, "count": 1 }
+  - do:
+      get: { index:  test_1, type: _doc, id: 1, _source_include: include.field1 }
+      warnings:
+           - "Deprecated parameter [_source_include] used, expected [_source_includes] instead"
+  - do:
+      get: { index:  test_1, type: _doc, id: 1, _source_includes: include, _source_exclude: "*.field2" }
+      warnings:
+           - "Deprecated parameter [_source_exclude] used, expected [_source_excludes] instead"
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/test/get/71_source_filtering_with_types.yml b/rest-api-spec/src/main/resources/rest-api-spec/test/get/71_source_filtering_with_types.yml
@@ -36,18 +36,18 @@
   - is_false: _source.include.field2
 
   - do:
-      get: { index:  test_1, type: test, id: 1, _source_include: include.field1 }
+      get: { index:  test_1, type: test, id: 1, _source_includes: include.field1 }
   - match:  { _source.include.field1: v1 }
   - is_false: _source.include.field2
 
   - do:
-      get: { index:  test_1, type: test, id: 1, _source_include: "include.field1,include.field2" }
+      get: { index:  test_1, type: test, id: 1, _source_includes: "include.field1,include.field2" }
   - match:  { _source.include.field1: v1 }
   - match:  { _source.include.field2: v2 }
   - is_false: _source.count
 
   - do:
-      get: { index:  test_1, type: test, id: 1, _source_include: include, _source_exclude: "*.field2" }
+      get: { index:  test_1, type: test, id: 1, _source_includes: include, _source_excludes: "*.field2" }
   - match:  { _source.include.field1: v1 }
   - is_false: _source.include.field2
   - is_false: _source.count

diff --git a/rest-api-spec/src/main/resources/rest-api-spec/test/get_source/70_source_filtering.yml b/rest-api-spec/src/main/resources/rest-api-spec/test/get_source/70_source_filtering.yml
@@ -9,18 +9,18 @@
         body:   { "include": { "field1": "v1", "field2": "v2" }, "count": 1 }
 
   - do:
-      get_source: { index:  test_1, type: test, id: 1, _source_include: include.field1 }
+      get_source: { index:  test_1, type: test, id: 1, _source_includes: include.field1 }
   - match:  { include.field1: v1 }
   - is_false: include.field2
 
   - do:
-      get_source: { index:  test_1, type: test, id: 1, _source_include: "include.field1,include.field2" }
+      get_source: { index:  test_1, type: test, id: 1, _source_includes: "include.field1,include.field2" }
   - match:  { include.field1: v1 }
   - match:  { include.field2: v2 }
   - is_false: count
 
   - do:
-      get_source: { index:  test_1, type: test, id: 1, _source_include: include, _source_exclude: "*.field2" }
+      get_source: { index:  test_1, type: test, id: 1, _source_includes: include, _source_excludes: "*.field2" }
   - match:  { include.field1: v1 }
   - is_false: include.field2
   - is_false: count