---
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/4493/api/doc/elasticsearch-serverless/operation/operation-indices-put-data-stream-mappings
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch-serverless/operation/operation-indices-put-data-stream-mappings
products:
  - Elasticsearch Serverless
---

# Update data stream mappings

## Paths

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

#### Path parameters

- `name` (union string | string[]) — required
  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`

## Authentication

- Api key: `Authorization: <value>`
  Elasticsearch APIs use key-based authentication.
  You must create an API key and use the encoded value in the request header.
  For example:
  
  
  ```
  curl -X GET "${ES_URL}/_cat/indices?v=true" \
    -H "Authorization: ApiKey ${API_KEY}"
  ```
  
  For more information about where to find API keys for the Elasticsearch endpoint (${ES_URL}) for a project, go to [Get started with Elasticsearch Serverless](https://www.elastic.co/docs/solutions/search/serverless-elasticsearch-get-started).

## Query string parameters

- `dry_run` (boolean · default: false) — optional
  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 · default: 30s) — optional
  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 · default: 30s) — optional
  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` (object) — 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) — optional
  Values: `strict`, `runtime`, `true`, `false`
- `dynamic_date_formats` (string[]) — optional
- `dynamic_templates` (string to object[]) — optional
- `_field_names` (object) — optional
  - `enabled` (boolean) — required
- `index_field` (object) — optional
  - `enabled` (boolean) — required
- `_meta` (object) — optional
- `numeric_detection` (boolean) — optional
- `properties` (map string to oneOf) — optional
- `_routing` (object) — optional
  - `required` (boolean) — required
- `_size` (object) — optional
  - `enabled` (boolean) — required
- `_source` (object) — optional
  - `enabled` (boolean) — optional
  - `excludes` (string[]) — optional
  - `includes` (string[]) — optional
  - `mode` (enum) — 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 object) — optional
  Map values (object)
  - `fields` (map string to object) — optional
    For type `composite`
    Map values (object)
    - `type` (enum) — required
      Values: `boolean`, `composite`, `date`, `double`, `geo_point`, `geo_shape`, `ip`, `keyword`, `long`, `lookup`
  - `fetch_fields` (object[]) — optional
    For type `lookup`
    - `field` (string) — required
    - `format` (string) — optional
  - `format` (string) — optional
    A custom format for `date` type runtime fields.
  - `input_field` (string) — optional
    For type `lookup`
  - `target_field` (string) — optional
    For type `lookup`
  - `target_index` (string) — optional
    For type `lookup`
  - `script` (string) — optional
    Painless script executed at query time.
  - `on_script_error` (enum) — optional
    Values: `fail`, `continue`
  - `type` (enum) — 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) — optional
  Values: `true`, `false`
- `_data_stream_timestamp` (object) — optional
  - `enabled` (boolean) — required

## Response

`application/json`

- `data_streams` (object[])
  - `name` (string)
    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` (object)
    The mappings that are specfic to this data stream that will override any mappings from the matching index template.
    - `all_field` (object)
      Same fields as `all_field`
    - `date_detection` (boolean)
    - `dynamic` (enum)
      Values: `strict`, `runtime`, `true`, `false`
    - `dynamic_date_formats` (string[])
    - `dynamic_templates` (string to object[])
    - `_field_names` (object)
      - `enabled` (boolean)
    - `index_field` (object)
      - `enabled` (boolean)
    - `_meta` (object)
    - `numeric_detection` (boolean)
    - `properties` (map string to oneOf)
    - `_routing` (object)
      - `required` (boolean)
    - `_size` (object)
      - `enabled` (boolean)
    - `_source` (object)
      - `enabled` (boolean)
      - `excludes` (string[])
      - `includes` (string[])
      - `mode` (enum)
        

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 object)
      Map values (object)
      - `fields` (map string to object)
        For type `composite`
        Map values (object)
        - `type` (enum)
          Values: `boolean`, `composite`, `date`, `double`, `geo_point`, `geo_shape`, `ip`, `keyword`, `long`, `lookup`
      - `fetch_fields` (object[])
        For type `lookup`
        - `field` (string)
        - `format` (string)
      - `format` (string)
        A custom format for `date` type runtime fields.
      - `input_field` (string)
        For type `lookup`
      - `target_field` (string)
        For type `lookup`
      - `target_index` (string)
        For type `lookup`
      - `script` (string)
        Painless script executed at query time.
      - `on_script_error` (enum)
        Values: `fail`, `continue`
      - `type` (enum)
        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)
      Values: `true`, `false`
    - `_data_stream_timestamp` (object)
      - `enabled` (boolean)
  - `effective_mappings` (object)
    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": {}
      }
    }
  ]
}
```