WARNING: The 2.x versions of Elasticsearch have passed their EOL dates. If you are running a 2.x version, we strongly advise you to upgrade.
This documentation is no longer maintained and may be removed. For the latest information, see the current Elasticsearch documentation.
Dynamic Mapping
editDynamic Mapping
editWhen Elasticsearch encounters a previously unknown field in a document, it uses dynamic mapping to determine the datatype for the field and automatically adds the new field to the type mapping.
Sometimes this is the desired behavior and sometimes it isn’t. Perhaps you don’t know what fields will be added to your documents later, but you want them to be indexed automatically. Perhaps you just want to ignore them. Or—especially if you are using Elasticsearch as a primary data store—perhaps you want unknown fields to throw an exception to alert you to the problem.
Fortunately, you can control this behavior with the dynamic
setting,
which accepts the following options:
-
true
- Add new fields dynamically—the default
-
false
- Ignore new fields
-
strict
- Throw an exception if an unknown field is encountered
The dynamic
setting may be applied to the root object or to any field
of type object
. You could set dynamic
to strict
by default,
but enable it just for a specific inner object:
PUT /my_index { "mappings": { "my_type": { "dynamic": "strict", "properties": { "title": { "type": "string"}, "stash": { "type": "object", "dynamic": true } } } } }
The |
|
The |
With this mapping, you can add new searchable fields into the stash
object:
PUT /my_index/my_type/1 { "title": "This doc adds a new field", "stash": { "new_field": "Success!" } }
But trying to do the same at the top level will fail:
PUT /my_index/my_type/1 { "title": "This throws a StrictDynamicMappingException", "new_field": "Fail!" }
Setting dynamic
to false
doesn’t alter the contents of the _source
field at all. The _source
will still contain the whole JSON document that
you indexed. However, any unknown fields will not be added to the mapping and
will not be searchable.