Docs: Improve the exists/missing filters documentation

Closes #7274
This commit is contained in:
Clinton Gormley 2014-11-08 16:57:41 +01:00
parent f5ad699284
commit b9149f836b
2 changed files with 167 additions and 9 deletions

View File

@ -1,7 +1,7 @@
[[query-dsl-exists-filter]]
=== Exists Filter
Filters documents where a specific field has a value in them.
Returns documents that have at least one non-`null` value in the original field:
[source,js]
--------------------------------------------------
@ -14,6 +14,67 @@ Filters documents where a specific field has a value in them.
}
--------------------------------------------------
For instance, these documents would all match the above filter:
[source,js]
--------------------------------------------------
{ "user": "jane" }
{ "user": "" } <1>
{ "user": "-" } <2>
{ "user": ["jane"] }
{ "user": ["jane", null ] } <3>
--------------------------------------------------
<1> An empty string is a non-`null` value.
<2> Even though the `standard` analyzer would emit zero tokens, the original field is non-`null`.
<3> At least one non-`null` value is required.
These documents would *not* match the above filter:
[source,js]
--------------------------------------------------
{ "user": null }
{ "user": [] } <1>
{ "user": [null] } <2>
{ "foo": "bar" } <3>
--------------------------------------------------
<1> This field has no values.
<2> At least one non-`null` value is required.
<3> The `user` field is missing completely.
[float]
==== `null_value` mapping
If the field mapping includes the `null_value` setting (see <<mapping-core-types>>)
then explicit `null` values are replaced with the specified `null_value`. For
instance, if the `user` field were mapped as follows:
[source,js]
--------------------------------------------------
"user": {
"type": "string",
"null_value": "_null_"
}
--------------------------------------------------
then explicit `null` values would be indexed as the string `_null_`, and the
following docs would match the `exists` filter:
[source,js]
--------------------------------------------------
{ "user": null }
{ "user": [null] }
--------------------------------------------------
However, these docs--without explicit `null` values--would still have
no values in the `user` field and thus would not match the `exists` filter:
[source,js]
--------------------------------------------------
{ "user": [] }
{ "foo": "bar" }
--------------------------------------------------
[float]
==== Caching

View File

@ -1,7 +1,7 @@
[[query-dsl-missing-filter]]
=== Missing Filter
Filters documents where a specific field has no value in them.
Returns documents that have no non-`null` values in the original field:
[source,js]
--------------------------------------------------
@ -14,11 +14,72 @@ Filters documents where a specific field has no value in them.
}
--------------------------------------------------
By default, the filter will only find "missing" fields, i.e., fields
that have no values. It can be configured also to find fields with an
explicit `null_value` mapped for them. Here is an example that will both
find missing field that doesn't exist (`existence` set to `true`), or
have null values (`null_value` set to `true`).
For instance, the following docs would match the above filter:
[source,js]
--------------------------------------------------
{ "user": null }
{ "user": [] } <1>
{ "user": [null] } <2>
{ "foo": "bar" } <3>
--------------------------------------------------
<1> This field has no values.
<2> This field has no non-`null` values.
<3> The `user` field is missing completely.
These documents would *not* match the above filter:
[source,js]
--------------------------------------------------
{ "user": "jane" }
{ "user": "" } <1>
{ "user": "-" } <2>
{ "user": ["jane"] }
{ "user": ["jane", null ] } <3>
--------------------------------------------------
<1> An empty string is a non-`null` value.
<2> Even though the `standard` analyzer would emit zero tokens, the original field is non-`null`.
<3> This field has one non-`null` value.
[float]
==== `null_value` mapping
If the field mapping includes a `null_value` (see <<mapping-core-types>>) then explicit `null` values
are replaced with the specified `null_value`. For instance, if the `user` field were mapped
as follows:
[source,js]
--------------------------------------------------
"user": {
"type": "string",
"null_value": "_null_"
}
--------------------------------------------------
then explicit `null` values would be indexed as the string `_null_`, and the
the following docs would *not* match the `missing` filter:
[source,js]
--------------------------------------------------
{ "user": null }
{ "user": [null] }
--------------------------------------------------
However, these docs--without explicit `null` values--would still have
no values in the `user` field and thus would match the `missing` filter:
[source,js]
--------------------------------------------------
{ "user": [] }
{ "foo": "bar" }
--------------------------------------------------
[float]
===== `existence` and `null_value` parameters
When the field being queried has a `null_value` mapping, then the behaviour of
the `missing` filter can be altered with the `existence` and `null_value`
parameters:
[source,js]
--------------------------------------------------
@ -28,13 +89,49 @@ have null values (`null_value` set to `true`).
"missing" : {
"field" : "user",
"existence" : true,
"null_value" : true
"null_value" : false
}
}
}
}
--------------------------------------------------
`existence`::
+
--
When the `existence` parameter is set to `true` (the default), the missing
filter will include documents where the field has *no* values, ie:
[source,js]
--------------------------------------------------
{ "user": [] }
{ "foo": "bar" }
--------------------------------------------------
When set to `false`, these documents will not be included.
--
`null_value`::
+
--
When the `null_value` parameter is set to `true`, the missing
filter will include documents where the field contains a `null` value, ie:
[source,js]
--------------------------------------------------
{ "user": null }
{ "user": [null] }
{ "user": ["jane",null] } <1>
--------------------------------------------------
<1> Matches because the field contains a `null` value, even though it also contains a non-`null` value.
When set to `false` (the default), these documents will not be included.
--
NOTE: Either `existence` or `null_value` or both must be set to `true`.
[float]
==== Caching