From b0ef313817743454452b3c7c8da221c9cff3df86 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 19 Aug 2019 09:32:37 -0400 Subject: [PATCH] [DOCS] Add examples to the mapping docs (#45520) --- docs/reference/indices/put-mapping.asciidoc | 21 ++- docs/reference/mapping.asciidoc | 164 ++++++++++++++++---- 2 files changed, 149 insertions(+), 36 deletions(-) diff --git a/docs/reference/indices/put-mapping.asciidoc b/docs/reference/indices/put-mapping.asciidoc index d5d73f8fc3f..d5edfe51be8 100644 --- a/docs/reference/indices/put-mapping.asciidoc +++ b/docs/reference/indices/put-mapping.asciidoc @@ -57,12 +57,23 @@ PUT /twitter-1,twitter-2/_mapping <1> [float] ==== Updating field mappings -In general, the mapping for existing fields cannot be updated. There are some -exceptions to this rule. For instance: +// tag::put-field-mapping-exceptions[] -* new <> can be added to <> fields. -* new <> can be added to existing fields. -* the <> parameter can be updated. +You can't change the mapping of an existing field, with the following +exceptions: + +* 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: diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index 8b6b1af3e58..b5d2e6ae37a 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -118,49 +118,151 @@ You know more about your data than Elasticsearch can guess, so while dynamic mapping can be useful to get started, at some point you will want to specify your own explicit mappings. -You can create field mappings when you -<>, and you can add -fields to an existing index with the <>. +You can create field mappings when you <> and +<>. [float] -== Updating existing field mappings +[[create-mapping]] +== Create an index with an explicit mapping -Other than where documented, *existing field mappings cannot be -updated*. Changing the mapping would mean invalidating already indexed -documents. Instead, you should create a new index with the correct mappings -and <> your data into that index. If you only wish -to rename a field and not change its mappings, it may make sense to introduce -an <> field. - -[float] -== Example mapping - -A mapping can be specified when creating an index, as follows: +You can use the <> API to create a new index +with an explicit mapping. [source,js] ---------------------------------------- -PUT my_index <1> +---- +PUT /my-index { "mappings": { - "properties": { <2> - "title": { "type": "text" }, <3> - "name": { "type": "text" }, <4> - "age": { "type": "integer" }, <5> - "created": { - "type": "date", <6> - "format": "strict_date_optional_time||epoch_millis" + "properties": { + "age": { "type": "integer" }, <1> + "email": { "type": "keyword" }, <2> + "name": { "type": "text" } <3> + } + } +} +---- +// CONSOLE + +<1> Creates `age`, an <> field +<2> Creates `email`, a <> field +<3> Creates `name`, a <> field + +[float] +[[add-field-mapping]] +== Add a field to an existing mapping + +You can use the <> API to add one or more new +fields to an existing index. + +The following example adds `employee-id`, a `keyword` field with an +<> mapping parameter value of `false`. This means values +for the `employee-id` field are stored but not indexed or available for search. + +[source,js] +---- +PUT /my-index/_mapping +{ + "properties": { + "employee-id": { + "type": "keyword", + "index": false + } + } +} +---- +// CONSOLE +// TEST[continued] + +[float] +[[update-mapping]] +=== Update the mapping of a field + +include::{docdir}/indices/put-mapping.asciidoc[tag=put-field-mapping-exceptions] + +[float] +[[view-mapping]] +== View the mapping of an index + +You can use the <> API to view the mapping of +an existing index. + +[source,js] +---- +GET /my-index/_mapping +---- +// CONSOLE +// TEST[continued] + +The API returns the following response: + +[source,js] +---- +{ + "my-index" : { + "mappings" : { + "properties" : { + "age" : { + "type" : "integer" + }, + "email" : { + "type" : "keyword" + }, + "employee-id" : { + "type" : "keyword", + "index" : false + }, + "name" : { + "type" : "text" + } } } } } ---------------------------------------- +---- +// TESTRESPONSE + + +[float] +[[view-field-mapping]] +== View the mapping of specific fields + +If you only want to view the mapping of one or more specific fields, you can use +the <> API. + +This is useful if you don't need the complete mapping of an index or your index +contains a large number of fields. + +The following request retrieves the mapping for the `employee-id` field. + +[source,js] +---- +GET /my-index/_mapping/field/employee-id +---- // CONSOLE -<1> Create an index called `my_index`. -<2> Specify the fields or _properties_ in the mapping. -<3> Specify that the `title` field contains `text` values. -<4> Specify that the `name` field contains `text` values. -<5> Specify that the `age` field contains `integer` values. -<6> Specify that the `created` field contains `date` values in two possible formats. +// TEST[continued] + +The API returns the following response: + +[source,js] +---- +{ + "my-index" : { + "mappings" : { + "employee-id" : { + "full_name" : "employee-id", + "mapping" : { + "employee-id" : { + "type" : "keyword", + "index" : false + } + } + } + } + } +} + +---- +// TESTRESPONSE --