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

[[dynamic]]
=== `dynamic`

When you index a document containing a new field, {es} <<dynamic-mapping,adds the field dynamically>> to a document or to inner objects within a document. The
following document adds the string field `username`, the object field
`name`, and two string fields under the `name` object:

[source,console]
----
PUT my-index-000001/_doc/1
{
  "username": "johnsmith",
  "name": { <1>
    "first": "John",
    "last": "Smith"
  }
}

GET my-index-000001/_mapping <2>
----
<1> Refer to fields under the `name` object as `name.first` and `name.last`.
<2> Check the mapping to view changes.

The following document adds two string fields: `email` and `name.middle`:

[source,console]
----
PUT my-index-000001/_doc/2
{
  "username": "marywhite",
  "email": "mary@white.com",
  "name": {
    "first": "Mary",
    "middle": "Alice",
    "last": "White"
  }
}

GET my-index-000001/_mapping
----

[[dynamic-inner-objects]]
==== Setting `dynamic` on inner objects
<<object,Inner objects>> inherit the `dynamic` setting from their parent
object or from the mapping type. In the following example, dynamic mapping is
disabled at the type level, so no new top-level fields will be added
dynamically.

However, the `user.social_networks` object enables dynamic mapping, so you can
add fields to this inner object.

[source,console]
----
PUT my-index-000001
{
  "mappings": {
    "dynamic": false, <1>
    "properties": {
      "user": { <2>
        "properties": {
          "name": {
            "type": "text"
          },
          "social_networks": {
            "dynamic": true, <3>
            "properties": {}
          }
        }
      }
    }
  }
}
----

<1> Disables dynamic mapping at the type level.
<2> The `user` object inherits the type-level setting.
<3> Enables dynamic mapping for this inner object.

[[dynamic-parameters]]
==== Parameters for `dynamic`
The `dynamic` parameter controls whether new fields are added dynamically, and
accepts the following parameters:

[horizontal]
`true`::    New fields are added to the mapping (default).
`runtime`:: New fields are added to the mapping as <<runtime,runtime fields>>.
            These fields are not indexed, and are loaded from `_source` at query time.
`false`::   New fields are ignored. These fields will not be indexed
            or searchable, but will still appear in the `_source` field of returned hits. These fields will not be added
            to the mapping, and 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.