From 3318c91fea31557ccade4d515d8d2324a0345582 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Wed, 21 Aug 2019 09:42:10 -0400 Subject: [PATCH] [DOCS] Reformat get mapping API. Reformat and reuse multi-index params. (#45699) --- docs/reference/api-conventions.asciidoc | 28 ++--------- docs/reference/indices/get-mapping.asciidoc | 50 ++++++++++++++++--- docs/reference/rest-api/common-parms.asciidoc | 42 ++++++++++++++++ 3 files changed, 89 insertions(+), 31 deletions(-) diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc index fdc053058d3..6a75df02c5f 100644 --- a/docs/reference/api-conventions.asciidoc +++ b/docs/reference/api-conventions.asciidoc @@ -21,33 +21,11 @@ ability to "exclude" (`-`), for example: `test*,-test3`. All multi index APIs support the following url query string parameters: -[horizontal] -`ignore_unavailable`:: +include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable] -Controls whether to ignore if any specified indices are unavailable, -including indices that don't exist or closed indices. Either `true` or `false` -can be specified. +include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices] -`allow_no_indices`:: - -Controls whether to fail if a wildcard indices expression results in no -concrete indices. Either `true` or `false` can be specified. For example if -the wildcard expression `foo*` is specified and no indices are available that -start with `foo`, then depending on this setting the request will fail. This -setting is also applicable when `_all`, `*`, or no index has been specified. This -settings also applies for aliases, in case an alias points to a closed index. - -`expand_wildcards`:: - -Controls what kind of concrete indices that wildcard indices expressions can expand -to. If `open` is specified then the wildcard expression is expanded to only -open indices. If `closed` is specified then the wildcard expression is -expanded only to closed indices. Also both values (`open,closed`) can be -specified to expand to all indices. -+ -If `none` is specified then wildcard expansion will be disabled. If `all` -is specified, wildcard expressions will expand to all indices (this is equivalent -to specifying `open,closed`). +include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards] The defaults settings for the above parameters depend on the API being used. diff --git a/docs/reference/indices/get-mapping.asciidoc b/docs/reference/indices/get-mapping.asciidoc index 69d4bb62233..ea96327bb3a 100644 --- a/docs/reference/indices/get-mapping.asciidoc +++ b/docs/reference/indices/get-mapping.asciidoc @@ -1,8 +1,10 @@ [[indices-get-mapping]] -=== Get Mapping +=== Get mapping API +++++ +Get mapping +++++ -The get mapping API allows to retrieve mapping definitions for an index or -index/type. +Retrieves <> for indices in a cluster. [source,js] -------------------------------------------------- @@ -13,10 +15,46 @@ GET /twitter/_mapping NOTE: Before 7.0.0, the 'mappings' definition used to include a type name. Although mappings in responses no longer contain a type name by default, you can still request the old format -through the parameter include_type_name. For more details, please see <>. +through the parameter `include_type_name`. For more details, please see <>. -[float] -==== Multiple Indices + +[[get-mapping-api-request]] +==== {api-request-title} + +`GET /_mapping` + +`GET /{index}/_mapping` + + +[[get-mapping-api-path-params]] +==== {api-path-parms-title} + +include::{docdir}/rest-api/common-parms.asciidoc[tag=index] + + +[[get-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=local] + +include::{docdir}/rest-api/common-parms.asciidoc[tag=master-timeout] + + +[[get-mapping-api-example]] +==== {api-examples-title} + +[[get-mapping-api-multi-ex]] +===== Multiple indices The get mapping API can be used to get more than one index with a single call. General usage of the API follows the following syntax: diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc index 84e4c57e99f..f7927df3217 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -1,9 +1,38 @@ +tag::allow-no-indices[] +`allow_no_indices`:: +(Optional, boolean) If `true`, the request returns an error if a wildcard +expression or `_all` value retrieves only missing or closed indices. This +parameter also applies to <> that point to a +missing or closed index. +end::allow-no-indices[] + tag::bytes[] `bytes`:: (Optional, <>) Unit used to display byte values. end::bytes[] +tag::expand-wildcards[] +`expand_wildcards`:: ++ +-- +(Optional, string) Controls what kind of indices that wildcard +expressions can expand to. Valid values are: + +`all`:: +Expand to open and closed indices. + +`open`:: +Expand only to open indices. + +`closed`:: +Expand only to closed indices. + +`none`:: +Wildcard expressions are not accepted. +-- +end::expand-wildcards[] + tag::cat-h[] `h`:: (Optional, string) Comma-separated list of column names to display. @@ -28,6 +57,19 @@ https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html[HTTP accept header]. Valid values include JSON, YAML, etc. end::http-format[] +tag::include-type-name[] +`include_type_name`:: +deprecated:[7.0.0, Mapping types have been deprecated. See <>.] +(Optional, boolean) If `true`, a mapping type is expected in the body of +mappings. Defaults to `false`. +end::include-type-name[] + +tag::index-ignore-unavailable[] +`ignore_unavailable`:: +(Optional, boolean) If `true`, missing or closed indices are not included in the +response. Defaults to `false`. +end::index-ignore-unavailable[] + tag::include-unloaded-segments[] `include_unloaded_segments`:: (Optional, boolean) If `true`, the response includes information from segments