From 681ca22fe4d273785032744aadad4d5cc796a325 Mon Sep 17 00:00:00 2001 From: Julie Tibshirani Date: Mon, 1 Jun 2020 17:29:48 -0700 Subject: [PATCH] Avoid unnecessary use of stored_fields in our docs. (#57488) Generally we don't advocate for using `stored_fields`, and we're interested in eventually removing the need for this parameter. So it's best to avoid using stored fields in our docs examples when it's not actually necessary. Individual changes: * Avoid using 'stored_fields' in our docs. * When defining script fields in top-hits, de-emphasize stored fields. --- .../painless-walkthrough.asciidoc | 6 +- docs/reference/scripting/fields.asciidoc | 103 +++++++++++------- .../search/request/highlighting.asciidoc | 2 +- 3 files changed, 67 insertions(+), 44 deletions(-) diff --git a/docs/painless/painless-guide/painless-walkthrough.asciidoc b/docs/painless/painless-guide/painless-walkthrough.asciidoc index d414418a90814..8648e30b07ee6 100644 --- a/docs/painless/painless-guide/painless-walkthrough.asciidoc +++ b/docs/painless/painless-guide/painless-walkthrough.asciidoc @@ -132,10 +132,6 @@ First, let's look at the source data for a player by submitting the following re ---------------------------------------------------------------- GET hockey/_search { - "stored_fields": [ - "_id", - "_source" - ], "query": { "term": { "_id": 1 @@ -189,7 +185,7 @@ Date fields are exposed as `ZonedDateTime`, so they support methods like `getYear`, `getDayOfWeek` or e.g. getting milliseconds since epoch with `getMillis`. To use these in a script, leave out the `get` prefix and continue with lowercasing the -rest of the method name. For example, the following returns every hockey +rest of the method name. For example, the following returns every hockey player's birth year: [source,console] diff --git a/docs/reference/scripting/fields.asciidoc b/docs/reference/scripting/fields.asciidoc index 6308fcdf623e1..47adda9337a6f 100644 --- a/docs/reference/scripting/fields.asciidoc +++ b/docs/reference/scripting/fields.asciidoc @@ -26,8 +26,10 @@ Depending on how many documents you have, this could mean millions or billions of executions: these scripts need to be fast! Field values can be accessed from a script using -<>, or -<>, which are explained below. +<>, +<>, or +<>, +each of which is explained below. [[scripting-score]] [float] @@ -137,32 +139,27 @@ access `text` fields from scripts. =================================================== [float] -[[modules-scripting-stored]] -=== Stored fields and `_source` - -_Stored fields_ -- fields explicitly marked as -<> -- can be accessed using the -`_fields['field_name'].value` or `_fields['field_name']` syntax. +[[modules-scripting-source]] +=== The document `_source` -The document <>, which is really just a -special stored field, can be accessed using the `_source.field_name` syntax. -The `_source` is loaded as a map-of-maps, so properties within object fields -can be accessed as, for example, `_source.name.first`. +The document <> can be accessed using the +`_source.field_name` syntax. The `_source` is loaded as a map-of-maps, so +properties within object fields can be accessed as, for example, +`_source.name.first`. [IMPORTANT] -.Prefer doc-values to stored fields +.Prefer doc-values to _source ========================================================= -Stored fields (which includes the stored `_source` field) are much slower than -doc-values. They are optimised for returning several fields per result, -while doc values are optimised for accessing the value of a specific field in -many documents. +Accessing the `_source` field is much slower than using doc-values. The +_source field is optimised for returning several fields per result, while doc +values are optimised for accessing the value of a specific field in many +documents. - -It makes sense to use `_source` or stored fields when generating a -<> for the top ten hits from a search -result but, for other search and aggregation use cases, always prefer using -doc values. +It makes sense to use `_source` when generating a +<> for the top ten hits from a +search result but, for other search and aggregation use cases, always prefer +using doc values. ========================================================= @@ -174,16 +171,11 @@ PUT my_index { "mappings": { "properties": { - "title": { <1> - "type": "text" - }, "first_name": { - "type": "text", - "store": true + "type": "text" }, "last_name": { - "type": "text", - "store": true + "type": "text" } } } @@ -191,7 +183,6 @@ PUT my_index PUT my_index/_doc/1?refresh { - "title": "Mr", "first_name": "Barry", "last_name": "White" } @@ -199,25 +190,61 @@ PUT my_index/_doc/1?refresh GET my_index/_search { "script_fields": { - "source": { + "full_name": { "script": { "lang": "painless", - "source": "params._source.title + ' ' + params._source.first_name + ' ' + params._source.last_name" <2> + "source": "params._source.first_name + ' ' + params._source.last_name" + } + } + } +} +------------------------------- + +[float] +[[modules-scripting-stored]] +=== Stored fields + +_Stored fields_ -- fields explicitly marked as +<> in the mapping -- can be accessed using the +`_fields['field_name'].value` or `_fields['field_name']` syntax: + +[source,console] +------------------------------- +PUT my_index +{ + "mappings": { + "properties": { + "full_name": { + "type": "text", + "store": true + }, + "title": { + "type": "text", + "store": true } - }, - "stored_fields": { + } + } +} + +PUT my_index/_doc/1?refresh +{ + "full_name": "Alice Ball", + "title": "Professor" +} + +GET my_index/_search +{ + "script_fields": { + "name_with_title": { "script": { "lang": "painless", - "source": "params._fields['first_name'].value + ' ' + params._fields['last_name'].value" + "source": "params._fields['title'].value + ' ' + params._fields['full_name'].value" } } } } ------------------------------- -<1> The `title` field is not stored and so cannot be used with the `_fields[]` syntax. -<2> The `title` field can still be accessed from the `_source`. - [TIP] .Stored vs `_source` ======================================================= diff --git a/docs/reference/search/request/highlighting.asciidoc b/docs/reference/search/request/highlighting.asciidoc index 6b2a976d44a47..8ab97f0ecf2b9 100644 --- a/docs/reference/search/request/highlighting.asciidoc +++ b/docs/reference/search/request/highlighting.asciidoc @@ -309,7 +309,6 @@ highlighting would only take the search query into account. -------------------------------------------------- GET /_search { - "stored_fields": [ "_id" ], "query" : { "match": { "comment": { @@ -331,6 +330,7 @@ GET /_search "rescore_query_weight" : 10 } }, + "_source": false, "highlight" : { "order" : "score", "fields" : {