subobjects
editsubobjects
editWhen indexing a document or updating mappings, Elasticsearch accepts fields that contain dots in their names,
which get expanded to their corresponding object structure. For instance, the field metrics.time.max
is mapped as a max
leaf field with a parent time
object, belonging to its parent metrics
object.
The described default behaviour is reasonable for most scenarios, but causes problems in certain situations
where for instance a field metrics.time
holds a value too, which is common when indexing metrics data.
A document holding a value for both metrics.time.max
and metrics.time
gets rejected given that time
would need to be a leaf field to hold a value as well as an object to hold the max
sub-field.
The subobjects
setting, which can be applied only to the top-level mapping definition and
to object
fields, disables the ability for an object to hold further subobjects and makes it possible
to store documents where field names contain dots and share common prefixes. From the example above, if the object
container metrics
has subobjects
set to false
, it can hold values for both time
and time.max
directly
without the need for any intermediate object, as dots in field names are preserved.
PUT my-index-000001 { "mappings": { "properties": { "metrics": { "type": "object", "subobjects": false } } } } PUT my-index-000001/_doc/metric_1 { "metrics.time" : 100, "metrics.time.min" : 10, "metrics.time.max" : 900 } PUT my-index-000001/_doc/metric_2 { "metrics" : { "time" : 100, "time.min" : 10, "time.max" : 900 } } GET my-index-000001/_mapping
{ "my-index-000001" : { "mappings" : { "properties" : { "metrics" : { "subobjects" : false, "properties" : { "time" : { "type" : "long" }, "time.min" : { "type" : "long" }, "time.max" : { "type" : "long" } } } } } } }
The |
|
Sample document holding flat paths |
|
Sample document holding an object (configured to not hold subobjects) and its leaf sub-fields |
|
The resulting mapping where dots in field names were preserved |
The entire mapping may be configured to not support subobjects as well, in which case the document can only ever hold leaf sub-fields:
PUT my-index-000001 { "mappings": { "subobjects": false } } PUT my-index-000001/_doc/metric_1 { "time" : "100ms", "time.min" : "10ms", "time.max" : "900ms" }
The subobjects
setting for existing fields and the top-level mapping definition cannot be updated.