Skip to content

Commit 9cefddf

Browse files
committed
Rename 'embedded JSON' to 'flattened object'.
The code refers to 'flat object' in some places for brevity.
1 parent 74ebc19 commit 9cefddf

31 files changed

+320
-318
lines changed

docs/reference/mapping/types.asciidoc

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,6 @@ string:: <<text,`text`>> and <<keyword,`keyword`>>
4242

4343
<<parent-join>>:: Defines parent/child relation for documents within the same index
4444

45-
<<alias>>:: Defines an alias to an existing field.
46-
47-
<<embedded-json>>:: Allows an entire JSON object to be indexed as a single field.
48-
4945
<<rank-feature>>:: Record numeric feature to boost hits at query time.
5046

5147
<<rank-features>>:: Record numeric features to boost hits at query time.
@@ -56,6 +52,11 @@ string:: <<text,`text`>> and <<keyword,`keyword`>>
5652

5753
<<search-as-you-type>>:: A text-like field optimized for queries to implement as-you-type completion
5854

55+
<<alias>>:: Defines an alias to an existing field.
56+
57+
<<flattened>>:: Allows an entire JSON object to be indexed as a single field.
58+
59+
5960
[float]
6061
=== Multi-fields
6162

@@ -84,7 +85,7 @@ include::types/date.asciidoc[]
8485

8586
include::types/date_nanos.asciidoc[]
8687

87-
include::types/embedded-json.asciidoc[]
88+
include::types/flattened.asciidoc[]
8889

8990
include::types/geo-point.asciidoc[]
9091

docs/reference/mapping/types/embedded-json.asciidoc renamed to docs/reference/mapping/types/flattened.asciidoc

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

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

8-
The `embedded_json` type provides an alternative approach, where the entire
9-
object is mapped as a single field. Given an object, the `embedded_json`
8+
The `flattened` type provides an alternative approach, where the entire
9+
object is mapped as a single field. Given an object, the `flattened`
1010
mapping will parse out its leaf values and index them into one field as
1111
keywords. The object's contents can then be searched through simple queries
1212
and aggregations.
@@ -16,17 +16,17 @@ number of unique keys. Only one field mapping is created for the whole JSON
1616
object, which can help prevent a <<mapping-limit-settings, mappings explosion>>
1717
from having too many distinct field mappings.
1818

19-
On the other hand, embedded JSON fields present a trade-off in terms of search
20-
functionality. Only basic queries are allowed, with no support for numeric
21-
range queries or highlighting. Further information on the limitations can be
22-
found in the <<supported-operations, Supported operations>> section.
19+
On the other hand, flattened object fields present a trade-off in terms of
20+
search functionality. Only basic queries are allowed, with no support for
21+
numeric range queries or highlighting. Further information on the limitations
22+
can be found in the <<supported-operations, Supported operations>> section.
2323

24-
NOTE: The `embedded_json` mapping type should **not** be used for indexing all
25-
JSON content, as it treats all values as keywords and does not provide full
24+
NOTE: The `flattened` mapping type should **not** be used for indexing all
25+
document content, as it treats all values as keywords and does not provide full
2626
search functionality. The default approach, where each subfield has its own
2727
entry in the mappings, works well in the majority of cases.
2828

29-
An embedded JSON field can be created as follows:
29+
An flattened object field can be created as follows:
3030
[source,js]
3131
--------------------------------
3232
PUT bug_reports
@@ -37,7 +37,7 @@ PUT bug_reports
3737
"type": "text"
3838
},
3939
"labels": {
40-
"type": "embedded_json"
40+
"type": "flattened"
4141
}
4242
}
4343
}
@@ -63,7 +63,7 @@ During indexing, tokens are created for each leaf value in the JSON object. The
6363
values are indexed as string keywords, without analysis or special handling for
6464
numbers or dates.
6565

66-
Querying the top-level `embedded_json` field searches all leaf values in the
66+
Querying the top-level `flattened` field searches all leaf values in the
6767
object:
6868

6969
[source,js]
@@ -77,7 +77,7 @@ POST bug_reports/_search
7777
--------------------------------
7878
// CONSOLE
7979

80-
To query on a specific key in the JSON object, object dot notation is used:
80+
To query on a specific key in the flattened object, object dot notation is used:
8181
[source,js]
8282
--------------------------------
8383
POST bug_reports/_search
@@ -92,11 +92,11 @@ POST bug_reports/_search
9292
[[supported-operations]]
9393
==== Supported operations
9494

95-
Because of the similarities in the way values are indexed, `embedded_json`
95+
Because of the similarities in the way values are indexed, `flattened`
9696
fields share much of the same mapping and search functionality as
9797
<<keyword, `keyword`>> fields.
9898

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

101101
- `term`, `terms`, and `terms_set`
102102
- `prefix`
@@ -108,19 +108,19 @@ Currently, embedded JSON fields can be used with the following query types:
108108
When querying, it is not possible to refer to field keys using wildcards, as in
109109
`{ "term": {"labels.time*": 1541457010}}`. Note that all queries, including
110110
`range`, treat the values as string keywords. Highlighting is not supported on
111-
`embedded_json` fields.
111+
`flattened` fields.
112112

113-
It is possible to sort on an embedded JSON field, as well as perform simple
113+
It is possible to sort on an flattened object 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
117117
lexicographically.
118118

119-
Embedded JSON fields currently cannot be stored. It is not possible to specify
120-
the <<mapping-store, `store`>> parameter in the mapping.
119+
Flattened object fields currently cannot be stored. It is not possible to
120+
specify the <<mapping-store, `store`>> parameter in the mapping.
121121

122-
[[json-params]]
123-
==== Parameters for JSON fields
122+
[[flattened-params]]
123+
==== Parameters for flattened object fields
124124

125125
The following mapping parameters are accepted:
126126

@@ -133,9 +133,9 @@ The following mapping parameters are accepted:
133133

134134
`depth_limit`::
135135

136-
The maximum allowed depth of the JSON field, in terms of nested inner
137-
objects. If a JSON field exceeds this limit, then an error will be
138-
thrown. Defaults to `20`.
136+
The maximum allowed depth of the flattened object field, in terms of nested
137+
inner objects. If a flattened object field exceeds this limit, then an
138+
error will be thrown. Defaults to `20`.
139139

140140
<<doc-values,`doc_values`>>::
141141

@@ -153,8 +153,8 @@ The following mapping parameters are accepted:
153153

154154
Leaf values longer than this limit will not be indexed. By default, there
155155
is no limit and all values will be indexed. Note that this limit applies
156-
to the leaf values within the JSON field, and not the length of the entire
157-
field.
156+
to the leaf values within the flattened object field, and not the length of
157+
the entire field.
158158

159159
<<mapping-index,`index`>>::
160160

@@ -170,8 +170,8 @@ The following mapping parameters are accepted:
170170
<<null-value,`null_value`>>::
171171

172172
A string value which is substituted for any explicit `null` values within
173-
the JSON field. Defaults to `null`, which means null sfields are treated as
174-
if it were missing.
173+
the flattened object field. Defaults to `null`, which means null sields are
174+
treated as if it were missing.
175175

176176
<<similarity,`similarity`>>::
177177

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

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1330,55 +1330,55 @@ setup:
13301330
- match: {hits.total: 3}
13311331

13321332
---
1333-
"Test exists query on JSON field":
1333+
"Test exists query on flat object field":
13341334
- skip:
13351335
version: " - 7.99.99"
1336-
reason: "JSON fields are currently only implemented in 8.0."
1336+
reason: "Flat object fields are currently only implemented in 8.0."
13371337

13381338
- do:
13391339
indices.create:
1340-
index: json_test
1340+
index: flat_object_test
13411341
body:
13421342
mappings:
13431343
dynamic: false
13441344
properties:
1345-
json:
1346-
type: embedded_json
1345+
flat_object:
1346+
type: flattened
13471347
- do:
13481348
index:
1349-
index: json_test
1349+
index: flat_object_test
13501350
id: 1
13511351
body:
1352-
json:
1352+
flat_object:
13531353
key: some_value
13541354
refresh: true
13551355

13561356
- do:
13571357
search:
1358-
index: json_test
1358+
index: flat_object_test
13591359
body:
13601360
query:
13611361
exists:
1362-
field: json
1362+
field: flat_object
13631363

13641364
- match: { hits.total.value: 1 }
13651365

13661366
- do:
13671367
search:
1368-
index: json_test
1368+
index: flat_object_test
13691369
body:
13701370
query:
13711371
exists:
1372-
field: json.key
1372+
field: flat_object.key
13731373

13741374
- match: { hits.total.value: 1 }
13751375

13761376
- do:
13771377
search:
1378-
index: json_test
1378+
index: flat_object_test
13791379
body:
13801380
query:
13811381
exists:
1382-
field: json.nonexistent_key
1382+
field: flat_object.nonexistent_key
13831383

13841384
- match: { hits.total.value: 0 }

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,10 +63,10 @@
6363
- match: {hits.total: 0}
6464

6565
---
66-
"search on JSON field":
66+
"search on flat object field":
6767
- skip:
6868
version: " - 7.99.99"
69-
reason: "JSON fields are currently only implemented in 8.0."
69+
reason: "Flat object fields are currently only implemented in 8.0."
7070

7171
- do:
7272
indices.create:
@@ -75,7 +75,7 @@
7575
mappings:
7676
properties:
7777
headers:
78-
type: embedded_json
78+
type: flattened
7979

8080
- do:
8181
index:

0 commit comments

Comments
 (0)