[DOCS] Move search API's docvalue_fields examples

docs/plugins/mapper-size.asciidoc

@@ -86,7 +86,7 @@ GET my_index/_search
 {ref}/search-request-body.html#request-body-search-script-fields[script field]
 to return the `_size` field in the search response.
 <5> Uses a
-{ref}/search-request-body.html#request-body-search-docvalue-fields[doc value
+{ref}/search-search.html#search-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

docs/reference/aggregations/metrics/tophits-aggregation.asciidoc

@@ -23,7 +23,7 @@ The top_hits aggregation returns regular search hits, because of this many per h
 * <<search-fields,Source filtering>>
 * <<request-body-search-stored-fields,Stored fields>>
 * <<request-body-search-script-fields,Script fields>>
-* <<request-body-search-docvalue-fields,Doc value fields>>
+* <<search-docvalue-fields,Doc value fields>>
 * <<request-body-search-version,Include versions>>
 * <<request-body-search-seq-no-primary-term,Include Sequence Numbers and Primary Terms>>
 

docs/reference/mapping/types/nested.asciidoc

@@ -180,8 +180,8 @@ For instance, if a string field within a nested document has
 during the highlighting, these offsets will not be available during the main highlighting
 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 <<request-body-search-docvalue-fields, `docvalue_fields`>>
-or <<request-body-search-stored-fields, `stored_fields`>>.
+fields during a search through <<search-docvalue-fields,
+`docvalue_fields`>> or <<request-body-search-stored-fields, `stored_fields`>>.
 
 =============================================
 

docs/reference/redirects.asciidoc

@@ -901,5 +901,10 @@ See <<paginate-search-results>>.
 [role="exclude",id="request-body-search-source-filtering"]
 ==== Source filtering
 
+See <<search-fields>>.
+
+[role="exclude",id="request-body-search-docvalue-fields"]
+==== Doc value fields
+
 See <<search-fields>>.
 ////

docs/reference/search/request/docvalue-fields.asciidoc

@@ -1,73 +1,4 @@
 [[request-body-search-docvalue-fields]]
-==== Doc value Fields
+==== Doc value fields
 
-Allows to return the <<doc-values,doc value>> representation of a field for each hit, for
-example:
-
-[source,console]
---------------------------------------------------
-GET /_search
-{
-    "query" : {
-        "match_all": {}
-    },
-    "docvalue_fields" : [
-        "my_ip_field", <1>
-        {
-            "field": "my_keyword_field" <2>
-        },
-        {
-            "field": "my_date_field",
-            "format": "epoch_millis" <3>
-        }
-    ]
-}
---------------------------------------------------
-
-<1> the name of the field
-<2> an object notation is supported as well
-<3> the object notation allows to specify a custom format
-
-Doc value fields can work on fields that have doc-values enabled, regardless of whether they are stored
-
-`*` can be used as a wild card, for example:
-
-[source,console]
---------------------------------------------------
-GET /_search
-{
-    "query" : {
-        "match_all": {}
-    },
-    "docvalue_fields" : [
-        {
-            "field": "*_date_field", <1>
-            "format": "epoch_millis" <2>
-        }
-    ]
-}
---------------------------------------------------
-
-<1> Match all fields ending with `field`
-<2> Format to be applied to all matching fields.
-
-Note that if the fields parameter specifies fields without docvalues it will try to load the value from the fielddata cache
-causing the terms for that field to be loaded to memory (cached), which will result in more memory consumption.
-
-[float]
-====== Custom formats
-
-While most fields do not support custom formats, some of them do:
-
- - <<date,Date>> fields can take any <<mapping-date-format,date format>>.
- - <<number,Numeric>> fields accept a https://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html[DecimalFormat pattern].
-
-By default fields are formatted based on a sensible configuration that depends
-on their mappings: `long`, `double` and other numeric fields are formatted as
-numbers, `keyword` fields are formatted as strings, `date` fields are formatted
-with the configured `date` format, etc.
-
-NOTE: On its own, `docvalue_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 docvalue field. To access nested fields, `docvalue_fields`
-must be used within an <<request-body-search-inner-hits, `inner_hits`>> block.
+See <<search-fields>>.

docs/reference/search/request/inner-hits.asciidoc

@@ -73,7 +73,7 @@ Inner hits also supports the following per document features:
 * <<request-body-search-explain,Explain>>
 * <<request-body-search-source-filtering,Source filtering>>
 * <<request-body-search-script-fields,Script fields>>
-* <<request-body-search-docvalue-fields,Doc value fields>>
+* <<search-docvalue-fields,Doc value fields>>
 * <<request-body-search-version,Include versions>>
 * <<request-body-search-seq-no-primary-term,Include Sequence Numbers and Primary Terms>>
 

docs/reference/search/search-fields.asciidoc

@@ -103,10 +103,50 @@ needed.
 {es} supports some alternative methods for returning fields that help avoid
 these downsides:
 
-* The <<request-body-search-docvalue-fields, `docvalue_fields`>>
-parameter allows for loading fields from their doc values. This can be a good
-choice when returning a fairly small number of fields that support doc values,
-such as keywords and dates.
+* You can use the <<search-docvalue-fields,`docvalue_fields`>> parameter to
+return doc values for one or more fields. This can be a good choice when
+returning a fairly small number of fields that support doc values, such as
+<<keyword,keywords>> or <<date,dates>> .
++
+.*Example*
+[%collapsible]
+====
+The following search API request uses the `docvalue_fields` parameter to return
+doc values for the following fields:
+
+* Fields with names starting with `my_ip`
+* `my_keyword_field`
+* Fields with names ending with `_date_field`
+
+[source,console]
+--------------------------------------------------
+GET /_search
+{
+  "query": {
+    "match_all": {}
+  },
+  "docvalue_fields": [
+    "my_ip*",                     <1>
+    {
+      "field": "my_keyword_field" <2>
+    },
+    {
+      "field": "*_date_field",
+      "format": "epoch_millis"    <3>
+    }
+  ]
+}
+--------------------------------------------------
+
+<1> Wildcard patten used to match field names, specified as a string.
+<2> Wildcard patten used to match field names, specified as an object.
+<3> With the object notation, you can use the `format` parameter to specify a 
+    format for the field's returned doc values. <<date,Date fields>> support a 
+    <<mapping-date-format,date `format`>>. <<number,Numeric fields>> support a
+    https://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html[DecimalFormat
+    pattern]. Other field datatypes do not support the `format` parameter.
+====
+
 * 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 return

docs/reference/search/search.asciidoc

@@ -247,6 +247,47 @@ If `true`, returns document version as part of a hit. Defaults to `false`.
 [[search-search-api-request-body]]
 ==== {api-request-body-title}
 
+[[search-docvalue-fields]]
+`docvalue_fields`::
+(Optional, array of strings and objects)
+Array of wildcard (`*`) patterns. The request returns doc values for field names
+matching these patterns in the `hits.fields` property of the response.
++
+You can specify items in the array as a string or object. See <<search-fields>>.
++
+.Properties of `docvalue_fields` objects
+[%collapsible]
+====
+`field`::
+(Required, string)
+Wildcard pattern. The request returns doc values for field names matching this
+pattern.
+
+`format`::
+(Optional, string)
+Format in which the doc values are returned.
++
+For <<date,date fields>>, you can specify a  date <<mapping-date-format,date
+`format`>>. For <<number,numeric fields>> fields, you can specify a
+https://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html[DecimalFormat
+pattern].
++
+For other field datatypes, this parameter is not supported.
+====
++
+WARNING: <<doc-values,Doc values>> are enabled on supported fields by default.
+However, they can be disabled using the <<doc-values,`doc_values`>> mapping
+parameter. If the `docvalue_fields` parameter specifies a field without a doc
+value, the search request attempts to load the value from the
+<<modules-fielddata,field data cache>>. This causes the field's terms to be
+loaded into memory, resulting in higher memory consumption.
++
+You cannot use the `docvalue_fields` parameter to return doc values
+for nested objects. If you specify a pattern containing a nested object, the
+request returns an empty array (`[ ]`) for the field. To access nested fields,
+use the <<request-body-search-inner-hits, `inner_hits`>> parameter's
+`docvalue_fields` property.
+
 [[request-body-search-explain]]
 `explain`::
 (Optional, boolean) If `true`, returns detailed information about score
@@ -457,6 +498,34 @@ returned document.
 `_source`::
 (object)
 Original JSON body passed for the document at index time.
++
+If the <<search-docvalue-fields,`docvalue_fields`>> parameter is specified and
+the `source` parameter is not specified, this property is not returned.
++
+.Properties of `_source`
+[%collapsible%open]
+======
+`<field>`::
+Key is the field name. Value is the JSON value passed for the field at index
+time.
+======
+
+`fields`::
+(object)
+Contains doc values for fields specified using the
+<<search-docvalue-fields,`docvalue_fields`>> parameter. This property is only
+returned if `docvalue_fields` is specified in the search request.
++
+.Properties of `fields`
+[%collapsible%open]
+======
+`<field>`::
+(array)
+Key is the field name. Value is the doc value for the field.
++
+If no doc values are available for the field, the value is an empty array
+(`[ ]`).
+======
 =====
 ====