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. This allows you to query or aggregate documents in which a field was originally null without modifying the document _source.

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; the null_value must be a valid date string.

Setting a null_value on a field

The following request creates an index named products. The category field is of type keyword and replaces null values with "unknown" during indexing:

PUT /products
{
  "mappings": {
    "properties": {
      "category": {
        "type": "keyword",
        "null_value": "unknown"
      }
    }
  }
}

Indexing a document with a null value

Use the following command to index a document in which the category field is set to null:

PUT /products/_doc/1
{
  "category": null
}

Querying the null substitute

Use the following command to search for documents in which the category field was previously null:

POST /products/_search
{
  "query": {
    "term": {
      "category": "unknown"
    }
  }
}

The response contains the matching document:

{
  ...
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.2876821,
    "hits": [
      {
        "_index": "products",
        "_id": "1",
        "_score": 0.2876821,
        "_source": {
          "category": null
        }
      }
    ]
  }
}

Aggregating on a null substitute

Because the null replacement is indexed, it also appears in aggregations. Use the following command to perform a terms aggregation on the category field:

POST /products/_search
{
  "size": 0,
  "aggs": {
    "category_count": {
      "terms": {
        "field": "category"
      }
    }
  }
}

The response contains aggregated results:

{
  ...
  "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
        }
      ]
    }
  }
}