Some clarifications in the 'enabled' documentation. (#40989)

This PR makes a few clarifications to the docs for the `enabled` setting:
- Replace references to 'mapping type' with 'mapping' or 'mapping definition'.
- In code examples, clarify that the disabled fields have type `object`.
- Add a section on how disabled fields can hold non-object data.
This commit is contained in:
Julie Tibshirani 2019-04-09 10:49:01 -07:00
parent f56b2ecb37
commit db13043d3b
1 changed files with 32 additions and 7 deletions

View File

@ -7,11 +7,11 @@ you are using Elasticsearch as a web session store. You may want to index the
session ID and last update time, but you don't need to query or run session ID and last update time, but you don't need to query or run
aggregations on the session data itself. aggregations on the session data itself.
The `enabled` setting, which can be applied only to the mapping type and to The `enabled` setting, which can be applied only to the top-level mapping
<<object,`object`>> fields, causes Elasticsearch to skip parsing of the definition and to <<object,`object`>> fields, causes Elasticsearch to skip
contents of the field entirely. The JSON can still be retrieved from the parsing of the contents of the field entirely. The JSON can still be retrieved
<<mapping-source-field,`_source`>> field, but it is not searchable or stored from the <<mapping-source-field,`_source`>> field, but it is not searchable or
in any other way: stored in any other way:
[source,js] [source,js]
-------------------------------------------------- --------------------------------------------------
@ -26,6 +26,7 @@ PUT my_index
"type": "date" "type": "date"
}, },
"session_data": { <1> "session_data": { <1>
"type": "object",
"enabled": false "enabled": false
} }
} }
@ -55,7 +56,7 @@ PUT my_index/_doc/session_2
<2> Any arbitrary data can be passed to the `session_data` field as it will be entirely ignored. <2> Any arbitrary data can be passed to the `session_data` field as it will be entirely ignored.
<3> The `session_data` will also ignore values that are not JSON objects. <3> The `session_data` will also ignore values that are not JSON objects.
The entire mapping type may be disabled as well, in which case the document is The entire mapping may be disabled as well, in which case the document is
stored in the <<mapping-source-field,`_source`>> field, which means it can be stored in the <<mapping-source-field,`_source`>> field, which means it can be
retrieved, but none of its contents are indexed in any way: retrieved, but none of its contents are indexed in any way:
@ -84,10 +85,34 @@ GET my_index/_doc/session_1 <2>
GET my_index/_mapping <3> GET my_index/_mapping <3>
-------------------------------------------------- --------------------------------------------------
// CONSOLE // CONSOLE
<1> The entire mapping type is disabled. <1> The entire mapping is disabled.
<2> The document can be retrieved. <2> The document can be retrieved.
<3> Checking the mapping reveals that no fields have been added. <3> Checking the mapping reveals that no fields have been added.
TIP: The `enabled` setting can be updated on existing fields TIP: The `enabled` setting can be updated on existing fields
using the <<indices-put-mapping,PUT mapping API>>. using the <<indices-put-mapping,PUT mapping API>>.
Note that because Elasticsearch completely skips parsing the field
contents, it is possible to add non-object data to a disabled field:
[source,js]
--------------------------------------------------
PUT my_index
{
"mappings": {
"properties": {
"session_data": {
"type": "object",
"enabled": false
}
}
}
}
PUT my_index/_doc/session_1
{
"session_data": "foo bar" <1>
}
--------------------------------------------------
// CONSOLE
<1> The document is added successfully, even though `session_data` contains non-object data.