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 aremapped dynamically.

Theflattened type provides an alternative approach, where the entire object is mapped as a single field. Given an object, theflattened 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 amappings 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 theSupported operations section.

A 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-levelflattened 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"}  }}

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

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

• term,terms, andterms_set
• prefix
• range
• match andmulti_match
• query_string andsimple_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, includingrange, treat the values as string keywords. Highlighting is not supported onflattened fields.

It is possible to sort on a flattened object field, as well as perform simple keyword-style aggregations such asterms. 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 thestore parameter in the mapping.

Field values and concrete subfields can be retrieved using thefields parameter. content. Since theflattened field maps an entire object with potentially many subfields as a single field, the response contains the unaltered structure from_source.

Single subfields, however, can be fetched by specifying them explicitly in the request. This only works for concrete paths, but not using wildcards:

PUT my-index-000001{  "mappings": {    "properties": {      "flattened_field": {        "type": "flattened"      }    }  }}PUT my-index-000001/_doc/1?refresh=true{  "flattened_field" : {    "subfield" : "value"  }}POST my-index-000001/_search{  "fields": ["flattened_field.subfield"],  "_source": false}

{  "took": 2,  "timed_out": false,  "_shards": {    "total": 1,    "successful": 1,    "skipped": 0,    "failed": 0  },  "hits": {    "total": {      "value": 1,      "relation": "eq"    },    "max_score": 1.0,    "hits": [{      "_index": "my-index-000001",      "_id": "1",      "_score": 1.0,      "fields": {        "flattened_field.subfield" : [ "value" ]      }    }]  }}

You can also use aPainless script to retrieve values from sub-fields of flattened fields. Instead of includingdoc['<field_name>'].value in your Painless script, usedoc['<field_name>.<sub-field_name>'].value. For example, if you have a flattened field calledlabel with arelease sub-field, your Painless script would bedoc['labels.release'].value.

For example, let’s say your mapping contains two fields, one of which is of theflattened type:

PUT my-index-000001{  "mappings": {    "properties": {      "title": {        "type": "text"      },      "labels": {        "type": "flattened"      }    }  }}

Index a few documents containing your mapped fields. Thelabels field has three sub-fields:

POST /my-index-000001/_bulk?refresh{"index":{}}{"title":"Something really urgent","labels":{"priority":"urgent","release":["v1.2.5","v1.3.0"],"timestamp":{"created":1541458026,"closed":1541457010}}}{"index":{}}{"title":"Somewhat less urgent","labels":{"priority":"high","release":["v1.3.0"],"timestamp":{"created":1541458026,"closed":1541457010}}}{"index":{}}{"title":"Not urgent","labels":{"priority":"low","release":["v1.2.0"],"timestamp":{"created":1541458026,"closed":1541457010}}}

Becauselabels is aflattened field type, the entire object is mapped as a single field. To retrieve values from this sub-field in a Painless script, use thedoc['<field_name>.<sub-field_name>'].value format.

"script": {  "source": """    if (doc['labels.release'].value.equals('v1.3.0'))    {emit(doc['labels.release'].value)}    else{emit('Version mismatch')}  """

The following mapping parameters are accepted:

depth_limit

The maximum allowed depth of the flattened object field, in terms of nested inner objects. If a flattened object field exceeds this limit, then an error will be thrown. Defaults to20. Note thatdepth_limit can be updated dynamically through theupdate mapping API.

doc_values

Should the field be stored on disk in a column-stride fashion, so that it can later be used for sorting, aggregations, or scripting? Acceptstrue (default) orfalse.

eager_global_ordinals

Should global ordinals be loaded eagerly on refresh? Acceptstrue orfalse (default). Enabling this is a good idea on fields that are frequently used for terms aggregations.

ignore_above

Leaf values longer than this limit will not be indexed. By default, there is no limit and all values will be indexed. Note that this limit applies to the leaf values within the flattened object field, and not the length of the entire field.

index

Determines if the field should be searchable. Acceptstrue (default) orfalse.

index_options

What information should be stored in the index for scoring purposes. Defaults todocs but can also be set tofreqs to take term frequency into account when computing scores.

null_value

A string value which is substituted for any explicitnull values within the flattened object field. Defaults tonull, which means null fields are treated as if they were missing.

similarity

Which scoring algorithm orsimilarity should be used. Defaults toBM25.

split_queries_on_whitespace

Whetherfull text queries should split the input on whitespace when building a query for this field. Acceptstrue orfalse (default).

time_series_dimensions

(Optional, array of strings) A list of fields inside the flattened object, where each field is a dimension of the time series. Each field is specified using the relative path from the root field and does not include the root field name.

Flattened fields supportsynthetic_source in their default configuration.

Synthetic source may sortflattened field values and remove duplicates. For example:

PUT idx{  "settings": {    "index": {      "mapping": {        "source": {          "mode": "synthetic"        }      }    }  },  "mappings": {    "properties": {      "flattened": { "type": "flattened" }    }  }}PUT idx/_doc/1{  "flattened": {    "field": [ "apple", "apple", "banana", "avocado", "10", "200", "AVOCADO", "Banana", "Tangerine" ]  }}

Will become:

{  "flattened": {    "field": [ "10", "200", "AVOCADO", "Banana", "Tangerine", "apple", "avocado", "banana" ]  }}

Synthetic source always uses nested objects instead of array of objects. For example:

PUT idx{  "settings": {    "index": {      "mapping": {        "source": {          "mode": "synthetic"        }      }    }  },  "mappings": {    "properties": {      "flattened": { "type": "flattened" }    }  }}PUT idx/_doc/1{  "flattened": {      "field": [        { "id": 1, "name": "foo" },        { "id": 2, "name": "bar" },        { "id": 3, "name": "baz" }      ]  }}

Will become (note the nested objects instead of the "flattened" array):

{    "flattened": {      "field": {          "id": [ "1", "2", "3" ],          "name": [ "bar", "baz", "foo" ]      }    }}

Synthetic source always uses single-valued fields for one-element arrays. For example:

PUT idx{  "settings": {    "index": {      "mapping": {        "source": {          "mode": "synthetic"        }      }    }  },  "mappings": {    "properties": {      "flattened": { "type": "flattened" }    }  }}PUT idx/_doc/1{  "flattened": {    "field": [ "foo" ]  }}

Will become (note the nested objects instead of the "flattened" array):

{  "flattened": {    "field": "foo"  }}

Flattened fields allow for a key to contain both an object and a scalar value.For example, consider the following flattened fieldflattened:

{  "flattened": {    "foo.bar": "10",    "foo": {      "bar": {        "baz": "20"      }    }  }}

Because"foo.bar": "10" is implicitly equivalent to"foo": { "bar": "10" },"bar" has both a scalar value"10", and an object value of{ "baz": "20" }.

With synthetic source, to produce a valid JSON output, objects with such fields will appear differently in_source.For example, if the field is defined in an index configured with synthetic source, the value of_source would be:

{  "flattened": {    "foo": {      "bar": "10",      "bar.baz": "20"    }  }}