浏览代码

[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 年之前
父节点
当前提交
7f201d7f4f

+ 5 - 0
docs/reference/redirects.asciidoc

@@ -903,4 +903,9 @@ For search examples, see <<run-a-search>>.
 ==== From / size
 ==== From / size
 
 
 See <<paginate-search-results>>.
 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,
   "from": 5,
   "size": 20,
   "size": 20,
   "query": {
   "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]]
 [[request-body-search-source-filtering]]
 ==== 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
 By default, each hit in the search response includes the document
 <<mapping-source-field,`_source`>>, which is the entire JSON object that was
 <<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
 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:
 Returning fields using only the document source has some limitations: