---
type: api
title: Update field mappings
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-indices-put-mapping
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-indices-put-mapping
products:
  - Elasticsearch Serverless
---

# Update field mappings


Availability:

## Paths

- `POST` (also `PUT`) `/{index}/_mapping`

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

#### Path Parameters

- `index` (union IndexName | [] IndexName)
  A comma-separated list of index names the mapping should be added to (supports wildcards).
Use `_all` or omit to add the mapping on all indices.

## Description

Add new fields to an existing data stream or index.
You can use the update mapping API to:

- Add a new field to an existing index
- Update mappings for multiple indices in a single request
- Add new properties to an object field
- Enable multi-fields for an existing field
- Update supported mapping parameters
- Change a field's mapping using reindexing
- Rename a field using a field alias

Learn how to use the update mapping API with practical examples in the [Update mapping API examples](https://www.elastic.co/docs/manage-data/data-store/mapping/update-mappings-examples) guide.

## Required authorization

* Index privileges: `manage`

[More about mapping parameters](https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/mapping-parameters)

## Query String Parameters

- `allow_no_indices` (boolean · default: true)
  A setting that does two separate checks on the index expression.
If `false`, the request returns an error (1) if any wildcard expression
(including `_all` and `*`) resolves to zero matching indices or (2) if the
complete set of resolved indices, aliases or data streams is empty after all
expressions are evaluated. If `true`, index expressions that resolve to no
indices are allowed and the request returns an empty result.
- `expand_wildcards` (string ExpandWildcards · default: open)
  Type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
Supports comma-separated values, such as `open,hidden`.

Supported values include:
  - `all`: Match any data stream or index, including hidden ones.
  - `open`: Match open, non-hidden indices. Also matches any non-hidden data stream.
  - `closed`: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
  - `hidden`: Match hidden data streams and hidden indices. Must be combined with `open`, `closed`, or `both`.
  - `none`: Wildcard expressions are not accepted.
  Values: `all`, `open`, `closed`, `hidden`, `none`
- `ignore_unavailable` (boolean · default: false)
  If `false`, the request returns an error if it targets a concrete (non-wildcarded)
index, alias, or data stream that is missing, closed, or otherwise unavailable.
If `true`, unavailable concrete targets are silently ignored.
- `master_timeout` (string Duration · default: 30s)
  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)
  Period to wait for a response.
If no response is received before the timeout expires, the request fails and returns an error.
- `write_index_only` (boolean · default: false)
  If `true`, the mappings are applied only to the current write index for the target.

## Request Body

`application/json`

- `date_detection` (boolean) — optional
  Controls whether dynamic date detection is enabled.
- `dynamic` (enum DynamicMapping) — optional
  Controls whether new fields are added dynamically.
  Values: `strict`, `runtime`, `true`, `false`
- `dynamic_date_formats` ([] string) — optional
  If date detection is enabled then new string fields are checked
against 'dynamic_date_formats' and if the value matches then
a new date field is added instead of string.
- `dynamic_templates` ([] string to DynamicTemplate) — optional
  Specify dynamic templates for the mapping.
- `_field_names` ({} FieldNamesField) — optional
  Control whether field names are enabled for the index.
  - `enabled` (boolean) — required
- `_meta` (Metadata) — optional
  A mapping type can have custom meta data associated with it. These are
not used at all by Elasticsearch, but can be used to store
application-specific metadata.
- `numeric_detection` (boolean · default: false) — optional
  Automatically map strings into numeric data types for all fields.
- `properties` (map string to Property) — optional
  Mapping for a field. For new fields, this mapping can include:

- Field name
- Field data type
- Mapping parameters
- `_routing` ({} RoutingField) — optional
  Enable making a routing value required on indexed documents.
  - `required` (boolean) — required
- `_source` ({} SourceField) — optional
  Control whether the _source field is enabled on the index.
  - `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` (RuntimeFields) — optional
  Mapping of runtime fields for the index.

## Response

`application/json`

- `acknowledged` (boolean)
  For a successful response, this value is always true. On failure, an exception is returned instead.
- `_shards` ({} ShardStatistics)
  - `failed` (number uint)
    The number of shards the operation or search attempted to run on but failed.
  - `successful` (number uint)
    The number of shards the operation or search succeeded on.
  - `total` (number uint)
    The number of shards the operation or search will run on overall.
  - `failures` ([] ShardFailure)
    - `index` (string IndexName)
    - `node` (string)
    - `reason` ({} ErrorCause)
      - `type` (string)
        The type of error
      - `reason` (union string) — nullable
        A human-readable explanation of the error, in English.
        One of: `string`
      - `stack_trace` (string)
        The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
      - `caused_by` ({} ErrorCause) — recursive
        Same fields as `reason` in `failures`
      - `root_cause` ([] ErrorCause) — recursive
        Same fields as `reason` in `failures`
      - `suppressed` ([] ErrorCause) — recursive
        Same fields as `reason` in `failures`
    - `shard` (number)
    - `status` (string)
    - `primary` (boolean)
  - `skipped` (number uint)
## Code Examples

#### Console

```console
POST /my-index-000001/_mapping
{
  "properties": {
    "user": {
      "properties": {
        "name": {
          "type": "keyword"
        }
      }
    }
  }
}
```

#### JavaScript

```javascript
const response = await client.indices.putMapping({
  index: "my-index-000001",
  properties: {
    user: {
      properties: {
        name: {
          type: "keyword",
        },
      },
    },
  },
});
```

#### Python

```python
resp = client.indices.put_mapping(
    index="my-index-000001",
    properties={
        "user": {
            "properties": {
                "name": {
                    "type": "keyword"
                }
            }
        }
    },
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/my-index-000001/_mapping" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "user": {
        "properties": {
          "name": {
            "type": "keyword"
          }
        }
      }
    }
  }'
```

#### Java

```java
client.indices().putMapping(p -> p
    .index("my-index-000001")
    .properties("user", pr -> pr
        .object(o -> o
            .properties("name", pro -> pro
                .keyword(k -> k)
            )
        )
    )
);
```

#### C#

```c#
var response = await client.Indices
    .PutMappingAsync(indices: new[] { "my-index-000001" }, d1 => d1
        .Properties(d2 => d2
            .Object(x => x.User, d3 => d3
                .Properties(d4 => d4
                    .Keyword(x => x.Name)
                )
            )
        )
    );
```

#### PHP

```php
$resp = $client->indices()->putMapping([
    "index" => "my-index-000001",
    "body" => [
        "properties" => [
            "user" => [
                "properties" => [
                    "name" => [
                        "type" => "keyword",
                    ],
                ],
            ],
        ],
    ],
]);
```

#### Ruby

```ruby
response = client.indices.put_mapping(
  index: "my-index-000001",
  body: {
    "properties": {
      "user": {
        "properties": {
          "name": {
            "type": "keyword"
          }
        }
      }
    }
  }
)
```