[DOCS] Add examples to the mapping docs (#45520)
This commit is contained in:
James Rodewig
parent
4b932519aa
commit
b0ef313817
|
|
@ -57,12 +57,23 @@ PUT /twitter-1,twitter-2/_mapping <1>
|
|||
[float]
|
||||
==== Updating field mappings
|
||||
|
||||
In general, the mapping for existing fields cannot be updated. There are some
|
||||
exceptions to this rule. For instance:
|
||||
// tag::put-field-mapping-exceptions[]
|
||||
|
||||
* new <<properties>> can be added to <<object>> fields.
|
||||
* new <<multi-fields,multi-fields>> can be added to existing fields.
|
||||
* the <<ignore-above>> parameter can be updated.
|
||||
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:
|
||||
|
||||
|
|
|
|||
|
|
@ -118,49 +118,151 @@ You know more about your data than Elasticsearch can guess, so while dynamic
|
|||
mapping can be useful to get started, at some point you will want to specify
|
||||
your own explicit mappings.
|
||||
|
||||
You can create field mappings when you
|
||||
<<indices-create-index,create an index>>, and you can add
|
||||
fields to an existing index with the <<indices-put-mapping,PUT mapping API>>.
|
||||
You can create field mappings when you <<create-mapping,create an index>> and
|
||||
<<add-field-mapping,add fields to an existing index>>.
|
||||
|
||||
[float]
|
||||
== Updating existing field mappings
|
||||
[[create-mapping]]
|
||||
== Create an index with an explicit mapping
|
||||
|
||||
Other than where documented, *existing field mappings cannot be
|
||||
updated*. Changing the mapping would mean invalidating already indexed
|
||||
documents. Instead, you should create a new index with the correct mappings
|
||||
and <<docs-reindex,reindex>> your data into that index. If you only wish
|
||||
to rename a field and not change its mappings, it may make sense to introduce
|
||||
an <<alias, `alias`>> field.
|
||||
|
||||
[float]
|
||||
== Example mapping
|
||||
|
||||
A mapping can be specified when creating an index, as follows:
|
||||
You can use the <<indices-create-index,create index>> API to create a new index
|
||||
with an explicit mapping.
|
||||
|
||||
[source,js]
|
||||
---------------------------------------
|
||||
PUT my_index <1>
|
||||
----
|
||||
PUT /my-index
|
||||
{
|
||||
"mappings": {
|
||||
"properties": { <2>
|
||||
"title": { "type": "text" }, <3>
|
||||
"name": { "type": "text" }, <4>
|
||||
"age": { "type": "integer" }, <5>
|
||||
"created": {
|
||||
"type": "date", <6>
|
||||
"format": "strict_date_optional_time||epoch_millis"
|
||||
"properties": {
|
||||
"age": { "type": "integer" }, <1>
|
||||
"email": { "type": "keyword" }, <2>
|
||||
"name": { "type": "text" } <3>
|
||||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
// CONSOLE
|
||||
|
||||
<1> Creates `age`, an <<number,`integer`>> field
|
||||
<2> Creates `email`, a <<keyword,`keyword`>> field
|
||||
<3> Creates `name`, a <<text,`text`>> field
|
||||
|
||||
[float]
|
||||
[[add-field-mapping]]
|
||||
== Add a field to an existing mapping
|
||||
|
||||
You can use the <<indices-put-mapping, put mapping>> API to add one or more new
|
||||
fields to an existing index.
|
||||
|
||||
The following example adds `employee-id`, a `keyword` field with an
|
||||
<<mapping-index,`index`>> mapping parameter value of `false`. This means values
|
||||
for the `employee-id` field are stored but not indexed or available for search.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
PUT /my-index/_mapping
|
||||
{
|
||||
"properties": {
|
||||
"employee-id": {
|
||||
"type": "keyword",
|
||||
"index": false
|
||||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
[float]
|
||||
[[update-mapping]]
|
||||
=== Update the mapping of a field
|
||||
|
||||
include::{docdir}/indices/put-mapping.asciidoc[tag=put-field-mapping-exceptions]
|
||||
|
||||
[float]
|
||||
[[view-mapping]]
|
||||
== View the mapping of an index
|
||||
|
||||
You can use the <<indices-get-mapping, get mapping>> API to view the mapping of
|
||||
an existing index.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
GET /my-index/_mapping
|
||||
----
|
||||
// CONSOLE
|
||||
// TEST[continued]
|
||||
|
||||
The API returns the following response:
|
||||
|
||||
[source,js]
|
||||
----
|
||||
{
|
||||
"my-index" : {
|
||||
"mappings" : {
|
||||
"properties" : {
|
||||
"age" : {
|
||||
"type" : "integer"
|
||||
},
|
||||
"email" : {
|
||||
"type" : "keyword"
|
||||
},
|
||||
"employee-id" : {
|
||||
"type" : "keyword",
|
||||
"index" : false
|
||||
},
|
||||
"name" : {
|
||||
"type" : "text"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
---------------------------------------
|
||||
----
|
||||
// TESTRESPONSE
|
||||
|
||||
|
||||
[float]
|
||||
[[view-field-mapping]]
|
||||
== View the mapping of specific fields
|
||||
|
||||
If you only want to view the mapping of one or more specific fields, you can use
|
||||
the <<indices-get-field-mapping, get field mapping>> API.
|
||||
|
||||
This is useful if you don't need the complete mapping of an index or your index
|
||||
contains a large number of fields.
|
||||
|
||||
The following request retrieves the mapping for the `employee-id` field.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
GET /my-index/_mapping/field/employee-id
|
||||
----
|
||||
// CONSOLE
|
||||
<1> Create an index called `my_index`.
|
||||
<2> Specify the fields or _properties_ in the mapping.
|
||||
<3> Specify that the `title` field contains `text` values.
|
||||
<4> Specify that the `name` field contains `text` values.
|
||||
<5> Specify that the `age` field contains `integer` values.
|
||||
<6> Specify that the `created` field contains `date` values in two possible formats.
|
||||
// TEST[continued]
|
||||
|
||||
The API returns the following response:
|
||||
|
||||
[source,js]
|
||||
----
|
||||
{
|
||||
"my-index" : {
|
||||
"mappings" : {
|
||||
"employee-id" : {
|
||||
"full_name" : "employee-id",
|
||||
"mapping" : {
|
||||
"employee-id" : {
|
||||
"type" : "keyword",
|
||||
"index" : false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
----
|
||||
// TESTRESPONSE
|
||||
|
||||
--
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue