From 9c7a5c7b83aad9bb38b5b2a490d4ea1d3e9426fa Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Thu, 4 Jun 2020 15:34:10 -0400 Subject: [PATCH] [DOCS] Move source filtering examples (#57689) (#57695) 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. --- docs/reference/redirects.asciidoc | 5 ++ .../search/request/from-size.asciidoc | 4 +- .../search/request/source-filtering.asciidoc | 69 +------------- docs/reference/search/search-fields.asciidoc | 89 ++++++++++++++++++- 4 files changed, 95 insertions(+), 72 deletions(-) diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc index 52adf6cbbf3..a977312cd2c 100644 --- a/docs/reference/redirects.asciidoc +++ b/docs/reference/redirects.asciidoc @@ -896,4 +896,9 @@ For search examples, see <>. ==== From / size See <>. + +[role="exclude",id="request-body-search-source-filtering"] +==== Source filtering + +See <>. //// \ No newline at end of file diff --git a/docs/reference/search/request/from-size.asciidoc b/docs/reference/search/request/from-size.asciidoc index 58a55a82373..2027055b5df 100644 --- a/docs/reference/search/request/from-size.asciidoc +++ b/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" + } } } ---- diff --git a/docs/reference/search/request/source-filtering.asciidoc b/docs/reference/search/request/source-filtering.asciidoc index fc838bdd908..39f47833177 100644 --- a/docs/reference/search/request/source-filtering.asciidoc +++ b/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 <>. diff --git a/docs/reference/search/search-fields.asciidoc b/docs/reference/search/search-fields.asciidoc index 3ead66bde2a..3a5af4bbde8 100644 --- a/docs/reference/search/search-fields.asciidoc +++ b/docs/reference/search/search-fields.asciidoc @@ -5,9 +5,92 @@ By default, each hit in the search response includes the document <>, 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 -<> to restrict what -parts of the source are returned. +search response, you can use the +<> 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: