You're viewing version 2.19 of the OpenSearch documentation. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

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
        }
      ]
    }
  }
}