Put mapping API
editPut mapping API
editAdds new fields to an existing index or changes the search settings of existing fields.
PUT /twitter/_mapping { "properties": { "email": { "type": "keyword" } } }
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 mapping types.
Path parameters
edit-
<index>
-
(Optional, string) Comma-separated list or wildcard expression of index names used to limit the request.
To update the mapping of all indices, omit this parameter or use a value of
_all
.
Query parameters
edit-
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.
-
expand_wildcards
-
(Optional, string) Controls what kind of indices that wildcard expressions can expand to. Valid values are:
-
all
- Expand to open and closed indices.
-
open
- Expand only to open indices.
-
closed
- Expand only to closed indices.
-
none
- Wildcard expressions are not accepted.
Defaults to
open
. -
-
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 tofalse
. -
ignore_unavailable
-
(Optional, boolean) If
true
, missing or closed indices are not included in the response. Defaults tofalse
. -
timeout
-
(Optional, time units) Specifies the period of time to wait for
a response. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to
30s
. -
master_timeout
-
(Optional, 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
.
Request body
edit-
properties
-
(Required, mapping object) Mapping for a field. For new fields, this mapping can include:
- Field name
- Field datatype
- Mapping parameters
For existing fields, see Update an existing field.
Examples
editExample with index setup
editThe put mapping API requires an existing index. The following
create index API request creates the publications
index with no mapping.
PUT /publications
The following put mapping API request adds title
, a new text
field,
to the publications
index.
PUT /publications/_mapping { "properties": { "title": { "type": "text"} } }
Multiple indices
editThe 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:
# Create the two indices PUT /twitter-1 PUT /twitter-2 # Update both mappings PUT /twitter-1,twitter-2/_mapping { "properties": { "user_name": { "type": "text" } } }
Note that the indices specified ( |
Update an existing field
editYou can’t change the mapping of an existing field, with the following exceptions:
-
You can add new properties to an
object
field. -
You can use the
field
mapping parameter to enable multi-fields. -
You can change the value of the
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 reindex your data into that index. If
you only want to rename a field, consider adding an alias
field.
For example:
PUT /my_index { "mappings": { "properties": { "name": { "properties": { "first": { "type": "text" } } }, "user_id": { "type": "keyword" } } } } PUT /my_index/_mapping { "properties": { "name": { "properties": { "last": { "type": "text" } } }, "user_id": { "type": "keyword", "ignore_above": 100 } } }
Create an index with a |
|
Add a |
|
Update the |
Each mapping parameter specifies whether or not its setting can be updated on an existing field.