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- "properties": {
60- "user": {
61- "type": "keyword",
62- "null_value": "_null_"
63- }
15+ "exists": {
16+ "field": "user"
17+ }
6418 }
65- }
6619}
67- --------------------------------------------------
20+ ----
6821// CONSOLE
6922
70- then explicit `null` values would be indexed as the string `_null_`, and the
71- following docs would match the `exists` filter:
72-
73- [source,js]
74- --------------------------------------------------
75- { "user": null }
76- { "user": [null] }
77- --------------------------------------------------
78- // NOTCONSOLE
79-
80- However, these docs--without explicit `null` values--would still have
81- 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.
8246
8347[source,js]
84- --------------------------------------------------
85- { "user": [] }
86- { "foo": "bar" }
87- --------------------------------------------------
88- // NOTCONSOLE
89-
90- [[missing-query]]
91- ==== `missing` query
92-
93- There isn't a `missing` query. Instead use the `exists` query inside a
94- `must_not` clause as follows:
95-
96- [source,js]
97- --------------------------------------------------
48+ ----
9849GET /_search
9950{
10051 "query": {
@@ -107,7 +58,5 @@ GET /_search
10758 }
10859 }
10960}
110- --------------------------------------------------
111- // CONSOLE
112-
113- This query returns documents that have no value in the user field.
61+ ----
62+ // CONSOLE
0 commit comments