diff --git a/docs/reference/search/run-a-search.asciidoc b/docs/reference/search/run-a-search.asciidoc index 9f4c961a996c0..5047ae4cd2508 100644 --- a/docs/reference/search/run-a-search.asciidoc +++ b/docs/reference/search/run-a-search.asciidoc @@ -285,3 +285,5 @@ GET /*/_search ==== include::request/from-size.asciidoc[] + +include::search-fields.asciidoc[] diff --git a/docs/reference/search/search-fields.asciidoc b/docs/reference/search/search-fields.asciidoc new file mode 100644 index 0000000000000..3ead66bde2ae0 --- /dev/null +++ b/docs/reference/search/search-fields.asciidoc @@ -0,0 +1,31 @@ +[discrete] +[[search-fields]] +=== Return fields in a search + +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. + +Returning fields using only the document source has some limitations: + +* The `_source` field does not include <> or +<>. Likewise, a field in the source does not contain +values copied using the <> mapping parameter. +* Since the `_source` is stored as a single field in Lucene, the whole source +object must be loaded and parsed, even if only a small number of fields are +needed. + +{es} supports some alternative methods for returning fields that help avoid +these downsides: + +* The <> +parameter allows for loading fields from their doc values. This can be a good +choice when returning a fairly small number of fields that support doc values, +such as keywords and dates. +* It's also possible to store an individual field's values by using the +<> mapping option. You can use the +<> parameter to return +these stored values in the search response.