35_Dynamic_Mapping.asciidoc

Dynamic mapping

When 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 behaviour and sometimes it isn’t. Perhaps you don’t know what fields will be added to your documents later on, 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 datastore — perhaps you want unknown fields to throw an exception to alert you to the problem.

Fortunately, you can control this behaviour 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", (1)
            "properties": {
                "title":  { "type": "string"},
                "stash":  {
                    "type":     "object",
                    "dynamic":  true (2)
                }
            }
        }
    }
}

1. The my_type object will throw an exception if an unknown field is encountered.

2. The stash object will create new fields dynamically.

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!"
}

Note	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.