From a701039f6e6654bce88d9abbec67b1d3385c2a6e Mon Sep 17 00:00:00 2001 From: kosabogi Date: Fri, 13 Jun 2025 11:17:00 +0200 Subject: [PATCH 1/4] Adds Update mapping API examples page --- .../mapping/update-mappings-examples.md | 277 ++++++++++++++++++ manage-data/toc.yml | 1 + 2 files changed, 278 insertions(+) create mode 100644 manage-data/data-store/mapping/update-mappings-examples.md diff --git a/manage-data/data-store/mapping/update-mappings-examples.md b/manage-data/data-store/mapping/update-mappings-examples.md new file mode 100644 index 0000000000..fd86023d67 --- /dev/null +++ b/manage-data/data-store/mapping/update-mappings-examples.md @@ -0,0 +1,277 @@ +--- +mapped_pages: + - https://www.elastic.co/guide/en/elasticsearch/reference/8.18/indices-put-mapping.html#put-mapping-api-example +applies_to: + stack: ga + serverless: ga +products: + - id: elasticsearch +--- + +# Update mapping API examples + +This page provides examples of how to use the [update mapping API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-put-mapping) to modify index mappings after creation. + +You can learn how to: + +- [Add a new field to a single index](#example-with-single-target) +- [Update multiple indices at once](#multiple-targets) +- [Add new properties to an object field](#add-new-properties-to-an-existing-object-field) +- [Enable multi-fields for an existing field](#add-multi-fields-to-an-existing-field) +- [Update supported mapping parameters](#change-supported-mapping-parameters-for-an-existing-field) +- [Change the mapping of a field using reindexing](#change-the-mapping-of-an-existing-field) +- [Rename a field using field aliases](#rename-a-field) + +## Example with single target + +The update mapping API requires an existing data stream or index. The following [create index](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html) API request creates the `publications` index with no mapping. + +```console +PUT /publications +``` + +The following update mapping API request adds `title`, a new [`text`](https://www.elastic.co/guide/en/elasticsearch/reference/current/text.html) field, to the `publications` index. + +```json +PUT /publications/_mapping +{ + "properties": { + "title": { "type": "text" } + } +} +``` + +## Multiple targets + +The update mapping API can be applied to multiple data streams or indices in a single request. For example, you can update mappings for the `my-index-000001` and `my-index-000002` indices at the same time: + +```json +# Create the two indices +PUT /my-index-000001 +PUT /my-index-000002 + +# Update both mappings +PUT /my-index-000001,my-index-000002/_mapping +{ + "properties": { + "user": { + "properties": { + "name": { + "type": "keyword" + } + } + } + } +} +``` + +## Add new properties to an existing object field + +You can use the update mapping API to add new properties to an existing [`object`](https://www.elastic.co/guide/en/elasticsearch/reference/current/object.html) field. + +First, create an index with the `name` object field and an inner `first` text field: + +```json +PUT /my-index-000001 +{ + "mappings": { + "properties": { + "name": { + "properties": { + "first": { + "type": "text" + } + } + } + } + } +} +``` + +Then, use the update mapping API to add a new inner `last` text field to the `name` field: + +```json +PUT /my-index-000001/_mapping +{ + "properties": { + "name": { + "properties": { + "last": { + "type": "text" + } + } + } + } +} +``` + +## Add multi-fields to an existing field + +[Multi-fields](https://www.elastic.co/guide/en/elasticsearch/reference/current/multi-fields.html) let you index the same field in different ways. You can use the update mapping API to update the `fields` mapping parameter and enable multi-fields for an existing field. + +::::{warning} +If an index (or data stream) contains documents when you add a multi-field, those documents will not have values for the new multi-field. You can populate the new multi-field with the [update by query API](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update-by-query.html). +:::: + +To see how this works, try the following example. + +Use the [create index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-create) to create an index with the `city` [`text`](https://www.elastic.co/guide/en/elasticsearch/reference/current/text.html) field: + +```json +PUT /my-index-000001 +{ + "mappings": { + "properties": { + "city": { + "type": "text" + } + } + } +} +``` + +Enable a multi-field for `city`: + +```json +PUT /my-index-000001/_mapping +{ + "properties": { + "city": { + "type": "text", + "fields": { + "raw": { + "type": "keyword" + } + } + } + } +} +``` + +## Change supported mapping parameters for an existing field + +Not all mapping parameters are updateable, but some like [`ignore_above`](https://www.elastic.co/guide/en/elasticsearch/reference/current/ignore-above.html) can be changed. + +Create an index with `ignore_above: 20`: + +```json +PUT /my-index-000001 +{ + "mappings": { + "properties": { + "user_id": { + "type": "keyword", + "ignore_above": 20 + } + } + } +} +``` + +Update `ignore_above` to `100`: + +```json +PUT /my-index-000001/_mapping +{ + "properties": { + "user_id": { + "type": "keyword", + "ignore_above": 100 + } + } +} +``` + +## Change the mapping of an existing field + +You **cannot** change the field type of an existing field. Instead, create a new index with the desired mapping and [reindex](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html) your data. + +Create an index with a `user_id` field of type `long`: + +```json +PUT /my-index-000001 +{ + "mappings": { + "properties": { + "user_id": { + "type": "long" + } + } + } +} +``` + +Index some documents: + +```json +POST /my-index-000001/_doc?refresh=wait_for +{ + "user_id": 12345 +} + +POST /my-index-000001/_doc?refresh=wait_for +{ + "user_id": 12346 +} +``` + +Create a new index with the `user_id` field as `keyword`: + +```json +PUT /my-new-index-000001 +{ + "mappings": { + "properties": { + "user_id": { + "type": "keyword" + } + } + } +} +``` + +Reindex the data: + +```json +POST /_reindex +{ + "source": { + "index": "my-index-000001" + }, + "dest": { + "index": "my-new-index-000001" + } +} +``` + +## Rename a field + +You **can't** rename a field directly. Instead, use a [`field alias`](https://www.elastic.co/guide/en/elasticsearch/reference/current/alias.html). + +Create an index with the `user_identifier` field: + +```json +PUT /my-index-000001 +{ + "mappings": { + "properties": { + "user_identifier": { + "type": "keyword" + } + } + } +} +``` + +Add the `user_id` alias: + +```json +PUT /my-index-000001/_mapping +{ + "properties": { + "user_id": { + "type": "alias", + "path": "user_identifier" + } + } +} diff --git a/manage-data/toc.yml b/manage-data/toc.yml index 9275294ab4..9435039836 100644 --- a/manage-data/toc.yml +++ b/manage-data/toc.yml @@ -36,6 +36,7 @@ toc: - file: data-store/mapping/index-runtime-field.md - file: data-store/mapping/explore-data-with-runtime-fields.md - file: data-store/mapping/removal-of-mapping-types.md + - file: data-store/mapping/update-mappings-examples.md - file: data-store/text-analysis.md children: - file: data-store/text-analysis/concepts.md From 932035cdc9a3ab6b24f312b7c38a318a7700d128 Mon Sep 17 00:00:00 2001 From: kosabogi Date: Fri, 13 Jun 2025 12:33:13 +0200 Subject: [PATCH 2/4] Adds test comments --- .../mapping/update-mappings-examples.md | 40 +++++++++++++------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/manage-data/data-store/mapping/update-mappings-examples.md b/manage-data/data-store/mapping/update-mappings-examples.md index fd86023d67..864b0b86f9 100644 --- a/manage-data/data-store/mapping/update-mappings-examples.md +++ b/manage-data/data-store/mapping/update-mappings-examples.md @@ -29,10 +29,11 @@ The update mapping API requires an existing data stream or index. The following ```console PUT /publications ``` +% TEST The following update mapping API request adds `title`, a new [`text`](https://www.elastic.co/guide/en/elasticsearch/reference/current/text.html) field, to the `publications` index. -```json +```console PUT /publications/_mapping { "properties": { @@ -40,6 +41,7 @@ PUT /publications/_mapping } } ``` +% TEST[continued] ## Multiple targets @@ -64,6 +66,7 @@ PUT /my-index-000001,my-index-000002/_mapping } } ``` +% TEST[continued] ## Add new properties to an existing object field @@ -71,7 +74,7 @@ You can use the update mapping API to add new properties to an existing [`object First, create an index with the `name` object field and an inner `first` text field: -```json +```console PUT /my-index-000001 { "mappings": { @@ -87,10 +90,11 @@ PUT /my-index-000001 } } ``` +% TEST Then, use the update mapping API to add a new inner `last` text field to the `name` field: -```json +```console PUT /my-index-000001/_mapping { "properties": { @@ -104,6 +108,7 @@ PUT /my-index-000001/_mapping } } ``` +% TEST[continued] ## Add multi-fields to an existing field @@ -117,7 +122,7 @@ To see how this works, try the following example. Use the [create index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-create) to create an index with the `city` [`text`](https://www.elastic.co/guide/en/elasticsearch/reference/current/text.html) field: -```json +```console PUT /my-index-000001 { "mappings": { @@ -129,10 +134,11 @@ PUT /my-index-000001 } } ``` +% TEST Enable a multi-field for `city`: -```json +```console PUT /my-index-000001/_mapping { "properties": { @@ -147,6 +153,7 @@ PUT /my-index-000001/_mapping } } ``` +% TEST[continued] ## Change supported mapping parameters for an existing field @@ -154,7 +161,7 @@ Not all mapping parameters are updateable, but some like [`ignore_above`](https: Create an index with `ignore_above: 20`: -```json +```console PUT /my-index-000001 { "mappings": { @@ -167,10 +174,11 @@ PUT /my-index-000001 } } ``` +% TEST Update `ignore_above` to `100`: -```json +```console PUT /my-index-000001/_mapping { "properties": { @@ -181,6 +189,7 @@ PUT /my-index-000001/_mapping } } ``` +% TEST[continued] ## Change the mapping of an existing field @@ -188,7 +197,7 @@ You **cannot** change the field type of an existing field. Instead, create a new Create an index with a `user_id` field of type `long`: -```json +```console PUT /my-index-000001 { "mappings": { @@ -200,6 +209,7 @@ PUT /my-index-000001 } } ``` +% TEST Index some documents: @@ -214,10 +224,11 @@ POST /my-index-000001/_doc?refresh=wait_for "user_id": 12346 } ``` +% TEST[continued] Create a new index with the `user_id` field as `keyword`: -```json +```console PUT /my-new-index-000001 { "mappings": { @@ -229,10 +240,11 @@ PUT /my-new-index-000001 } } ``` +% TEST[continued] Reindex the data: -```json +```console POST /_reindex { "source": { @@ -243,6 +255,7 @@ POST /_reindex } } ``` +% TEST[continued] ## Rename a field @@ -250,7 +263,7 @@ You **can't** rename a field directly. Instead, use a [`field alias`](https://ww Create an index with the `user_identifier` field: -```json +```console PUT /my-index-000001 { "mappings": { @@ -262,10 +275,11 @@ PUT /my-index-000001 } } ``` +% TEST[continued] Add the `user_id` alias: -```json +```console PUT /my-index-000001/_mapping { "properties": { @@ -275,3 +289,5 @@ PUT /my-index-000001/_mapping } } } +``` +% TEST[continued] \ No newline at end of file From b7650d47b7153251eee6b7115a1a80ca32972087 Mon Sep 17 00:00:00 2001 From: kosabogi <105062005+kosabogi@users.noreply.github.com> Date: Fri, 13 Jun 2025 13:31:12 +0200 Subject: [PATCH 3/4] Update manage-data/data-store/mapping/update-mappings-examples.md Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- manage-data/data-store/mapping/update-mappings-examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manage-data/data-store/mapping/update-mappings-examples.md b/manage-data/data-store/mapping/update-mappings-examples.md index 864b0b86f9..a813b028da 100644 --- a/manage-data/data-store/mapping/update-mappings-examples.md +++ b/manage-data/data-store/mapping/update-mappings-examples.md @@ -47,7 +47,7 @@ PUT /publications/_mapping The update mapping API can be applied to multiple data streams or indices in a single request. For example, you can update mappings for the `my-index-000001` and `my-index-000002` indices at the same time: -```json +```console # Create the two indices PUT /my-index-000001 PUT /my-index-000002 From 61f85b9a16cde048fbb16a4726ac8bd1618e6236 Mon Sep 17 00:00:00 2001 From: kosabogi <105062005+kosabogi@users.noreply.github.com> Date: Mon, 16 Jun 2025 11:50:40 +0200 Subject: [PATCH 4/4] Update manage-data/data-store/mapping/update-mappings-examples.md Co-authored-by: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> --- manage-data/data-store/mapping/update-mappings-examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manage-data/data-store/mapping/update-mappings-examples.md b/manage-data/data-store/mapping/update-mappings-examples.md index a813b028da..22ccccaa5a 100644 --- a/manage-data/data-store/mapping/update-mappings-examples.md +++ b/manage-data/data-store/mapping/update-mappings-examples.md @@ -259,7 +259,7 @@ POST /_reindex ## Rename a field -You **can't** rename a field directly. Instead, use a [`field alias`](https://www.elastic.co/guide/en/elasticsearch/reference/current/alias.html). +You **cannot** rename a field directly. Instead, use a [`field alias`](https://www.elastic.co/guide/en/elasticsearch/reference/current/alias.html). Create an index with the `user_identifier` field: