Skip to content

Commit 49c9daa

Browse files
authored
[DOCS] Rewrite exists query docs (#41868)
1 parent 372ab92 commit 49c9daa

File tree

1 file changed

+36
-87
lines changed

1 file changed

+36
-87
lines changed
Lines changed: 36 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,51 @@
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+
----
812
GET /_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+
----
9849
GET /_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

Comments
 (0)