From 51aefbdd3d0c30b479cd1ce8dc8e5e5166c378a9 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Fri, 19 Jul 2019 10:50:36 -0400 Subject: [PATCH] [DOCS] Reformat `has_parent` query docs (#44443) --- .../query-dsl/has-parent-query.asciidoc | 170 +++++++++++------- 1 file changed, 103 insertions(+), 67 deletions(-) diff --git a/docs/reference/query-dsl/has-parent-query.asciidoc b/docs/reference/query-dsl/has-parent-query.asciidoc index 60bd906117c..39cb22fb750 100644 --- a/docs/reference/query-dsl/has-parent-query.asciidoc +++ b/docs/reference/query-dsl/has-parent-query.asciidoc @@ -4,93 +4,129 @@ Has parent ++++ -The `has_parent` query accepts a query and a parent type. The query is -executed in the parent document space, which is specified by the parent -type. This query returns child documents which associated parents have -matched. For the rest `has_parent` query has the same options and works -in the same manner as the `has_child` query. +Returns child documents whose <> parent document matches a +provided query. You can create parent-child relationships between documents in +the same index using a <> field mapping. + +[WARNING] +==== +Because it performs a join, the `has_parent` query is slow compared to other queries. +Its performance degrades as the number of matching parent documents increases. +Each `has_parent` query in a search can increase query time significantly. +==== + +[[has-parent-query-ex-request]] +==== Example request + +[[has-parent-index-setup]] +===== Index setup +To use the `has_parent` query, your index must include a <> +field mapping. For example: [source,js] --------------------------------------------------- -GET /_search +---- +PUT /my-index +{ + "mappings": { + "properties" : { + "my-join-field" : { + "type" : "join", + "relations": { + "parent": "child" + } + }, + "tag" : { + "type" : "keyword" + } + } + } +} + +---- +// CONSOLE +// TESTSETUP + +[[has-parent-query-ex-query]] +===== Example query + +[source,js] +---- +GET /my-index/_search { "query": { "has_parent" : { - "parent_type" : "blog", + "parent_type" : "parent", "query" : { "term" : { - "tag" : "something" + "tag" : { + "value" : "Elasticsearch" + } } } } } } --------------------------------------------------- +---- // CONSOLE -Note that the `has_parent` is a slow query compared to other queries in the -query dsl due to the fact that it performs a join. The performance degrades -as the number of matching parent documents increases. If you care about query -performance you should not use this query. However if you do happen to use -this query then use it as less as possible. Each `has_parent` query that gets -added to a search request can increase query time significantly. +[[has-parent-top-level-params]] +==== Top-level parameters for `has_parent` -[float] -==== Scoring capabilities +`parent_type`:: +(Required, string) Name of the parent relationship mapped for the +<> field. -The `has_parent` also has scoring support. The default is `false` which -ignores the score from the parent document. The score is in this -case equal to the boost on the `has_parent` query (Defaults to 1). If -the score is set to `true`, then the score of the matching parent -document is aggregated into the child documents belonging to the -matching parent document. The score mode can be specified with the -`score` field inside the `has_parent` query: +`query`:: +(Required, query object) Query you wish to run on parent documents of the +`parent_type` field. If a parent document matches the search, the query returns +its child documents. + +`score`:: ++ +-- +(Optional, boolean) Indicates whether the <> of a matching parent document is aggregated into its child documents. +Defaults to `false`. + +If `false`, {es} ignores the relevance score of the parent document. {es} also +assigns each child document a relevance score equal to the `query`'s `boost`, +which defaults to `1`. + +If `true`, the relevance score of the matching parent document is aggregated +into its child documents' relevance scores. +-- + +`ignore_unmapped`:: ++ +-- +(Optional, boolean) Indicates whether to ignore an unmapped `parent_type` and +not return any documents instead of an error. Defaults to `false`. + +If `false`, {es} returns an error if the `parent_type` is unmapped. + +You can use this parameter to query multiple indices that may not contain the +`parent_type`. +-- + +[[has-parent-query-notes]] +==== Notes + +[[has-parent-query-performance]] +===== Sorting +You cannot sort the results of a `has_parent` query using standard +<>. + +If you need to sort returned documents by a field in their parent documents, use +a `function_score` query and sort by `_score`. For example, the following query +sorts returned documents by the `view_count` field of their parent documents. [source,js] --------------------------------------------------- +---- GET /_search { "query": { "has_parent" : { - "parent_type" : "blog", - "score" : true, - "query" : { - "term" : { - "tag" : "something" - } - } - } - } -} --------------------------------------------------- -// CONSOLE - -[float] -==== Ignore Unmapped - -When set to `true` the `ignore_unmapped` option will ignore an unmapped `type` -and will not match any documents for this query. This can be useful when -querying multiple indexes which might have different mappings. When set to -`false` (the default value) the query will throw an exception if the `type` -is not mapped. - -[float] -==== Sorting - -Child documents can't be sorted by fields in matching parent documents via the -regular sort options. If you need to sort child documents by field in the parent -documents then you should use the `function_score` query and then just sort -by `_score`. - -Sorting tags by parent document' `view_count` field: - -[source,js] --------------------------------------------------- -GET /_search -{ - "query": { - "has_parent" : { - "parent_type" : "blog", + "parent_type" : "parent", "score" : true, "query" : { "function_score" : { @@ -102,5 +138,5 @@ GET /_search } } } --------------------------------------------------- -// CONSOLE +---- +// CONSOLE \ No newline at end of file