From b9149f836b61382446f8d14feb05cde5810602e8 Mon Sep 17 00:00:00 2001
From: Clinton Gormley <clint@traveljury.com>
Date: Sat, 8 Nov 2014 16:57:41 +0100
Subject: [PATCH] Docs: Improve the exists/missing filters documentation

Closes #7274
---
 .../query-dsl/filters/exists-filter.asciidoc  |  63 +++++++++-
 .../query-dsl/filters/missing-filter.asciidoc | 113 ++++++++++++++++--
 2 files changed, 167 insertions(+), 9 deletions(-)

diff --git a/docs/reference/query-dsl/filters/exists-filter.asciidoc b/docs/reference/query-dsl/filters/exists-filter.asciidoc
index 80e9495c7d3..1b08cd2675e 100644
--- a/docs/reference/query-dsl/filters/exists-filter.asciidoc
+++ b/docs/reference/query-dsl/filters/exists-filter.asciidoc
@@ -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
 
diff --git a/docs/reference/query-dsl/filters/missing-filter.asciidoc b/docs/reference/query-dsl/filters/missing-filter.asciidoc
index a5a16c0945c..9374524b822 100644
--- a/docs/reference/query-dsl/filters/missing-filter.asciidoc
+++ b/docs/reference/query-dsl/filters/missing-filter.asciidoc
@@ -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,27 +14,124 @@ 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]
 --------------------------------------------------
 {
     "constant_score" : {
         "filter" : {
-            "missing" : { 
+            "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