Clarify that inner_hits must be used to access nested fields. (#42724)

This PR updates the docs for `docvalue_fields` and `stored_fields` to clarify
that nested fields must be accessed through `inner_hits`. It also tweaks the
nested fields documentation to make this point more visible.

Addresses #23766.

Author: jtibshirani

docs/reference/mapping/types/nested.asciidoc

@@ -161,6 +161,22 @@ Nested documents can be:
 * sorted with <<nested-sorting,nested sorting>>.
 * retrieved and highlighted with <<nested-inner-hits,nested inner hits>>.
 
+[IMPORTANT]
+=============================================
+
+Because nested documents are indexed as separate documents, they can only be
+accessed  within the scope of the `nested` query, the
+`nested`/`reverse_nested` aggregations, or <<nested-inner-hits,nested inner hits>>.
+
+For instance, if a string field within a nested document has
+<<index-options,`index_options`>> set to `offsets` to allow use of the postings
+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 <<search-request-docvalue-fields, `docvalue_fields`>>
+or <<search-request-stored-fields, `stored_fields`>>.
+
+=============================================
 
 [[nested-params]]
 ==== Parameters for `nested` fields
@@ -180,21 +196,6 @@ The following parameters are accepted by `nested` fields:
     may be added to an existing nested object.
 
 
-[IMPORTANT]
-=============================================
-
-Because nested documents are indexed as separate documents, they can only be
-accessed  within the scope of the `nested` query, the
-`nested`/`reverse_nested` aggregations, or <<nested-inner-hits,nested inner hits>>.
-
-For instance, if a string field within a nested document has
-<<index-options,`index_options`>> set to `offsets` to allow use of the postings
-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>>.
-
-=============================================
-
 [float]
 === Limits on `nested` mappings and objects
 

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

@@ -68,3 +68,8 @@ Elasticsearch to use the mappings to figure out a default format.
 NOTE: The default is currently to return the same output as
 <<search-request-script-fields,script fields>>. However it will change in 7.0
 to behave as if the `use_field_mapping` format was provided.
+
+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 <<search-request-inner-hits, `inner_hits`>> block.

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

@@ -49,6 +49,11 @@ Script fields can also be automatically detected and used as fields, so
 things like `_source.obj1.field1` can be used, though not recommended, as
 `obj1.field1` will work as well.
 
+NOTE: 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 <<search-request-inner-hits, `inner_hits`>> block.
+
 ==== Disable stored fields entirely
 
 To disable the stored fields (and metadata fields) entirely use: `_none_`: