[[mapping]]
= Mapping

[partintro]
--

Mapping is the process of defining how a document, and the fields it contains,
are stored and indexed.

Each document is a collection of fields, which each have their own
<<mapping-types,data type>>. When mapping your data, you create a mapping
definition, which contains a list of fields that are pertinent to the document.
A mapping definition also includes <<mapping-fields,metadata fields>>, like the
`_source` field, which customize how a document's associated metadata is
handled.

Use _dynamic mapping_ and _explicit mapping_ to define your data. Each method
provides different benefits based on where you are in your data journey. For
example, explicitly map fields where you don't want to use the defaults, or to
gain greater control over which fields are created. You can then allow {es} to
add other fields dynamically.

NOTE: Before 7.0.0, the mapping definition included a type name.
{es} 7.0.0 and later no longer accept a _default_ mapping. See <<removal-of-types>>.

.Experiment with mapping options
****
<<runtime-search-request,Define runtime fields in a search request>> to
experiment with different mapping options, and also fix mistakes in your index
mapping values by overriding values in the mapping during the search request.
****

[discrete]
[[mapping-dynamic]]
== Dynamic mapping

When you use <<dynamic-field-mapping,dynamic mapping>>, {es} automatically
attempts to detect the data type of fields in your documents. This allows 
you to get started quickly by just adding data to an index. If you index
additional documents with new fields, {es} will add these fields automatically. 
You can add fields to the top-level mapping, and to inner <<object,`object`>> 
and <<nested,`nested`>> fields.

Use <<dynamic-templates,dynamic templates>> to define custom mappings that are
applied to dynamically added fields based on the matching condition.

[discrete]
[[mapping-explicit]]
== Explicit mapping

Use <<explicit-mapping,explicit mapping>> to define exactly how data types
are mapped to fields, customized to your specific use case.

Defining your own mappings enables you to:

* Define which string fields should be treated as full-text fields.
* Define which fields contain numbers, dates, or geolocations.
* Use data types that cannot be automatically detected (such as `geo_point` and `geo_shape`.)
* Choose date value <<mapping-date-format,formats>>, including custom date formats.
* Create custom rules to control the mapping for <<dynamic-mapping,dynamically added fields>>.
* Optimize fields for partial matching.
* Perform language-specific text analysis.

[TIP]
====
It’s often useful to index the same field in different ways for different purposes.
For example, you might want to index a string field as both a text field for full-text 
search and as a keyword field for sorting or aggregating your data. Or, you might 
choose to use more than one language analyzer to process the contents of a string field 
that contains user input.
====

Use <<runtime-mapping-fields,runtime fields>> to make schema changes without
reindexing. You can use runtime fields in conjunction with indexed fields to
balance resource usage and performance. Your index will be smaller, but with
slower search performance.

[discrete]
[[mapping-limit-settings]]
== Settings to prevent mapping explosion
Defining too many fields in an index can lead to a mapping explosion, which can
cause out of memory errors and difficult situations to recover from.

Consider a situation where every new document inserted
introduces new fields, such as with <<dynamic-mapping,dynamic mapping>>.
Each new field is added to the index mapping, which can become a
problem as the mapping grows.

Use the <<mapping-settings-limit,mapping limit settings>> to limit the number
of field mappings (created manually or dynamically) and prevent documents from
causing a mapping explosion.

--

include::mapping/dynamic-mapping.asciidoc[]

include::mapping/explicit-mapping.asciidoc[]

include::mapping/runtime.asciidoc[]

include::mapping/types.asciidoc[]

include::mapping/fields.asciidoc[]

include::mapping/params.asciidoc[]

include::mapping/mapping-settings-limit.asciidoc[]

include::mapping/removal_of_types.asciidoc[]
