This is an automated email from the ASF dual-hosted git repository.
morningman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new d45756a61de [docs] Document explicit JSON array field extraction in
dev and 4.x (#2885)
d45756a61de is described below
commit d45756a61de22d89dd1f7c81de28d4d1d8f1dbbd
Author: John Zhang <[email protected]>
AuthorDate: Sat Oct 17 05:41:06 2026 +0800
[docs] Document explicit JSON array field extraction in dev and 4.x (#2885)
## Summary
Show explicit JSON array traversal with $[*].k1, demonstrate that $.k1
returns SQL NULL for an array input, and distinguish STRING JSON-array
text from a SQL ARRAY. Cover missing fields in array elements and
normalize the touched parameter/output sections.
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1 or older
Dev and 4.x, English and Chinese. The examples follow the current 4.0+
JSON path implementation; historical 3.x/2.1 edits from the old proposal
are excluded.
## Languages
- [x] Chinese
- [x] English
## Validation
Reviewed against Doris master `88f22fd875e0be4dea2c58c53744f4074378a870`
and the corresponding current 4.0, 4.1, and 4.2 source branches. Rebased
onto website master `f582020241f825849ffa3b57fc3220cb674d28a7`.
- SQL function structure and internal-link checks passed for the final
changed pages.
- `git diff --check` passed.
- English and Chinese changes are synchronized. Remaining version-sync
notices are explained above.
- Doris and the website were not built; examples were checked against
source and existing regression expectations where available.
---------
Co-authored-by: morningman <[email protected]>
---
.../json-functions/json-extract-string.md | 32 +++++++++--
.../json-functions/json-extract.md | 65 +++++++++++++++-------
.../json-functions/json-extract-string.md | 32 +++++++++--
.../json-functions/json-extract.md | 65 +++++++++++++++-------
.../json-functions/json-extract-string.md | 32 +++++++++--
.../json-functions/json-extract.md | 65 +++++++++++++++-------
.../json-functions/json-extract-string.md | 32 +++++++++--
.../json-functions/json-extract.md | 65 +++++++++++++++-------
8 files changed, 292 insertions(+), 96 deletions(-)
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
index 8053bf0d546..a38cd005edd 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
@@ -15,8 +15,11 @@ JSON_EXTRACT_STRING(<json_object>, <json_path>)
```
## Parameters
-- `<json_object>`: JSON type, the target parameter to extract from.
-- `<json_path>`: String type, the JSON path to extract the target element from
the target JSON.
+
+| Parameter | Description |
+| --- | --- |
+| `<json_object>` | Required. A JSON value, or valid JSON text that can be
converted to JSON. |
+| `<json_path>` | Required. A JSON path of type STRING; use an explicit
wildcard to traverse arrays. |
## Return Value
`Nullable(STRING)` Returns the extracted STRING value, returns NULL in some
cases
@@ -40,7 +43,10 @@ If you want to check whether an element is null, please use
the function [`JSON
SELECT json_extract_string('{"id": 123, "name": "doris"}', '$.name');
```
```text
- +---------------------------------------------------------------+
+```
+
+```text
++---------------------------------------------------------------+
| json_extract_string('{"id": 123, "name": "doris"}', '$.name') |
+---------------------------------------------------------------+
| doris |
@@ -99,4 +105,22 @@ If you want to check whether an element is null, please use
the function [`JSON
+-------------------------------------------------------------+
| null |
+-------------------------------------------------------------+
- ```
\ No newline at end of file
+ ```
+
+### Extracting the same field from array elements (Doris 4.0 and later)
+
+Use `$[*].k1` to traverse array elements explicitly. `$.k1` only accesses
object members and does not implicitly traverse an array, so the direct path
below returns SQL `NULL`. Array elements without `k1` are omitted from the
matches.
+
+The result is a `STRING` containing JSON array text, rather than a SQL `ARRAY`.
+```sql
+SELECT
json_extract_string('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$.k1') AS direct_path,
+
json_extract_string('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$[*].k1') AS all_values;
+```
+
+```text
++-------------+------------------+
+| direct_path | all_values |
++-------------+------------------+
+| NULL | ["v1","v3","v4"] |
++-------------+------------------+
+```
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
index 5f589aeb9f6..bef1de4a96e 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
@@ -14,13 +14,19 @@ Extract the field specified by json_path from JSON type
data.
JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```
## Parameters
-### Required Parameters:
-- `<json_object>`: The JSON type expression to extract from.
-- `<path>`: The JSON path to extract the target element from the target JSON.
-### Optional/Variable Parameters
-- `<path2>` Multiple path values can be extracted from the JSON object.
+
+| Parameter | Description |
+| --- | --- |
+| `<json_object>` | Required. A JSON value, or valid JSON text that can be
converted to JSON. |
+| `<path>` | Required. A JSON path of type STRING; use an explicit wildcard to
traverse arrays. |
+| `<path2>, ...` | Optional additional STRING paths; matching results are
combined into a JSON array. |
+
+<a id="required-parameters"></a>
+<a id="optionalvariable-parameters"></a>
## Return Value
+
+Returns SQL `NULL` if any argument is `NULL` or no path matches.
- `Nullable(JSON)`: Returns the JSON element pointed to by `<path>`. If
multiple results are matched, they will be returned as a JSON array.
## Usage Notes
@@ -45,8 +51,11 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k1');
```
- ```
- +-----------------------------------------------+
+ ```text
+```
+
+```text
++-----------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k1') |
+-----------------------------------------------+
| "v31" |
@@ -57,7 +66,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT(null, '$.k1');
```
- ```
+ ```text
+----------------------------+
| JSON_EXTRACT(null, '$.k1') |
+----------------------------+
@@ -68,7 +77,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', NULL);
```
- ```
+ ```text
+---------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":300}', NULL) |
+---------------------------------------------+
@@ -79,7 +88,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":{"sub_key": 1234.56}}',
'$.k2.sub_key');
```
- ```
+ ```text
+------------------------------------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":{"sub_key": 1234.56}}', '$.k2.sub_key') |
+------------------------------------------------------------------------+
@@ -90,7 +99,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT(json_array("abc", 123, cast(now() as string)), '$[2]');
```
- ```
+ ```text
+----------------------------------------------------------------------+
| JSON_EXTRACT(json_array("abc", 123, cast(now() as string)), '$[2]') |
+----------------------------------------------------------------------+
@@ -101,7 +110,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k3');
```
- ```
+ ```text
+-----------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k3') |
+-----------------------------------------------+
@@ -112,7 +121,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id',
'$.not_exists');
```
- ```
+ ```text
+--------------------------------------------------------------------------------+
| JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id',
'$.not_exists') |
+--------------------------------------------------------------------------------+
@@ -123,7 +132,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name');
```
- ```
+ ```text
+-----------------------------------------------------------------+
| json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name') |
+-----------------------------------------------------------------+
@@ -134,7 +143,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.k1', '$.k2',
'$.not_exists');
```
- ```
+ ```text
+------------------------------------------------------------------------------+
| JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.k1', '$.k2',
'$.not_exists') |
+------------------------------------------------------------------------------+
@@ -146,7 +155,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('{"k": [1,2,3,4,5]}', '$.k[*]');
```
- ```
+ ```text
+----------------------------------------------+
| json_extract('{"k": [1,2,3,4,5]}', '$.k[*]') |
+----------------------------------------------+
@@ -156,7 +165,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('{"k": [1,2,3,4,5], "k2": "abc", "k3": {"k4": "v4"}}',
'$.*', '$.k3.k4');
```
- ```
+ ```text
+---------------------------------------------------------------------------------------+
| json_extract('{"k": [1,2,3,4,5], "k2": "abc", "k3": {"k4": "v4"}}',
'$.*', '$.k3.k4') |
+---------------------------------------------------------------------------------------+
@@ -179,7 +188,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT('{"id": 123, "name": null}', '$.name') v,
JSON_EXTRACT('{"id": 123, "name": null}', '$.name') is null v2;
```
- ```
+ ```text
+------+------+
| v | v2 |
+------+------+
@@ -191,7 +200,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k');
```
- ```
+ ```text
+--------------------------------------------------+
| json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k') |
+--------------------------------------------------+
@@ -202,7 +211,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k');
```
- ```
+ ```text
+-----------------------------------------------------+
| json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k') |
+-----------------------------------------------------+
@@ -210,3 +219,19 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
+-----------------------------------------------------+
```
> Use `$[*].k` to extract the field from every element of the array.
+
+### Extracting the same field from array elements (Doris 4.0 and later)
+
+Use `$[*].k1` to traverse array elements explicitly. `$.k1` only accesses
object members and does not implicitly traverse an array, so the direct path
below returns SQL `NULL`. Array elements without `k1` are omitted from the
matches.
+```sql
+SELECT json_extract('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$.k1') AS direct_path,
+ json_extract('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$[*].k1') AS all_values;
+```
+
+```text
++-------------+------------------+
+| direct_path | all_values |
++-------------+------------------+
+| NULL | ["v1","v3","v4"] |
++-------------+------------------+
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
index b6555f6c33e..dc3eb1f0a22 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
@@ -15,8 +15,11 @@ JSON_EXTRACT_STRING(<json_object>, <json_path>)
```
## 参数
-- `<json_object>` JSON 类型，要提取的目标参数。
-- `<json_path>` String 类型，要从目标 JSON 中提取目标元素的 JSON 路径。
+
+| 参数 | 描述 |
+| --- | --- |
+| `<json_object>` | 必需。JSON 值，或可转换为 JSON 的合法 JSON 字符串。 |
+| `<json_path>` | 必需。STRING 类型的 JSON 路径；数组遍历使用显式通配符。 |
## 返回值
`Nullable(STRING)` 返回提取出的 STRING 值，某些情况会得到 NULL
@@ -39,7 +42,10 @@ JSON_EXTRACT_STRING(<json_object>, <json_path>)
SELECT json_extract_string('{"id": 123, "name": "doris"}', '$.name');
```
```text
- +---------------------------------------------------------------+
+```
+
+```text
++---------------------------------------------------------------+
| json_extract_string('{"id": 123, "name": "doris"}', '$.name') |
+---------------------------------------------------------------+
| doris |
@@ -98,4 +104,22 @@ JSON_EXTRACT_STRING(<json_object>, <json_path>)
+-------------------------------------------------------------+
| null |
+-------------------------------------------------------------+
- ```
\ No newline at end of file
+ ```
+
+### 提取数组中的同名字段（Doris 4.0 及后续版本）
+
+使用 `$[*].k1` 显式遍历数组元素；`$.k1` 只访问对象成员，不会隐式遍历数组，因此下面的直接路径返回 SQL `NULL`。没有 `k1`
的数组元素会被忽略。
+
+返回值是包含 JSON 数组文本的 `STRING`，不是 SQL `ARRAY`。
+```sql
+SELECT
json_extract_string('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$.k1') AS direct_path,
+
json_extract_string('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$[*].k1') AS all_values;
+```
+
+```text
++-------------+------------------+
+| direct_path | all_values |
++-------------+------------------+
+| NULL | ["v1","v3","v4"] |
++-------------+------------------+
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
index 2e7bb69a762..a68dd979f80 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
@@ -14,13 +14,19 @@
JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```
## 参数
-### 必须参数：
-- `<json_object>`: 要提取的 JSON 类型的表达式。
-- `<path>`: 要从目标 JSON 中提取目标元素的 JSON 路径。
-### 可选/可变参数
-- `<path2>` 可以从 JSON 对象中提取多个路径的值。
+
+| 参数 | 描述 |
+| --- | --- |
+| `<json_object>` | 必需。JSON 值，或可转换为 JSON 的合法 JSON 字符串。 |
+| `<path>` | 必需。STRING 类型的 JSON 路径；数组遍历使用显式通配符。 |
+| `<path2>, ...` | 可选。其他 STRING 类型路径；匹配结果组合为 JSON 数组。 |
+
+<a id="required-parameters"></a>
+<a id="optionalvariable-parameters"></a>
## 返回值
+
+任一参数为 `NULL`，或所有路径均没有匹配值时，返回 SQL `NULL`。
- `Nullable(JSON)`: 返回 `<path>` 指向的 JSON 元素，如果匹配了多个结果会以 JSON 数组的形式返回。
## 使用说明
@@ -46,8 +52,11 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k1');
```
- ```
- +-----------------------------------------------+
+ ```text
+```
+
+```text
++-----------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k1') |
+-----------------------------------------------+
| "v31" |
@@ -58,7 +67,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT(null, '$.k1');
```
- ```
+ ```text
+----------------------------+
| JSON_EXTRACT(null, '$.k1') |
+----------------------------+
@@ -69,7 +78,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', NULL);
```
- ```
+ ```text
+---------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":300}', NULL) |
+---------------------------------------------+
@@ -80,7 +89,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":{"sub_key": 1234.56}}',
'$.k2.sub_key');
```
- ```
+ ```text
+------------------------------------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":{"sub_key": 1234.56}}', '$.k2.sub_key') |
+------------------------------------------------------------------------+
@@ -91,7 +100,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT(json_array("abc", 123, cast(now() as string)), '$[2]');
```
- ```
+ ```text
+----------------------------------------------------------------------+
| JSON_EXTRACT(json_array("abc", 123, cast(now() as string)), '$.[2]') |
+----------------------------------------------------------------------+
@@ -102,7 +111,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k3');
```
- ```
+ ```text
+-----------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k3') |
+-----------------------------------------------+
@@ -113,7 +122,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id',
'$.not_exists');
```
- ```
+ ```text
+--------------------------------------------------------------------------------+
| JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id',
'$.not_exists') |
+--------------------------------------------------------------------------------+
@@ -124,7 +133,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name');
```
- ```
+ ```text
+-----------------------------------------------------------------+
| json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name') |
+-----------------------------------------------------------------+
@@ -135,7 +144,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
> 如果所有路径都没有匹配则返回 NULL
select JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.k1', '$.k2',
'$.not_exists');
```
- ```
+ ```text
+------------------------------------------------------------------------------+
| JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.k1', '$.k2',
'$.not_exists') |
+------------------------------------------------------------------------------+
@@ -147,7 +156,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('{"k": [1,2,3,4,5]}', '$.k[*]');
```
- ```
+ ```text
+----------------------------------------------+
| json_extract('{"k": [1,2,3,4,5]}', '$.k[*]') |
+----------------------------------------------+
@@ -157,7 +166,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('{"k": [1,2,3,4,5], "k2": "abc", "k3": {"k4": "v4"}}',
'$.*', '$.k3.k4');
```
- ```
+ ```text
+---------------------------------------------------------------------------------------+
| json_extract('{"k": [1,2,3,4,5], "k2": "abc", "k3": {"k4": "v4"}}',
'$.*', '$.k3.k4') |
+---------------------------------------------------------------------------------------+
@@ -179,7 +188,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT('{"id": 123, "name": null}', '$.name') v,
JSON_EXTRACT('{"id": 123, "name": null}', '$.name') is null v2;
```
- ```
+ ```text
+------+------+
| v | v2 |
+------+------+
@@ -191,7 +200,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k');
```
- ```
+ ```text
+--------------------------------------------------+
| json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k') |
+--------------------------------------------------+
@@ -202,7 +211,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k');
```
- ```
+ ```text
+-----------------------------------------------------+
| json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k') |
+-----------------------------------------------------+
@@ -210,3 +219,19 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
+-----------------------------------------------------+
```
> 使用 `$[*].k` 从数组的每个元素提取字段。
+
+### 提取数组中的同名字段（Doris 4.0 及后续版本）
+
+使用 `$[*].k1` 显式遍历数组元素；`$.k1` 只访问对象成员，不会隐式遍历数组，因此下面的直接路径返回 SQL `NULL`。没有 `k1`
的数组元素会被忽略。
+```sql
+SELECT json_extract('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$.k1') AS direct_path,
+ json_extract('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$[*].k1') AS all_values;
+```
+
+```text
++-------------+------------------+
+| direct_path | all_values |
++-------------+------------------+
+| NULL | ["v1","v3","v4"] |
++-------------+------------------+
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
index b6555f6c33e..dc3eb1f0a22 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
@@ -15,8 +15,11 @@ JSON_EXTRACT_STRING(<json_object>, <json_path>)
```
## 参数
-- `<json_object>` JSON 类型，要提取的目标参数。
-- `<json_path>` String 类型，要从目标 JSON 中提取目标元素的 JSON 路径。
+
+| 参数 | 描述 |
+| --- | --- |
+| `<json_object>` | 必需。JSON 值，或可转换为 JSON 的合法 JSON 字符串。 |
+| `<json_path>` | 必需。STRING 类型的 JSON 路径；数组遍历使用显式通配符。 |
## 返回值
`Nullable(STRING)` 返回提取出的 STRING 值，某些情况会得到 NULL
@@ -39,7 +42,10 @@ JSON_EXTRACT_STRING(<json_object>, <json_path>)
SELECT json_extract_string('{"id": 123, "name": "doris"}', '$.name');
```
```text
- +---------------------------------------------------------------+
+```
+
+```text
++---------------------------------------------------------------+
| json_extract_string('{"id": 123, "name": "doris"}', '$.name') |
+---------------------------------------------------------------+
| doris |
@@ -98,4 +104,22 @@ JSON_EXTRACT_STRING(<json_object>, <json_path>)
+-------------------------------------------------------------+
| null |
+-------------------------------------------------------------+
- ```
\ No newline at end of file
+ ```
+
+### 提取数组中的同名字段（Doris 4.0 及后续版本）
+
+使用 `$[*].k1` 显式遍历数组元素；`$.k1` 只访问对象成员，不会隐式遍历数组，因此下面的直接路径返回 SQL `NULL`。没有 `k1`
的数组元素会被忽略。
+
+返回值是包含 JSON 数组文本的 `STRING`，不是 SQL `ARRAY`。
+```sql
+SELECT
json_extract_string('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$.k1') AS direct_path,
+
json_extract_string('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$[*].k1') AS all_values;
+```
+
+```text
++-------------+------------------+
+| direct_path | all_values |
++-------------+------------------+
+| NULL | ["v1","v3","v4"] |
++-------------+------------------+
+```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
index 2e7bb69a762..a68dd979f80 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
@@ -14,13 +14,19 @@
JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```
## 参数
-### 必须参数：
-- `<json_object>`: 要提取的 JSON 类型的表达式。
-- `<path>`: 要从目标 JSON 中提取目标元素的 JSON 路径。
-### 可选/可变参数
-- `<path2>` 可以从 JSON 对象中提取多个路径的值。
+
+| 参数 | 描述 |
+| --- | --- |
+| `<json_object>` | 必需。JSON 值，或可转换为 JSON 的合法 JSON 字符串。 |
+| `<path>` | 必需。STRING 类型的 JSON 路径；数组遍历使用显式通配符。 |
+| `<path2>, ...` | 可选。其他 STRING 类型路径；匹配结果组合为 JSON 数组。 |
+
+<a id="required-parameters"></a>
+<a id="optionalvariable-parameters"></a>
## 返回值
+
+任一参数为 `NULL`，或所有路径均没有匹配值时，返回 SQL `NULL`。
- `Nullable(JSON)`: 返回 `<path>` 指向的 JSON 元素，如果匹配了多个结果会以 JSON 数组的形式返回。
## 使用说明
@@ -46,8 +52,11 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k1');
```
- ```
- +-----------------------------------------------+
+ ```text
+```
+
+```text
++-----------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k1') |
+-----------------------------------------------+
| "v31" |
@@ -58,7 +67,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT(null, '$.k1');
```
- ```
+ ```text
+----------------------------+
| JSON_EXTRACT(null, '$.k1') |
+----------------------------+
@@ -69,7 +78,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', NULL);
```
- ```
+ ```text
+---------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":300}', NULL) |
+---------------------------------------------+
@@ -80,7 +89,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":{"sub_key": 1234.56}}',
'$.k2.sub_key');
```
- ```
+ ```text
+------------------------------------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":{"sub_key": 1234.56}}', '$.k2.sub_key') |
+------------------------------------------------------------------------+
@@ -91,7 +100,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT(json_array("abc", 123, cast(now() as string)), '$[2]');
```
- ```
+ ```text
+----------------------------------------------------------------------+
| JSON_EXTRACT(json_array("abc", 123, cast(now() as string)), '$.[2]') |
+----------------------------------------------------------------------+
@@ -102,7 +111,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k3');
```
- ```
+ ```text
+-----------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k3') |
+-----------------------------------------------+
@@ -113,7 +122,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id',
'$.not_exists');
```
- ```
+ ```text
+--------------------------------------------------------------------------------+
| JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id',
'$.not_exists') |
+--------------------------------------------------------------------------------+
@@ -124,7 +133,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name');
```
- ```
+ ```text
+-----------------------------------------------------------------+
| json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name') |
+-----------------------------------------------------------------+
@@ -135,7 +144,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
> 如果所有路径都没有匹配则返回 NULL
select JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.k1', '$.k2',
'$.not_exists');
```
- ```
+ ```text
+------------------------------------------------------------------------------+
| JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.k1', '$.k2',
'$.not_exists') |
+------------------------------------------------------------------------------+
@@ -147,7 +156,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('{"k": [1,2,3,4,5]}', '$.k[*]');
```
- ```
+ ```text
+----------------------------------------------+
| json_extract('{"k": [1,2,3,4,5]}', '$.k[*]') |
+----------------------------------------------+
@@ -157,7 +166,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('{"k": [1,2,3,4,5], "k2": "abc", "k3": {"k4": "v4"}}',
'$.*', '$.k3.k4');
```
- ```
+ ```text
+---------------------------------------------------------------------------------------+
| json_extract('{"k": [1,2,3,4,5], "k2": "abc", "k3": {"k4": "v4"}}',
'$.*', '$.k3.k4') |
+---------------------------------------------------------------------------------------+
@@ -179,7 +188,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT('{"id": 123, "name": null}', '$.name') v,
JSON_EXTRACT('{"id": 123, "name": null}', '$.name') is null v2;
```
- ```
+ ```text
+------+------+
| v | v2 |
+------+------+
@@ -191,7 +200,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k');
```
- ```
+ ```text
+--------------------------------------------------+
| json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k') |
+--------------------------------------------------+
@@ -202,7 +211,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k');
```
- ```
+ ```text
+-----------------------------------------------------+
| json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k') |
+-----------------------------------------------------+
@@ -210,3 +219,19 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
+-----------------------------------------------------+
```
> 使用 `$[*].k` 从数组的每个元素提取字段。
+
+### 提取数组中的同名字段（Doris 4.0 及后续版本）
+
+使用 `$[*].k1` 显式遍历数组元素；`$.k1` 只访问对象成员，不会隐式遍历数组，因此下面的直接路径返回 SQL `NULL`。没有 `k1`
的数组元素会被忽略。
+```sql
+SELECT json_extract('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$.k1') AS direct_path,
+ json_extract('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$[*].k1') AS all_values;
+```
+
+```text
++-------------+------------------+
+| direct_path | all_values |
++-------------+------------------+
+| NULL | ["v1","v3","v4"] |
++-------------+------------------+
+```
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
index 8053bf0d546..a38cd005edd 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract-string.md
@@ -15,8 +15,11 @@ JSON_EXTRACT_STRING(<json_object>, <json_path>)
```
## Parameters
-- `<json_object>`: JSON type, the target parameter to extract from.
-- `<json_path>`: String type, the JSON path to extract the target element from
the target JSON.
+
+| Parameter | Description |
+| --- | --- |
+| `<json_object>` | Required. A JSON value, or valid JSON text that can be
converted to JSON. |
+| `<json_path>` | Required. A JSON path of type STRING; use an explicit
wildcard to traverse arrays. |
## Return Value
`Nullable(STRING)` Returns the extracted STRING value, returns NULL in some
cases
@@ -40,7 +43,10 @@ If you want to check whether an element is null, please use
the function [`JSON
SELECT json_extract_string('{"id": 123, "name": "doris"}', '$.name');
```
```text
- +---------------------------------------------------------------+
+```
+
+```text
++---------------------------------------------------------------+
| json_extract_string('{"id": 123, "name": "doris"}', '$.name') |
+---------------------------------------------------------------+
| doris |
@@ -99,4 +105,22 @@ If you want to check whether an element is null, please use
the function [`JSON
+-------------------------------------------------------------+
| null |
+-------------------------------------------------------------+
- ```
\ No newline at end of file
+ ```
+
+### Extracting the same field from array elements (Doris 4.0 and later)
+
+Use `$[*].k1` to traverse array elements explicitly. `$.k1` only accesses
object members and does not implicitly traverse an array, so the direct path
below returns SQL `NULL`. Array elements without `k1` are omitted from the
matches.
+
+The result is a `STRING` containing JSON array text, rather than a SQL `ARRAY`.
+```sql
+SELECT
json_extract_string('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$.k1') AS direct_path,
+
json_extract_string('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$[*].k1') AS all_values;
+```
+
+```text
++-------------+------------------+
+| direct_path | all_values |
++-------------+------------------+
+| NULL | ["v1","v3","v4"] |
++-------------+------------------+
+```
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
index 5f589aeb9f6..bef1de4a96e 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
@@ -14,13 +14,19 @@ Extract the field specified by json_path from JSON type
data.
JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```
## Parameters
-### Required Parameters:
-- `<json_object>`: The JSON type expression to extract from.
-- `<path>`: The JSON path to extract the target element from the target JSON.
-### Optional/Variable Parameters
-- `<path2>` Multiple path values can be extracted from the JSON object.
+
+| Parameter | Description |
+| --- | --- |
+| `<json_object>` | Required. A JSON value, or valid JSON text that can be
converted to JSON. |
+| `<path>` | Required. A JSON path of type STRING; use an explicit wildcard to
traverse arrays. |
+| `<path2>, ...` | Optional additional STRING paths; matching results are
combined into a JSON array. |
+
+<a id="required-parameters"></a>
+<a id="optionalvariable-parameters"></a>
## Return Value
+
+Returns SQL `NULL` if any argument is `NULL` or no path matches.
- `Nullable(JSON)`: Returns the JSON element pointed to by `<path>`. If
multiple results are matched, they will be returned as a JSON array.
## Usage Notes
@@ -45,8 +51,11 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k1');
```
- ```
- +-----------------------------------------------+
+ ```text
+```
+
+```text
++-----------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k1') |
+-----------------------------------------------+
| "v31" |
@@ -57,7 +66,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT(null, '$.k1');
```
- ```
+ ```text
+----------------------------+
| JSON_EXTRACT(null, '$.k1') |
+----------------------------+
@@ -68,7 +77,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', NULL);
```
- ```
+ ```text
+---------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":300}', NULL) |
+---------------------------------------------+
@@ -79,7 +88,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":{"sub_key": 1234.56}}',
'$.k2.sub_key');
```
- ```
+ ```text
+------------------------------------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":{"sub_key": 1234.56}}', '$.k2.sub_key') |
+------------------------------------------------------------------------+
@@ -90,7 +99,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT(json_array("abc", 123, cast(now() as string)), '$[2]');
```
- ```
+ ```text
+----------------------------------------------------------------------+
| JSON_EXTRACT(json_array("abc", 123, cast(now() as string)), '$[2]') |
+----------------------------------------------------------------------+
@@ -101,7 +110,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k3');
```
- ```
+ ```text
+-----------------------------------------------+
| JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k3') |
+-----------------------------------------------+
@@ -112,7 +121,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id',
'$.not_exists');
```
- ```
+ ```text
+--------------------------------------------------------------------------------+
| JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id',
'$.not_exists') |
+--------------------------------------------------------------------------------+
@@ -123,7 +132,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
SELECT json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name');
```
- ```
+ ```text
+-----------------------------------------------------------------+
| json_extract('{"id": 123, "name": "doris"}', '$.aaa', '$.name') |
+-----------------------------------------------------------------+
@@ -134,7 +143,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.k1', '$.k2',
'$.not_exists');
```
- ```
+ ```text
+------------------------------------------------------------------------------+
| JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.k1', '$.k2',
'$.not_exists') |
+------------------------------------------------------------------------------+
@@ -146,7 +155,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('{"k": [1,2,3,4,5]}', '$.k[*]');
```
- ```
+ ```text
+----------------------------------------------+
| json_extract('{"k": [1,2,3,4,5]}', '$.k[*]') |
+----------------------------------------------+
@@ -156,7 +165,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('{"k": [1,2,3,4,5], "k2": "abc", "k3": {"k4": "v4"}}',
'$.*', '$.k3.k4');
```
- ```
+ ```text
+---------------------------------------------------------------------------------------+
| json_extract('{"k": [1,2,3,4,5], "k2": "abc", "k3": {"k4": "v4"}}',
'$.*', '$.k3.k4') |
+---------------------------------------------------------------------------------------+
@@ -179,7 +188,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select JSON_EXTRACT('{"id": 123, "name": null}', '$.name') v,
JSON_EXTRACT('{"id": 123, "name": null}', '$.name') is null v2;
```
- ```
+ ```text
+------+------+
| v | v2 |
+------+------+
@@ -191,7 +200,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k');
```
- ```
+ ```text
+--------------------------------------------------+
| json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k') |
+--------------------------------------------------+
@@ -202,7 +211,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
```sql
select json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k');
```
- ```
+ ```text
+-----------------------------------------------------+
| json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k') |
+-----------------------------------------------------+
@@ -210,3 +219,19 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
+-----------------------------------------------------+
```
> Use `$[*].k` to extract the field from every element of the array.
+
+### Extracting the same field from array elements (Doris 4.0 and later)
+
+Use `$[*].k1` to traverse array elements explicitly. `$.k1` only accesses
object members and does not implicitly traverse an array, so the direct path
below returns SQL `NULL`. Array elements without `k1` are omitted from the
matches.
+```sql
+SELECT json_extract('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$.k1') AS direct_path,
+ json_extract('[{"k1":"v1"},{"k2":"v2"},{"k1":"v3"},{"k1":"v4"}]',
'$[*].k1') AS all_values;
+```
+
+```text
++-------------+------------------+
+| direct_path | all_values |
++-------------+------------------+
+| NULL | ["v1","v3","v4"] |
++-------------+------------------+
+```
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
