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

Author: lipsill

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

@@ -747,10 +747,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;

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

@@ -1589,13 +1589,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));
             }

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/migration/migrate_6_6.asciidoc

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

docs/reference/search/explain.asciidoc

@@ -117,7 +117,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"
         },