Link Search Menu Expand Document Documentation Menu
Documentation

You're viewing version 2.16 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 parameter

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 Specfies 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

  1. Create an index with dynamic set to true by sending the following request:
PUT testindex1
{
  "mappings": {
    "dynamic": true
  }
}

  1. 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"
  } 
}

  1. 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

  1. Create an index with explicit mappings and dynamic set to false by sending the following request:
PUT testindex1
{
  "mappings": {
    "dynamic": false,
    "properties": {
      "patient": {
        "properties": {
          "id": {
            "type": "keyword"
          },
          "name": {
            "type": "keyword"
          }
        }
      }
    }
  }
}

  1. 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"
}

  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"
            }
          }
        }
      }
    }
  }
}
  1. Get the unmapped fields room and floor 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

  1. Create an index with explicit mappings and dynamic set to strict by sending the following request:
PUT testindex1
{
  "mappings": {
    "dynamic": strict,
    "properties": {
      "patient": {
        "properties": {
          "id": {
            "type": "keyword"
          },
          "name": {
            "type": "keyword"
          }
        }
      }
    }
  }
}

  1. 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

  1. Create an index with predefined dynamic templates and dynamic set to strict_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"
          }
        }
      }
    }
  }
}

  1. Index a document with an object field patient containing two string fields and a new field room 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"
}
350 characters left

Have a question? .

Want to contribute? or .