elasticsearch/docs/reference/mapping/dynamic/field-mapping.asciidoc

[[dynamic-field-mapping]]
=== Dynamic field mapping

When {es} detects a new field in a document, it _dynamically_ adds the field to
the type mapping by default. The <<dynamic,`dynamic`>> parameter controls this behavior.

You can explicitly instruct {es} to dynamically create fields based on incoming
documents by setting the `dynamic` parameter to `true` or `runtime`. When
dynamic field mapping is enabled, {es} uses the rules in the following table to
determine how to map data types for each field.

NOTE: The field data types in the following table are the only
<<mapping-types,field data types>> that {es} detects dynamically. You must
explicitly map all other data types.

[[dynamic-field-mapping-types]]
// tag::dynamic-field-mapping-types-tag[]
[cols="3"]
|===
h| JSON data type h| `"dynamic":"true"` h| `"dynamic":"runtime"`
 |`null` 2*| No field added
 |`true` or `false` 2*| `boolean`
 |`double` | `float` | `double`
 |`integer` 2*| `long`
 |`object`^1^  2*| `object`
 |`array` 2*|  Depends on the first non-`null` value in the array
 |`string` that passes <<date-detection,date detection>> 2*| `date`
 |`string` that passes <<numeric-detection,numeric detection>> | `float` or `long` | `double` or `long`
 |`string` that doesn't pass `date` detection or `numeric` detection | `text` with a `.keyword` sub-field | `keyword`
3+| ^1^Objects are always mapped as part of the `properties` section, even when the `dynamic` parameter is set to `runtime`. | |
|===
// end::dynamic-field-mapping-types-tag[]

You can disable dynamic mapping, both at the document and at the
<<object,`object`>> level. Setting the `dynamic` parameter to
`false` ignores new fields, and `strict` rejects the document if {es}
encounters an unknown field.

TIP: Use the <<indices-put-mapping,update mapping API>> to update the `dynamic`
setting on existing fields.

You can customize dynamic field mapping rules for
<<date-detection,date detection>> and <<numeric-detection,numeric detection>>.
To define custom mappings rules that you can apply to additional dynamic
fields, use <<dynamic-templates,`dynamic_templates`>>.

[[date-detection]]
==== Date detection

If `date_detection` is enabled (default), then new string fields are checked
to see whether their contents match any of the date patterns specified in
`dynamic_date_formats`.  If a match is found, a new <<date,`date`>> field is
added with the corresponding format.

The default value for `dynamic_date_formats` is:

&#91; <<strict-date-time,`"strict_date_optional_time"`>>,`"yyyy/MM/dd HH:mm:ss Z||yyyy/MM/dd Z"`]

For example:


[source,console]
--------------------------------------------------
PUT my-index-000001/_doc/1
{
  "create_date": "2015/09/02"
}

GET my-index-000001/_mapping <1>
--------------------------------------------------

<1> The `create_date` field has been added as a <<date,`date`>>
    field with the <<mapping-date-format,`format`>>: +
    `"yyyy/MM/dd HH:mm:ss Z||yyyy/MM/dd Z"`.

===== Disabling date detection

Dynamic date detection can be disabled by setting `date_detection` to `false`:

[source,console]
--------------------------------------------------
PUT my-index-000001
{
  "mappings": {
    "date_detection": false
  }
}

PUT my-index-000001/_doc/1 <1>
{
  "create": "2015/09/02"
}
--------------------------------------------------

<1> The `create_date` field has been added as a <<text,`text`>> field.

===== Customizing detected date formats

Alternatively, the `dynamic_date_formats` can be customized to support your
own <<mapping-date-format,date formats>>:

[source,console]
--------------------------------------------------
PUT my-index-000001
{
  "mappings": {
    "dynamic_date_formats": ["MM/dd/yyyy"]
  }
}

PUT my-index-000001/_doc/1
{
  "create_date": "09/25/2015"
}
--------------------------------------------------


[[numeric-detection]]
==== Numeric detection

While JSON has support for native floating point and integer data types, some
applications or languages may sometimes render numbers as strings. Usually the
correct solution is to map these fields explicitly, but numeric detection
(which is disabled by default) can be enabled to do this automatically:


[source,console]
--------------------------------------------------
PUT my-index-000001
{
  "mappings": {
    "numeric_detection": true
  }
}

PUT my-index-000001/_doc/1
{
  "my_float":   "1.0", <1>
  "my_integer": "1" <2>
}
--------------------------------------------------

<1> The `my_float` field is added as a <<number,`float`>> field.
<2> The `my_integer` field is added as a <<number,`long`>> field.