From 8e350a1196b24b0d97d7adeb32693456b4f94a36 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Sun, 18 Aug 2019 13:27:29 -0400 Subject: [PATCH 1/8] [DOCS] Reformat get field mapping API docs --- .../indices/get-field-mapping.asciidoc | 82 ++++++++++++++----- 1 file changed, 63 insertions(+), 19 deletions(-) diff --git a/docs/reference/indices/get-field-mapping.asciidoc b/docs/reference/indices/get-field-mapping.asciidoc index 2223231436624..2d096d68d6921 100644 --- a/docs/reference/indices/get-field-mapping.asciidoc +++ b/docs/reference/indices/get-field-mapping.asciidoc @@ -1,15 +1,67 @@ [[indices-get-field-mapping]] -=== Get Field Mapping +=== Get field mapping API +++++ +Get field mapping +++++ -The get field mapping API allows you to retrieve mapping definitions for one or more fields. -This is useful when you do not need the complete type mapping returned by -the <> API. +Retrieves <> for one or more fields. This is useful +if you don't need the <> of an index or +your index contains a large number of fields. -For example, consider the following mapping: +[source,js] +---- +GET /twitter/_mapping/field/user +---- +// CONSOLE + + +[[get-field-mapping-api-request]] +==== {api-request-title} + +`GET /_mapping/field/{field}` + +`GET /{index}/_mapping/field/{field}` + + +[[get-field-mapping-api-path-params]] +==== {api-path-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index] + +`{field}`:: +(Optional, string) Comma-separated list or wildcard expression of fields used to +limit returned information. + + +[[get-field-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] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] + +`include_defaults`:: +(Optional, boolean) If `true`, the response includes default mapping values. +Defaults to `false`. + +include::{docdir}/rest-api/common-parms.asciidoc[tag=local] + + +[[get-field-mapping-api-example]] +==== {api-examples-title} + +[[get-field-mapping-api-basic-ex]] +===== Example with index setup + +You can provide field mappings when creating a new index. The following +<> API creates the `publications` index with +several field mappings. [source,js] -------------------------------------------------- -PUT publications +PUT /publications { "mappings": { "properties": { @@ -37,7 +89,7 @@ GET publications/_mapping/field/title -------------------------------------------------- // CONSOLE -For which the response is: +The API returns the following response: [source,js] -------------------------------------------------- @@ -58,8 +110,8 @@ For which the response is: -------------------------------------------------- // TESTRESPONSE -[float] -==== Multiple Indices and Fields +[[get-field-mapping-api-multi-index-ex]] +===== Multiple indices and fields The get field mapping API can be used to get the mapping of multiple fields from more than one index with a single call. General usage of the API follows the @@ -80,8 +132,8 @@ GET /_all/_mapping/field/*.id // TEST[setup:twitter] // TEST[s/^/PUT kimchy\nPUT book\n/] -[float] -==== Specifying fields +[[get-field-mapping-api-specific-fields-ex]] +===== Specifying fields The get mapping api allows you to specify a comma-separated list of fields. @@ -167,11 +219,3 @@ returns: -------------------------------------------------- // TESTRESPONSE -[float] -==== Other options - -[horizontal] -`include_defaults`:: - - adding `include_defaults=true` to the query string will cause the response - to include default values, which are normally suppressed. From d4c1492618ae859b5882d2629d7d66e30f6ee9f1 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 19 Aug 2019 14:37:26 -0400 Subject: [PATCH 2/8] Add missing word --- docs/reference/indices/get-field-mapping.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/indices/get-field-mapping.asciidoc b/docs/reference/indices/get-field-mapping.asciidoc index 2d096d68d6921..a019addbb1249 100644 --- a/docs/reference/indices/get-field-mapping.asciidoc +++ b/docs/reference/indices/get-field-mapping.asciidoc @@ -56,8 +56,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=local] ===== Example with index setup You can provide field mappings when creating a new index. The following -<> API creates the `publications` index with -several field mappings. +<> API request creates the `publications` +index with several field mappings. [source,js] -------------------------------------------------- From 7cf5fc933c5a0af7242960615ec042b67e17e2d4 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 19 Aug 2019 15:07:23 -0400 Subject: [PATCH 3/8] Add `include_type_name` parameter --- docs/reference/indices/get-field-mapping.asciidoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/reference/indices/get-field-mapping.asciidoc b/docs/reference/indices/get-field-mapping.asciidoc index a019addbb1249..daaf4204dfa09 100644 --- a/docs/reference/indices/get-field-mapping.asciidoc +++ b/docs/reference/indices/get-field-mapping.asciidoc @@ -40,6 +40,8 @@ include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices] include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards] +include::{docdir}/rest-api/common-parms.asciidoc[tag=include-type-name] + include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] `include_defaults`:: From 9b36d30f08a243b5fe87c7c0d88362c3f081e2ae Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 21 Aug 2019 10:23:07 -0400 Subject: [PATCH 4/8] Update snippets and reorder examples --- .../indices/get-field-mapping.asciidoc | 48 ++++++++++--------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/docs/reference/indices/get-field-mapping.asciidoc b/docs/reference/indices/get-field-mapping.asciidoc index daaf4204dfa09..5d418d998806c 100644 --- a/docs/reference/indices/get-field-mapping.asciidoc +++ b/docs/reference/indices/get-field-mapping.asciidoc @@ -13,6 +13,7 @@ your index contains a large number of fields. GET /twitter/_mapping/field/user ---- // CONSOLE +// TEST[setup:twitter] [[get-field-mapping-api-request]] @@ -80,7 +81,6 @@ PUT /publications } } -------------------------------------------------- -// TESTSETUP // CONSOLE The following returns the mapping of the field `title` only: @@ -90,6 +90,7 @@ The following returns the mapping of the field `title` only: GET publications/_mapping/field/title -------------------------------------------------- // CONSOLE +// TEST[continued] The API returns the following response: @@ -112,28 +113,6 @@ The API returns the following response: -------------------------------------------------- // TESTRESPONSE -[[get-field-mapping-api-multi-index-ex]] -===== Multiple indices and fields - -The get field mapping API can be used to get the mapping of multiple fields from more than one index -with a single call. General usage of the API follows the -following syntax: `host:port/{index}/_mapping/field/{field}` where -`{index}` and `{field}` can stand for comma-separated list of names or wild cards. To -get mappings for all indices you can use `_all` for `{index}`. The -following are some examples: - -[source,js] --------------------------------------------------- -GET /twitter,kimchy/_mapping/field/message - -GET /_all/_mapping/field/message,user.id - -GET /_all/_mapping/field/*.id --------------------------------------------------- -// CONSOLE -// TEST[setup:twitter] -// TEST[s/^/PUT kimchy\nPUT book\n/] - [[get-field-mapping-api-specific-fields-ex]] ===== Specifying fields @@ -146,6 +125,7 @@ For instance to select the `id` of the `author` field, you must use its full nam GET publications/_mapping/field/author.id,abstract,name -------------------------------------------------- // CONSOLE +// TEST[continued] returns: @@ -183,6 +163,7 @@ The get field mapping API also supports wildcard notation. GET publications/_mapping/field/a* -------------------------------------------------- // CONSOLE +// TEST[continued] returns: @@ -221,3 +202,24 @@ returns: -------------------------------------------------- // TESTRESPONSE +[[get-field-mapping-api-multi-index-ex]] +===== Multiple indices and fields + +The get field mapping API can be used to get the mapping of multiple fields from more than one index +with a single call. General usage of the API follows the +following syntax: `host:port/{index}/_mapping/field/{field}` where +`{index}` and `{field}` can stand for comma-separated list of names or wild cards. To +get mappings for all indices you can use `_all` for `{index}`. The +following are some examples: + +[source,js] +-------------------------------------------------- +GET /twitter,kimchy/_mapping/field/message + +GET /_all/_mapping/field/message,user.id + +GET /_all/_mapping/field/*.id +-------------------------------------------------- +// CONSOLE +// TEST[setup:twitter] +// TEST[s/^/PUT kimchy\nPUT book\n/] \ No newline at end of file From ff21971a34bd71a06112c99ee31521474e130a08 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Fri, 23 Aug 2019 09:57:59 -0400 Subject: [PATCH 5/8] change "{var}" convention to "" --- docs/reference/indices/get-field-mapping.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/indices/get-field-mapping.asciidoc b/docs/reference/indices/get-field-mapping.asciidoc index 5d418d998806c..f66ee1a8dc5f6 100644 --- a/docs/reference/indices/get-field-mapping.asciidoc +++ b/docs/reference/indices/get-field-mapping.asciidoc @@ -19,9 +19,9 @@ GET /twitter/_mapping/field/user [[get-field-mapping-api-request]] ==== {api-request-title} -`GET /_mapping/field/{field}` +`GET /_mapping/field/` -`GET /{index}/_mapping/field/{field}` +`GET //_mapping/field/` [[get-field-mapping-api-path-params]] @@ -29,7 +29,7 @@ GET /twitter/_mapping/field/user include::{docdir}/rest-api/common-parms.asciidoc[tag=index] -`{field}`:: +``:: (Optional, string) Comma-separated list or wildcard expression of fields used to limit returned information. From 5594be8ccaadbe0a996a8ab6f958b8023b1af229 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 26 Aug 2019 09:11:36 -0400 Subject: [PATCH 6/8] Update docs/reference/indices/get-field-mapping.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: István Zoltán Szabó --- docs/reference/indices/get-field-mapping.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/indices/get-field-mapping.asciidoc b/docs/reference/indices/get-field-mapping.asciidoc index f66ee1a8dc5f6..99ed65be841dd 100644 --- a/docs/reference/indices/get-field-mapping.asciidoc +++ b/docs/reference/indices/get-field-mapping.asciidoc @@ -207,7 +207,7 @@ returns: The get field mapping API can be used to get the mapping of multiple fields from more than one index with a single call. General usage of the API follows the -following syntax: `host:port/{index}/_mapping/field/{field}` where +following syntax: `host:port//_mapping/field/` where `{index}` and `{field}` can stand for comma-separated list of names or wild cards. To get mappings for all indices you can use `_all` for `{index}`. The following are some examples: @@ -222,4 +222,4 @@ GET /_all/_mapping/field/*.id -------------------------------------------------- // CONSOLE // TEST[setup:twitter] -// TEST[s/^/PUT kimchy\nPUT book\n/] \ No newline at end of file +// TEST[s/^/PUT kimchy\nPUT book\n/] From 35b237cfb37bf17e8a54d8a86eea4c7251f92750 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 26 Aug 2019 09:11:44 -0400 Subject: [PATCH 7/8] Update docs/reference/indices/get-field-mapping.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: István Zoltán Szabó --- docs/reference/indices/get-field-mapping.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/indices/get-field-mapping.asciidoc b/docs/reference/indices/get-field-mapping.asciidoc index 99ed65be841dd..fa4d385bec7ff 100644 --- a/docs/reference/indices/get-field-mapping.asciidoc +++ b/docs/reference/indices/get-field-mapping.asciidoc @@ -208,7 +208,7 @@ returns: The get field mapping API can be used to get the mapping of multiple fields from more than one index with a single call. General usage of the API follows the following syntax: `host:port//_mapping/field/` where -`{index}` and `{field}` can stand for comma-separated list of names or wild cards. To +`` and `` can stand for comma-separated list of names or wild cards. To get mappings for all indices you can use `_all` for `{index}`. The following are some examples: From cb925262bbc8bfb87effbe1ccd5b9aea97ed567f Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Mon, 26 Aug 2019 09:11:50 -0400 Subject: [PATCH 8/8] Update docs/reference/indices/get-field-mapping.asciidoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: István Zoltán Szabó --- docs/reference/indices/get-field-mapping.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/indices/get-field-mapping.asciidoc b/docs/reference/indices/get-field-mapping.asciidoc index fa4d385bec7ff..9397052b2871b 100644 --- a/docs/reference/indices/get-field-mapping.asciidoc +++ b/docs/reference/indices/get-field-mapping.asciidoc @@ -209,7 +209,7 @@ The get field mapping API can be used to get the mapping of multiple fields from with a single call. General usage of the API follows the following syntax: `host:port//_mapping/field/` where `` and `` can stand for comma-separated list of names or wild cards. To -get mappings for all indices you can use `_all` for `{index}`. The +get mappings for all indices you can use `_all` for ``. The following are some examples: [source,js]