From 61de50b95ff67716b94d2424d86a5fc29dea80c4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mantas=20Marcinkevi=C4=8Dius?= <marc.mantas@gmail.com>
Date: Thu, 21 Jul 2016 10:15:03 +0300
Subject: [PATCH] added documentation for the nested inner hit

---
 docs/InnerHits/Nested.md | 111 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 docs/InnerHits/Nested.md

diff --git a/docs/InnerHits/Nested.md b/docs/InnerHits/Nested.md
new file mode 100644
index 0000000..76b6990
--- /dev/null
+++ b/docs/InnerHits/Nested.md
@@ -0,0 +1,111 @@
+# Nested Inner Hits
+
+> More info about inner hits is in the [official elasticsearch docs][1]
+
+The nested inner_hits can be used to include nested inner objects as inner hits to a search hit.
+The actual matches in the different scopes that caused a document to be returned is hidden.
+In many cases, it’s very useful to know which inner nested objects caused certain information to be returned.
+
+## Simple example
+
+```JSON
+{
+    "query" : {
+        "nested" : {
+            "path" : "comments",
+            "query" : {
+                "match" : {"comments.message" : "[actual query]"}
+            }
+        }
+    },
+    "inner_hits" : {
+        "comment" : {
+            "path" : {
+                "comments" : {
+                    "query" : {
+                        "match" : {"comments.message" : "[different query]"}
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+And now the query via DSL:
+
+```php
+$matchQuery = new MatchQuery('comments.message', '[different query]');
+$nestedQuery = new NestedQuery('comments', $matchQuery);
+$innerHit = new NestedInnerHit('comment', 'comments', $matchQuery);
+
+$search = new Search();
+$search->addQuery(new MatchQuery('comments.message', '[actual query]'));
+$search->addInnerHit($innerHit);
+$search->toArray();
+```
+
+In the example above `comment` is the name of the inner hit, `comments` is the path
+to the nested field and `$matchQuery` is the actual query that will be executed.
+
+## Nesting inner hits
+
+It is possible to nest inner hits in order to reach deeper levels of nested objects.
+Here is an example of nesting inner hits:
+
+```JSON
+{
+  "inner_hits": {
+    "cars": {
+      "path": {
+        "cars": {
+          "query": {
+            "nested": {
+              "path": "cars.manufacturers",
+              "query": {
+                "match": {
+                  "cars.manufacturers.country": {
+                    "query": "Japan"
+                  }
+                }
+              }
+            }
+          },
+          "inner_hits": {
+            "manufacturers": {
+              "path": {
+                "cars.manufacturers": {
+                  "query": {
+                    "match": {
+                      "cars.manufacturers.country": {
+                        "query": "Japan"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+And now the query via DSL:
+
+```php
+
+$matchQuery = new MatchQuery('cars.manufacturers.country', 'Japan');
+$nestedQuery = new NestedQuery('cars.manufacturers', $matchQuery);
+$innerHitNested = new NestedInnerHit('manufacturers', 'cars.manufacturers', $matchQuery);
+$innerHit = new NestedInnerHit('cars', 'cars', $nestedQuery);
+$innerHit->addInnerHit($innerHitNested);
+
+$search = new Search();
+$search->addInnerHit($innerHit);
+$search->toArray();
+
+```
+[1]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-inner-hits.html
\ No newline at end of file
-- 
GitLab