Skip to content

Commit e75595c

Browse files
mrhhsgmrhhsg
authored
update json_extract (#2632)
## Versions - [x] dev - [ ] 3.0 - [ ] 2.1 - [ ] 2.0
1 parent 71953de commit e75595c

File tree

2 files changed

+309
-336
lines changed
  • docs/sql-manual/sql-functions/scalar-functions/json-functions
  • i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions

2 files changed

+309
-336
lines changed

‎docs/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md

Lines changed: 155 additions & 169 deletions
Original file line numberDiff line numberDiff line change
@@ -6,182 +6,168 @@
66
---
77

88
## Description
9-
JSON_EXTRACT is a series of functions that extract the field specified by json_path from JSON data and provide different series of functions according to the type of the field to be extracted.
10-
11-
* JSON_EXTRACT returns the VARCHAR type for a json string of the VARCHAR type.
12-
* JSON_EXTRACT_NO_QUOTES returns the VARCHAR type for a json string of the VARCHAR type, if the value of a JSON field is a string, the double quotes will be removed.
13-
* JSON_EXTRACT_ISNULL returns the BOOLEAN type indicating whether it is a json null.
14-
* JSON_EXTRACT_BOOL returns the BOOLEAN type.
15-
* JSON_EXTRACT_INT returns the INT type.
16-
* JSON_EXTRACT_BIGINT returns the BIGINT type.
17-
* JSON_EXTRACT_LARGEINT returns the LARGEINT type.
18-
* JSON_EXTRACT_DOUBLE returns the DOUBLE type.
19-
* JSON_EXTRACT_STRING returns the STRING type.
20-
21-
:::tip
22-
The `JSON_EXTRACT_NO_QUOTES` function is supported since version 3.0.6.
23-
:::
24-
25-
## Alias
26-
* JSONB_EXTRACT is the same as JSON_EXTRACT.
27-
* JSON_EXTRACT_NO_QUOTES is the same as JSON_EXTRACT_NO_QUOTES.
28-
* JSONB_EXTRACT_ISNULL is the same as JSON_EXTRACT_ISNULL.
29-
* JSONB_EXTRACT_BOOL is the same as JSON_EXTRACT_BOOL.
30-
* JSONB_EXTRACT_INT is the same as JSON_EXTRACT_INT.
31-
* JSONB_EXTRACT_BIGINT is the same as JSON_EXTRACT_BIGINT.
32-
* JSONB_EXTRACT_LARGEINT is the same as JSON_EXTRACT_LARGEINT.
33-
* JSONB_EXTRACT_DOUBLE is the same as JSON_EXTRACT_DOUBLE.
34-
* JSONB_EXTRACT_STRING is the same as JSON_EXTRACT_STRING.
9+
Extract the field specified by json_path from JSON type data.
3510

3611
## Syntax
3712
```sql
38-
JSON_EXTRACT (<json_str>, <path>[, path] ...)
39-
```
40-
```sql
41-
JSON_EXTRACT_NO_QUOTES (<json_str>, <path>[, path] ...)
42-
```
43-
```sql
44-
JSON_EXTRACT_ISNULL (<json_str>, <path>)
45-
```
46-
```sql
47-
JSON_EXTRACT_BOOL (<json_str>, <path>)
48-
```
49-
```sql
50-
JSON_EXTRACT_INT (<json_str>, <path>)
51-
```
52-
```sql
53-
JSON_EXTRACT_BIGINT (<json_str>, <path>)
13+
JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
5414
```
55-
```sql
56-
JSON_EXTRACT_LARGEINT (<json_str>, <path>)
57-
```
58-
```sql
59-
JSON_EXTRACT_DOUBLE (<json_str>, <path>)
60-
```
61-
```sql
62-
JSON_EXTRACT_STRING (<json_str>, <path>)
63-
```
64-
Alias functions have the same syntax and usage as the above functions, except for the function names.
65-
6615
## Parameters
67-
| Parameter | Description |
68-
|--------------|-----------------------------|
69-
| `<json_str>` | The JSON-type parameter or field to be extracted. |
70-
| `<path>` | The JSON path to extract the target element from the target JSON. |
71-
json path syntax:
72-
- '$' for json document root
73-
- '.k1' for element of json object with key 'k1'
74-
- If the key column value contains ".", double quotes are required in json_path, For example: SELECT json_extract('{"k1.a":"abc","k2":300}', '$."k1.a"');
75-
- '[i]' for element of json array at index i
76-
- Use '$[last]' to get the last element of json_array, and '$[last-1]' to get the penultimate element, and so on.
77-
78-
## Return Values
79-
According to the type of the field to be extracted, return the data type of the specified JSON_PATH in the target JSON. Special case handling is as follows:
80-
* If the field specified by json_path does not exist in the JSON, return NULL.
81-
* If the actual type of the field specified by json_path in the JSON is inconsistent with the type specified by json_extract_t.
82-
* if it can be losslessly converted to the specified type, return the specified type t; if not, return NULL.
16+
### Required Parameters:
17+
- `<json_object>`: The JSON type expression to extract from.
18+
- `<path>`: The JSON path to extract the target element from the target JSON.
19+
### Optional/Variable Parameters
20+
- `<path2>` Multiple path values can be extracted from the JSON object.
8321

22+
## Return Value
23+
- `Nullable(JSON)`: Returns the JSON element pointed to by `<path>`. If multiple results are matched, they will be returned as a JSON array.
8424

25+
## Usage Notes
26+
- If `<json_object>` is NULL, or `<path>` is NULL, returns NULL.
27+
- For single `<path>` parameter cases, if the `<path>` does not exist, returns NULL.
28+
- For multiple `<path>` parameter cases, non-existent paths are ignored, and matched elements are returned as a JSON array. If no matches are found, returns NULL.
29+
- If `<path>` is not a valid path, an error is reported.
30+
- If the value corresponding to `<path>` is a string, the returned string will be surrounded by double quotes (`"`). To get results without double quotes, please use the function [`JSON_UNQUOTE`](./json-unquote.md).
31+
- The syntax of `<path>` is as follows:
32+
* `$` represents the json root
33+
* `.k1` represents the element with key `k1` in the json object
34+
* If the key value contains ".", `<path>` needs to use double quotes, for example `SELECT json_extract('{"k1.a":"abc","k2":300}', '$."k1.a"')`;
35+
* `[i]` represents the element at index i in the json array
36+
* To get the last element of json_array, you can use `$[last]`, the second to last element can use `$[last-1]`, and so on.
37+
* `*` represents a wildcard, where `$.*` represents all members of the root object, and `$[*]` represents all elements of the array.
38+
- If `<path>` contains wildcards (`*`), the matching results will be returned in array form.
8539

8640
## Examples
87-
```sql
88-
SELECT json_extract('{"id": 123, "name": "doris"}', '$.id');
89-
```
41+
1. General parameters
42+
```sql
43+
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k1');
44+
```
45+
```
46+
+-----------------------------------------------+
47+
| JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k1') |
48+
+-----------------------------------------------+
49+
| "v31" |
50+
+-----------------------------------------------+
51+
```
52+
> Note: The returned result is `"v31"` not `v31`.
53+
2. NULL parameters
54+
```sql
55+
select JSON_EXTRACT(null, '$.k1');
56+
```
57+
```
58+
+----------------------------+
59+
| JSON_EXTRACT(null, '$.k1') |
60+
+----------------------------+
61+
| NULL |
62+
+----------------------------+
63+
```
64+
3. `<path>` is NULL
65+
```sql
66+
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', NULL);
67+
```
68+
```
69+
+---------------------------------------------+
70+
| JSON_EXTRACT('{"k1":"v31","k2":300}', NULL) |
71+
+---------------------------------------------+
72+
| NULL |
73+
+---------------------------------------------+
74+
```
75+
4. Multi-level path
76+
```sql
77+
SELECT JSON_EXTRACT('{"k1":"v31","k2":{"sub_key": 1234.56}}', '$.k2.sub_key');
78+
```
79+
```
80+
+------------------------------------------------------------------------+
81+
| JSON_EXTRACT('{"k1":"v31","k2":{"sub_key": 1234.56}}', '$.k2.sub_key') |
82+
+------------------------------------------------------------------------+
83+
| 1234.56 |
84+
+------------------------------------------------------------------------+
85+
```
86+
5. Array path
87+
```sql
88+
SELECT JSON_EXTRACT(json_array("abc", 123, cast(now() as string)), '$[2]');
89+
```
90+
```
91+
+----------------------------------------------------------------------+
92+
| JSON_EXTRACT(json_array("abc", 123, cast(now() as string)), '$.[2]') |
93+
+----------------------------------------------------------------------+
94+
| "2025-07-16 18:35:25" |
95+
+----------------------------------------------------------------------+
96+
```
97+
6. Non-existent path
98+
```sql
99+
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k3');
100+
```
101+
```
102+
+-----------------------------------------------+
103+
| JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k3') |
104+
+-----------------------------------------------+
105+
| NULL |
106+
+-----------------------------------------------+
107+
```
108+
7. Multiple path parameters
109+
```sql
110+
select JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id', '$.not_exists');
111+
```
112+
```
113+
+--------------------------------------------------------------------------------+
114+
| JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id', '$.not_exists') |
115+
+--------------------------------------------------------------------------------+
116+
| ["doris",123] |
117+
+--------------------------------------------------------------------------------+
118+
```
119+
> Even if there is only one match, it will be returned in array form
120+
```sql
121+
select JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id2', '$.not_exists');
122+
```
123+
```
124+
+---------------------------------------------------------------------------------+
125+
| JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id2', '$.not_exists') |
126+
+---------------------------------------------------------------------------------+
127+
| ["doris"] |
128+
+---------------------------------------------------------------------------------+
129+
```
130+
> If all paths have no matches, return NULL
131+
```sql
132+
select JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.k1', '$.k2', '$.not_exists');
133+
```
134+
```
135+
+------------------------------------------------------------------------------+
136+
| JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.k1', '$.k2', '$.not_exists') |
137+
+------------------------------------------------------------------------------+
138+
| NULL |
139+
+------------------------------------------------------------------------------+
140+
```
90141

91-
```text
92-
+------------------------------------------------------+
93-
| json_extract('{"id": 123, "name": "doris"}', '$.id') |
94-
+------------------------------------------------------+
95-
| 123 |
96-
+------------------------------------------------------+
97-
```
98-
```sql
99-
SELECT json_extract('[1, 2, 3]', '$.[1]');
100-
```
101-
```text
102-
+------------------------------------+
103-
| json_extract('[1, 2, 3]', '$.[1]') |
104-
+------------------------------------+
105-
| 2 |
106-
+------------------------------------+
107-
```
108-
```sql
109-
SELECT json_extract('{"k1": "v1", "k2": { "k21": 6.6, "k22": [1, 2] } }', '$.k1', '$.k2.k21', '$.k2.k22', '$.k2.k22[1]');
110-
```
111-
```text
112-
+-------------------------------------------------------------------------------------------------------------------+
113-
| json_extract('{"k1": "v1", "k2": { "k21": 6.6, "k22": [1, 2] } }', '$.k1', '$.k2.k21', '$.k2.k22', '$.k2.k22[1]') |
114-
+-------------------------------------------------------------------------------------------------------------------+
115-
| ["v1",6.6,[1,2],2] |
116-
+-------------------------------------------------------------------------------------------------------------------+
117-
```
118-
```sql
119-
SELECT json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name');
120-
```
121-
```text
122-
+-----------------------------------------------------------------+
123-
| json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name') |
124-
+-----------------------------------------------------------------+
125-
| [null,"doris"] |
126-
+-----------------------------------------------------------------+
127-
```
128-
```sql
129-
SELECT json_extract_no_quotes('{"id": 123, "name": "doris"}', '$.name');
130-
```
131-
```text
132-
+------------------------------------------------------------------+
133-
| json_extract_no_quotes('{"id": 123, "name": "doris"}', '$.name') |
134-
+------------------------------------------------------------------+
135-
| doris |
136-
+------------------------------------------------------------------+
137-
```
138-
```sql
139-
SELECT JSON_EXTRACT_ISNULL('{"id": 123, "name": "doris"}', '$.id');
140-
```
141-
```text
142-
+----------------------------------------------------------------------------+
143-
| jsonb_extract_isnull(cast('{"id": 123, "name": "doris"}' as JSON), '$.id') |
144-
+----------------------------------------------------------------------------+
145-
| 0 |
146-
+----------------------------------------------------------------------------+
147-
```
148-
```sql
149-
SELECT JSON_EXTRACT_BOOL('{"id": 123, "name": "NULL"}', '$.id');
150-
```
151-
```text
152-
+-------------------------------------------------------------------------+
153-
| jsonb_extract_bool(cast('{"id": 123, "name": "NULL"}' as JSON), '$.id') |
154-
+-------------------------------------------------------------------------+
155-
| NULL |
156-
+-------------------------------------------------------------------------+
157-
```
158-
```sql
159-
SELECT JSON_EXTRACT_INT('{"id": 123, "name": "NULL"}', '$.id');
160-
```
161-
```text
162-
+------------------------------------------------------------------------+
163-
| jsonb_extract_int(cast('{"id": 123, "name": "NULL"}' as JSON), '$.id') |
164-
+------------------------------------------------------------------------+
165-
| 123 |
166-
+------------------------------------------------------------------------+
167-
```
168-
```sql
169-
SELECT JSON_EXTRACT_INT('{"id": 123, "name": "doris"}', '$.name');
170-
```
171-
```text
172-
+---------------------------------------------------------------------------+
173-
| jsonb_extract_int(cast('{"id": 123, "name": "doris"}' as JSON), '$.name') |
174-
+---------------------------------------------------------------------------+
175-
| NULL |
176-
+---------------------------------------------------------------------------+
177-
```
178-
```sql
179-
SELECT JSON_EXTRACT_STRING('{"id": 123, "name": "doris"}', '$.name');
180-
```
181-
```text
182-
+------------------------------------------------------------------------------+
183-
| jsonb_extract_string(cast('{"id": 123, "name": "doris"}' as JSON), '$.name') |
184-
+------------------------------------------------------------------------------+
185-
| doris |
186-
+------------------------------------------------------------------------------+
187-
```
142+
8. Wildcard path
143+
```sql
144+
select json_extract('{"k": [1,2,3,4,5]}', '$.k[*]');
145+
```
146+
```
147+
+----------------------------------------------+
148+
| json_extract('{"k": [1,2,3,4,5]}', '$.k[*]') |
149+
+----------------------------------------------+
150+
| [1,2,3,4,5] |
151+
+----------------------------------------------+
152+
```
153+
```sql
154+
select json_extract('{"k": [1,2,3,4,5], "k2": "abc", "k3": {"k4": "v4"}}', '$.*', '$.k3.k4');
155+
```
156+
```
157+
+---------------------------------------------------------------------------------------+
158+
| json_extract('{"k": [1,2,3,4,5], "k2": "abc", "k3": {"k4": "v4"}}', '$.*', '$.k3.k4') |
159+
+---------------------------------------------------------------------------------------+
160+
| [[1,2,3,4,5],"abc",{"k4":"v4"},"v4"] |
161+
+---------------------------------------------------------------------------------------+
162+
```
163+
9. Value is NULL case
164+
```sql
165+
select JSON_EXTRACT('{"id": 123, "name": null}', '$.name') v, JSON_EXTRACT('{"id": 123, "name": null}', '$.name') is null v2;
166+
```
167+
```
168+
+------+------+
169+
| v | v2 |
170+
+------+------+
171+
| null | 0 |
172+
+------+------+
173+
```

0 commit comments

Comments
 (0)