adding null_value mapping parameter docs

_field-types/mapping-parameters/null-value.md

@@ -0,0 +1,135 @@
+---
+layout: default
+title: Null value
+parent: Mapping parameters
+grand_parent: Mapping and field types
+nav_order: 130
+has_children: false
+has_toc: false
+---
+
+# Null value
+
+The `null_value` mapping parameter allows you to replace explicit `null` values with a predefined substitute during indexing. By default, if a field is set to `null`, it is not indexed and cannot be searched. With `null_value` defined, the specified replacement value is indexed instead, making it possible to query or aggregate on documents where a field was originally `null`, however, it does not modify the `_source` of the document.
+
+The `null_value` must be of the same type as the field it is applied to. For instance, a `date` field cannot use a `boolean` such as `true` as its `null_value`. It must be a valid date string.
+{: .important}
+
+## Setting a null_value on a field
+
+The following request creates an index named `products` where the `category` field is of type `keyword` and replaces `null` values with `"unknown"` during indexing:
+
+```json
+PUT /products
+{
+  "mappings": {
+    "properties": {
+      "category": {
+        "type": "keyword",
+        "null_value": "unknown"
+      }
+    }
+  }
+}
+```
+{% include copy-curl.html %}
+
+## Indexing a document with a null value
+
+Use the following command to index a document that has null for category:
+
+```json
+PUT /products/_doc/1
+{
+  "category": null
+}
+```
+{% include copy-curl.html %}
+
+## Querying the null substitute
+
+Use the following command to search for documents where category was previously `null`:
+
+```json
+POST /products/_search
+{
+  "query": {
+    "term": {
+      "category": "unknown"
+    }
+  }
+}
+```
+{% include copy-curl.html %}
+
+Expected result:
+
+```json
+{
+  ...
+  "hits": {
+    "total": {
+      "value": 1,
+      "relation": "eq"
+    },
+    "max_score": 0.2876821,
+    "hits": [
+      {
+        "_index": "products",
+        "_id": "1",
+        "_score": 0.2876821,
+        "_source": {
+          "category": null
+        }
+      }
+    ]
+  }
+}
+```
+
+## Aggregating on null substitute
+
+Since the null replacement is indexed, it also appears in aggregations. Use the following command to perform a `terms` aggregation on the `category` field:
+
+```json
+POST /products/_search
+{
+  "size": 0,
+  "aggs": {
+    "category_count": {
+      "terms": {
+        "field": "category"
+      }
+    }
+  }
+}
+```
+{% include copy-curl.html %}
+
+Expected result:
+
+```json
+{
+  ...
+  "hits": {
+    "total": {
+      "value": 1,
+      "relation": "eq"
+    },
+    "max_score": null,
+    "hits": []
+  },
+  "aggregations": {
+    "category_count": {
+      "doc_count_error_upper_bound": 0,
+      "sum_other_doc_count": 0,
+      "buckets": [
+        {
+          "key": "unknown",
+          "doc_count": 1
+        }
+      ]
+    }
+  }
+}
+```