diff --git a/docs/reference/elasticsearch/rest-apis/retrieve-selected-fields.md b/docs/reference/elasticsearch/rest-apis/retrieve-selected-fields.md index d39aaa3f0c21e..b7cb8af099614 100644 --- a/docs/reference/elasticsearch/rest-apis/retrieve-selected-fields.md +++ b/docs/reference/elasticsearch/rest-apis/retrieve-selected-fields.md @@ -17,7 +17,7 @@ By default, each hit in the search response includes the document [`_source`](/r You can use both of these methods, though the `fields` option is preferred because it consults both the document data and index mappings. In some instances, you might want to use [other methods](#field-retrieval-methods) of retrieving data. -### The `fields` option [search-fields-param] +## The `fields` option [search-fields-param] To retrieve specific fields in the search response, use the `fields` parameter. Because it consults the index mappings, the `fields` parameter provides several advantages over referencing the `_source` directly. Specifically, the `fields` parameter: @@ -33,7 +33,7 @@ Other mapping options are also respected, including [`ignore_above`](/reference/ The `fields` option returns values in the way that matches how {{es}} indexes them. For standard fields, this means that the `fields` option looks in `_source` to find the values, then parses and formats them using the mappings. Selected fields that can’t be found in `_source` are skipped. -#### Retrieve specific fields [search-fields-request] +### Retrieve specific fields [search-fields-request] The following search request uses the `fields` parameter to retrieve values for the `user.id` field, all fields starting with `http.response.`, and the `@timestamp` field. @@ -69,7 +69,7 @@ By default, document metadata fields like `_id` or `_index` are not returned whe -#### Response always returns an array [search-fields-response] +### Response always returns an array [search-fields-response] The `fields` response always returns an array of values for each field, even when there is a single value in the `_source`. This is because {{es}} has no dedicated array type, and any field could contain multiple values. The `fields` parameter also does not guarantee that array values are returned in a specific order. See the mapping documentation on [arrays](/reference/elasticsearch/mapping-reference/array.md) for more background. @@ -109,7 +109,7 @@ The response includes values as a flat list in the `fields` section for each hit ``` -#### Retrieve nested fields [search-fields-nested] +### Retrieve nested fields [search-fields-nested] ::::{dropdown} The `fields` response for [`nested` fields](/reference/elasticsearch/mapping-reference/nested.md) is slightly different from that of regular object fields. While leaf values inside regular `object` fields are returned as a flat list, values inside `nested` fields are grouped to maintain the independence of each object inside the original nested array. For each entry inside a nested field array, values are again returned as a flat list unless there are other `nested` fields inside the parent nested object, in which case the same procedure is repeated again for the deeper nested fields. @@ -246,7 +246,7 @@ However, when the `fields` pattern targets the nested `user` field directly, no -#### Retrieve unmapped fields [retrieve-unmapped-fields] +### Retrieve unmapped fields [retrieve-unmapped-fields] ::::{dropdown} By default, the `fields` parameter returns only values of mapped fields. However, {{es}} allows storing fields in `_source` that are unmapped, such as setting [dynamic field mapping](docs-content://manage-data/data-store/mapping/dynamic-field-mapping.md) to `false` or by using an object field with `enabled: false`. These options disable parsing and indexing of the object content. @@ -326,7 +326,7 @@ The response will contain field results under the `session_data.object.*` path, -#### Ignored field values [ignored-field-values] +### Ignored field values [ignored-field-values] ::::{dropdown} The `fields` section of the response only returns values that were valid when indexed. If your search request asks for values from a field that ignored certain values because they were malformed or too large these values are returned separately in an `ignored_field_values` section. @@ -578,6 +578,7 @@ Also only leaf fields can be returned via the `stored_fields` option. If an obje On its own, `stored_fields` cannot be used to load fields in nested objects — if a field contains a nested object in its path, then no data will be returned for that stored field. To access nested fields, `stored_fields` must be used within an [`inner_hits`](/reference/elasticsearch/rest-apis/retrieve-inner-hits.md) block. :::: +For an example that uses the `stored_fields` parameter, refer to [](retrieve-stored-fields.md). ##### Disable stored fields [disable-stored-fields] diff --git a/docs/reference/elasticsearch/rest-apis/retrieve-stored-fields.md b/docs/reference/elasticsearch/rest-apis/retrieve-stored-fields.md new file mode 100644 index 0000000000000..319093c8bb923 --- /dev/null +++ b/docs/reference/elasticsearch/rest-apis/retrieve-stored-fields.md @@ -0,0 +1,84 @@ +--- +navigation_title: "Retrieve stored fields" +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html +applies_to: + stack: all +--- + +# Retrieve stored fields using the Get document API [get-stored-fields] + +Use the `stored_fields` query parameter in a [Get document](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-get) API request to retrieve fields marked as stored (`"store": true`) in the index mapping. + +Fields not marked as stored are excluded from the response, even if specified in the request. + +::::{tip} +In most cases, the [`fields`](retrieve-selected-fields.md#search-fields-param) and [`_source`](retrieve-selected-fields.md#source-filtering) parameters produce better results than `stored_fields`. +:::: + +For example, these PUT requests define a stored field in the mapping and add a document: + +```console +PUT my-index-000001 +{ + "mappings": { + "properties": { + "counter": { + "type": "integer", + "store": false + }, + "tags": { + "type": "keyword", + "store": true + } + } + } +} +``` + +```console +PUT my-index-000001/_doc/1 +{ + "counter": 1, + "tags": [ "production" ] +} +``` + +% TEST[continued] + +This request retrieves the stored fields from the document: + +```console +GET my-index-000001/_doc/1?stored_fields=tags,counter +``` + +% TEST[continued] + +The API returns the following response: + +```console-result +{ + "_index": "my-index-000001", + "_id": "1", + "_version": 1, + "_seq_no": 22, + "_primary_term": 1, + "found": true, + "fields": { + "tags": [ + "production" + ] + } +} +``` + +% TESTRESPONSE[s/"_seq_no" : \d+/"_seq_no" : $body._seq_no/ s/"_primary_term" : 1/"_primary_term" : $body._primary_term/] + +Although the `counter` field is specified in the request, it's not included in the response because it's not actually a stored field. + +Field values are returned as an array. + +::::{note} +Only leaf fields can be retrieved with the `stored_fields` parameter. If you specify an object field instead, an error is returned. +:::: + diff --git a/docs/reference/elasticsearch/toc.yml b/docs/reference/elasticsearch/toc.yml index 2c53008e0bccf..d64155d04347a 100644 --- a/docs/reference/elasticsearch/toc.yml +++ b/docs/reference/elasticsearch/toc.yml @@ -92,6 +92,7 @@ toc: - file: rest-apis/reindex-data-stream.md - file: rest-apis/retrieve-inner-hits.md - file: rest-apis/retrieve-selected-fields.md + - file: rest-apis/retrieve-stored-fields.md - file: rest-apis/retrievers.md - file: rest-apis/search-multiple-data-streams-indices.md - file: rest-apis/search-profile.md