[DOCS] Move script and stored fields content to search fields page (#60826) (#60835)

jrodewig · web-flow · commit a761985fabfe · 2020-08-06T13:06:06.000-04:00
Changes:

* Moves `Retrieve selected fields` to its own page and adds a title abbreviation.
* Adds existing script and stored fields content to `Retrieve selected fields`
* Adds a xref for `Retrieve selected fields` to `Search your data`
* Adds related redirects and updates existing xrefs
diff --git a/docs/painless/painless-contexts.asciidoc b/docs/painless/painless-contexts.asciidoc
@@ -31,7 +31,7 @@ specialized code may define new ways to use a Painless script.
 | Score                             | <<painless-score-context, Painless Documentation>>
                                     | {ref}/query-dsl-function-score-query.html[Elasticsearch Documentation]
 | Field                             | <<painless-field-context, Painless Documentation>>
-                                    | {ref}/search-request-body.html#request-body-search-script-fields[Elasticsearch Documentation]
+                                    | {ref}/search-fields.html#script-fields[Elasticsearch Documentation]
 | Filter                            | <<painless-filter-context, Painless Documentation>>
                                     | {ref}/query-dsl-script-query.html[Elasticsearch Documentation]
 | Minimum should match              | <<painless-min-should-match-context, Painless Documentation>>
diff --git a/docs/painless/painless-contexts/painless-field-context.asciidoc b/docs/painless/painless-contexts/painless-field-context.asciidoc
@@ -2,7 +2,7 @@
 === Field context
 
 Use a Painless script to create a
-{ref}/search-request-body.html#request-body-search-script-fields[script field] to return
+{ref}/search-fields.html#script-fields[script field] to return
 a customized value for each document in the results of a query.
 
 *Variables*
diff --git a/docs/painless/painless-guide/painless-datetime.asciidoc b/docs/painless/painless-guide/painless-datetime.asciidoc
@@ -825,7 +825,7 @@ GET /messages/_search?pretty=true
 ===== Age of a Message Script Field Example
 
 The following example uses a
-{ref}/search-request-body.html#request-body-search-script-fields[script field] as part of the
+{ref}/search-fields.html#script-fields[script field] as part of the
 <<painless-field-context, field context>> to display the elapsed time between
 "now" and when a message was received.
 
diff --git a/docs/plugins/mapper-size.asciidoc b/docs/plugins/mapper-size.asciidoc
@@ -83,10 +83,10 @@ GET my-index-000001/_search
 <2> Aggregating on the `_size` field
 <3> Sorting on the `_size` field
 <4> Uses a
-{ref}/search-request-body.html#request-body-search-script-fields[script field]
+{ref}/search-fields.html#script-fields[script field]
 to return the `_size` field in the search response.
 <5> Uses a
-{ref}/search-your-data.html#docvalue-fields[doc value
+{ref}/search-fields.html#docvalue-fields[doc value
 field] to return the `_size` field in the search response. Doc value fields are
 useful if
 {ref}/modules-scripting-security.html#allowed-script-types-setting[inline
diff --git a/docs/reference/aggregations/metrics/tophits-aggregation.asciidoc b/docs/reference/aggregations/metrics/tophits-aggregation.asciidoc
@@ -21,8 +21,8 @@ The top_hits aggregation returns regular search hits, because of this many per h
 * <<request-body-search-explain,Explain>>
 * <<named-queries,Named queries>>
 * <<source-filtering,Source filtering>>
-* <<request-body-search-stored-fields,Stored fields>>
-* <<request-body-search-script-fields,Script fields>>
+* <<stored-fields,Stored fields>>
+* <<script-fields,Script fields>>
 * <<docvalue-fields,Doc value fields>>
 * <<request-body-search-version,Include versions>>
 * <<request-body-search-seq-no-primary-term,Include Sequence Numbers and Primary Terms>>
diff --git a/docs/reference/how-to/search-speed.asciidoc b/docs/reference/how-to/search-speed.asciidoc
@@ -165,7 +165,7 @@ include::../mapping/types/numeric.asciidoc[tag=map-ids-as-keyword]
 === Avoid scripts
 
 If possible, avoid using <<modules-scripting,scripts>> or
-<<request-body-search-script-fields,scripted fields>> in searches. See
+<<script-fields,scripted fields>> in searches. See
 <<scripts-and-search-speed>>.
 
 
diff --git a/docs/reference/mapping/types/nested.asciidoc b/docs/reference/mapping/types/nested.asciidoc
@@ -181,7 +181,7 @@ during the highlighting, these offsets will not be available during the main hig
 phase.  Instead, highlighting needs to be performed via
 <<nested-inner-hits,nested inner hits>>. The same consideration applies when loading
 fields during a search through <<docvalue-fields,
-`docvalue_fields`>> or <<request-body-search-stored-fields, `stored_fields`>>.
+`docvalue_fields`>> or <<stored-fields, `stored_fields`>>.
 
 =============================================
 
diff --git a/docs/reference/ml/anomaly-detection/ml-configuring-transform.asciidoc b/docs/reference/ml/anomaly-detection/ml-configuring-transform.asciidoc
@@ -153,7 +153,7 @@ error count.
 
 The syntax for the `script_fields` property is identical to that used by {es}.
 For more information, see
-{ref}/search-request-body.html#request-body-search-script-fields[Script fields].
+{ref}/search-fields.html#script-fields[Script fields].
 
 You can preview the contents of the {dfeed} by using the following API:
 
diff --git a/docs/reference/ml/ml-shared.asciidoc b/docs/reference/ml/ml-shared.asciidoc
@@ -1224,7 +1224,7 @@ Specifies scripts that evaluate custom expressions and returns script fields to
 the {dfeed}. The detector configuration objects in a job can contain functions
 that use these script fields. For more information, see
 {ml-docs}/ml-configuring-transform.html[Transforming data with script fields]
-and <<request-body-search-script-fields,Script fields>>.
+and <<script-fields,Script fields>>.
 end::script-fields[]
 
 tag::scroll-size[]
diff --git a/docs/reference/redirects.asciidoc b/docs/reference/redirects.asciidoc
@@ -107,7 +107,7 @@ See <<request-body-search-rescore>>.
 
 [role="exclude",id="search-request-script-fields"]
 === Script fields parameter for request body search API
-See <<request-body-search-script-fields>>.
+See <<script-fields>>.
 
 [role="exclude",id="search-request-scroll"]
 === Scroll parameter for request body search API
@@ -136,7 +136,7 @@ See <<source-filtering>>.
 
 [role="exclude",id="search-request-stored-fields"]
 === Stored fields parameter for request body search API
-See <<request-body-search-stored-fields>>.
+See <<stored-fields>>.
 
 [role="exclude",id="search-request-track-total-hits"]
 === Track total hits parameter for request body search API
@@ -1007,12 +1007,17 @@ See <<highlighting>>.
 [role="exclude",id="highlighter-internal-work"]
 ==== How highlighters work internally
 
+See <<how-es-highlighters-work-internally>>.
+
 [role="exclude",id="request-body-search-queries-and-filters"]
 === Named queries
 
 See <<named-queries>.
 
-See <<how-es-highlighters-work-internally>>.
+[role="exclude",id="request-body-search-script-fields"]
+==== Script fields
+
+See <<script-fields>>.
 
 [role="exclude",id="request-body-search-scroll"]
 ==== Scroll
@@ -1030,7 +1035,7 @@ See <<clear-scroll-api>>.
 See <<slice-scroll>>.
 
 [role="exclude",id="request-body-search-search-after"]
-==== Search After
+==== Search after
 
 See <<search-after>>.
 
@@ -1043,4 +1048,9 @@ See <<sort-search-results>>.
 ==== Source filtering
 
 See <<source-filtering>>.
+
+[role="exclude",id="request-body-search-stored-fields"]
+==== Stored fields
+
+See <<stored-fields>>.
 ////
diff --git a/docs/reference/scripting/fields.asciidoc b/docs/reference/scripting/fields.asciidoc
@@ -19,7 +19,7 @@ API will have access to the `ctx` variable which exposes:
 [discrete]
 == Search and aggregation scripts
 
-With the exception of <<request-body-search-script-fields,script fields>> which are
+With the exception of <<script-fields,script fields>> which are
 executed once per search hit, scripts used in search and aggregations will be
 executed once for every document which might match a query or an aggregation.
 Depending on how many documents you have, this could mean millions or billions
@@ -157,7 +157,7 @@ values are optimised for accessing the value of a specific field in many
 documents.
 
 It makes sense to use `_source` when generating a
-<<request-body-search-script-fields,script field>> for the top ten hits from a
+<<script-fields,script field>> for the top ten hits from a
 search result but, for other search and aggregation use cases, always prefer
 using doc values.
 =========================================================
diff --git a/docs/reference/scripting/using.asciidoc b/docs/reference/scripting/using.asciidoc
@@ -18,7 +18,7 @@ the same pattern:
 <3> Any named parameters that should be passed into the script.
 
 For example, the following script is used in a search request to return a
-<<request-body-search-script-fields, scripted field>>:
+<<script-fields, scripted field>>:
 
 [source,console]
 -------------------------------------
diff --git a/docs/reference/search/request-body.asciidoc b/docs/reference/search/request-body.asciidoc
@@ -140,7 +140,10 @@ include::request/preference.asciidoc[]
 
 include::request/rescore.asciidoc[]
 
-include::request/script-fields.asciidoc[]
+[[request-body-search-script-fields]]
+==== Script Fields
+
+See <<script-fields>>.
 
 [[request-body-search-scroll]]
 ==== Scroll
@@ -174,6 +177,9 @@ See <<sort-search-results>>.
 
 See <<source-filtering>>.
 
-include::request/stored-fields.asciidoc[]
+[[request-body-search-stored-fields]]
+==== Stored fields
+
+See <<stored-fields>>.
 
 include::request/track-total-hits.asciidoc[]
diff --git a/docs/reference/search/request/inner-hits.asciidoc b/docs/reference/search/request/inner-hits.asciidoc
@@ -73,7 +73,7 @@ Inner hits also supports the following per document features:
 * <<highlighting,Highlighting>>
 * <<request-body-search-explain,Explain>>
 * <<request-body-search-source-filtering,Source filtering>>
-* <<request-body-search-script-fields,Script fields>>
+* <<script-fields,Script fields>>
 * <<docvalue-fields,Doc value fields>>
 * <<request-body-search-version,Include versions>>
 * <<request-body-search-seq-no-primary-term,Include Sequence Numbers and Primary Terms>>
diff --git a/docs/reference/search/request/script-fields.asciidoc b/docs/reference/search/request/script-fields.asciidoc
@@ -1,8 +1,9 @@
-[[request-body-search-script-fields]]
-==== Script Fields
+[discrete]
+[[script-fields]]
+=== Script fields
 
-Allows to return a <<modules-scripting,script
-evaluation>> (based on different fields) for each hit, for example:
+You can use the `script_fields` parameter to retrieve a <<modules-scripting,script
+evaluation>> (based on different fields) for each hit. For example:
 
 [source,console]
 --------------------------------------------------
diff --git a/docs/reference/search/request/stored-fields.asciidoc b/docs/reference/search/request/stored-fields.asciidoc
@@ -1,7 +1,4 @@
-[[request-body-search-stored-fields]]
-==== Stored Fields
-
-WARNING: The `stored_fields` parameter is about fields that are explicitly marked as
+WARNING: The `stored_fields` parameter is for fields that are explicitly marked as
 stored in the mapping, which is off by default and generally not recommended.
 Use <<source-filtering,source filtering>> instead to select
 subsets of the original source document to be returned.
@@ -47,7 +44,9 @@ 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 <<request-body-search-inner-hits, `inner_hits`>> block.
 
-===== Disable stored fields entirely
+[discrete]
+[[disable-stored-fields]]
+==== Disable stored fields
 
 To disable the stored fields (and metadata fields) entirely use: `_none_`:
 
diff --git a/docs/reference/search/search-fields.asciidoc b/docs/reference/search/search-fields.asciidoc
@@ -1,6 +1,8 @@
-[discrete]
 [[search-fields]]
-=== Retrieve selected fields
+== Retrieve selected fields from a search
+++++
+<titleabbrev>Retrieve selected fields</titleabbrev>
+++++
 
 By default, each hit in the search response includes the document
 <<mapping-source-field,`_source`>>, which is the entire JSON object that was
@@ -41,13 +43,19 @@ such as keywords and dates.
 get the values for specific stored fields (fields that use the
 <<mapping-store,`store`>> mapping option).
 
+If needed, you can use the <<script-fields,`script_field`>> parameter to
+transform field values in the response using a script. However, scripts can’t
+make use of {es}'s index structures or related optimizations. This can sometimes
+result in slower search speeds.
+
 You can find more detailed information on each of these methods in the
 following sections:
 
 * <<search-fields-param>>
 * <<docvalue-fields>>
 * <<stored-fields>>
 * <<source-filtering>>
+* <<script-fields>>
 
 [discrete]
 [[search-fields-param]]
@@ -221,8 +229,9 @@ property.
 
 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 include
-these stored values in the search response.
+`stored_fields` parameter to include these stored values in the search response.
+
+include::request/stored-fields.asciidoc[]
 
 [discrete]
 [[source-filtering]]
@@ -309,3 +318,5 @@ GET /_search
   }
 }
 ----
+
+include::request/script-fields.asciidoc[]
diff --git a/docs/reference/search/search-your-data.asciidoc b/docs/reference/search/search-your-data.asciidoc
@@ -70,6 +70,10 @@ The response sorts documents in `hits.hits` by `_score`, a
 <<relevance-scores,relevance score>> that measures how well each document
 matches the query.
 
+The `hit.hits` property also includes the <<mapping-source-field,`_source`>> for
+each matching document. To retrieve only a subset of the `_source` or other
+fields, see <<search-fields>>.
+
 [source,console-result]
 ----
 {
@@ -224,11 +228,11 @@ GET /*/_search
 ----
 // TEST[setup:my_index]
 
-include::search-fields.asciidoc[]
 include::request/collapse.asciidoc[]
 include::request/highlighting.asciidoc[]
-include::paginate-search-results.asciidoc[]
-include::request/sort.asciidoc[]
 include::{es-repo-dir}/async-search.asciidoc[]
-include::{es-repo-dir}/modules/cross-cluster-search.asciidoc[]
 include::{es-repo-dir}/search/near-real-time.asciidoc[]
+include::paginate-search-results.asciidoc[]
+include::search-fields.asciidoc[]
+include::{es-repo-dir}/modules/cross-cluster-search.asciidoc[]
+include::request/sort.asciidoc[]
diff --git a/docs/reference/search/search.asciidoc b/docs/reference/search/search.asciidoc
@@ -575,8 +575,8 @@ Contains field values for the documents. These fields must be specified in the
 request using one or more of the following request parameters:
 
 * <<search-docvalue-fields-param,`docvalue_fields`>>
-* <<request-body-search-script-fields,`script_fields`>>
-* <<request-body-search-stored-fields,`stored_fields`>>
+* <<script-fields,`script_fields`>>
+* <<stored-fields,`stored_fields`>>
 
 This property is returned only if one or more of these parameters are set.
 --
