Skip to content

Commit db13043

Browse files
committed
Some clarifications in the 'enabled' documentation. (elastic#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.
1 parent f56b2ec commit db13043

File tree

1 file changed

+32
-7
lines changed

1 file changed

+32
-7
lines changed

docs/reference/mapping/params/enabled.asciidoc

+32-7
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,11 @@ you are using Elasticsearch as a web session store. You may want to index the
77
session ID and last update time, but you don't need to query or run
88
aggregations on the session data itself.
99

10-
The `enabled` setting, which can be applied only to the mapping type and to
11-
<<object,`object`>> fields, causes Elasticsearch to skip parsing of the
12-
contents of the field entirely. The JSON can still be retrieved from the
13-
<<mapping-source-field,`_source`>> field, but it is not searchable or stored
14-
in any other way:
10+
The `enabled` setting, which can be applied only to the top-level mapping
11+
definition and to <<object,`object`>> fields, causes Elasticsearch to skip
12+
parsing of the contents of the field entirely. The JSON can still be retrieved
13+
from the <<mapping-source-field,`_source`>> field, but it is not searchable or
14+
stored in any other way:
1515

1616
[source,js]
1717
--------------------------------------------------
@@ -26,6 +26,7 @@ PUT my_index
2626
"type": "date"
2727
},
2828
"session_data": { <1>
29+
"type": "object",
2930
"enabled": false
3031
}
3132
}
@@ -55,7 +56,7 @@ PUT my_index/_doc/session_2
5556
<2> Any arbitrary data can be passed to the `session_data` field as it will be entirely ignored.
5657
<3> The `session_data` will also ignore values that are not JSON objects.
5758

58-
The entire mapping type may be disabled as well, in which case the document is
59+
The entire mapping may be disabled as well, in which case the document is
5960
stored in the <<mapping-source-field,`_source`>> field, which means it can be
6061
retrieved, but none of its contents are indexed in any way:
6162

@@ -84,10 +85,34 @@ GET my_index/_doc/session_1 <2>
8485
GET my_index/_mapping <3>
8586
--------------------------------------------------
8687
// CONSOLE
87-
<1> The entire mapping type is disabled.
88+
<1> The entire mapping is disabled.
8889
<2> The document can be retrieved.
8990
<3> Checking the mapping reveals that no fields have been added.
9091

9192
TIP: The `enabled` setting can be updated on existing fields
9293
using the <<indices-put-mapping,PUT mapping API>>.
9394

95+
Note that because Elasticsearch completely skips parsing the field
96+
contents, it is possible to add non-object data to a disabled field:
97+
[source,js]
98+
--------------------------------------------------
99+
PUT my_index
100+
{
101+
"mappings": {
102+
"properties": {
103+
"session_data": {
104+
"type": "object",
105+
"enabled": false
106+
}
107+
}
108+
}
109+
}
110+
111+
PUT my_index/_doc/session_1
112+
{
113+
"session_data": "foo bar" <1>
114+
}
115+
--------------------------------------------------
116+
// CONSOLE
117+
118+
<1> The document is added successfully, even though `session_data` contains non-object data.

0 commit comments

Comments
 (0)