From 58524d31bf704987d18b79315749ced8a9e7d3c2 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 13 Aug 2019 17:04:15 -0400 Subject: [PATCH 1/5] [DOCS] Add examples to the mapping docs --- docs/reference/mapping.asciidoc | 166 +++++++++++++++++++++++++++----- 1 file changed, 140 insertions(+), 26 deletions(-) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index 8b6b1af3e5895..d545e1f63771e 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -123,44 +123,158 @@ You can create field mappings when you fields to an existing index with the <>. [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. +You can use the <> API to create a new index +with an explicit mapping. + +[source,js] +---- +PUT my-index +{ + "mappings": { + "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] -== Example mapping +[[add-field-mapping]] +== Add a field to an existing mapping -A mapping can be specified when creating an index, as follows: +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 <1> +---- +PUT /my-index/_mapping { - "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": { + "employee-id": { + "type": "keyword", + "index": false + } + } +} +---- +// CONSOLE +// TEST[continued] + +[float] +[[update-mapping]] +== Update the mapping of a field + +You can't change the mapping of an existing field, except for the following: + +* 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. + +[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 -- From 32008f67501d6bd8f8e7397164dac3292a0630ed Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Tue, 13 Aug 2019 18:18:43 -0400 Subject: [PATCH 2/5] clarify wording of exceptions --- docs/reference/mapping.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index d545e1f63771e..76d1ebcaeb603 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -178,7 +178,8 @@ PUT /my-index/_mapping [[update-mapping]] == Update the mapping of a field -You can't change the mapping of an existing field, except for the following: +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 From cbe9827a554386922808763da8a9eb7aa5e519d4 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 14 Aug 2019 19:37:28 -0400 Subject: [PATCH 3/5] iter --- docs/reference/mapping.asciidoc | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index 76d1ebcaeb603..e5e37477da7c3 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -118,9 +118,8 @@ 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] [[create-mapping]] @@ -176,7 +175,7 @@ PUT /my-index/_mapping [float] [[update-mapping]] -== Update the mapping of a field +=== Update the mapping of a field You can't change the mapping of an existing field, with the following exceptions: From 41bd30780d082410519dbbb25b078dafbbb827b3 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Fri, 16 Aug 2019 16:43:08 -0400 Subject: [PATCH 4/5] Add include for put field mapping exceptions --- docs/reference/indices/put-mapping.asciidoc | 21 ++++++++++++++++----- docs/reference/mapping.asciidoc | 16 ++-------------- 2 files changed, 18 insertions(+), 19 deletions(-) diff --git a/docs/reference/indices/put-mapping.asciidoc b/docs/reference/indices/put-mapping.asciidoc index d5d73f8fc3f23..4cd537cd12539 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::field-mapping-exceptions For example: diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index e5e37477da7c3..123c822fafc78 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -130,7 +130,7 @@ with an explicit mapping. [source,js] ---- -PUT my-index +PUT /my-index { "mappings": { "properties": { @@ -177,19 +177,7 @@ PUT /my-index/_mapping [[update-mapping]] === Update the mapping of a field -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. +include::docs/reference/indices/put-mapping.asciidoc[tag=put-field-mapping-exceptions] [float] [[view-mapping]] From ac0e5c8c2762fd9c9794085c8f8867f0f37effa4 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Fri, 16 Aug 2019 16:58:52 -0400 Subject: [PATCH 5/5] Fix include syntax --- docs/reference/indices/put-mapping.asciidoc | 4 ++-- docs/reference/mapping.asciidoc | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/indices/put-mapping.asciidoc b/docs/reference/indices/put-mapping.asciidoc index 4cd537cd12539..d5edfe51be81a 100644 --- a/docs/reference/indices/put-mapping.asciidoc +++ b/docs/reference/indices/put-mapping.asciidoc @@ -57,7 +57,7 @@ PUT /twitter-1,twitter-2/_mapping <1> [float] ==== Updating field mappings -// tag::put-field-mapping-exceptions +// tag::put-field-mapping-exceptions[] You can't change the mapping of an existing field, with the following exceptions: @@ -73,7 +73,7 @@ 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::field-mapping-exceptions +// end::put-field-mapping-exceptions[] For example: diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index 123c822fafc78..b5d2e6ae37a73 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -177,7 +177,7 @@ PUT /my-index/_mapping [[update-mapping]] === Update the mapping of a field -include::docs/reference/indices/put-mapping.asciidoc[tag=put-field-mapping-exceptions] +include::{docdir}/indices/put-mapping.asciidoc[tag=put-field-mapping-exceptions] [float] [[view-mapping]]