mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
129 lines
5.1 KiB
Text
129 lines
5.1 KiB
Text
[[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-manage-update]]
|
||
== Managing and updating mappings
|
||
|
||
Explicit mappings should be defined at index creation for fields you know in advance.
|
||
You can still add _new fields_ to mappings at any time, as your data evolves.
|
||
|
||
Use the <<indices-put-mapping,Update mapping API>> to update an existing mapping.
|
||
|
||
In most cases, you can't change mappings for fields that are already mapped.
|
||
These changes require <<docs-reindex,reindexing>>.
|
||
|
||
However, you can _update_ mappings under certain conditions:
|
||
|
||
* You can add new fields to an existing mapping at any time, explicitly or dynamically.
|
||
* You can add new <<multi-fields,multi-fields>> for existing fields.
|
||
** Documents indexed before the mapping update will not have values for the new multi-fields until they are updated or reindexed. Documents indexed after the mapping change will automatically have values for the new multi-fields.
|
||
* Some <<mapping-params,mapping parameters>> can be updated for existing fields of certain <<mapping-types,data types>>.
|
||
|
||
[discrete]
|
||
[[mapping-limit-settings]]
|
||
== Prevent mapping explosions
|
||
|
||
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[]
|