Flattened field type

By default, each subfield in an object is mapped and indexed separately. If the names or types of the subfields are not known in advance, then they are mapped dynamically.

The flattened type provides an alternative approach, where the entire object is mapped as a single field. Given an object, the flattened mapping will parse out its leaf values and index them into one field as keywords. The object’s contents can then be searched through simple queries and aggregations.

This data type can be useful for indexing objects with a large or unknown number of unique keys. Only one field mapping is created for the whole JSON object, which can help prevent a mappings explosion from having too many distinct field mappings.

On the other hand, flattened object fields present a trade-off in terms of search functionality. Only basic queries are allowed, with no support for numeric range queries or highlighting. Further information on the limitations can be found in the Supported operations section.

The flattened mapping type should not be used for indexing all document content, as it treats all values as keywords and does not provide full search functionality. The default approach, where each subfield has its own entry in the mappings, works well in the majority of cases.

An flattened object field can be created as follows:

PUT bug_reports
{
  "mappings": {
    "properties": {
      "title": {
        "type": "text"
      },
      "labels": {
        "type": "flattened"
      }
    }
  }
}
POST bug_reports/_doc/1
{
  "title": "Results are not sorted correctly.",
  "labels": {
    "priority": "urgent",
    "release": ["v1.2.5", "v1.3.0"],
    "timestamp": {
      "created": 1541458026,
      "closed": 1541457010
    }
  }
}

During indexing, tokens are created for each leaf value in the JSON object. The values are indexed as string keywords, without analysis or special handling for numbers or dates.

Querying the top-level flattened field searches all leaf values in the object:

POST bug_reports/_search
{
  "query": {
    "term": {"labels": "urgent"}
  }
}

To query on a specific key in the flattened object, object dot notation is used:

POST bug_reports/_search
{
  "query": {
    "term": {"labels.release": "v1.3.0"}
  }
}

Supported operations

Because of the similarities in the way values are indexed, flattened fields share much of the same mapping and search functionality as keyword fields.

Currently, flattened object fields can be used with the following query types:

• term, terms, and terms_set
• prefix
• range
• match and multi_match
• query_string and simple_query_string
• exists

When querying, it is not possible to refer to field keys using wildcards, as in { "term": {"labels.time*": 1541457010}}. Note that all queries, including range, treat the values as string keywords. Highlighting is not supported on flattened fields.

It is possible to sort on an flattened object field, as well as perform simple keyword-style aggregations such as terms. As with queries, there is no special support for numerics — all values in the JSON object are treated as keywords. When sorting, this implies that values are compared lexicographically.

Flattened object fields currently cannot be stored. It is not possible to specify the store parameter in the mapping.

Parameters for flattened object fields

The following mapping parameters are accepted: