Imported Upstream version 1.0.3upstream/1.0.3

1 files changed, 71 insertions, 0 deletions

diff --git a/docs/reference/query-dsl/queries/top-children-query.asciidoc b/docs/reference/query-dsl/queries/top-children-query.asciidoc
new file mode 100644
index 0000000..00c32bf
--- /dev/null
+++ b/docs/reference/query-dsl/queries/top-children-query.asciidoc
@@ -0,0 +1,71 @@
+[[query-dsl-top-children-query]]
+=== Top Children Query
+
+The `top_children` query runs the child query with an estimated hits
+size, and out of the hit docs, aggregates it into parent docs. If there
+aren't enough parent docs matching the requested from/size search
+request, then it is run again with a wider (more hits) search.
+
+The `top_children` also provide scoring capabilities, with the ability
+to specify `max`, `sum` or `avg` as the score type.
+
+One downside of using the `top_children` is that if there are more child
+docs matching the required hits when executing the child query, then the
+`total_hits` result of the search response will be incorrect.
+
+How many hits are asked for in the first child query run is controlled
+using the `factor` parameter (defaults to `5`). For example, when asking
+for 10 parent docs (with `from` set to 0), then the child query will
+execute with 50 hits expected. If not enough parents are found (in our
+example 10), and there are still more child docs to query, then the
+child search hits are expanded by multiplying by the
+`incremental_factor` (defaults to `2`).
+
+The required parameters are the `query` and `type` (the child type to
+execute the query on). Here is an example with all different parameters,
+including the default values:
+
+[source,js]
+--------------------------------------------------
+{
+    "top_children" : {
+        "type": "blog_tag",
+        "query" : {
+            "term" : {
+                "tag" : "something"
+            }
+        },
+        "score" : "max",
+        "factor" : 5,
+        "incremental_factor" : 2
+    }
+}
+--------------------------------------------------
+
+[float]
+==== Scope
+
+A `_scope` can be defined on the query allowing to run facets on the
+same scope name that will work against the child documents. For example:
+
+[source,js]
+--------------------------------------------------
+{
+    "top_children" : {
+        "_scope" : "my_scope",
+        "type": "blog_tag",
+        "query" : {
+            "term" : {
+                "tag" : "something"
+            }
+        }
+    }
+}
+--------------------------------------------------
+
+[float]
+==== Memory Considerations
+
+With the current implementation, all `_id` values are loaded to memory
+(heap) in order to support fast lookups, so make sure there is enough
+memory for it.