You're viewing version 2.17 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
Dynamic
The dynamic
parameter specifies whether newly detected fields can be added dynamically to a mapping. It accepts the parameters listed in the following table.
Parameter | Description |
---|---|
true | Specifies that new fields can be added dynamically to the mapping. Default is true . |
false | Specifies that new fields cannot be added dynamically to the mapping. If a new field is detected, then it is not indexed or searchable but can be retrieved from the _source field. |
strict | Throws an exception. The indexing operation fails when new fields are detected. |
strict_allow_templates | Adds new fields if they match predefined dynamic templates in the mapping. |
Example: Create an index with dynamic
set to true
- Create an index with
dynamic
set totrue
by sending the following request:
PUT testindex1
{
"mappings": {
"dynamic": true
}
}
- Index a document with an object field
patient
containing two string fields by sending the following request:
PUT testindex1/_doc/1
{
"patient": {
"name" : "John Doe",
"id" : "123456"
}
}
- Confirm the mapping works as expected by sending the following request:
GET testindex1/_mapping
The object field patient
and two subfields name
and id
are added to the mapping, as shown in the following response:
{
"testindex1": {
"mappings": {
"dynamic": "true",
"properties": {
"patient": {
"properties": {
"id": {
"type": "text",
"fields": {
"keyword": {
"type": "keyword",
"ignore_above": 256
}
}
},
"name": {
"type": "text",
"fields": {
"keyword": {
"type": "keyword",
"ignore_above": 256
}
}
}
}
}
}
}
}
}
Example: Create an index with dynamic
set to false
- Create an index with explicit mappings and
dynamic
set tofalse
by sending the following request:
PUT testindex1
{
"mappings": {
"dynamic": false,
"properties": {
"patient": {
"properties": {
"id": {
"type": "keyword"
},
"name": {
"type": "keyword"
}
}
}
}
}
}
- Index a document with an object field
patient
containing two string fields and additional unmapped fields by sending the following request:
PUT testindex1/_doc/1
{
"patient": {
"name" : "John Doe",
"id" : "123456"
},
"room": "room1",
"floor": "1"
}
- Confirm the mapping works as expected by sending the following request:
GET testindex1/_mapping
The following response shows that the new fields room
and floor
were not added to the mapping, which remained unchanged:
{
"testindex1": {
"mappings": {
"dynamic": "false",
"properties": {
"patient": {
"properties": {
"id": {
"type": "keyword"
},
"name": {
"type": "keyword"
}
}
}
}
}
}
}
- Get the unmapped fields
room
andfloor
from the document by sending the following request:
PUT testindex1/_doc/1
{
"patient": {
"name" : "John Doe",
"id" : "123456"
},
"room": "room1",
"floor": "1"
}
The following request searches for the fields room
and floor
:
POST testindex1/_search
{
"query": {
"term": {
"room": "room1"
}
}
}
The response returns no results:
{
"took": 3,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 0,
"relation": "eq"
},
"max_score": null,
"hits": []
}
}
Example: Create an index with dynamic
set to strict
- Create an index with explicit mappings and
dynamic
set tostrict
by sending the following request:
PUT testindex1
{
"mappings": {
"dynamic": strict,
"properties": {
"patient": {
"properties": {
"id": {
"type": "keyword"
},
"name": {
"type": "keyword"
}
}
}
}
}
}
- Index a document with an object field
patient
containing two string fields and additional unmapped fields by sending the following request:
PUT testindex1/_doc/1
{
"patient": {
"name" : "John Doe",
"id" : "123456"
},
"room": "room1",
"floor": "1"
}
Note that an exception is thrown, as shown in the following response:
{
"error": {
"root_cause": [
{
"type": "strict_dynamic_mapping_exception",
"reason": "mapping set to strict, dynamic introduction of [room] within [_doc] is not allowed"
}
],
"type": "strict_dynamic_mapping_exception",
"reason": "mapping set to strict, dynamic introduction of [room] within [_doc] is not allowed"
},
"status": 400
}
Example: Create an index with dynamic
set to strict_allow_templates
- Create an index with predefined dynamic templates and
dynamic
set tostrict_allow_templates
by sending the following request:
PUT testindex1
{
"mappings": {
"dynamic": "strict_allow_templates",
"dynamic_templates": [
{
"strings": {
"match": "room*",
"match_mapping_type": "string",
"mapping": {
"type": "keyword"
}
}
}
],
"properties": {
"patient": {
"properties": {
"id": {
"type": "keyword"
},
"name": {
"type": "keyword"
}
}
}
}
}
}
- Index a document with an object field
patient
containing two string fields and a new fieldroom
that matches one of the dynamic templates by sending the following request:
PUT testindex1/_doc/1
{
"patient": {
"name" : "John Doe",
"id" : "123456"
},
"room": "room1"
}
Indexing succeeds because the new field room
matches the dynamic templates. However, indexing fails for the new field floor
because it does not match one of the dynamic templates and is not explicitly mapped, as shown in the following response:
PUT testindex1/_doc/1
{
"patient": {
"name" : "John Doe",
"id" : "123456"
},
"room": "room1",
"floor": "1"
}