From 4c6d56bef0179043ba5f7a0a70d791bf7e9ef6c3 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Thu, 17 Oct 2019 09:30:46 -0400 Subject: [PATCH] [DOCS] Expand put mapping API docs examples (#47462) --- docs/reference/indices/put-mapping.asciidoc | 461 ++++++++++++++++++-- docs/reference/mapping.asciidoc | 4 +- 2 files changed, 425 insertions(+), 40 deletions(-) diff --git a/docs/reference/indices/put-mapping.asciidoc b/docs/reference/indices/put-mapping.asciidoc index e9655edcc5d..62258d9f85e 100644 --- a/docs/reference/indices/put-mapping.asciidoc +++ b/docs/reference/indices/put-mapping.asciidoc @@ -131,32 +131,24 @@ PUT /twitter-1,twitter-2/_mapping <1> <1> Note that the indices specified (`twitter-1,twitter-2`) follows <> and wildcard format. -[[updating-field-mappings]] -===== Update an existing field -// tag::put-field-mapping-exceptions[] +[[add-new-field-to-object]] +===== Add new properties to an existing object field -You can't change the mapping of an existing field, with the following -exceptions: +You can use the put mapping API +to add new properties +to an existing <> field. +To see how this works, +try the following example. -* You can add new <> to an <> field. -* You can use the <> mapping parameter to enable -multi-fields. -* You can change the value of the <> mapping -parameter. - -Changing the mapping of an existing field could invalidate data that's already -indexed. If you need to change the mapping of a field, create a new index with -the correct mappings and <> your data into that index. If -you only want to rename a field, consider adding an <> field. - -// end::put-field-mapping-exceptions[] - -For example: +Use the <> API +to create an index +with the `name` object field +and an inner `first` text field. [source,console] ------------------------------------ -PUT /my_index <1> +---- +PUT /my_index { "mappings": { "properties": { @@ -166,35 +158,426 @@ PUT /my_index <1> "type": "text" } } - }, + } + } + } +} +---- + +Use the put mapping API +to add a new inner `last` text field +to the `name` field. + +[source,console] +---- +PUT /my_index/_mapping +{ + "properties": { + "name": { + "properties": { + "last": { + "type": "text" + } + } + } + } +} +---- +// TEST[continued] + +Use the <> API +to verify your changes. + +[source,console] +---- +GET /my_index/_mapping +---- +// TEST[continued] + +The API returns the following response: + +[source,console-result] +---- +{ + "my_index" : { + "mappings" : { + "properties" : { + "name" : { + "properties" : { + "first" : { + "type" : "text" + }, + "last" : { + "type" : "text" + } + } + } + } + } + } +} +---- + + +[[add-multi-fields-existing-field-ex]] +===== Add multi-fields to an existing field + +<> +let you index the same field +in different ways. +You can use the put mapping API +to update the `fields` mapping parameter +and enable multi-fields for an existing field. + +To see how this works, +try the following example. + +Use the <> API +to create an index +with the `city` <> field. + +[source,console] +---- +PUT /my_index +{ + "mappings": { + "properties": { + "city": { + "type": "text" + } + } + } +} +---- + +While text fields work well for full-text search, +<> fields are not analyzed +and may work better for sorting or aggregations. + +Use the put mapping API +to enable a multi-field for the `city` field. +This request adds the `city.raw` keyword multi-field, +which can be used for sorting. + +[source,console] +---- +PUT /my_index/_mapping +{ + "properties": { + "city": { + "type": "text", + "fields": { + "raw": { + "type": "keyword" + } + } + } + } +} +---- +// TEST[continued] + +Use the <> API +to verify your changes. + +[source,console] +---- +GET /my_index/_mapping +---- +// TEST[continued] + +The API returns the following response: + +[source,console-result] +---- +{ + "my_index" : { + "mappings" : { + "properties" : { + "city" : { + "type" : "text", + "fields" : { + "raw" : { + "type" : "keyword" + } + } + } + } + } + } +} +---- + + +[[change-existing-mapping-parms]] +===== Change supported mapping parameters for an existing field + +The documentation for each <> +indicates whether you can update it +for an existing field +using the put mapping API. +For example, +you can use the put mapping API +to update the <> parameter. + +To see how this works, +try the following example. + +Use the <> API to create an index +containing a `user_id` keyword field. +The `user_id` field +has an `ignore_above` parameter value +of `20`. + +[source,console] +---- +PUT /my_index +{ + "mappings": { + "properties": { + "user_id": { + "type": "keyword", + "ignore_above": 20 + } + } + } +} +---- + +Use the put mapping API +to change the `ignore_above` parameter value +to `100`. + +[source,console] +---- +PUT /my_index/_mapping +{ + "properties": { + "user_id": { + "type": "keyword", + "ignore_above": 100 + } + } +} +---- +// TEST[continued] + +Use the <> API +to verify your changes. + +[source,console] +---- +GET /my_index/_mapping +---- +// TEST[continued] + +The API returns the following response: + +[source,console-result] +---- +{ + "my_index" : { + "mappings" : { + "properties" : { + "user_id" : { + "type" : "keyword", + "ignore_above" : 100 + } + } + } + } +} +---- + + +[[updating-field-mappings]] +===== Change the mapping of an existing field + +// tag::change-field-mapping[] +Except for supported <>, +you can't change the mapping or field type of an existing field. +Changing an existing field could invalidate data that's already indexed. + +If you need to change the mapping of a field, +create a new index with the correct mapping +and <> your data into that index. +// end::change-field-mapping[] + +To see how this works, +try the following example. + +Use the <> API +to create the `users` index +with the `user_id` field +with the <> field type. + +[source,console] +---- +PUT /users +{ + "mappings" : { + "properties": { + "user_id": { + "type": "long" + } + } + } +} +---- + +Use the <> API +to index several documents +with `user_id` field values. + +[source,console] +---- +POST /users/_doc?refresh=wait_for +{ + "user_id" : 12345 +} + +POST /users/_doc?refresh=wait_for +{ + "user_id" : 12346 +} +---- +// TEST[continued] + +To change the `user_id` field +to the <> field type, +use the create index API +to create the `new_users` index with the correct mapping. + +[source,console] +---- +PUT /new_users +{ + "mappings" : { + "properties": { "user_id": { "type": "keyword" } } } } +---- +// TEST[continued] -PUT /my_index/_mapping +Use the <> API +to copy documents from the `users` index +to the `new_users` index. + +[source,console] +---- +POST /_reindex { - "properties": { - "name": { - "properties": { - "last": { <2> - "type": "text" - } + "source": { + "index": "users" + }, + "dest": { + "index": "new_users" + } +} +---- +// TEST[continued] + +The API returns the following response: + +[source,console-result] +---- +{ + "took": 147, + "timed_out": false, + "total": 2, + "updated": 0, + "created": 2, + "deleted": 0, + "batches": 1, + "version_conflicts": 0, + "noops": 0, + "retries": { + "bulk": 0, + "search": 0 + }, + "throttled_millis": 0, + "requests_per_second": -1.0, + "throttled_until_millis": 0, + "failures" : [ ] +} +---- +// TESTRESPONSE[s/"took": 147/"took": "$body.took"/] + + +[[rename-existing-field]] +===== Rename a field + +// tag::rename-field[] +Renaming a field would invalidate data already indexed under the old field name. +Instead, add an <> field to create an alternate field name. +// end::rename-field[] + +For example, +use the <> API +to create an index +with the `user_identifier` field. + +[source,console] +---- +PUT /my_index +{ + "mappings": { + "properties": { + "user_identifier": { + "type": "keyword" } - }, - "user_id": { - "type": "keyword", - "ignore_above": 100 <3> } } } ------------------------------------ +---- -<1> Create an index with a `first` field under the `name` <> field, and a `user_id` field. -<2> Add a `last` field under the `name` object field. -<3> Update the `ignore_above` setting from its default of 0. +Use the put mapping API to add the `user_id` field alias +for the existing `user_identifier` field. -Each <> specifies whether or not its setting -can be updated on an existing field. +[source,console] +---- +PUT /my_index/_mapping +{ + "properties": { + "user_id": { + "type": "alias", + "path": "user_identifier" + } + } +} +---- +// TEST[continued] + +Use the <> API +to verify your changes. + +[source,console] +---- +GET /my_index/_mapping +---- +// TEST[continued] + +The API returns the following response: + +[source,console-result] +---- +{ + "my_index" : { + "mappings" : { + "properties" : { + "user_id" : { + "type" : "alias", + "path" : "user_identifier" + }, + "user_identifier" : { + "type" : "keyword" + } + } + } + } +} +---- diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index 6067e90e78d..5c3a7df0aa3 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -176,7 +176,9 @@ PUT /my-index/_mapping [[update-mapping]] === Update the mapping of a field -include::{docdir}/indices/put-mapping.asciidoc[tag=put-field-mapping-exceptions] +include::{docdir}/indices/put-mapping.asciidoc[tag=change-field-mapping] + +include::{docdir}/indices/put-mapping.asciidoc[tag=rename-field] [float] [[view-mapping]]