168 lines
5.7 KiB
Plaintext
168 lines
5.7 KiB
Plaintext
[[mapping]]
|
|
= Mapping
|
|
|
|
[partintro]
|
|
--
|
|
|
|
Mapping is the process of defining how a document, and the fields it contains,
|
|
are stored and indexed. For instance, use mappings to define:
|
|
|
|
* which string fields should be treated as full text fields.
|
|
* which fields contain numbers, dates, or geolocations.
|
|
* whether the values of all fields in the document should be
|
|
indexed into the catch-all <<mapping-all-field,`_all`>> field.
|
|
* the <<mapping-date-format,format>> of date values.
|
|
* custom rules to control the mapping for
|
|
<<dynamic-mapping,dynamically added fields>>.
|
|
|
|
[float]
|
|
[[mapping-type]]
|
|
== Mapping Type
|
|
|
|
Each index has one _mapping type_ which determines how the document will be
|
|
indexed.
|
|
|
|
deprecated[6.0.0,See <<removal-of-types>>].
|
|
|
|
A mapping type has:
|
|
|
|
<<mapping-fields,Meta-fields>>::
|
|
|
|
Meta-fields are used to customize how a document's metadata associated is
|
|
treated. Examples of meta-fields include the document's
|
|
<<mapping-index-field,`_index`>>, <<mapping-type-field,`_type`>>,
|
|
<<mapping-id-field,`_id`>>, and <<mapping-source-field,`_source`>> fields.
|
|
|
|
<<mapping-types,Fields>> or _properties_::
|
|
|
|
A mapping type contains a list of fields or `properties` pertinent to the
|
|
document.
|
|
|
|
|
|
[float]
|
|
== Field datatypes
|
|
|
|
Each field has a data `type` which can be:
|
|
|
|
* a simple type like <<text,`text`>>, <<keyword,`keyword`>>, <<date,`date`>>, <<number,`long`>>,
|
|
<<number,`double`>>, <<boolean,`boolean`>> or <<ip,`ip`>>.
|
|
* a type which supports the hierarchical nature of JSON such as
|
|
<<object,`object`>> or <<nested,`nested`>>.
|
|
* or a specialised type like <<geo-point,`geo_point`>>,
|
|
<<geo-shape,`geo_shape`>>, or <<search-suggesters-completion,`completion`>>.
|
|
|
|
It is often useful to index the same field in different ways for different
|
|
purposes. For instance, a `string` field could be <<mapping-index,indexed>> as
|
|
a `text` field for full-text search, and as a `keyword` field for
|
|
sorting or aggregations. Alternatively, you could index a string field with
|
|
the <<analysis-standard-analyzer,`standard` analyzer>>, the
|
|
<<english-analyzer,`english`>> analyzer, and the
|
|
<<french-analyzer,`french` analyzer>>.
|
|
|
|
This is the purpose of _multi-fields_. Most datatypes support multi-fields
|
|
via the <<multi-fields>> parameter.
|
|
|
|
[[mapping-limit-settings]]
|
|
[float]
|
|
=== Settings to prevent mappings explosion
|
|
|
|
Defining too many fields in an index is a condition that can lead to a
|
|
mapping explosion, which can cause out of memory errors and difficult
|
|
situations to recover from. This problem may be more common than expected.
|
|
As an example, consider a situation in which every new document inserted
|
|
introduces new fields. This is quite common with dynamic mappings.
|
|
Every time a document contains new fields, those will end up in the index's
|
|
mappings. This isn't worrying for a small amount of data, but it can become a
|
|
problem as the mapping grows.
|
|
The following settings allow you to limit the number of field mappings that
|
|
can be created manually or dynamically, in order to prevent bad documents from
|
|
causing a mapping explosion:
|
|
|
|
`index.mapping.total_fields.limit`::
|
|
The maximum number of fields in an index. The default value is `1000`.
|
|
|
|
`index.mapping.depth.limit`::
|
|
The maximum depth for a field, which is measured as the number of inner
|
|
objects. For instance, if all fields are defined at the root object level,
|
|
then the depth is `1`. If there is one object mapping, then the depth is
|
|
`2`, etc. The default is `20`.
|
|
|
|
`index.mapping.nested_fields.limit`::
|
|
The maximum number of `nested` fields in an index, defaults to `50`.
|
|
Indexing 1 document with 100 nested fields actually indexes 101 documents
|
|
as each nested document is indexed as a separate hidden document.
|
|
|
|
|
|
[float]
|
|
== Dynamic mapping
|
|
|
|
Fields and mapping types do not need to be defined before being used. Thanks
|
|
to _dynamic mapping_, new field names will be added automatically, just by
|
|
indexing a document. New fields can be added both to the top-level mapping
|
|
type, and to inner <<object,`object`>> and <<nested,`nested`>> fields.
|
|
|
|
The <<dynamic-mapping,dynamic mapping>> rules can be configured to customise
|
|
the mapping that is used for new fields.
|
|
|
|
[float]
|
|
== Explicit mappings
|
|
|
|
You know more about your data than Elasticsearch can guess, so while dynamic
|
|
mapping can be useful to get started, at some point you will want to specify
|
|
your own explicit mappings.
|
|
|
|
You can create field mappings when you
|
|
<<indices-create-index,create an index>>, and you can add
|
|
fields to an existing index with the <<indices-put-mapping,PUT mapping API>>.
|
|
|
|
[float]
|
|
== Updating existing field mappings
|
|
|
|
Other than where documented, *existing field mappings cannot be
|
|
updated*. Changing the mapping would mean invalidating already indexed
|
|
documents. Instead, you should create a new index with the correct mappings
|
|
and <<docs-reindex,reindex>> your data into that index.
|
|
|
|
[float]
|
|
== Example mapping
|
|
|
|
A mapping could be specified when creating an index, as follows:
|
|
|
|
[source,js]
|
|
---------------------------------------
|
|
PUT my_index <1>
|
|
{
|
|
"mappings": {
|
|
"doc": { <2>
|
|
"properties": { <3>
|
|
"title": { "type": "text" }, <4>
|
|
"name": { "type": "text" }, <4>
|
|
"age": { "type": "integer" }, <4>
|
|
"created": {
|
|
"type": "date", <4>
|
|
"format": "strict_date_optional_time||epoch_millis"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
---------------------------------------
|
|
// CONSOLE
|
|
<1> Create an index called `my_index`.
|
|
<2> Add a mapping type called `doc`.
|
|
<3> Specify fields or _properties_.
|
|
<4> Specify the data `type` and mapping for each field.
|
|
|
|
|
|
--
|
|
|
|
include::mapping/removal_of_types.asciidoc[]
|
|
|
|
include::mapping/types.asciidoc[]
|
|
|
|
include::mapping/fields.asciidoc[]
|
|
|
|
include::mapping/params.asciidoc[]
|
|
|
|
include::mapping/dynamic-mapping.asciidoc[]
|