From b77254871b714a558d39f268f2beaf5a7516302a Mon Sep 17 00:00:00 2001
From: Martijn van Groningen <martijn.v.groningen@gmail.com>
Date: Fri, 28 Apr 2017 11:09:24 +0200
Subject: [PATCH] docs: document alternative for nested inner hits source

Closes #24110
---
 .../search/request/inner-hits.asciidoc        | 49 +++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/docs/reference/search/request/inner-hits.asciidoc b/docs/reference/search/request/inner-hits.asciidoc
index 28914cd9b5e..1b118a419ed 100644
--- a/docs/reference/search/request/inner-hits.asciidoc
+++ b/docs/reference/search/request/inner-hits.asciidoc
@@ -148,6 +148,55 @@ An important default is that the `_source` returned in hits inside `inner_hits`
 So in the above example only the comment part is returned per nested hit and not the entire source of the top level
 document that contained the comment.
 
+[[nested-inner-hits-source]]
+==== Nested inner hits and _source
+
+Nested document don't have a `_source` field, because the entire source of document is stored with the root document under
+its `_source` field. To include the source of just the nested document, the source of the root document is parsed and just
+the relevant bit for the nested document is included as source in the inner hit. Doing this for each matching nested document
+has an impact on the time it takes to execute the entire search request, especially when `size` and the inner hits' `size`
+are set higher than the default. To avoid the relative expensive source extraction for nested inner hits, one can disable
+including the source and solely rely on stored fields.
+
+Enabled stored field for fields under the nested object field in your mapping:
+
+[source,js]
+--------------------------------------------------
+{
+    "properties": {
+        "comment": {
+          "type": "comments",
+          "properties" : {
+            "message" : {
+                "type" : "text",
+                "store" : true
+            }
+          }
+        }
+    }
+}
+--------------------------------------------------
+
+Disable including source and include specific stored fields in the inner hits definition:
+
+[source,js]
+--------------------------------------------------
+{
+    "query" : {
+        "nested" : {
+            "path" : "comments",
+            "query" : {
+                "match" : {"comments.message" : "[actual query]"}
+            },
+            "inner_hits" : {
+                "_source" : false,
+                "stored_fields" : ["comments.text"]
+            }
+        }
+    }
+}
+--------------------------------------------------
+
 [[hierarchical-nested-inner-hits]]
 ==== Hierarchical levels of nested object fields and inner hits.