mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 23:57:20 -04:00
f642b8a3aa
Adds a new `index.mapping.total_fields.ignore_dynamic_beyond_limit` index setting. When set to `true`, new fields are added to the mapping as long as the field limit (`index.mapping.total_fields.limit`) is not exceeded. Fields that would exceed the limit are not added to the mapping, similar to `dynamic: false`. Ignored fields are added to the `_ignored` metadata field. Relates to https://github.com/elastic/elasticsearch/issues/89911 To make this easier to review, this is split into the following PRs: - [x] https://github.com/elastic/elasticsearch/pull/102915 - [x] https://github.com/elastic/elasticsearch/pull/102936 - [x] https://github.com/elastic/elasticsearch/pull/104769 Related but not a prerequisite: - [ ] https://github.com/elastic/elasticsearch/pull/102885
99 lines
3.1 KiB
Text
99 lines
3.1 KiB
Text
[[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. 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.
|
|
|
|
[[dynamic-field-limit]]
|
|
==== Behavior when reaching the field limit
|
|
Setting `dynamic` to either `true` or `runtime` will only add dynamic fields until <<mapping-settings-limit,`index.mapping.total_fields.limit`>> is reached.
|
|
By default, index requests for documents that would exceed the field limit will fail,
|
|
unless <<mapping-settings-limit,`index.mapping.total_fields.ignore_dynamic_beyond_limit`>> is set to `true`.
|
|
In that case, ignored fields are added to the <<mapping-ignored-field, `_ignored` metadata field>>.
|