From 8ebeedac3b5e46fdce3f2b44df6b6e24148ab012 Mon Sep 17 00:00:00 2001
From: Julie Tibshirani <julie.tibshirani@elastic.co>
Date: Wed, 3 Jun 2020 09:33:26 -0700
Subject: [PATCH] Add a reference on returning fields during a search. (#57500)

This PR adds a section to the new 'run a search' reference that explains
the options for returning fields. Previously each option was only listed as a
separate request parameter and it was hard to know what was available.
---
 docs/reference/search/run-a-search.asciidoc  |  2 ++
 docs/reference/search/search-fields.asciidoc | 31 ++++++++++++++++++++
 2 files changed, 33 insertions(+)
 create mode 100644 docs/reference/search/search-fields.asciidoc

diff --git a/docs/reference/search/run-a-search.asciidoc b/docs/reference/search/run-a-search.asciidoc
index aa8524a2321d6..29ffb1fef5061 100644
--- a/docs/reference/search/run-a-search.asciidoc
+++ b/docs/reference/search/run-a-search.asciidoc
@@ -289,3 +289,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
+<<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.
+
+Returning fields using only the document source has some limitations:
+
+* The `_source` field does not include <<multi-fields, multi-fields>> or
+<<alias, field aliases>>. Likewise, a field in the source does not contain
+values copied using the <<copy-to,`copy_to`>> 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 <<request-body-search-docvalue-fields, `docvalue_fields`>>
+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-store,`store`>> mapping option. You can use the
+<<request-body-search-stored-fields, `stored_fields`>> parameter to return
+these stored values in the search response.