From a75964d8fd1f407409d6408ab3dc6c5dcfcdaeea Mon Sep 17 00:00:00 2001 From: markharwood Date: Wed, 12 Jun 2019 09:26:26 +0100 Subject: [PATCH] Docs change for exists query. (#43092) Now emphasises the test is for indexed values. Previous documentation only mentioned the state of the input JSON doc (null values) but this is only one of several reasons why an indexed value may not exist. Closes #24256 --- .../reference/query-dsl/exists-query.asciidoc | 21 ++++++++++++------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/reference/query-dsl/exists-query.asciidoc b/docs/reference/query-dsl/exists-query.asciidoc index 9c7553e314c..f35e97db8ec 100644 --- a/docs/reference/query-dsl/exists-query.asciidoc +++ b/docs/reference/query-dsl/exists-query.asciidoc @@ -1,8 +1,14 @@ [[query-dsl-exists-query]] === Exists Query -Returns documents that contain a value other than `null` or `[]` in a provided -field. +Returns documents that contain an indexed value for a field. + +An indexed value may not exist for a document's field due to a variety of reasons: + +* The field in the source JSON is `null` or `[]` +* The field has `"index" : false` set in the mapping +* The length of the field value exceeded an `ignore_above` setting in the mapping +* The field value was malformed and `ignore_malformed` was defined in the mapping [[exists-query-ex-request]] ==== Example request @@ -25,8 +31,7 @@ GET /_search `field`:: Name of the field you wish to search. + -To return a document, this field must exist and contain a value other -than `null` or `[]`. These values can include: +While a field is deemed non-existant if the JSON value is `null` or `[]`, these values will indicate the field does exist: + * Empty strings, such as `""` or `"-"` * Arrays containing `null` and another value, such as `[null, "foo"]` @@ -36,13 +41,13 @@ than `null` or `[]`. These values can include: ==== Notes [[find-docs-null-values]] -===== Find documents with null values -To find documents that contain only `null` values or `[]` in a provided field, +===== Find documents missing indexed values +To find documents that are missing an indexed value for a field, use the `must_not` <> with the `exists` query. -The following search returns documents that contain only `null` values or `[]` -in the `user` field. +The following search returns documents that are missing an indexed value for +the `user` field. [source,js] ----