From d734443b0e2a8a4c5d54877d69b24546e0c371d3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christoph=20B=C3=BCscher?= <cbuescher@posteo.de>
Date: Mon, 8 Feb 2021 14:22:30 +0100
Subject: [PATCH] Add docs for nested fields in fields API

This change adds a paragraph on the different response format for nested fields
in the fields API and adds an example snippet.

Related to #63709
---
 .../retrieve-selected-fields.asciidoc         | 99 +++++++++++++++++++
 1 file changed, 99 insertions(+)

diff --git a/docs/reference/search/search-your-data/retrieve-selected-fields.asciidoc b/docs/reference/search/search-your-data/retrieve-selected-fields.asciidoc
index 81f2406fd5d9f..f3b371f852af3 100644
--- a/docs/reference/search/search-your-data/retrieve-selected-fields.asciidoc
+++ b/docs/reference/search/search-your-data/retrieve-selected-fields.asciidoc
@@ -167,6 +167,105 @@ no dedicated array type, and any field could contain multiple values. The
 a specific order. See the mapping documentation on <<array, arrays>> for more
 background.
 
+[discrete]
+[[search-fields-nested]]
+==== Handling of nested fields
+
+The `fields` response for <<nested,`nested` fields>> is slightly different from that
+of regular object fields. While leaf values inside regular `object` fields are
+returned as a flat list, values inside `nested` fields are grouped according
+to maintain the independence of each object inside the original nested array.
+For each entry inside a nested field array, values are again returned as a flat list
+unless there are other `nested` fields inside the parent nested object, in which case
+the same procedure is repeated again for the deeper nested fields.
+
+Given the following mapping where `user` is a nested field, after indexing
+the following document and retrieving all fields under the `user` field:
+
+[source,console]
+--------------------------------------------------
+PUT my-index-000001
+{
+  "mappings": {
+    "properties": {
+      "user": {
+        "type": "nested"
+      }
+    }
+  }
+}
+
+PUT my-index-000001/_doc/1?refresh=true
+{
+  "group" : "fans",
+  "user" : [
+    {
+      "first" : "John",
+      "last" :  "Smith"
+    },
+    {
+      "first" : "Alice",
+      "last" :  "White"
+    }
+  ]
+}
+
+POST my-index-000001/_search
+{
+  "fields": ["*"],
+  "_source": false
+}
+--------------------------------------------------
+
+the response will group `first` and `last` name instead of
+returning them as a flat list.
+
+[source,console-result]
+----
+{
+  "took": 2,
+  "timed_out": false,
+  "_shards": {
+    "total": 1,
+    "successful": 1,
+    "skipped": 0,
+    "failed": 0
+  },
+  "hits": {
+    "total": {
+      "value": 1,
+      "relation": "eq"
+    },
+    "max_score": 1.0,
+    "hits": [{
+      "_index": "my-index-000001",
+      "_id": "1",
+      "_score": 1.0,
+      "fields": {
+        "group" : ["fans"],
+        "group.keyword" : ["fans"],
+        "user": [{
+            "first": ["John"],
+            "first.keyword": ["John"],
+            "last": ["Smith"],
+            "last.keyword": ["Smith"]
+          },
+          {
+            "first": ["Alice"],
+            "first.keyword": ["Alice"],
+            "last": ["White"],
+            "last.keyword": ["White"]
+          }
+        ]
+      }
+    }]
+  }
+}
+----
+// TESTRESPONSE[s/"took": 2/"took": $body.took/]
+// TESTRESPONSE[s/"max_score" : 1.0/"max_score" : $body.hits.max_score/]
+// TESTRESPONSE[s/"_score" : 1.0/"_score" : $body.hits.hits.0._score/]
+
 [discrete]
 [[retrieve-unmapped-fields]]
 ==== Retrieving unmapped fields