253 lines
6.5 KiB
Plaintext
253 lines
6.5 KiB
Plaintext
[[indices-get-field-mapping]]
|
|
=== Get field mapping API
|
|
++++
|
|
<titleabbrev>Get field mapping</titleabbrev>
|
|
++++
|
|
|
|
Retrieves <<mapping,mapping definitions>> for one or more fields. For data
|
|
streams, the API retrieves field mappings for the stream's backing indices.
|
|
|
|
This API is useful if you don't need a <<indices-get-mapping,complete mapping>>
|
|
or if an index mapping contains a large number of fields.
|
|
|
|
[source,console]
|
|
----
|
|
GET /my-index-000001/_mapping/field/user
|
|
----
|
|
// TEST[setup:my_index]
|
|
|
|
|
|
[[get-field-mapping-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`GET /_mapping/field/<field>`
|
|
|
|
`GET /<target>/_mapping/field/<field>`
|
|
|
|
|
|
[[get-field-mapping-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<target>`::
|
|
(Optional, string)
|
|
Comma-separated list of data streams, indices, and index aliases used to limit
|
|
the request. Wildcard (`*`) expressions are supported.
|
|
+
|
|
To target all indices in a cluster, omit this parameter or use `_all` or `*`.
|
|
|
|
`<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::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
|
|
+
|
|
Defaults to `true`.
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=include-type-name]
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
|
|
|
|
`include_defaults`::
|
|
(Optional, boolean) If `true`, the response includes default mapping values.
|
|
Defaults to `false`.
|
|
|
|
`local`::
|
|
deprecated:[7.8.0, This parameter is a no-op and field mappings are always retrieved locally]
|
|
(Optional, boolean) If `true`, the request retrieves information from the local
|
|
node only. Defaults to `false`, which means information is retrieved from
|
|
the master node.
|
|
|
|
|
|
[[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
|
|
<<indices-create-index, create index>> API request creates the `publications`
|
|
index with several field mappings.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /publications
|
|
{
|
|
"mappings": {
|
|
"properties": {
|
|
"id": { "type": "text" },
|
|
"title": { "type": "text" },
|
|
"abstract": { "type": "text" },
|
|
"author": {
|
|
"properties": {
|
|
"id": { "type": "text" },
|
|
"name": { "type": "text" }
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
The following returns the mapping of the field `title` only:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET publications/_mapping/field/title
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"publications": {
|
|
"mappings": {
|
|
"title": {
|
|
"full_name": "title",
|
|
"mapping": {
|
|
"title": {
|
|
"type": "text"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[[get-field-mapping-api-specific-fields-ex]]
|
|
===== Specifying fields
|
|
|
|
The get mapping API allows you to specify a comma-separated list of fields.
|
|
|
|
For instance to select the `id` of the `author` field, you must use its full name `author.id`.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET publications/_mapping/field/author.id,abstract,name
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
returns:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"publications": {
|
|
"mappings": {
|
|
"author.id": {
|
|
"full_name": "author.id",
|
|
"mapping": {
|
|
"id": {
|
|
"type": "text"
|
|
}
|
|
}
|
|
},
|
|
"abstract": {
|
|
"full_name": "abstract",
|
|
"mapping": {
|
|
"abstract": {
|
|
"type": "text"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
The get field mapping API also supports wildcard notation.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET publications/_mapping/field/a*
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
returns:
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"publications": {
|
|
"mappings": {
|
|
"author.name": {
|
|
"full_name": "author.name",
|
|
"mapping": {
|
|
"name": {
|
|
"type": "text"
|
|
}
|
|
}
|
|
},
|
|
"abstract": {
|
|
"full_name": "abstract",
|
|
"mapping": {
|
|
"abstract": {
|
|
"type": "text"
|
|
}
|
|
}
|
|
},
|
|
"author.id": {
|
|
"full_name": "author.id",
|
|
"mapping": {
|
|
"id": {
|
|
"type": "text"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
[[get-field-mapping-api-multi-index-ex]]
|
|
===== Multiple targets and fields
|
|
|
|
The get field mapping API can be used to get mappings for multiple fields from
|
|
multiple data streams or indices with a single request.
|
|
|
|
The `<target>` and `<field>` request path parameters both support
|
|
comma-separated lists and wildcard expressions.
|
|
|
|
You can omit the `<target>` parameter or use a value of `*` or `_all` to target
|
|
all data streams and indices in a cluster.
|
|
|
|
Similarly, you can omit the `<field>` parameter or use a value of `*` to
|
|
retrieve mappings for all fields in the targeted data streams or indices.
|
|
However, the `<field>` parameter does not support the `_all` value.
|
|
|
|
For example, the following request retrieves mappings for the `message` field in
|
|
any data stream or index named `my-index-000001` or `my-index-000002`.
|
|
|
|
[source,console]
|
|
----
|
|
GET /my-index-000001,my-index-000002/_mapping/field/message
|
|
----
|
|
// TEST[setup:my_index]
|
|
// TEST[s/^/PUT my-index-000002\n/]
|
|
|
|
The following request retrieves mappings for the `message` and `user.id` fields
|
|
in any data stream or index in the cluster.
|
|
|
|
[source,console]
|
|
----
|
|
GET /_all/_mapping/field/message
|
|
----
|
|
// TEST[setup:my_index]
|
|
|
|
The following request retrieves mappings for fields with an `id` property in any
|
|
data stream or index in the cluster.
|
|
|
|
[source,console]
|
|
----
|
|
GET /_all/_mapping/field/*.id
|
|
----
|
|
// TEST[setup:my_index]
|