Get field mapping API
Retrieves 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 complete mapping or if an index mapping contains a large number of fields.
GET /my-index-000001/_mapping/field/user
Request
GET /_mapping/field/<field>
GET /<target>/_mapping/field/<field>
Path parameters
<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.
Query parameters
allow_no_indices
(Optional, boolean) If true
, the request does not return an error if a wildcard expression or _all
value retrieves only missing or closed indices.
This parameter also applies to index aliases that point to a missing or closed index.
Defaults to true
.
expand_wildcards
(Optional, string) Controls what kind of indices that wildcard expressions can expand to. Multiple values are accepted when separated by a comma, as in open,hidden
. Valid values are:
all
Expand to open and closed indices, including hidden indices.
open
Expand only to open indices.
closed
Expand only to closed indices.
hidden
Expansion of wildcards will include hidden indices. Must be combined with
open
,closed
, or both.none
Wildcard expressions are not accepted.
include_type_name
[7.0.0] Deprecated in 7.0.0. Mapping types have been deprecated. See Removal of mapping types. (Optional, boolean) If true
, a mapping type is expected in the body of mappings. Defaults to false
.
ignore_unavailable
(Optional, boolean) If true
, missing or closed indices are not included in the response. Defaults to false
.
include_defaults
(Optional, boolean) If true
, the response includes default mapping values. Defaults to false
.
local
[7.8.0] Deprecated in 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.
Examples
Example with index setup
You can provide field mappings when creating a new index. The following create index API request creates the publications
index with several field mappings.
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:
GET publications/_mapping/field/title
The API returns the following response:
{
"publications": {
"mappings": {
"title": {
"full_name": "title",
"mapping": {
"title": {
"type": "text"
}
}
}
}
}
}
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
.
GET publications/_mapping/field/author.id,abstract,name
returns:
{
"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.
GET publications/_mapping/field/a*
returns:
{
"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"
}
}
}
}
}
}
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
.
GET /my-index-000001,my-index-000002/_mapping/field/message
The following request retrieves mappings for the message
and user.id
fields in any data stream or index in the cluster.
GET /_all/_mapping/field/message
The following request retrieves mappings for fields with an id
property in any data stream or index in the cluster.
GET /_all/_mapping/field/*.id