From 8f5490b102066c0a833315441acbcceece62f1d6 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 19 Aug 2019 15:13:03 -0400 Subject: [PATCH 1/3] [DOCS] Reformat put mapping API docs --- docs/reference/indices/put-mapping.asciidoc | 163 ++++++++++++++------ docs/reference/mapping.asciidoc | 1 + 2 files changed, 121 insertions(+), 43 deletions(-) diff --git a/docs/reference/indices/put-mapping.asciidoc b/docs/reference/indices/put-mapping.asciidoc index d5edfe51be81a..4351ca3097549 100644 --- a/docs/reference/indices/put-mapping.asciidoc +++ b/docs/reference/indices/put-mapping.asciidoc @@ -1,14 +1,15 @@ [[indices-put-mapping]] -=== Put Mapping +=== Put mapping API +++++ +Put mapping +++++ -The PUT mapping API allows you to add fields to an existing index or to change search only settings of existing fields. +Adds new fields to an existing index or changes the search settings of existing +fields. [source,js] --------------------------------------------------- -PUT twitter <1> -{} - -PUT twitter/_mapping <2> +---- +PUT /twitter/_mapping { "properties": { "email": { @@ -16,19 +17,116 @@ PUT twitter/_mapping <2> } } } --------------------------------------------------- +---- +// CONSOLE +// TEST[setup:twitter] + +NOTE: Before 7.0.0, the 'mappings' definition used to include a type name. +Although specifying types in requests is now deprecated, a type can still be +provided if the request parameter `include_type_name` is set. For more details, +please see <>. + + +[[put-mapping-api-request]] +==== {api-request-title} + +`PUT /{index}/_mapping` + +`PUT /_mapping` + + +[[put-mapping-api-desc]] +==== {api-description-title} + +You can use the put mapping API to add fields to an existing index or to change +the search settings of existing fields. + +[[updating-field-mappings]] +===== Restrictions for existing fields + +In general, the mapping for existing fields cannot be updated. There are some +exceptions to this rule. For instance: + +* new <> can be added to <> fields. +* new <> can be added to existing fields. +* the <> parameter can be updated. + + +[[put-mapping-api-path-params]] +==== {api-path-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index] ++ +To update the mapping of all indices, omit this parameter or use a value of +`_all`. + + +[[put-mapping-api-query-params]] +==== {api-query-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards] ++ +Defaults to `open`. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=include-type-name] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=timeoutparms] + + +[[put-mapping-api-request-body]] +==== {api-request-body-title} + +`properties`:: ++ +-- +(Required, <>) Mapping for a field. For new +fields, this mapping can include: + +* Field name +* <> +* <> + +For existing fields, see <>. +-- + + +[[put-mapping-api-example]] +==== {api-examples-title} + +[[put-field-mapping-api-basic-ex]] +===== Example with index setup + +The put mapping API requires an existing index. The following +<> API request creates the `publications` +index with no mapping. + +[source,js] +---- +PUT /publications +---- // CONSOLE -<1> <> called `twitter` without any mapping. -<2> Uses the PUT mapping API to add a new field called `email`. -More information on how to define mappings can be found in the <> section. +The following put mapping API request adds `title`, a new <> field, +to the `publications` index. -NOTE: Before 7.0.0, the 'mappings' definition used to include a type name. Although specifying -types in requests is now deprecated, a type can still be provided if the request parameter -include_type_name is set. For more details, please see <>. +[source,js] +---- +PUT /publications/_mapping +{ + "properties": { + "title": { "type": "text"} + } +} +---- +// CONSOLE +// TEST[continued] -[float] -==== Multi-index +[[put-mapping-api-multi-ex]] +===== Multiple indices The PUT mapping API can be applied to multiple indices with a single request. For example, we can update the `twitter-1` and `twitter-2` mappings at the same time: @@ -36,8 +134,8 @@ For example, we can update the `twitter-1` and `twitter-2` mappings at the same [source,js] -------------------------------------------------- # Create the two indices -PUT twitter-1 -PUT twitter-2 +PUT /twitter-1 +PUT /twitter-2 # Update both mappings PUT /twitter-1,twitter-2/_mapping <1> @@ -50,36 +148,15 @@ PUT /twitter-1,twitter-2/_mapping <1> } -------------------------------------------------- // CONSOLE -<1> Note that the indices specified (`twitter-1,twitter-2`) follows <> and wildcard format. - +// TEST[setup:twitter] -[[updating-field-mappings]] -[float] -==== Updating field mappings - -// tag::put-field-mapping-exceptions[] - -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[] +<1> Note that the indices specified (`twitter-1,twitter-2`) follows <> and wildcard format. For example: [source,js] ----------------------------------- -PUT my_index <1> +PUT /my_index <1> { "mappings": { "properties": { @@ -97,7 +174,7 @@ PUT my_index <1> } } -PUT my_index/_mapping +PUT /my_index/_mapping { "properties": { "name": { diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index b5d2e6ae37a73..de6951f967083 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -38,6 +38,7 @@ document. [float] +[[field-datatypes]] == Field datatypes Each field has a data `type` which can be: From aad4cd24b3a51941378b17a6ba0582fd98a1bb4b Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 21 Aug 2019 10:50:08 -0400 Subject: [PATCH 2/3] Re-add field mapping exceptions tag --- docs/reference/indices/put-mapping.asciidoc | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/docs/reference/indices/put-mapping.asciidoc b/docs/reference/indices/put-mapping.asciidoc index 4351ca3097549..968bbd6d416c4 100644 --- a/docs/reference/indices/put-mapping.asciidoc +++ b/docs/reference/indices/put-mapping.asciidoc @@ -44,12 +44,23 @@ the search settings of existing fields. [[updating-field-mappings]] ===== Restrictions for existing fields -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[] [[put-mapping-api-path-params]] From 35e9d8260e700c6f30eac8f51ff7e2a58c8090dc Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Thu, 22 Aug 2019 08:34:38 -0400 Subject: [PATCH 3/3] Relocaate existing field info --- docs/reference/indices/put-mapping.asciidoc | 49 +++++++++------------ 1 file changed, 21 insertions(+), 28 deletions(-) diff --git a/docs/reference/indices/put-mapping.asciidoc b/docs/reference/indices/put-mapping.asciidoc index 968bbd6d416c4..a47f417d6a219 100644 --- a/docs/reference/indices/put-mapping.asciidoc +++ b/docs/reference/indices/put-mapping.asciidoc @@ -35,34 +35,6 @@ please see <>. `PUT /_mapping` -[[put-mapping-api-desc]] -==== {api-description-title} - -You can use the put mapping API to add fields to an existing index or to change -the search settings of existing fields. - -[[updating-field-mappings]] -===== Restrictions for existing fields - -// tag::put-field-mapping-exceptions[] - -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[] - - [[put-mapping-api-path-params]] ==== {api-path-parms-title} @@ -163,6 +135,27 @@ 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[] + +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: [source,js]