You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/en/sql-reference/data-types/newjson.md
+54-1Lines changed: 54 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -322,7 +322,60 @@ SELECT json.^a.b, json.^d.e.f FROM test;
322
322
```
323
323
324
324
:::note
325
-
Reading sub-objects as sub-columns may be inefficient, as this may require a near full scan of the JSON data.
325
+
When paths are stored in basic (`map`) [shared data](#shared-data-structure), reading sub-object sub-columns may be inefficient as it requires scanning the entire shared data structure. With `map_with_buckets` or `advanced` shared data serialization, reading sub-columns from shared data is highly optimized.
The `JSON` type supports reading a path as a **combined sub-column** using the special syntax `json.@some.path`.
331
+
A combined sub-column for a given path returns:
332
+
- The literal value stored at that path as `Dynamic`, if the path has a literal value.
333
+
- A JSON sub-object at that path as `Dynamic`, if the path has no literal value but has nested sub-paths.
334
+
-`NULL`, if neither a literal value nor any sub-paths exist for that path.
335
+
336
+
This is useful when a path may hold either a scalar value or a nested object across different rows, and is more convenient than separately querying the literal sub-column (`json.a`) and the sub-object sub-column (`json.^a`).
337
+
338
+
The following example compares all three sub-column types for path `a`:
- Row 1: `a` holds a literal `42`. `json.a` returns it as `Dynamic(Int64)`, `json.^a` returns an empty sub-object `{}` (no nested keys under `a`), and `json.@a` returns the literal `42`.
374
+
- Row 2: `a` holds a nested object. `json.a` returns `NULL` (no literal at that path), `json.^a` returns the sub-object as `JSON`, and `json.@a` also returns the sub-object as `Dynamic(JSON)`.
375
+
- Row 3: `a` is absent entirely. Both `json.a` and `json.@a` return `NULL`, while `json.^a` returns an empty `{}`.
376
+
377
+
:::note
378
+
When paths are stored in basic (`map`) [shared data](#shared-data-structure), reading combined sub-columns may be inefficient as it requires scanning the entire shared data structure. With `map_with_buckets` or `advanced` shared data serialization, reading sub-columns from shared data is highly optimized.
326
379
:::
327
380
328
381
## Type inference for paths {#type-inference-for-paths}
0 commit comments