Skip to content

Commit 79fc6bd

Browse files
committed
Add a reference on returning fields during a search.
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.
1 parent 2558699 commit 79fc6bd

File tree

2 files changed

+32
-0
lines changed

2 files changed

+32
-0
lines changed

docs/reference/search/run-a-search.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -285,3 +285,5 @@ GET /*/_search
285285
====
286286

287287
include::request/from-size.asciidoc[]
288+
289+
include::search-fields.asciidoc[]
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
[discrete]
2+
[[search-fields]]
3+
=== Return fields in a search
4+
5+
By default, each hit in the search response includes the document
6+
<<mapping-source-field,`_source`>>, which is the entire JSON object that was
7+
provided when indexing the document. Often only certain fields are required in
8+
the response. In this case you can use
9+
<<request-body-search-source-filtering,source filtering>> to restrict what
10+
parts of the source are returned.
11+
12+
Returning fields using the document source has some limitations:
13+
14+
* The `_source` field does not include <<multi-fields, multi-fields>> or
15+
<<alias, field aliases>>. Likewise, a field in the source will not contain
16+
values that were copied into it through `copy_to`.
17+
* Since the `_source` is stored as a single field in Lucene, the whole source
18+
object must be loaded and parsed, even if only a small number of fields is needed.
19+
20+
Elasticsearch supports some alternative methods for returning fields that help
21+
avoid these downsides:
22+
23+
* The <<request-body-search-docvalue-fields, docvalue fields>>
24+
parameter allows for loading fields from their docvalues. This can be a good
25+
choice when returning a fairly small number of fields that support docvalues,
26+
such as keywords and dates.
27+
* It's also possible to store an individual field's values by using the
28+
<<mapping-store,`store`>> mapping option. These stored values can then be
29+
returned in a search through the
30+
<<request-body-search-stored-fields, `stored_fields`>> parameter.

0 commit comments

Comments
 (0)