elasticsearch/docs/reference/mapping/params/dynamic.asciidoc

[[dynamic]]
=== `dynamic`

By default, fields can be added _dynamically_ to a document, or to
<<object,inner objects>> within a document, just by indexing a document
containing the new field.  For instance:

[source,js]
--------------------------------------------------
DELETE my_index <1>

PUT my_index/my_type/1 <2>
{
  "username": "johnsmith",
  "name": {
    "first": "John",
    "last": "Smith"
  }
}

GET my_index/_mapping <3>

PUT my_index/my_type/2 <4>
{
  "username": "marywhite",
  "email": "mary@white.com",
  "name": {
    "first": "Mary",
    "middle": "Alice",
    "last": "White"
  }
}

GET my_index/_mapping <5>
--------------------------------------------------
// AUTOSENSE
<1> First delete the index, in case it already exists.
<2> This document introduces the string field `username`, the object field
    `name`, and two string fields under the `name` object which can be
    referred to as `name.first` and `name.last`.
<3> Check the mapping to verify the above.
<4> This document adds two string fields: `email` and `name.middle`.
<5> Check the mapping to verify the changes.

The details of how new fields are detected and added to the mapping is explained in <<dynamic-mapping>>.

The `dynamic` setting controls whether new fields can be added dynamically or
not.  It accepts three settings:

[horizontal]
`true`::    Newly detected fields are added to the mapping. (default)
`false`::   Newly detected fields are ignored.  New fields must be added explicitly.
`strict`::  If new fields are detected, an exception is thrown and the document is rejected.

The `dynamic` setting may be set at the mapping type level, and on each
<<object,inner object>>.  Inner objects inherit the setting from their parent
object or from the mapping type.  For instance:

[source,js]
--------------------------------------------------
PUT my_index
{
  "mappings": {
    "my_type": {
      "dynamic": false, <1>
      "properties": {
        "user": { <2>
          "properties": {
            "name": {
              "type": "string"
            },
            "social_networks": { <3>
              "dynamic": true,
              "properties": {}
            }
          }
        }
      }
    }
  }
}
--------------------------------------------------
// AUTOSENSE
<1> Dynamic mapping is disabled at the type level, so no new top-level fields will be added dynamically.
<2> The `user` object inherits the type-level setting.
<3> The `user.social_networks` object enables dynamic mapping, so new fields may be added to this inner object.

TIP: The `dynamic` setting is allowed to have different settings for fields of
the same name in the same index.  Its value can be updated on existing fields
using the <<indices-put-mapping,PUT mapping API>>.