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

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

@@ -705,10 +705,10 @@ final class RequestConverters {
                     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;

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

@@ -1514,13 +1514,13 @@ public class RequestConvertersTests extends ESTestCase {
                 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));
             }

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]

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:

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

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,

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"
         },

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"
         },

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"
         },

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"
         },

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"
         }

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"

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"
         },

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"
         }

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"
         },

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"
         },

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"
         },

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" } }

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" } }

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

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"

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

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

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

@@ -100,7 +100,7 @@ setup:
 
   - do:
       mget:
-        _source_include: "include.field1,count"
+        _source_includes: "include.field1,count"
         index: test_1
         body: { ids: [ 1,2 ] }
   - match:   { docs.0._source: { include: { field1: v1 }, count: 1} }
@@ -111,8 +111,8 @@ setup:
 
   - do:
       mget:
-        _source_include: include
-        _source_exclude: "*.field2"
+        _source_includes: include
+        _source_excludes: "*.field2"
         index: test_1
         body: { ids: [ 1,2 ] }
   - match:   { docs.0._source: { include: { field1: v1 } } }

rest-api-spec/src/main/resources/rest-api-spec/test/search/10_source_filtering.yml

@@ -49,20 +49,20 @@ setup:
   - is_false: hits.hits.0._source.include.field2
 
 ---
-"_source include and _source in body":
-  - do: { search: { _source_include: include.field1, body: { _source: include.field2, query: { match_all: {} } } } }
+"_source_includes and _source in body":
+  - do: { search: { _source_includes: include.field1, body: { _source: include.field2, query: { match_all: {} } } } }
   - match:  { hits.hits.0._source.include.field1: v1 }
   - is_false: hits.hits.0._source.include.field2
 
 ---
-"_source_include":
-  - do: { search: { _source_include: include.field1, body: { query: { match_all: {} } } } }
+"_source_includes":
+  - do: { search: { _source_includes: include.field1, body: { query: { match_all: {} } } } }
   - match:  { hits.hits.0._source.include.field1: v1 }
   - is_false: hits.hits.0._source.include.field2
 
 ---
-"_source_exclude":
-  - do: { search: { _source_exclude: count, body: { query: { match_all: {} } } } }
+"_source_excludes":
+  - do: { search: { _source_excludes: count, body: { query: { match_all: {} } } } }
   - match:  { hits.hits.0._source.include: { field1 : v1 , field2: v2 }}
   - is_false: hits.hits.0._source.count
 

server/src/main/java/org/elasticsearch/search/fetch/subphase/FetchSourceContext.java

@@ -19,6 +19,7 @@
 
 package org.elasticsearch.search.fetch.subphase;
 
+import org.apache.logging.log4j.LogManager;
 import org.elasticsearch.common.Booleans;
 import org.elasticsearch.common.ParseField;
 import org.elasticsearch.common.ParsingException;
@@ -26,6 +27,7 @@ import org.elasticsearch.common.Strings;
 import org.elasticsearch.common.io.stream.StreamInput;
 import org.elasticsearch.common.io.stream.StreamOutput;
 import org.elasticsearch.common.io.stream.Writeable;
+import org.elasticsearch.common.logging.DeprecationLogger;
 import org.elasticsearch.common.xcontent.ToXContentObject;
 import org.elasticsearch.common.xcontent.XContentBuilder;
 import org.elasticsearch.common.xcontent.XContentParser;
@@ -44,6 +46,8 @@ import java.util.function.Function;
  */
 public class FetchSourceContext implements Writeable, ToXContentObject {
 
+    private static final DeprecationLogger DEPRECATION_LOGGER = new DeprecationLogger(LogManager.getLogger(FetchSourceContext.class));
+
     public static final ParseField INCLUDES_FIELD = new ParseField("includes", "include");
     public static final ParseField EXCLUDES_FIELD = new ParseField("excludes", "exclude");
 
@@ -91,8 +95,8 @@ public class FetchSourceContext implements Writeable, ToXContentObject {
 
     public static FetchSourceContext parseFromRestRequest(RestRequest request) {
         Boolean fetchSource = null;
-        String[] source_excludes = null;
-        String[] source_includes = null;
+        String[] sourceExcludes = null;
+        String[] sourceIncludes = null;
 
         String source = request.param("_source");
         if (source != null) {
@@ -101,23 +105,32 @@ public class FetchSourceContext implements Writeable, ToXContentObject {
             } else if (Booleans.isFalse(source)) {
                 fetchSource = false;
             } else {
-                source_includes = Strings.splitStringByCommaToArray(source);
+                sourceIncludes = Strings.splitStringByCommaToArray(source);
             }
         }
+
         String sIncludes = request.param("_source_includes");
-        sIncludes = request.param("_source_include", sIncludes);
+        String sInclude = request.param("_source_include");
+        if (sInclude != null) {
+            DEPRECATION_LOGGER.deprecated("Deprecated parameter [_source_include] used, expected [_source_includes] instead");
+            sIncludes = sInclude;
+        }
         if (sIncludes != null) {
-            source_includes = Strings.splitStringByCommaToArray(sIncludes);
+            sourceIncludes = Strings.splitStringByCommaToArray(sIncludes);
         }
 
         String sExcludes = request.param("_source_excludes");
-        sExcludes = request.param("_source_exclude", sExcludes);
+        String sExclude = request.param("_source_exclude");
+        if (sExclude != null) {
+            DEPRECATION_LOGGER.deprecated("Deprecated parameter [_source_exclude] used, expected [_source_excludes] instead");
+            sExcludes = sExclude;
+        }
         if (sExcludes != null) {
-            source_excludes = Strings.splitStringByCommaToArray(sExcludes);
+            sourceExcludes = Strings.splitStringByCommaToArray(sExcludes);
         }
 
-        if (fetchSource != null || source_includes != null || source_excludes != null) {
-            return new FetchSourceContext(fetchSource == null ? true : fetchSource, source_includes, source_excludes);
+        if (fetchSource != null || sourceIncludes != null || sourceExcludes != null) {
+            return new FetchSourceContext(fetchSource == null ? true : fetchSource, sourceIncludes, sourceExcludes);
         }
         return null;
     }