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,console]
--------------------------------------------------
PUT my_index/_doc/1 <1>
{
  "username": "johnsmith",
  "name": {
    "first": "John",
    "last": "Smith"
  }
}

GET my_index/_mapping <2>

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

GET my_index/_mapping <4>
--------------------------------------------------

<1> 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`.
<2> Check the mapping to verify the above.
<3> This document adds two string fields: `email` and `name.middle`.
<4> 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. These fields will not be indexed so will not be searchable 
            but will still appear in the `_source` field of returned hits. These fields will not be added 
            to the mapping,  new fields must be added explicitly.
`strict`::  If new fields are detected, an exception is thrown and the document is rejected. New fields 
            must be explicitly added to the mapping.

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,console]
--------------------------------------------------
PUT my_index
{
  "mappings": {
    "dynamic": false, <1>
    "properties": {
      "user": { <2>
        "properties": {
          "name": {
            "type": "text"
          },
          "social_networks": { <3>
            "dynamic": true,
            "properties": {}
          }
        }
      }
    }
  }
}
--------------------------------------------------

<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 can be updated on existing fields
using the <<indices-put-mapping,PUT mapping API>>.