Pārlūkot izejas kodu

[DOCS] Move source filtering examples (#57689)

Moves the source filtering example snippets form the "Request body
search" API docs page to the "Return fields in a search" section of the
"Run a search" page.
James Rodewig 5 gadi atpakaļ
vecāks
revīzija
7f201d7f4f

+ 5 - 0
docs/reference/redirects.asciidoc

@@ -903,4 +903,9 @@ For search examples, see <<run-a-search>>.
 ==== From / size
 
 See <<paginate-search-results>>.
+
+[role="exclude",id="request-body-search-source-filtering"]
+==== Source filtering
+
+See <<search-fields>>.
 ////

+ 3 - 1
docs/reference/search/request/from-size.asciidoc

@@ -25,7 +25,9 @@ GET /_search
   "from": 5,
   "size": 20,
   "query": {
-    "term": { "user": "kimchy" }
+    "term": {
+      "user.id": "8a4f500d"
+    }
   }
 }
 ----

+ 1 - 68
docs/reference/search/request/source-filtering.asciidoc

@@ -1,71 +1,4 @@
 [[request-body-search-source-filtering]]
 ==== Source filtering
 
-
-Allows to control how the `_source` field is returned with every hit.
-
-By default operations return the contents of the `_source` field unless
-you have used the `stored_fields` parameter or if the `_source` field is disabled.
-
-You can turn off `_source` retrieval by using the `_source` parameter:
-
-To disable `_source` retrieval set to `false`:
-
-[source,console]
---------------------------------------------------
-GET /_search
-{
-    "_source": false,
-    "query" : {
-        "term" : { "user" : "kimchy" }
-    }
-}
---------------------------------------------------
-
-The `_source` also accepts one or more wildcard patterns to control what parts of the `_source` should be returned:
-
-For example:
-
-[source,console]
---------------------------------------------------
-GET /_search
-{
-    "_source": "obj.*",
-    "query" : {
-        "term" : { "user" : "kimchy" }
-    }
-}
---------------------------------------------------
-
-Or
-
-[source,console]
---------------------------------------------------
-GET /_search
-{
-    "_source": [ "obj1.*", "obj2.*" ],
-    "query" : {
-        "term" : { "user" : "kimchy" }
-    }
-}
---------------------------------------------------
-
-Finally, for complete control, you can specify both `includes` and `excludes`
-patterns. If `includes` is not empty, then only fields that match one of the
-patterns in `includes` but none of the patterns in `excludes` are provided in
-`_source`. If `includes` is empty, then all fields are provided in `_source`,
-except for those that match a pattern in `excludes`.
-
-[source,console]
---------------------------------------------------
-GET /_search
-{
-    "_source": {
-        "includes": [ "obj1.*", "obj2.*" ],
-        "excludes": [ "*.description" ]
-    },
-    "query" : {
-        "term" : { "user" : "kimchy" }
-    }
-}
---------------------------------------------------
+See <<search-fields>>.

+ 86 - 3
docs/reference/search/search-fields.asciidoc

@@ -5,9 +5,92 @@
 By default, each hit in the search response includes the document
 <<mapping-source-field,`_source`>>, which is the entire JSON object that was
 provided when indexing the document. If you only need certain fields in the
-search response, you can use
-<<request-body-search-source-filtering,source filtering>> to restrict what
-parts of the source are returned.
+search response, you can use the
+<<request-body-search-source-filtering,`_source`>> parameter to restrict what
+parts of the source are returned. This is called _source filtering_.
+
+.*Example*
+[%collapsible]
+====
+The following search API request sets the `_source` request body parameter to
+`false`. The document source is not included in the response.
+
+[source,console]
+----
+GET /_search
+{
+  "_source": false,
+  "query": {
+    "term": {
+      "user.id": "8a4f500d"
+    }
+  }
+}
+----
+
+To return only a subset of source fields, specify a wildcard (`*`) pattern in
+the `_source` parameter. The following search API request returns the source for
+only the `obj` field and its properties.
+
+[source,console]
+----
+GET /_search
+{
+  "_source": "obj.*",
+  "query": {
+    "term": {
+      "user.id": "8a4f500d"
+    }
+  }
+}
+----
+
+You can also specify an array of wildcard patterns in the `_source` field. The
+following search API request returns the source for only the `obj1` and
+`obj2` fields and their properties.
+
+[source,console]
+----
+GET /_search
+{
+  "_source": [ "obj1.*", "obj2.*" ],
+  "query": {
+    "term": {
+      "user.id": "8a4f500d"
+    }
+  }
+}
+----
+
+For finer control, you can specify an object containing arrays of `includes` and
+`excludes` patterns in the `_source` parameter.
+
+If the `includes` property is specified, only source fields that match one of
+its patterns are returned. You can exclude fields from this subset using the
+`excludes` property.
+
+If the `includes` property is not specified, the entire document source is
+returned, excluding any fields that match a pattern in the `excludes` property.
+
+The following search API request returns the source for only the `obj1` and
+`obj2` fields and their properties, excluding any child `description` fields.
+
+[source,console]
+----
+GET /_search
+{
+  "_source": {
+    "includes": [ "obj1.*", "obj2.*" ],
+    "excludes": [ "*.description" ]
+  },
+  "query": {
+    "term": {
+      "user.id": "8a4f500d"
+    }
+  }
+}
+----
+====
 
 Returning fields using only the document source has some limitations: