From df61d995774aa3d07c93ef59e287fec891d70a5b Mon Sep 17 00:00:00 2001 From: Julie Tibshirani Date: Mon, 1 Jun 2020 20:41:28 -0700 Subject: [PATCH] Avoid unnecessary use of stored_fields in our docs. (#57497) 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-getting-started.asciidoc | 4 - docs/reference/scripting/fields.asciidoc | 97 ++++++++++++------- .../search/request/highlighting.asciidoc | 2 +- 3 files changed, 65 insertions(+), 38 deletions(-) diff --git a/docs/painless/painless-getting-started.asciidoc b/docs/painless/painless-getting-started.asciidoc index a9995b6139aee..d6397c76d031f 100644 --- a/docs/painless/painless-getting-started.asciidoc +++ b/docs/painless/painless-getting-started.asciidoc @@ -155,10 +155,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 diff --git a/docs/reference/scripting/fields.asciidoc b/docs/reference/scripting/fields.asciidoc index 70fe881da4d24..ec7b4ad0e29dc 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] @@ -139,27 +141,22 @@ 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 @@ -177,16 +174,11 @@ PUT my_index "mappings": { "_doc": { "properties": { - "title": { <1> - "type": "text" - }, "first_name": { - "type": "text", - "store": true + "type": "text" }, "last_name": { - "type": "text", - "store": true + "type": "text" } } } @@ -195,7 +187,6 @@ PUT my_index PUT my_index/_doc/1?refresh { - "title": "Mr", "first_name": "Barry", "last_name": "White" } @@ -203,24 +194,64 @@ 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" + } + } + } +} +------------------------------- +// CONSOLE + +[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,js] +------------------------------- +PUT my_index +{ + "mappings": { + "_doc": { + "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" } } } } ------------------------------- // CONSOLE -<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 51e7ddff565b9..7efb4d804c966 100644 --- a/docs/reference/search/request/highlighting.asciidoc +++ b/docs/reference/search/request/highlighting.asciidoc @@ -313,7 +313,6 @@ highlighting would only take the search query into account. -------------------------------------------------- GET /_search { - "stored_fields": [ "_id" ], "query" : { "match": { "comment": { @@ -335,6 +334,7 @@ GET /_search "rescore_query_weight" : 10 } }, + "_source": false, "highlight" : { "order" : "score", "fields" : {