201 lines
4.5 KiB
Plaintext
201 lines
4.5 KiB
Plaintext
[[indices-put-mapping]]
|
|
=== Put mapping API
|
|
++++
|
|
<titleabbrev>Put mapping</titleabbrev>
|
|
++++
|
|
|
|
Adds new fields to an existing index or changes the search settings of existing
|
|
fields.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /twitter/_mapping
|
|
{
|
|
"properties": {
|
|
"email": {
|
|
"type": "keyword"
|
|
}
|
|
}
|
|
}
|
|
----
|
|
// TEST[setup:twitter]
|
|
|
|
NOTE: Before 7.0.0, the 'mappings' definition used to include a type name.
|
|
Although specifying types in requests is now deprecated, a type can still be
|
|
provided if the request parameter `include_type_name` is set. For more details,
|
|
please see <<removal-of-types>>.
|
|
|
|
|
|
[[put-mapping-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT /<index>/_mapping`
|
|
|
|
`PUT /_mapping`
|
|
|
|
|
|
[[put-mapping-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
include::{docdir}/rest-api/common-parms.asciidoc[tag=index]
|
|
+
|
|
To update the mapping of all indices, omit this parameter or use a value of
|
|
`_all`.
|
|
|
|
|
|
[[put-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=timeoutparms]
|
|
|
|
|
|
[[put-mapping-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
`properties`::
|
|
+
|
|
--
|
|
(Required, <<mapping,mapping object>>) Mapping for a field. For new
|
|
fields, this mapping can include:
|
|
|
|
* Field name
|
|
* <<field-datatypes,Field datatype>>
|
|
* <<mapping-params,Mapping parameters>>
|
|
|
|
For existing fields, see <<updating-field-mappings>>.
|
|
--
|
|
|
|
|
|
[[put-mapping-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
[[put-field-mapping-api-basic-ex]]
|
|
===== Example with index setup
|
|
|
|
The put mapping API requires an existing index. The following
|
|
<<indices-create-index, create index>> API request creates the `publications`
|
|
index with no mapping.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /publications
|
|
----
|
|
|
|
The following put mapping API request adds `title`, a new <<text,`text`>> field,
|
|
to the `publications` index.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /publications/_mapping
|
|
{
|
|
"properties": {
|
|
"title": { "type": "text"}
|
|
}
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
|
|
[[put-mapping-api-multi-ex]]
|
|
===== Multiple indices
|
|
|
|
The PUT mapping API can be applied to multiple indices with a single request.
|
|
For example, we can update the `twitter-1` and `twitter-2` mappings at the same time:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
# Create the two indices
|
|
PUT /twitter-1
|
|
PUT /twitter-2
|
|
|
|
# Update both mappings
|
|
PUT /twitter-1,twitter-2/_mapping <1>
|
|
{
|
|
"properties": {
|
|
"user_name": {
|
|
"type": "text"
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[setup:twitter]
|
|
|
|
<1> Note that the indices specified (`twitter-1,twitter-2`) follows <<multi-index,multiple index names>> and wildcard format.
|
|
|
|
[[updating-field-mappings]]
|
|
===== Update an existing field
|
|
|
|
// tag::put-field-mapping-exceptions[]
|
|
|
|
You can't change the mapping of an existing field, with the following
|
|
exceptions:
|
|
|
|
* You can add new <<properties,properties>> to an <<object,`object`>> field.
|
|
* You can use the <<multi-fields,`field`>> mapping parameter to enable
|
|
multi-fields.
|
|
* You can change the value of the <<ignore-above,`ignore_above`>> mapping
|
|
parameter.
|
|
|
|
Changing the mapping of an existing field could invalidate data that's already
|
|
indexed. If you need to change the mapping of a field, create a new index with
|
|
the correct mappings and <<docs-reindex,reindex>> your data into that index. If
|
|
you only want to rename a field, consider adding an <<alias, `alias`>> field.
|
|
|
|
// end::put-field-mapping-exceptions[]
|
|
|
|
For example:
|
|
|
|
[source,console]
|
|
-----------------------------------
|
|
PUT /my_index <1>
|
|
{
|
|
"mappings": {
|
|
"properties": {
|
|
"name": {
|
|
"properties": {
|
|
"first": {
|
|
"type": "text"
|
|
}
|
|
}
|
|
},
|
|
"user_id": {
|
|
"type": "keyword"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
PUT /my_index/_mapping
|
|
{
|
|
"properties": {
|
|
"name": {
|
|
"properties": {
|
|
"last": { <2>
|
|
"type": "text"
|
|
}
|
|
}
|
|
},
|
|
"user_id": {
|
|
"type": "keyword",
|
|
"ignore_above": 100 <3>
|
|
}
|
|
}
|
|
}
|
|
-----------------------------------
|
|
|
|
<1> Create an index with a `first` field under the `name` <<object>> field, and a `user_id` field.
|
|
<2> Add a `last` field under the `name` object field.
|
|
<3> Update the `ignore_above` setting from its default of 0.
|
|
|
|
Each <<mapping-params,mapping parameter>> specifies whether or not its setting
|
|
can be updated on an existing field.
|