Skip to content

Commit 6a0c377

Browse files
jtibshiranijtibshirani
authored
Rename 'json' to 'embedded_json'. (#40712)
One concern around the name `json` is that because the entire document is JSON, new users may see this field and think that they should always use it. We thought that a more verbose name like `embedded_json` would help convey that the field type has a special, non-obvious purpose. This commit updates documentation references to `embedded_json`, but leaves the `JsonField` naming in the code to avoid very long class names.
1 parent 80b0c08 commit 6a0c377

File tree

20 files changed

+61
-61
lines changed

20 files changed

+61
-61
lines changed

‎docs/reference/mapping/types.asciidoc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ string:: <<text,`text`>> and <<keyword,`keyword`>>
4444

4545
<<alias>>:: Defines an alias to an existing field.
4646

47-
<<json>>:: Allows an entire JSON object to be indexed as a single field.
47+
<<embedded-json>>:: Allows an entire JSON object to be indexed as a single field.
4848

4949
<<rank-feature>>:: Record numeric feature to boost hits at query time.
5050

@@ -84,14 +84,14 @@ include::types/date.asciidoc[]
8484

8585
include::types/date_nanos.asciidoc[]
8686

87+
include::types/embedded_json.asciidoc[]
88+
8789
include::types/geo-point.asciidoc[]
8890

8991
include::types/geo-shape.asciidoc[]
9092

9193
include::types/ip.asciidoc[]
9294

93-
include::types/json.asciidoc[]
94-
9595
include::types/keyword.asciidoc[]
9696

9797
include::types/nested.asciidoc[]

‎docs/reference/mapping/types/json.asciidoc renamed to ‎docs/reference/mapping/types/embedded_json.asciidoc

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,38 @@
1-
[[json]]
2-
=== JSON datatype
1+
[[embedded-json]]
2+
=== Embedded JSON datatype
33

4-
experimental[The `json` field type is experimental and may be changed in a breaking way in future releases.]
4+
experimental[The `embedded_json` field type is experimental and may be changed in a breaking way in future releases.]
55

66
By default, each subfield in an object is mapped and indexed separately. If
77
the names or types of the subfields are not known in advance, then they are
88
<<dynamic-mapping, mapped dynamically>>.
99

10-
The `json` type provides an alternative approach, where the entire object is
11-
mapped as a single field. Given an object, the `json` mapping will parse out
10+
The `embedded_json` type provides an alternative approach, where the entire object is
11+
mapped as a single field. Given an object, the `embedded_json` mapping will parse out
1212
its leaf values and index them into one field. The object's contents can then
1313
be searched through simple keyword-style queries.
1414

1515
This data type can be useful for indexing objects with a very large number of
16-
distinct keys. Compared to mapping each field separately, `json` fields have
16+
distinct keys. Compared to mapping each field separately, embedded JSON fields have
1717
the following advantages:
1818

1919
- Only one field mapping is created for the whole object, which can help
2020
prevent a <<mapping-limit-settings, mappings explosion>> due to a large
2121
number of field mappings.
22-
- A `json` field may take up less space in the index, as only one underlying
22+
- An embedded JSON field may take up less space in the index, as only one underlying
2323
field is created.
2424

25-
However, `json` fields present a trade-off in terms of search functionality.
25+
However, embedded JSON fields present a trade-off in terms of search functionality.
2626
Only basic queries are allowed, with no support for numeric range queries or
2727
highlighting. Further information on the limitations can be found in the
2828
<<supported-operations, Supported operations>> section.
2929

30-
NOTE: The `json` mapping type should **not** be used for indexing all JSON
30+
NOTE: The `embedded_json` mapping type should **not** be used for indexing all JSON
3131
content, as it provides only limited search functionality. The default
3232
approach, where each subfield has its own entry in the mappings, works well in
3333
the majority of cases.
3434

35-
A `json` field can be created as follows:
35+
An embedded JSON field can be created as follows:
3636
[source,js]
3737
--------------------------------
3838
PUT bug_reports
@@ -43,7 +43,7 @@ PUT bug_reports
4343
"type": "text"
4444
},
4545
"labels": {
46-
"type": "json"
46+
"type": "embedded_json"
4747
}
4848
}
4949
}
@@ -69,7 +69,7 @@ During indexing, tokens are created for each leaf value in the JSON object. The
6969
values are indexed as string keywords, without analysis or special handling for
7070
numbers or dates.
7171

72-
Querying the top-level `json` field searches all leaf values in the object:
72+
Querying the top-level `embedded_json` field searches all leaf values in the object:
7373
[source,js]
7474
--------------------------------
7575
POST bug_reports/_search
@@ -96,7 +96,7 @@ POST bug_reports/_search
9696
[[supported-operations]]
9797
==== Supported operations
9898

99-
Currently, `json` fields can be used with the following query types:
99+
Currently, embedded JSON fields can be used with the following query types:
100100

101101
- `term`, `terms`, and `terms_set`
102102
- `prefix`
@@ -110,7 +110,7 @@ When querying, it is not possible to refer to field keys using wildcards, as in
110110
`range`, treat the values as string keywords. Highlighting is not supported on
111111
`json` fields.
112112

113-
It is possible to sort on a `json` field, as well as perform simple
113+
It is possible to sort on an embedded JSON field, as well as perform simple
114114
keyword-style aggregations such as `terms`. As with queries, there is no
115115
special support for numerics -- all values in the JSON object are treated as
116116
keywords. When sorting, this implies that values are compared lexicographically.
@@ -123,7 +123,7 @@ character `\0` is not allowed to appear in the keys of the JSON object.
123123

124124
If the <<mapping-store,`store`>> option is enabled, the entire JSON object will
125125
be stored in pretty-printed format. It can be retrieved through the top-level
126-
`json` field:
126+
`embedded_json` field:
127127

128128
[source,js]
129129
--------------------------------
@@ -141,7 +141,7 @@ Field keys cannot be used to load stored content. For example, specifying
141141
[[json-params]]
142142
==== Parameters for JSON fields
143143

144-
Because of the similarities in the way values are indexed, the `json` type
144+
Because of the similarities in the way values are indexed, the `embedded_json` type
145145
shares many mapping options with <<keyword, `keyword`>>. The following
146146
parameters are accepted:
147147

‎rest-api-spec/src/main/resources/rest-api-spec/test/search/160_exists_query.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1349,7 +1349,7 @@ setup:
13491349
dynamic: false
13501350
properties:
13511351
json:
1352-
type: json
1352+
type: embedded_json
13531353
- do:
13541354
index:
13551355
index: json_test

‎rest-api-spec/src/main/resources/rest-api-spec/test/search/60_query_string.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@
7575
mappings:
7676
properties:
7777
headers:
78-
type: json
78+
type: embedded_json
7979

8080
- do:
8181
index:

‎server/src/main/java/org/elasticsearch/index/mapper/JsonFieldMapper.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@
9898
*/
9999
public final class JsonFieldMapper extends FieldMapper {
100100

101-
public static final String CONTENT_TYPE = "json";
101+
public static final String CONTENT_TYPE = "embedded_json";
102102
public static final NamedAnalyzer WHITESPACE_ANALYZER = new NamedAnalyzer(
103103
"whitespace", AnalyzerScope.INDEX, new WhitespaceAnalyzer());
104104
private static final String KEYED_FIELD_SUFFIX = "._keyed";

‎server/src/main/java/org/elasticsearch/index/mapper/JsonFieldParser.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ private void addField(ContentPath path,
139139

140140
String key = path.pathAsText(currentName);
141141
if (key.contains(SEPARATOR)) {
142-
throw new IllegalArgumentException("Keys in [json] fields cannot contain the reserved character \\0."
142+
throw new IllegalArgumentException("Keys in [embedded_json] fields cannot contain the reserved character \\0."
143143
+ " Offending key: [" + key + "].");
144144
}
145145
String keyedValue = createKeyedValue(key, value);

‎server/src/test/java/org/elasticsearch/index/mapper/JsonFieldMapperTests.java

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ public void testDefaults() throws Exception {
6464
.startObject("type")
6565
.startObject("properties")
6666
.startObject("field")
67-
.field("type", "json")
67+
.field("type", "embedded_json")
6868
.endObject()
6969
.endObject()
7070
.endObject()
@@ -119,7 +119,7 @@ public void testDisableIndex() throws Exception {
119119
.startObject("type")
120120
.startObject("properties")
121121
.startObject("field")
122-
.field("type", "json")
122+
.field("type", "embedded_json")
123123
.field("index", false)
124124
.endObject()
125125
.endObject()
@@ -151,7 +151,7 @@ public void testDisableDocValues() throws Exception {
151151
.startObject("type")
152152
.startObject("properties")
153153
.startObject("field")
154-
.field("type", "json")
154+
.field("type", "embedded_json")
155155
.field("doc_values", false)
156156
.endObject()
157157
.endObject()
@@ -187,11 +187,11 @@ public void testEnableStore() throws Exception {
187187
.startObject("type")
188188
.startObject("properties")
189189
.startObject("store")
190-
.field("type", "json")
190+
.field("type", "embedded_json")
191191
.field("store", true)
192192
.endObject()
193193
.startObject("store_only")
194-
.field("type", "json")
194+
.field("type", "embedded_json")
195195
.field("index", false)
196196
.field("store", true)
197197
.field("doc_values", false)
@@ -241,7 +241,7 @@ public void testIndexOptions() throws IOException {
241241
.startObject("type")
242242
.startObject("properties")
243243
.startObject("field")
244-
.field("type", "json")
244+
.field("type", "embedded_json")
245245
.field("index_options", "freqs")
246246
.endObject()
247247
.endObject()
@@ -256,15 +256,15 @@ public void testIndexOptions() throws IOException {
256256
.startObject("type")
257257
.startObject("properties")
258258
.startObject("field")
259-
.field("type", "json")
259+
.field("type", "embedded_json")
260260
.field("index_options", indexOptions)
261261
.endObject()
262262
.endObject()
263263
.endObject()
264264
.endObject());
265265
IllegalArgumentException e = expectThrows(IllegalArgumentException.class,
266266
() -> parser.parse("type", new CompressedXContent(invalidMapping)));
267-
assertEquals("The [json] field does not support positions, got [index_options]=" + indexOptions, e.getMessage());
267+
assertEquals("The [embedded_json] field does not support positions, got [index_options]=" + indexOptions, e.getMessage());
268268
}
269269
}
270270

@@ -273,7 +273,7 @@ public void testNullField() throws Exception {
273273
.startObject("type")
274274
.startObject("properties")
275275
.startObject("field")
276-
.field("type", "json")
276+
.field("type", "embedded_json")
277277
.endObject()
278278
.endObject()
279279
.endObject()
@@ -296,7 +296,7 @@ public void testMalformedJson() throws Exception {
296296
.startObject("type")
297297
.startObject("properties")
298298
.startObject("field")
299-
.field("type", "json")
299+
.field("type", "embedded_json")
300300
.endObject()
301301
.endObject()
302302
.endObject()
@@ -322,7 +322,7 @@ public void testFieldMultiplicity() throws Exception {
322322
.startObject("type")
323323
.startObject("properties")
324324
.startObject("field")
325-
.field("type", "json")
325+
.field("type", "embedded_json")
326326
.endObject()
327327
.endObject()
328328
.endObject()
@@ -363,7 +363,7 @@ public void testDepthLimit() throws IOException {
363363
.startObject("type")
364364
.startObject("properties")
365365
.startObject("field")
366-
.field("type", "json")
366+
.field("type", "embedded_json")
367367
.field("depth_limit", 2)
368368
.endObject()
369369
.endObject()
@@ -392,7 +392,7 @@ public void testEagerGlobalOrdinals() throws IOException {
392392
.startObject("type")
393393
.startObject("properties")
394394
.startObject("field")
395-
.field("type", "json")
395+
.field("type", "embedded_json")
396396
.field("eager_global_ordinals", true)
397397
.endObject().endObject()
398398
.endObject().endObject());
@@ -409,7 +409,7 @@ public void testIgnoreAbove() throws IOException {
409409
.startObject("type")
410410
.startObject("properties")
411411
.startObject("field")
412-
.field("type", "json")
412+
.field("type", "embedded_json")
413413
.field("ignore_above", 10)
414414
.endObject()
415415
.endObject()
@@ -437,10 +437,10 @@ public void testNullValues() throws Exception {
437437
.startObject("type")
438438
.startObject("properties")
439439
.startObject("field")
440-
.field("type", "json")
440+
.field("type", "embedded_json")
441441
.endObject()
442442
.startObject("other_field")
443-
.field("type", "json")
443+
.field("type", "embedded_json")
444444
.field("null_value", "placeholder")
445445
.endObject()
446446
.endObject()
@@ -480,7 +480,7 @@ public void testSplitQueriesOnWhitespace() throws IOException {
480480
.startObject("type")
481481
.startObject("properties")
482482
.startObject("field")
483-
.field("type", "json")
483+
.field("type", "embedded_json")
484484
.field("split_queries_on_whitespace", true)
485485
.endObject()
486486
.endObject()

‎server/src/test/java/org/elasticsearch/index/mapper/JsonFieldParserTests.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -318,7 +318,7 @@ public void testReservedCharacters() throws Exception {
318318
XContentParser xContentParser = createXContentParser(input.utf8ToString());
319319

320320
IllegalArgumentException e = expectThrows(IllegalArgumentException.class, () -> parser.parse(xContentParser));
321-
assertEquals("Keys in [json] fields cannot contain the reserved character \\0. Offending key: [k\0y].",
321+
assertEquals("Keys in [embedded_json] fields cannot contain the reserved character \\0. Offending key: [k\0y].",
322322
e.getMessage());
323323
}
324324

‎server/src/test/java/org/elasticsearch/index/mapper/KeyedJsonFieldTypeTests.java

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ public void testFuzzyQuery() {
117117

118118
UnsupportedOperationException e = expectThrows(UnsupportedOperationException.class,
119119
() -> ft.fuzzyQuery("valuee", Fuzziness.fromEdits(2), 1, 50, true));
120-
assertEquals("[fuzzy] queries are not currently supported on [json] fields.", e.getMessage());
120+
assertEquals("[fuzzy] queries are not currently supported on [embedded_json] fields.", e.getMessage());
121121
}
122122

123123
public void testRangeQuery() {
@@ -136,12 +136,12 @@ public void testRangeQuery() {
136136

137137
IllegalArgumentException e = expectThrows(IllegalArgumentException.class, () ->
138138
ft.rangeQuery("lower", null, false, false, null));
139-
assertEquals("[range] queries on keyed [json] fields must include both an upper and a lower bound.",
139+
assertEquals("[range] queries on keyed [embedded_json] fields must include both an upper and a lower bound.",
140140
e.getMessage());
141141

142142
e = expectThrows(IllegalArgumentException.class, () ->
143143
ft.rangeQuery(null, "upper", false, false, null));
144-
assertEquals("[range] queries on keyed [json] fields must include both an upper and a lower bound.",
144+
assertEquals("[range] queries on keyed [embedded_json] fields must include both an upper and a lower bound.",
145145
e.getMessage());
146146
}
147147

@@ -151,7 +151,7 @@ public void testRegexpQuery() {
151151

152152
UnsupportedOperationException e = expectThrows(UnsupportedOperationException.class,
153153
() -> ft.regexpQuery("valu*", 0, 10, null, null));
154-
assertEquals("[regexp] queries are not currently supported on [json] fields.", e.getMessage());
154+
assertEquals("[regexp] queries are not currently supported on [embedded_json] fields.", e.getMessage());
155155
}
156156

157157
public void testWildcardQuery() {
@@ -160,6 +160,6 @@ public void testWildcardQuery() {
160160

161161
UnsupportedOperationException e = expectThrows(UnsupportedOperationException.class,
162162
() -> ft.wildcardQuery("valu*", null, null));
163-
assertEquals("[wildcard] queries are not currently supported on [json] fields.", e.getMessage());
163+
assertEquals("[wildcard] queries are not currently supported on [embedded_json] fields.", e.getMessage());
164164
}
165165
}

‎server/src/test/java/org/elasticsearch/index/mapper/RootJsonFieldTypeTests.java

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ public void testFuzzyQuery() {
8585

8686
UnsupportedOperationException e = expectThrows(UnsupportedOperationException.class,
8787
() -> ft.fuzzyQuery("valuee", Fuzziness.fromEdits(2), 1, 50, true));
88-
assertEquals("[fuzzy] queries are not currently supported on [json] fields.", e.getMessage());
88+
assertEquals("[fuzzy] queries are not currently supported on [embedded_json] fields.", e.getMessage());
8989
}
9090

9191
public void testRangeQuery() {
@@ -109,7 +109,7 @@ public void testRegexpQuery() {
109109

110110
UnsupportedOperationException e = expectThrows(UnsupportedOperationException.class,
111111
() -> ft.regexpQuery("valu*", 0, 10, null, null));
112-
assertEquals("[regexp] queries are not currently supported on [json] fields.", e.getMessage());
112+
assertEquals("[regexp] queries are not currently supported on [embedded_json] fields.", e.getMessage());
113113
}
114114

115115
public void testWildcardQuery() {
@@ -118,6 +118,6 @@ public void testWildcardQuery() {
118118

119119
UnsupportedOperationException e = expectThrows(UnsupportedOperationException.class,
120120
() -> ft.wildcardQuery("valu*", null, null));
121-
assertEquals("[wildcard] queries are not currently supported on [json] fields.", e.getMessage());
121+
assertEquals("[wildcard] queries are not currently supported on [embedded_json] fields.", e.getMessage());
122122
}
123123
}

‎server/src/test/java/org/elasticsearch/index/search/MultiMatchQueryTests.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -343,10 +343,10 @@ public void testJsonSplitQueriesOnWhitespace() throws IOException {
343343
.startObject("type")
344344
.startObject("properties")
345345
.startObject("field")
346-
.field("type", "json")
346+
.field("type", "embedded_json")
347347
.endObject()
348348
.startObject("field_split")
349-
.field("type", "json")
349+
.field("type", "embedded_json")
350350
.field("split_queries_on_whitespace", true)
351351
.endObject()
352352
.endObject()

0 commit comments

Comments
 (0)