Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCS] Rewrite get mapping API docs to use new format #44085

Closed
wants to merge 12 commits into from
Closed

[DOCS] Rewrite get mapping API docs to use new format #44085

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
44307d0
[DOCS] Rewrite get mapping API to use new API reference format
jrodewig Jul 8, 2019
91a8e96
Add TESTSETUP comment
jrodewig Jul 9, 2019
0f50a5a
Change "field mapping information" to "mapping definitions"
jrodewig Jul 10, 2019
406149e
Move examples to top of page
jrodewig Jul 10, 2019
0d55000
Move type deprecation note closer to top of page
jrodewig Jul 10, 2019
4e01d52
Switch variable syntax from <variable> to {variable}
jrodewig Jul 10, 2019
f676309
Move multi-index parameters to separate file
jrodewig Jul 10, 2019
c955d35
Remove redundant note
jrodewig Jul 10, 2019
2dcd6c5
Move optional/required indicators
jrodewig Jul 10, 2019
7ddb2ad
Update parameter format
jrodewig Jul 31, 2019
7b64b80
Merge branch 'master' into get-mapping
jrodewig Jul 31, 2019
6804de1
Update parameter format for multi-index params
jrodewig Jul 31, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 78 additions & 33 deletions docs/reference/indices/get-mapping.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,45 +1,90 @@
[[indices-get-mapping]]
== Get Mapping
== Get mapping API
++++
<titleabbrev>Get mapping</titleabbrev>
++++

The get mapping API allows to retrieve mapping definitions for an index or
index/type.
Returns field mapping information for an index.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be nice to continue to refer to 'mapping definitions' as opposed to 'field mapping information', since this API returns more than just field mappings (for example dynamic_templates).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great point! Changed with 0f50a5a.


[source,js]
--------------------------------------------------
GET /twitter/_mapping
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]
[float]
[[indices-get-mapping-request]]
=== {api-request-title}

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 <<removal-of-types>>.
`GET /<index>/_mapping`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In other documentation and technical communication, I've seen the style GET /{index}/_mapping. I haven't really seen us use angle brackets (a quick code search through *.asciidoc files confirms this trend).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done with 4e01d52. This will also match the current rest spec.


[float]
=== Multiple Indices
[[indices-get-mapping-desc]]
=== {api-description-title}

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:
`host:port/{index}/_mapping` where `{index}` can accept a comma-separated
list of names. To get mappings for all indices you can use `_all` for `{index}`.
The following are some examples:
You can use the get mapping API to retrieve field mapping information for one or
more indices.

[source,js]
--------------------------------------------------
GET /twitter,kimchy/_mapping
--------------------------------------------------
// CONSOLE
// TEST[setup:twitter]
// TEST[s/^/PUT kimchy\nPUT book\n/]
[float]
[[indices-get-mapping-path-params]]
=== {api-path-parms-title}

If you want to get mappings of all indices and types then the following
two examples are equivalent:
`<index>` (Optional)::
+
--
(string) Comma-separated list or wildcard expression of index names for which to
retrieve field mapping information.

[source,js]
--------------------------------------------------
GET /_all/_mapping
You can use a value of `_all` or `*` to retrieve mapping information for all
indices.

If no value is provided, the API retrieves mapping information for all indices.
--

[float]
[[indices-get-mapping-query-params]]
=== {api-query-parms-title}

`allow_no_indices` (Optional)::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we link to the documentation on multiple indices (https://www.elastic.co/guide/en/elasticsearch/reference/current/multi-index.html), instead of repeating this information in every API reference?

Copy link
Contributor Author

@jrodewig jrodewig Jul 10, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there is some value in listing the parameters here rather than directing people to a separate page.

As a compromise, I moved these parameters to a separate file and included them with
f676309. That way we can edit and reuse them from a single source but still make the content available everywhere.

Let me know if you think that works. I can also add an indicator that this is a rarely used or expert parameter if wanted.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That seems like a good compromise to me, it will make the information easier to keep in sync.

(boolean) Indicates whether the operation is skipped if a wildcard expression
matches no indices. Defaults to `false`.

GET /_mapping
--------------------------------------------------
`expand_wildcards` (Optional)::
+
--
(string) Indicates whether wildcard expressions should expand to
<<indices-open-close, open or closed indices>>. Possible values are:

* `open` (Default)
* `closed`
* `none`
* `all`
--

`ignore_unavailable` (Optional)::
(boolean) Indicates whether unavailable indices are skipped. Defaults to
`false`.

`include_type_name` (Optional)::
+
--
(boolean) Indicates whether the type name is included in the response. Defaults
to `false`.

NOTE: Before 7.0.0, the 'mappings' definition used to include a type name.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's important for this note to remain near the top of the page. In 7.0 we removed types from all APIs, which was a breaking change to several core, long-standing APIs. Having the note at the top of the page allows users to quickly debug the situation once they run into the change -- I'm not sure most users will benefit from the note when it's in this subsection.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree. Fixed with 0d55000.

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 <<removal-of-types>>.
--

`local` (Optional)::
(boolean) Indicates whether only local node information is included in the
response. Defaults to `false`. If `true`, state information is not retrieved
from the master node.

include::{docdir}/rest-api/timeoutparms.asciidoc[tag=master_timeout]

[float]
[[indices-get-mapping-example]]
=== {api-example-title}

[source,js]
----
GET /twitter/_mapping
----
// CONSOLE
// TEST[setup:twitter]
// TEST[setup:twitter]
2 changes: 2 additions & 0 deletions docs/reference/rest-api/timeoutparms.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,10 @@
returns an error. Defaults to `30s`. For more information about
time units, see <<time-units>>.

// tag::master_timeout[]
`master_timeout`::
(time units) Specifies the period of time to wait for a connection to the
master node. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to `30s`. For more information about
time units, see <<time-units>>.
// end::master_timeout[]