11[[query-dsl-exists-query]]
22=== Exists Query
33
4- Returns documents that have at least one non-`null` value in the original field:
4+ Returns documents that contain a value other than `null` or `[]` in a provided
5+ field.
6+
7+ [[exists-query-ex-request]]
8+ ==== Example request
59
610[source,js]
7- --------------------------------------------------
11+ ----
812GET /_search
913{
1014 "query": {
11- "exists" : { "field" : "user" }
12- }
13- }
14- --------------------------------------------------
15- // CONSOLE
16-
17- For instance, these documents would all match the above query:
18-
19- [source,js]
20- --------------------------------------------------
21- { "user": "jane" }
22- { "user": "" } <1>
23- { "user": "-" } <2>
24- { "user": ["jane"] }
25- { "user": ["jane", null ] } <3>
26- --------------------------------------------------
27- // NOTCONSOLE
28- <1> An empty string is a non-`null` value.
29- <2> Even though the `standard` analyzer would emit zero tokens, the original field is non-`null`.
30- <3> At least one non-`null` value is required.
31-
32- These documents would *not* match the above query:
33-
34- [source,js]
35- --------------------------------------------------
36- { "user": null }
37- { "user": [] } <1>
38- { "user": [null] } <2>
39- { "foo": "bar" } <3>
40- --------------------------------------------------
41- // NOTCONSOLE
42- <1> This field has no values.
43- <2> At least one non-`null` value is required.
44- <3> The `user` field is missing completely.
45-
46- [float]
47- [[null-value-mapping]]
48- ==== `null_value` mapping
49-
50- If the field mapping includes the <<null-value,`null_value`>> setting
51- then explicit `null` values are replaced with the specified `null_value`. For
52- instance, if the `user` field were mapped as follows:
53-
54- [source,js]
55- --------------------------------------------------
56- PUT /example
57- {
58- "mappings": {
59- "_doc": {
60- "properties": {
61- "user": {
62- "type": "keyword",
63- "null_value": "_null_"
15+ "exists": {
16+ "field": "user"
6417 }
65- }
6618 }
67- }
6819}
69- --------------------------------------------------
20+ ----
7021// CONSOLE
7122
72- then explicit `null` values would be indexed as the string `_null_`, and the
73- following docs would match the `exists` filter:
74-
75- [source,js]
76- --------------------------------------------------
77- { "user": null }
78- { "user": [null] }
79- --------------------------------------------------
80- // NOTCONSOLE
81-
82- However, these docs--without explicit `null` values--would still have
83- no values in the `user` field and thus would not match the `exists` filter:
23+ [[exists-query-top-level-params]]
24+ ==== Top-level parameters for `exists`
25+ `field`::
26+ Name of the field you wish to search.
27+ +
28+ To return a document, this field must exist and contain a value other
29+ than `null` or `[]`. These values can include:
30+ +
31+ * Empty strings, such as `""` or `"-"`
32+ * Arrays containing `null` and another value, such as `[null, "foo"]`
33+ * A custom <<null-value, `null-value`>>, defined in field mapping
34+
35+ [[exists-query-notes]]
36+ ==== Notes
37+
38+ [[find-docs-null-values]]
39+ ===== Find documents with null values
40+ To find documents that contain only `null` values or `[]` in a provided field,
41+ use the `must_not` <<query-dsl-bool-query, boolean query>> with the `exists`
42+ query.
43+
44+ The following search returns documents that contain only `null` values or `[]`
45+ in the `user` field.
8446
8547[source,js]
86- --------------------------------------------------
87- { "user": [] }
88- { "foo": "bar" }
89- --------------------------------------------------
90- // NOTCONSOLE
91-
92- [[missing-query]]
93- ==== `missing` query
94-
95- There isn't a `missing` query. Instead use the `exists` query inside a
96- `must_not` clause as follows:
97-
98- [source,js]
99- --------------------------------------------------
48+ ----
10049GET /_search
10150{
10251 "query": {
@@ -109,7 +58,5 @@ GET /_search
10958 }
11059 }
11160}
112- --------------------------------------------------
113- // CONSOLE
114-
115- This query returns documents that have no value in the user field.
61+ ----
62+ // CONSOLE
0 commit comments