594 lines
11 KiB
Plaintext
594 lines
11 KiB
Plaintext
[[indices-put-mapping]]
|
|
=== Put mapping API
|
|
++++
|
|
<titleabbrev>Put mapping</titleabbrev>
|
|
++++
|
|
|
|
Adds new fields to an existing data stream or index. You can also use the
|
|
put mapping API to change the search settings of existing fields.
|
|
|
|
For data streams, these changes are applied to all backing indices by default.
|
|
|
|
[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 /<target>/_mapping`
|
|
|
|
`PUT /_mapping`
|
|
|
|
|
|
[[put-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 data streams and indices in a cluster, omit this parameter or use
|
|
`_all` or `*`.
|
|
|
|
|
|
[[put-mapping-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
|
|
+
|
|
Defaults to `false`.
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
|
|
+
|
|
Defaults to `open`.
|
|
|
|
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::{es-repo-dir}/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 data type>>
|
|
* <<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 single target
|
|
|
|
The put mapping API requires an existing data stream or 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 targets
|
|
|
|
The PUT mapping API can be applied to multiple data streams or indices with a single request.
|
|
For example, you can update mappings for the `twitter-1` and `twitter-2` indices 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.
|
|
|
|
|
|
[[add-new-field-to-object]]
|
|
===== Add new properties to an existing object field
|
|
|
|
You can use the put mapping API
|
|
to add new properties
|
|
to an existing <<object,`object`>> field.
|
|
To see how this works,
|
|
try the following example.
|
|
|
|
Use the <<indices-create-index,create index>> API
|
|
to create an index
|
|
with the `name` object field
|
|
and an inner `first` text field.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /my_index
|
|
{
|
|
"mappings": {
|
|
"properties": {
|
|
"name": {
|
|
"properties": {
|
|
"first": {
|
|
"type": "text"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
Use the put mapping API
|
|
to add a new inner `last` text field
|
|
to the `name` field.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /my_index/_mapping
|
|
{
|
|
"properties": {
|
|
"name": {
|
|
"properties": {
|
|
"last": {
|
|
"type": "text"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
|
|
Use the <<indices-get-mapping,get mapping>> API
|
|
to verify your changes.
|
|
|
|
[source,console]
|
|
----
|
|
GET /my_index/_mapping
|
|
----
|
|
// TEST[continued]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"my_index" : {
|
|
"mappings" : {
|
|
"properties" : {
|
|
"name" : {
|
|
"properties" : {
|
|
"first" : {
|
|
"type" : "text"
|
|
},
|
|
"last" : {
|
|
"type" : "text"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
|
|
[[add-multi-fields-existing-field-ex]]
|
|
===== Add multi-fields to an existing field
|
|
|
|
<<multi-fields,Multi-fields>>
|
|
let you index the same field
|
|
in different ways.
|
|
You can use the put mapping API
|
|
to update the `fields` mapping parameter
|
|
and enable multi-fields for an existing field.
|
|
|
|
To see how this works,
|
|
try the following example.
|
|
|
|
Use the <<indices-create-index,create index>> API
|
|
to create an index
|
|
with the `city` <<text,text>> field.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /my_index
|
|
{
|
|
"mappings": {
|
|
"properties": {
|
|
"city": {
|
|
"type": "text"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
While text fields work well for full-text search,
|
|
<<keyword,keyword>> fields are not analyzed
|
|
and may work better for sorting or aggregations.
|
|
|
|
Use the put mapping API
|
|
to enable a multi-field for the `city` field.
|
|
This request adds the `city.raw` keyword multi-field,
|
|
which can be used for sorting.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /my_index/_mapping
|
|
{
|
|
"properties": {
|
|
"city": {
|
|
"type": "text",
|
|
"fields": {
|
|
"raw": {
|
|
"type": "keyword"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
|
|
Use the <<indices-get-mapping,get mapping>> API
|
|
to verify your changes.
|
|
|
|
[source,console]
|
|
----
|
|
GET /my_index/_mapping
|
|
----
|
|
// TEST[continued]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"my_index" : {
|
|
"mappings" : {
|
|
"properties" : {
|
|
"city" : {
|
|
"type" : "text",
|
|
"fields" : {
|
|
"raw" : {
|
|
"type" : "keyword"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
|
|
[[change-existing-mapping-parms]]
|
|
===== Change supported mapping parameters for an existing field
|
|
|
|
The documentation for each <<mapping-params,mapping parameter>>
|
|
indicates whether you can update it
|
|
for an existing field
|
|
using the put mapping API.
|
|
For example,
|
|
you can use the put mapping API
|
|
to update the <<ignore-above,`ignore_above`>> parameter.
|
|
|
|
To see how this works,
|
|
try the following example.
|
|
|
|
Use the <<indices-create-index,create index>> API to create an index
|
|
containing a `user_id` keyword field.
|
|
The `user_id` field
|
|
has an `ignore_above` parameter value
|
|
of `20`.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /my_index
|
|
{
|
|
"mappings": {
|
|
"properties": {
|
|
"user_id": {
|
|
"type": "keyword",
|
|
"ignore_above": 20
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
Use the put mapping API
|
|
to change the `ignore_above` parameter value
|
|
to `100`.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /my_index/_mapping
|
|
{
|
|
"properties": {
|
|
"user_id": {
|
|
"type": "keyword",
|
|
"ignore_above": 100
|
|
}
|
|
}
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
|
|
Use the <<indices-get-mapping,get mapping>> API
|
|
to verify your changes.
|
|
|
|
[source,console]
|
|
----
|
|
GET /my_index/_mapping
|
|
----
|
|
// TEST[continued]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"my_index" : {
|
|
"mappings" : {
|
|
"properties" : {
|
|
"user_id" : {
|
|
"type" : "keyword",
|
|
"ignore_above" : 100
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
|
|
[[updating-field-mappings]]
|
|
===== Change the mapping of an existing field
|
|
|
|
// tag::change-field-mapping[]
|
|
Except for supported <<mapping-params,mapping parameters>>,
|
|
you can't change the mapping or field type of an existing field.
|
|
Changing an existing field could invalidate data that's already indexed.
|
|
|
|
If you need to change the mapping of a field in a data stream's backing indices,
|
|
see <<data-streams-change-mappings-and-settings>>.
|
|
|
|
If you need to change the mapping of a field in other indices,
|
|
create a new index with the correct mapping
|
|
and <<docs-reindex,reindex>> your data into that index.
|
|
// end::change-field-mapping[]
|
|
|
|
To see how you can change the mapping of an existing field in an index,
|
|
try the following example.
|
|
|
|
Use the <<indices-create-index,create index>> API
|
|
to create the `users` index
|
|
with the `user_id` field
|
|
with the <<number,`long`>> field type.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /users
|
|
{
|
|
"mappings" : {
|
|
"properties": {
|
|
"user_id": {
|
|
"type": "long"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
Use the <<docs-index_,index>> API
|
|
to index several documents
|
|
with `user_id` field values.
|
|
|
|
[source,console]
|
|
----
|
|
POST /users/_doc?refresh=wait_for
|
|
{
|
|
"user_id" : 12345
|
|
}
|
|
|
|
POST /users/_doc?refresh=wait_for
|
|
{
|
|
"user_id" : 12346
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
|
|
To change the `user_id` field
|
|
to the <<keyword,`keyword`>> field type,
|
|
use the create index API
|
|
to create the `new_users` index with the correct mapping.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /new_users
|
|
{
|
|
"mappings" : {
|
|
"properties": {
|
|
"user_id": {
|
|
"type": "keyword"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
|
|
Use the <<docs-reindex,reindex>> API
|
|
to copy documents from the `users` index
|
|
to the `new_users` index.
|
|
|
|
[source,console]
|
|
----
|
|
POST /_reindex
|
|
{
|
|
"source": {
|
|
"index": "users"
|
|
},
|
|
"dest": {
|
|
"index": "new_users"
|
|
}
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"took": 147,
|
|
"timed_out": false,
|
|
"total": 2,
|
|
"updated": 0,
|
|
"created": 2,
|
|
"deleted": 0,
|
|
"batches": 1,
|
|
"version_conflicts": 0,
|
|
"noops": 0,
|
|
"retries": {
|
|
"bulk": 0,
|
|
"search": 0
|
|
},
|
|
"throttled_millis": 0,
|
|
"requests_per_second": -1.0,
|
|
"throttled_until_millis": 0,
|
|
"failures" : [ ]
|
|
}
|
|
----
|
|
// TESTRESPONSE[s/"took": 147/"took": "$body.took"/]
|
|
|
|
|
|
[[rename-existing-field]]
|
|
===== Rename a field
|
|
|
|
// tag::rename-field[]
|
|
Renaming a field would invalidate data already indexed under the old field name.
|
|
Instead, add an <<alias, `alias`>> field to create an alternate field name.
|
|
// end::rename-field[]
|
|
|
|
For example,
|
|
use the <<indices-create-index,create index>> API
|
|
to create an index
|
|
with the `user_identifier` field.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /my_index
|
|
{
|
|
"mappings": {
|
|
"properties": {
|
|
"user_identifier": {
|
|
"type": "keyword"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|
|
|
|
Use the put mapping API to add the `user_id` field alias
|
|
for the existing `user_identifier` field.
|
|
|
|
[source,console]
|
|
----
|
|
PUT /my_index/_mapping
|
|
{
|
|
"properties": {
|
|
"user_id": {
|
|
"type": "alias",
|
|
"path": "user_identifier"
|
|
}
|
|
}
|
|
}
|
|
----
|
|
// TEST[continued]
|
|
|
|
Use the <<indices-get-mapping,get mapping>> API
|
|
to verify your changes.
|
|
|
|
[source,console]
|
|
----
|
|
GET /my_index/_mapping
|
|
----
|
|
// TEST[continued]
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"my_index" : {
|
|
"mappings" : {
|
|
"properties" : {
|
|
"user_id" : {
|
|
"type" : "alias",
|
|
"path" : "user_identifier"
|
|
},
|
|
"user_identifier" : {
|
|
"type" : "keyword"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
----
|