---
type: api
title: Update data stream mappings
description: This API can be used to override mappings on specific data streams. These overrides will take precedence over what
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-indices-put-data-stream-mappings
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-indices-put-data-stream-mappings
products:
  - Elasticsearch Serverless
---

# Update data stream mappings

Availability:

## Paths

- `PUT` `/_data_stream/{name}/_mappings`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/authentication#apikeyauth)

#### Path Parameters

- `name` (union IndexName | [] IndexName)
  A comma-separated list of data streams or data stream patterns.

## Description

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`

## Query String Parameters

- `dry_run` (boolean · default: false)
  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 Duration · default: 30s)
  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.
- `timeout` (string Duration · default: 30s)
  The period to wait for a response. If no response is received before the
 timeout expires, the request fails and returns an error.

## Request Body

`application/json`

- `all_field` ({} AllField) — optional
  - `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) — optional
- `dynamic` (enum DynamicMapping) — optional
  Values: `strict`, `runtime`, `true`, `false`
- `dynamic_date_formats` ([] string) — optional
- `dynamic_templates` ([] string to DynamicTemplate) — optional
- `_field_names` ({} FieldNamesField) — optional
  - `enabled` (boolean) — required
- `index_field` ({} IndexField) — optional
  - `enabled` (boolean) — required
- `_meta` (Metadata) — optional
- `numeric_detection` (boolean) — optional
- `properties` (map string to Property) — optional
- `_routing` ({} RoutingField) — optional
  - `required` (boolean) — required
- `_size` ({} SizeField) — optional
  - `enabled` (boolean) — required
- `_source` ({} SourceField) — optional
  - `enabled` (boolean) — optional
  - `excludes` ([] string) — optional
  - `includes` ([] string) — optional
  - `mode` (enum SourceFieldMode) — optional
    

Supported values include:
  - `disabled`
  - `stored`
  - `synthetic`: Instead of storing source documents on disk exactly as you send them,
 Elasticsearch can reconstruct source content on the fly upon retrieval.
    Values: `disabled`, `stored`, `synthetic`
- `runtime` (map string to RuntimeField) — optional
  Map values ({} RuntimeField)
  - `fields` (map string to CompositeSubField) — optional
    For type `composite`
    Map values ({} CompositeSubField)
    - `type` (enum RuntimeFieldType) — required
      Values: `boolean`, `composite`, `date`, `double`, `geo_point`, `geo_shape`, `ip`, `keyword`, `long`, `lookup`
  - `fetch_fields` ([] RuntimeFieldFetchFields) — optional
    For type `lookup`
    - `field` (string Field) — required
    - `format` (string) — optional
  - `format` (string) — optional
    A custom format for `date` type runtime fields.
  - `input_field` (string Field) — optional
    For type `lookup`
  - `target_field` (string Field) — optional
    For type `lookup`
  - `target_index` (string IndexName) — optional
    For type `lookup`
  - `script` (string Script) — optional
    Painless script executed at query time.
  - `on_script_error` (enum OnScriptError) — optional
    Values: `fail`, `continue`
  - `type` (enum RuntimeFieldType) — required
    Field type, which can be: `boolean`, `composite`, `date`, `double`, `geo_point`, `ip`,`keyword`, `long`, or `lookup`.
    Values: `boolean`, `composite`, `date`, `double`, `geo_point`, `geo_shape`, `ip`, `keyword`, `long`, `lookup`
- `enabled` (boolean) — optional
- `subobjects` (enum Subobjects) — optional
  Values: `true`, `false`
- `_data_stream_timestamp` ({} DataStreamTimestamp) — optional
  - `enabled` (boolean) — required

## Response

`application/json`

- `data_streams` ([] UpdatedDataStreamMappings)
  - `name` (string IndexName)
    The data stream name.
  - `applied_to_data_stream` (boolean)
    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` ({} TypeMapping)
    The mappings that are specfic to this data stream that will override any mappings from the matching index template.
    - `all_field` ({} AllField)
      Same fields as `all_field`
    - `date_detection` (boolean)
    - `dynamic` (enum DynamicMapping)
      Values: `strict`, `runtime`, `true`, `false`
    - `dynamic_date_formats` ([] string)
    - `dynamic_templates` ([] string to DynamicTemplate)
    - `_field_names` ({} FieldNamesField)
      - `enabled` (boolean)
    - `index_field` ({} IndexField)
      - `enabled` (boolean)
    - `_meta` (Metadata)
    - `numeric_detection` (boolean)
    - `properties` (map string to Property)
    - `_routing` ({} RoutingField)
      - `required` (boolean)
    - `_size` ({} SizeField)
      - `enabled` (boolean)
    - `_source` ({} SourceField)
      - `enabled` (boolean)
      - `excludes` ([] string)
      - `includes` ([] string)
      - `mode` (enum SourceFieldMode)
        

Supported values include:
  - `disabled`
  - `stored`
  - `synthetic`: Instead of storing source documents on disk exactly as you send them,
 Elasticsearch can reconstruct source content on the fly upon retrieval.
        Values: `disabled`, `stored`, `synthetic`
    - `runtime` (map string to RuntimeField)
      Map values ({} RuntimeField)
      - `fields` (map string to CompositeSubField)
        For type `composite`
        Map values ({} CompositeSubField)
        - `type` (enum RuntimeFieldType)
          Values: `boolean`, `composite`, `date`, `double`, `geo_point`, `geo_shape`, `ip`, `keyword`, `long`, `lookup`
      - `fetch_fields` ([] RuntimeFieldFetchFields)
        For type `lookup`
        - `field` (string Field)
        - `format` (string)
      - `format` (string)
        A custom format for `date` type runtime fields.
      - `input_field` (string Field)
        For type `lookup`
      - `target_field` (string Field)
        For type `lookup`
      - `target_index` (string IndexName)
        For type `lookup`
      - `script` (string Script)
        Painless script executed at query time.
      - `on_script_error` (enum OnScriptError)
        Values: `fail`, `continue`
      - `type` (enum RuntimeFieldType)
        Field type, which can be: `boolean`, `composite`, `date`, `double`, `geo_point`, `ip`,`keyword`, `long`, or `lookup`.
        Values: `boolean`, `composite`, `date`, `double`, `geo_point`, `geo_shape`, `ip`, `keyword`, `long`, `lookup`
    - `enabled` (boolean)
    - `subobjects` (enum Subobjects)
      Values: `true`, `false`
    - `_data_stream_timestamp` ({} DataStreamTimestamp)
      - `enabled` (boolean)
  - `effective_mappings` ({} TypeMapping)
    The mappings that are effective on this data stream, taking into account the mappings from the matching index
template and the mappings specific to this data stream.
    Same fields as `mappings` in `data_streams`
## Code Examples

#### Console

```console
PUT /_data_stream/my-data-stream/_mappings
{
   "properties":{
      "field1":{
         "type":"ip"
      },
      "field3":{
         "type":"text"
      }
   }
}
```

#### JavaScript

```javascript
const response = await client.indices.putDataStreamMappings({
  name: "my-data-stream",
  mappings: {
    properties: {
      field1: {
        type: "ip",
      },
      field3: {
        type: "text",
      },
    },
  },
});
```

#### Python

```python
resp = client.indices.put_data_stream_mappings(
    name="my-data-stream",
    mappings={
        "properties": {
            "field1": {
                "type": "ip"
            },
            "field3": {
                "type": "text"
            }
        }
    },
)
```

#### curl

```curl
curl -X PUT "$ELASTICSEARCH_URL/_data_stream/my-data-stream/_mappings" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "field1": {
        "type": "ip"
      },
      "field3": {
        "type": "text"
      }
    }
  }'
```

#### Java

```java
client.indices().putDataStreamMappings(p -> p
    .name("my-data-stream")
    .mappings(m -> m
        .properties(Map.of("field1", Property.of(pr -> pr
                .ip(i -> i)
            ),"field3", Property.of(pro -> pro
                .text(t -> t)
            )))
    )
);
```

#### C#

```c#
var response = await client.Indices
    .PutDataStreamMappingsAsync(name: new[] { "my-data-stream" }, d1 => d1
        .Mappings(d2 => d2
            .Properties(d3 => d3
                .Ip(x => x.Field1)
                .Text(x => x.Field3)
            )
        )
    );
```

#### PHP

```php
$resp = $client->indices()->putDataStreamMappings([
    "name" => "my-data-stream",
    "body" => [
        "properties" => [
            "field1" => [
                "type" => "ip",
            ],
            "field3" => [
                "type" => "text",
            ],
        ],
    ],
]);
```

#### Ruby

```ruby
response = client.indices.put_data_stream_mappings(
  name: "my-data-stream",
  body: {
    "properties": {
      "field1": {
        "type": "ip"
      },
      "field3": {
        "type": "text"
      }
    }
  }
)
```

## Response Examples

#### Change data stream settings on a data stream

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.

```json
{
  "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"
          }
        }
      }
    }
  ]
}
```

#### Attempt to change a data stream setting that is not allowed

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.

```json
{
  "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": {}
      }
    }
  ]
}
```