dynamic

By default, fields can be added dynamically to a document, or to inner objects within a document, just by indexing a document containing the new field. For instance:

  1. PUT my-index-000001/_doc/1 
  2. {
  3.   "username": "johnsmith",
  4.   "name": {
  5.     "first": "John",
  6.     "last": "Smith"
  7.   }
  8. }
  10. GET my-index-000001/_mapping 
  12. PUT my-index-000001/_doc/2 
  13. {
  14.   "username": "marywhite",
  15.   "email": "mary@white.com",
  16.   "name": {
  17.     "first": "Mary",
  18.     "middle": "Alice",
  19.     "last": "White"
  20.   }
  21. }
  23. GET my-index-000001/_mapping

This document introduces the string field username, the object field name, and two string fields under the name object which can be referred to as name.first and name.last.

Check the mapping to verify the above.

This document adds two string fields: email and name.middle.

Check the mapping to verify the changes.

The details of how new fields are detected and added to the mapping is explained in Dynamic Mapping.

The dynamic setting controls whether new fields can be added dynamically or not. It accepts three settings:

true

Newly detected fields are added to the mapping. (default)

false

Newly detected fields are ignored. These fields will not be indexed so will not be searchable but will still appear in the _source field of returned hits. These fields will not be added to the mapping, 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.

The dynamic setting may be set at the mapping type level, and on each inner object. Inner objects inherit the setting from their parent object or from the mapping type. For instance:

  1. PUT my-index-000001
  2. {
  3.   "mappings": {
  4.     "dynamic": false, 
  5.     "properties": {
  6.       "user": { 
  7.         "properties": {
  8.           "name": {
  9.             "type": "text"
  10.           },
  11.           "social_networks": { 
  12.             "dynamic": true,
  13.             "properties": {}
  14.           }
  15.         }
  16.       }
  17.     }
  18.   }
  19. }

Dynamic mapping is disabled at the type level, so no new top-level fields will be added dynamically.

The user object inherits the type-level setting.

The user.social_networks object enables dynamic mapping, so new fields may be added to this inner object.

The dynamic setting can be updated on existing fields using the PUT mapping API.