From de5db5f2536f61fb03cf75844b1cbfc6e4c4a248 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 23 Sep 2019 17:01:49 -0400 Subject: [PATCH 1/8] [DOCS] Add multi-level example to nested query docs --- .../reference/query-dsl/nested-query.asciidoc | 131 +++++++++++++++++- 1 file changed, 127 insertions(+), 4 deletions(-) diff --git a/docs/reference/query-dsl/nested-query.asciidoc b/docs/reference/query-dsl/nested-query.asciidoc index 619fe8c3dda23..bd2f0ea5d0b38 100644 --- a/docs/reference/query-dsl/nested-query.asciidoc +++ b/docs/reference/query-dsl/nested-query.asciidoc @@ -23,7 +23,7 @@ mapping. For example: ---- PUT /my_index { - "mappings": { + "mappings" : { "properties" : { "obj1" : { "type" : "nested" @@ -33,7 +33,6 @@ PUT /my_index } ---- -// TESTSETUP [[nested-query-ex-query]] ===== Example query @@ -42,7 +41,7 @@ PUT /my_index ---- GET /my_index/_search { - "query": { + "query": { "nested" : { "path" : "obj1", "query" : { @@ -58,6 +57,7 @@ GET /my_index/_search } } ---- +// TEST[continued] [[nested-top-level-params]] ==== Top-level parameters for `nested` @@ -78,6 +78,8 @@ such as `obj1.name`. Multi-level nesting is automatically supported, and detected, resulting in an inner nested query to automatically match the relevant nesting level, rather than root, if it exists within another nested query. + +See <> for an example. -- `score_mode`:: @@ -114,4 +116,125 @@ If `false`, {es} returns an error if the `path` is an unmapped field. You can use this parameter to query multiple indices that may not contain the field `path`. --- \ No newline at end of file +-- + +[[nested-query-notes]] +==== Notes + +[[multi-level-nested-query-ex]] +===== Multi-level nested queries + +To see how multi-level nested queries work, +try the following example. + +First, create an index, `drivers` +with a nested field mapping. + +Note the `model` field is nested as follows: + +``` +driver → vehicle → model +``` + +[source,console] +---- +PUT /drivers +{ + "mappings" : { + "properties" : { + "driver" : { + "type" : "nested", + "properties" : { + "vehicle" : { + "type" : "nested", + "properties" : { + "model" : { + "type" : "keyword" + } + } + } + } + } + } + } +} +---- + +Next, index a document to the `drivers` index. + +[source,console] +---- +PUT /drivers/_doc/1?refresh +{ + "driver" : { + "vehicle" : { + "model" : "Canyonero" + } + } +} +---- +// TEST[continued] + +You can now use a search request with a multi-level nested query +to return documents based on the `model` field. + +[source,console] +---- +GET /drivers/_search +{ + "query" : { + "nested" : { + "path" : "driver", + "query" : { + "nested" : { + "path" : "driver.vehicle", + "query" : { + "match" : { + "driver.vehicle.model" : "Canyonero" + } + } + } + } + } + } +} +---- +// TEST[continued] + +The search request returns the following response: + +[source,console-result] +---- +{ + "took" : 75, + "timed_out" : false, + "_shards" : { + "total" : 1, + "successful" : 1, + "skipped" : 0, + "failed" : 0 + }, + "hits" : { + "total" : { + "value" : 1, + "relation" : "eq" + }, + "max_score" : 0.2876821, + "hits" : [ + { + "_index" : "drivers", + "_id" : "1", + "_score" : 0.2876821, + "_source" : { + "driver" : { + "vehicle" : { + "model" : "Canyonero" + } + } + }, + } + ] + } +} +---- +// TESTRESPONSE[s/"took" : 75/"took": $body.took/] From 9e33d8d404458df019f0131d6cea57401776f67b Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 23 Sep 2019 20:10:39 -0400 Subject: [PATCH 2/8] Relocate mapping note --- docs/reference/query-dsl/nested-query.asciidoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/reference/query-dsl/nested-query.asciidoc b/docs/reference/query-dsl/nested-query.asciidoc index bd2f0ea5d0b38..3f4828090da5b 100644 --- a/docs/reference/query-dsl/nested-query.asciidoc +++ b/docs/reference/query-dsl/nested-query.asciidoc @@ -127,15 +127,9 @@ field `path`. To see how multi-level nested queries work, try the following example. -First, create an index, `drivers` +First, create an index, `drivers`, with a nested field mapping. -Note the `model` field is nested as follows: - -``` -driver → vehicle → model -``` - [source,console] ---- PUT /drivers @@ -148,7 +142,7 @@ PUT /drivers "vehicle" : { "type" : "nested", "properties" : { - "model" : { + "model" : { <1> "type" : "keyword" } } @@ -160,6 +154,12 @@ PUT /drivers } ---- +<1> Note the `model` field is nested as follows: ++ +``` +driver → vehicle → model +``` + Next, index a document to the `drivers` index. [source,console] From eb515648869dbcd2768ce00b549a2b0fe56dc0a4 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 24 Sep 2019 08:27:48 -0400 Subject: [PATCH 3/8] Relocate mapping note --- docs/reference/query-dsl/nested-query.asciidoc | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/docs/reference/query-dsl/nested-query.asciidoc b/docs/reference/query-dsl/nested-query.asciidoc index 3f4828090da5b..67f81c70aa579 100644 --- a/docs/reference/query-dsl/nested-query.asciidoc +++ b/docs/reference/query-dsl/nested-query.asciidoc @@ -125,10 +125,9 @@ field `path`. ===== Multi-level nested queries To see how multi-level nested queries work, -try the following example. - -First, create an index, `drivers`, -with a nested field mapping. +first you need an index that has nested fields. +The following request defines mappings for the `drivers` index +with the `model` field nested under `driver -> vehicle -> model`: [source,console] ---- @@ -142,7 +141,7 @@ PUT /drivers "vehicle" : { "type" : "nested", "properties" : { - "model" : { <1> + "model" : { "type" : "keyword" } } @@ -154,12 +153,6 @@ PUT /drivers } ---- -<1> Note the `model` field is nested as follows: -+ -``` -driver → vehicle → model -``` - Next, index a document to the `drivers` index. [source,console] From e3c6f4c6ce616cbb669202790326fd96e383e252 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 24 Sep 2019 08:29:54 -0400 Subject: [PATCH 4/8] Reword search request sentence --- docs/reference/query-dsl/nested-query.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/query-dsl/nested-query.asciidoc b/docs/reference/query-dsl/nested-query.asciidoc index 67f81c70aa579..537ed0808f88b 100644 --- a/docs/reference/query-dsl/nested-query.asciidoc +++ b/docs/reference/query-dsl/nested-query.asciidoc @@ -168,8 +168,8 @@ PUT /drivers/_doc/1?refresh ---- // TEST[continued] -You can now use a search request with a multi-level nested query -to return documents based on the `model` field. +You can now use a multi-level nested query +to retrieve documents based on the `model` field. [source,console] ---- From 40e4c5c3136678a85756ecc53e4a7872979948c4 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 24 Sep 2019 08:31:32 -0400 Subject: [PATCH 5/8] Reword search request sentence --- docs/reference/query-dsl/nested-query.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-dsl/nested-query.asciidoc b/docs/reference/query-dsl/nested-query.asciidoc index 537ed0808f88b..08eca20a6aef0 100644 --- a/docs/reference/query-dsl/nested-query.asciidoc +++ b/docs/reference/query-dsl/nested-query.asciidoc @@ -169,7 +169,7 @@ PUT /drivers/_doc/1?refresh // TEST[continued] You can now use a multi-level nested query -to retrieve documents based on the `model` field. +to search documents based on the `model` field. [source,console] ---- From 5179a365e9596c675ba974fb85bbaee317b0c6a4 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 24 Sep 2019 08:33:16 -0400 Subject: [PATCH 6/8] Reword search request sentence --- docs/reference/query-dsl/nested-query.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/query-dsl/nested-query.asciidoc b/docs/reference/query-dsl/nested-query.asciidoc index 08eca20a6aef0..21116efbdc3d1 100644 --- a/docs/reference/query-dsl/nested-query.asciidoc +++ b/docs/reference/query-dsl/nested-query.asciidoc @@ -169,7 +169,7 @@ PUT /drivers/_doc/1?refresh // TEST[continued] You can now use a multi-level nested query -to search documents based on the `model` field. +to match documents based on the `model` field. [source,console] ---- From 0eb74e542c719501b8f44d6fcca68f3d5efaecd5 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 24 Sep 2019 11:17:26 -0400 Subject: [PATCH 7/8] Rework example --- .../reference/query-dsl/nested-query.asciidoc | 74 +++++++++++++++---- 1 file changed, 58 insertions(+), 16 deletions(-) diff --git a/docs/reference/query-dsl/nested-query.asciidoc b/docs/reference/query-dsl/nested-query.asciidoc index 21116efbdc3d1..0bd892942090d 100644 --- a/docs/reference/query-dsl/nested-query.asciidoc +++ b/docs/reference/query-dsl/nested-query.asciidoc @@ -138,11 +138,17 @@ PUT /drivers "driver" : { "type" : "nested", "properties" : { + "last_name" : { + "type" : "text" + }, "vehicle" : { "type" : "nested", "properties" : { + "make" : { + "type" : "text" + }, "model" : { - "type" : "keyword" + "type" : "text" } } } @@ -153,16 +159,41 @@ PUT /drivers } ---- -Next, index a document to the `drivers` index. +Next, index some documents to the `drivers` index. [source,console] ---- -PUT /drivers/_doc/1?refresh +PUT /drivers/_doc/1 { "driver" : { - "vehicle" : { - "model" : "Canyonero" - } + "last_name" : "McQueen", + "vehicle" : [ + { + "make" : "Powell Motors", + "model" : "Canyonero" + }, + { + "make" : "Miller-Meteor", + "model" : "Ecto-1" + } + ] + } +} + +PUT /drivers/_doc/2?refresh +{ + "driver" : { + "last_name" : "Hudson", + "vehicle" : [ + { + "make" : "Mifune", + "model" : "Mach Five" + }, + { + "make" : "Miller-Meteor", + "model" : "Ecto-1" + } + ] } } ---- @@ -182,8 +213,11 @@ GET /drivers/_search "nested" : { "path" : "driver.vehicle", "query" : { - "match" : { - "driver.vehicle.model" : "Canyonero" + "bool" : { + "must" : [ + { "match" : { "driver.vehicle.make" : "Powell Motors" } }, + { "match" : { "driver.vehicle.model" : "Canyonero" } } + ] } } } @@ -199,7 +233,7 @@ The search request returns the following response: [source,console-result] ---- { - "took" : 75, + "took" : 5, "timed_out" : false, "_shards" : { "total" : 1, @@ -212,22 +246,30 @@ The search request returns the following response: "value" : 1, "relation" : "eq" }, - "max_score" : 0.2876821, + "max_score" : 3.7349272, "hits" : [ { "_index" : "drivers", "_id" : "1", - "_score" : 0.2876821, + "_score" : 3.7349272, "_source" : { "driver" : { - "vehicle" : { - "model" : "Canyonero" - } + "last_name" : "McQueen", + "vehicle" : [ + { + "make" : "Powell Motors", + "model" : "Canyonero" + }, + { + "make" : "Miller-Meteor", + "model" : "Ecto-1" + } + ] } - }, + } } ] } } ---- -// TESTRESPONSE[s/"took" : 75/"took": $body.took/] +// TESTRESPONSE[s/"took" : 5/"took": $body.took/] From 2dedd5899178696a8b45ad64abc022368a21be99 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 24 Sep 2019 11:20:42 -0400 Subject: [PATCH 8/8] Adjust wording for example updates --- docs/reference/query-dsl/nested-query.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/query-dsl/nested-query.asciidoc b/docs/reference/query-dsl/nested-query.asciidoc index 0bd892942090d..24d3e619f5970 100644 --- a/docs/reference/query-dsl/nested-query.asciidoc +++ b/docs/reference/query-dsl/nested-query.asciidoc @@ -127,7 +127,7 @@ field `path`. To see how multi-level nested queries work, first you need an index that has nested fields. The following request defines mappings for the `drivers` index -with the `model` field nested under `driver -> vehicle -> model`: +with nested `make` and `model` fields. [source,console] ---- @@ -200,7 +200,7 @@ PUT /drivers/_doc/2?refresh // TEST[continued] You can now use a multi-level nested query -to match documents based on the `model` field. +to match documents based on the `make` and `model` fields. [source,console] ----