Update data stream mappings Generally available

PUT /_data_stream/{name}/_mappings

This API can be used to override mappings on specific data streams. These overrides will take precedence over what is specified in the template that the data stream matches. The mapping change is only applied to new write indices that are created during rollover after this API is called. No indices are changed by this API.

Required authorization

  • Index privileges: manage

Path parameters

  • name string | array[string] Required

    A comma-separated list of data streams or data stream patterns.

Query parameters

  • dry_run boolean

    If true, the request does not actually change the mappings on any data streams. Instead, it simulates changing the settings and reports back to the user what would have happened had these settings actually been applied.

  • master_timeout string

    The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

    Values are -1 or 0.

  • timeout string

    The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

    Values are -1 or 0.

application/json

Body Required

  • all_field object
    Hide all_field attributes Show all_field attributes object
    • analyzer string Required
    • enabled boolean Required
    • omit_norms boolean Required
    • search_analyzer string Required
    • similarity string Required
    • store boolean Required
    • store_term_vector_offsets boolean Required
    • store_term_vector_payloads boolean Required
    • store_term_vector_positions boolean Required
    • store_term_vectors boolean Required
  • date_detection boolean
  • dynamic string

    Values are strict, runtime, true, or false.

  • dynamic_date_formats array[string]
  • dynamic_templates array[object]
  • _field_names object
    Hide _field_names attribute Show _field_names attribute object
    • enabled boolean Required
  • index_field object
    Hide index_field attribute Show index_field attribute object
    • enabled boolean Required
  • _meta object
    Hide _meta attribute Show _meta attribute object
    • * object Additional properties
  • numeric_detection boolean
  • properties object
  • _routing object
    Hide _routing attribute Show _routing attribute object
    • required boolean Required
  • _size object
    Hide _size attribute Show _size attribute object
    • enabled boolean Required
  • _source object
    Hide _source attributes Show _source attributes object
    • compress boolean
    • compress_threshold string
    • enabled boolean
    • excludes array[string]
    • includes array[string]
    • mode string

      Values are disabled, stored, or synthetic.

  • runtime object
    Hide runtime attribute Show runtime attribute object
    • * object Additional properties
      Hide * attributes Show * attributes object
      • fields object

        For type composite

        Hide fields attribute Show fields attribute object
        • * object Additional properties
          Hide * attribute Show * attribute object
          • type string Required

            Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

      • fetch_fields array[object]

        For type lookup

        Hide fetch_fields attributes Show fetch_fields attributes object
        • field string Required

          Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

        • format string
      • format string

        A custom format for date type runtime fields.

      • input_field string

        Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

      • target_field string

        Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

      • target_index string
      • script object
        Hide script attributes Show script attributes object
        • source string | object

          One of:
        • id string
        • params object

          Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

          Hide params attribute Show params attribute object
          • * object Additional properties
        • lang string

          Any of:

          Values are painless, expression, mustache, or java.

        • options object
          Hide options attribute Show options attribute object
          • * string Additional properties
      • type string Required

        Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

  • enabled boolean
  • subobjects string

    Values are true or false.

  • _data_stream_timestamp object
    Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
    • enabled boolean Required

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • data_streams array[object] Required
      Hide data_streams attributes Show data_streams attributes object
      • name string Required
      • applied_to_data_stream boolean Required

        If the mappings were successfully applied to the data stream (or would have been, if running in dry_run mode), it is true. If an error occurred, it is false.

      • error string

        A message explaining why the mappings could not be applied to the data stream.

      • mappings object
        Hide mappings attributes Show mappings attributes object
        • all_field object
          Hide all_field attributes Show all_field attributes object
          • analyzer string Required
          • enabled boolean Required
          • omit_norms boolean Required
          • search_analyzer string Required
          • similarity string Required
          • store boolean Required
          • store_term_vector_offsets boolean Required
          • store_term_vector_payloads boolean Required
          • store_term_vector_positions boolean Required
          • store_term_vectors boolean Required
        • date_detection boolean
        • dynamic string

          Values are strict, runtime, true, or false.

        • dynamic_date_formats array[string]
        • dynamic_templates array[object]
        • _field_names object
          Hide _field_names attribute Show _field_names attribute object
          • enabled boolean Required
        • index_field object
          Hide index_field attribute Show index_field attribute object
          • enabled boolean Required
        • _meta object
          Hide _meta attribute Show _meta attribute object
          • * object Additional properties
        • numeric_detection boolean
        • properties object
        • _routing object
          Hide _routing attribute Show _routing attribute object
          • required boolean Required
        • _size object
          Hide _size attribute Show _size attribute object
          • enabled boolean Required
        • _source object
          Hide _source attributes Show _source attributes object
          • compress boolean
          • compress_threshold string
          • enabled boolean
          • excludes array[string]
          • includes array[string]
          • mode string

            Values are disabled, stored, or synthetic.

        • runtime object
          Hide runtime attribute Show runtime attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • fields object

              For type composite

            • fetch_fields array[object]

              For type lookup

            • format string

              A custom format for date type runtime fields.

            • input_field string

              Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

            • target_field string

              Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

            • target_index string
            • script object
            • type string Required

              Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

        • enabled boolean
        • subobjects string

          Values are true or false.

        • _data_stream_timestamp object
          Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
          • enabled boolean Required
      • effective_mappings object
        Hide effective_mappings attributes Show effective_mappings attributes object
        • all_field object
          Hide all_field attributes Show all_field attributes object
          • analyzer string Required
          • enabled boolean Required
          • omit_norms boolean Required
          • search_analyzer string Required
          • similarity string Required
          • store boolean Required
          • store_term_vector_offsets boolean Required
          • store_term_vector_payloads boolean Required
          • store_term_vector_positions boolean Required
          • store_term_vectors boolean Required
        • date_detection boolean
        • dynamic string

          Values are strict, runtime, true, or false.

        • dynamic_date_formats array[string]
        • dynamic_templates array[object]
        • _field_names object
          Hide _field_names attribute Show _field_names attribute object
          • enabled boolean Required
        • index_field object
          Hide index_field attribute Show index_field attribute object
          • enabled boolean Required
        • _meta object
          Hide _meta attribute Show _meta attribute object
          • * object Additional properties
        • numeric_detection boolean
        • properties object
        • _routing object
          Hide _routing attribute Show _routing attribute object
          • required boolean Required
        • _size object
          Hide _size attribute Show _size attribute object
          • enabled boolean Required
        • _source object
          Hide _source attributes Show _source attributes object
          • compress boolean
          • compress_threshold string
          • enabled boolean
          • excludes array[string]
          • includes array[string]
          • mode string

            Values are disabled, stored, or synthetic.

        • runtime object
          Hide runtime attribute Show runtime attribute object
          • * object Additional properties
            Hide * attributes Show * attributes object
            • fields object

              For type composite

            • fetch_fields array[object]

              For type lookup

            • format string

              A custom format for date type runtime fields.

            • input_field string

              Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

            • target_field string

              Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

            • target_index string
            • script object
            • type string Required

              Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

        • enabled boolean
        • subobjects string

          Values are true or false.

        • _data_stream_timestamp object
          Hide _data_stream_timestamp attribute Show _data_stream_timestamp attribute object
          • enabled boolean Required
PUT /_data_stream/{name}/_mappings
PUT /_data_stream/my-data-stream/_mappings
{
   "properties":{
      "field1":{
         "type":"ip"
      },
      "field3":{
         "type":"text"
      }
   }
}
resp = client.indices.put_data_stream_mappings(
    name="my-data-stream",
    mappings={
        "properties": {
            "field1": {
                "type": "ip"
            },
            "field3": {
                "type": "text"
            }
        }
    },
)
const response = await client.indices.putDataStreamMappings({
  name: "my-data-stream",
  mappings: {
    properties: {
      field1: {
        type: "ip",
      },
      field3: {
        type: "text",
      },
    },
  },
});
response = client.indices.put_data_stream_mappings(
  name: "my-data-stream",
  body: {
    "properties": {
      "field1": {
        "type": "ip"
      },
      "field3": {
        "type": "text"
      }
    }
  }
)
$resp = $client->indices()->putDataStreamMappings([
    "name" => "my-data-stream",
    "body" => [
        "properties" => [
            "field1" => [
                "type" => "ip",
            ],
            "field3" => [
                "type" => "text",
            ],
        ],
    ],
]);
curl -X PUT -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"properties":{"field1":{"type":"ip"},"field3":{"type":"text"}}}' "$ELASTICSEARCH_URL/_data_stream/my-data-stream/_mappings"
Request example
This is a request to add or modify two fields in a mapping on a data stream.
{
   "properties":{
      "field1":{
         "type":"ip"
      },
      "field3":{
         "type":"text"
      }
   }
}
This shows a response to `PUT /_data_stream/my-data-stream/_settings` when two settings are successfully updated on the data stream. In this case, `index.number_of_shards` is only applied to the data stream -- it will be applied to the write index on rollover. The setting `index.lifecycle.name` is applied to the data stream and all backing indices.
{
  "data_streams": [
    {
      "name": "my-data-stream",
      "applied_to_data_stream": true,
      "mappings": {
        "properties": {
          "field1": {
            "type": "ip"
          },
          "field3": {
            "type": "text"
          }
        }
      },
      "effective_mappings": {
        "properties": {
          "field1": {
            "type": "ip"
          },
          "field3": {
            "type": "text"
          }
        }
      }
    }
  ]
}
This shows a response to `PUT /_data_stream/my-data-stream/_settings` when a user attempts to set a setting that is not allowed on a data stream. As a result, no change was applied to the data stream.
{
  "data_streams": [
    {
      "name": "my-data-stream",
      "applied_to_data_stream": false,
      "error": "Failed to parse mapping: The mapper type [txt] declared on field [field1] does not exist. It might have been created within a future version or requires a plugin to be installed. Check the documentation.",
      "mappings": {
        "_doc": {}
      },
      "effective_mappings": {
        "_doc": {}
      }
    }
  ]
}