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 6d8db7f5647 [fix](doc) document json_extract no-auto-broadcast over
arrays (#3749)
6d8db7f5647 is described below
commit 6d8db7f56478c0c6e1efcd02e03d44b5e8dd4e22
Author: boluor <[email protected]>
AuthorDate: Sat May 23 05:24:29 2026 -0700
[fix](doc) document json_extract no-auto-broadcast over arrays (#3749)
## Summary
Fixes #3318. A user upgrading from Doris 2.0.2 to 2.1.11 reported that
the same SQL changed result:
\`\`\`sql
SELECT json_extract(product_specific, '\$.categoryId')
FROM ods_product_goods_full;
-- product_specific is varchar holding e.g.
[{\"categoryId\":1000},{\"categoryId\":1003},...]
-- 2.0.2 returned [1000,1003,1006,1012,2,1015]
-- 2.1.11 returns NULL
\`\`\`
The 2.1+ behavior is intentional and engine-correct: \`\$.k\` traverses
only object members and does not auto-broadcast over array elements
(aligning with MySQL's \`JSON_EXTRACT\` semantics). Verified in
[\`be/src/util/jsonb_document.h::findValue\`](https://github.com/apache/doris/blob/branch-2.1/be/src/util/jsonb_document.h)
on \`branch-2.1\`, \`branch-3.0\`, \`branch-3.1\`, \`branch-4.0\`,
\`branch-4.1\`: the \`MEMBER_CODE\` case returns \`nullptr\` when
\`pval\` is not a \`T_Object\`.
The doc previously did not call this out. This PR adds a single line to
the path-syntax section on each of the 8 maintained version pages
(current/2.1/3.x/4.x EN+zh):
- \`\$.k\` on an array returns NULL — no auto-broadcast
- Use \`\$[i].k\` for index access
- Array-wildcard broadcasting via \`\$[*].k\` was introduced in Doris
4.0 (the wildcard \`continue\` on 2.1/3.x does not actually iterate
elements — also verified in branch source)
- On 2.1 and 3.x, recommend \`LATERAL VIEW EXPLODE\` patterns for
per-element extraction
## Scope
8 files, +12 lines:
- \`docs/.../json-extract.md\`
- \`versioned_docs/version-{2.1,3.x,4.x}/.../json-extract.md\`
-
\`i18n/zh-CN/.../{current,version-2.1,version-3.x,version-4.x}/.../json-extract.md\`
No existing examples changed; no behavior change in the engine.
## Test plan
- [x] Each of the 8 pages contains the new \"no auto-broadcast\"
sentence
- [x] Dead-link check passes
- [x] Version-specific advice matches \`findValue\` source per branch
Closes #3318
---------
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
---
.../json-functions/json-extract.md | 25 ++++++++++++++++++++++
.../json-functions/json-extract.md | 25 ++++++++++++++++++++++
.../json-functions/json-extract.md | 2 ++
.../json-functions/json-extract.md | 2 ++
.../json-functions/json-extract.md | 25 ++++++++++++++++++++++
.../json-functions/json-extract.md | 2 ++
.../json-functions/json-extract.md | 2 ++
.../json-functions/json-extract.md | 25 ++++++++++++++++++++++
8 files changed, 108 insertions(+)
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 1ffbda5be99..c7e9b59e30c 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
@@ -38,6 +38,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
* `*` represents a wildcard, where `$.*` represents all members of the
root object, and `$[*]` represents all elements of the array.
* `**` is used in combination with '$', '$**' represents all paths
(including multi-level subpaths).
- If `<path>` contains wildcards (`*`), the matching results will be returned
in array form.
+- `<path>` does not auto-broadcast over arrays. If `<json_object>` is a JSON
array and `<path>` is `$.k`, the result is NULL — `$.k` only traverses object
members. To target an element by index, use `$[i].k`; to extract a field from
every element of an array, use the wildcard syntax `$[*].k`, which is supported
from Doris 4.0 onward.
## Examples
1. General parameters
@@ -185,3 +186,27 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
| null | 0 |
+------+------+
```
+
+11. Extracting a field from each element of a JSON array (Doris 4.0+)
+ ```sql
+ select json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k');
+ ```
+ ```
+ +--------------------------------------------------+
+ | json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k') |
+ +--------------------------------------------------+
+ | NULL |
+ +--------------------------------------------------+
+ ```
+ > `$.k` does not traverse arrays; it only descends into object members.
+ ```sql
+ select json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k');
+ ```
+ ```
+ +-----------------------------------------------------+
+ | json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k') |
+ +-----------------------------------------------------+
+ | [1,2,3] |
+ +-----------------------------------------------------+
+ ```
+ > Use `$[*].k` to extract the field from every element of the array.
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 04bb633631d..d0296536e5b 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
@@ -39,6 +39,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
* `**` 代表通配符，通常和 '$' 一起使用： '$**' 代表所有的路径（以及多层的子路径，见下面的示例 9）。
- 如果 `<path>` 存在通配符(`*`)，匹配的结果会以数组形式返回。
+- `<path>` 不会在数组上自动广播。如果 `<json_object>` 是 JSON 数组，`<path>` 为 `$.k`，结果为 NULL
—— `$.k` 只会遍历 object 的成员。要按下标访问元素，使用 `$[i].k`；要从数组的每个元素中提取字段，使用通配符语法
`$[*].k`，该语法自 Doris 4.0 起支持。
## 示例
1. 一般参数
@@ -185,3 +186,27 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
| null | 0 |
+------+------+
```
+
+11. 从 JSON 数组的每个元素中提取字段（Doris 4.0+）
+ ```sql
+ select json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k');
+ ```
+ ```
+ +--------------------------------------------------+
+ | json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k') |
+ +--------------------------------------------------+
+ | NULL |
+ +--------------------------------------------------+
+ ```
+ > `$.k` 不会遍历数组，只会下钻到对象的成员。
+ ```sql
+ select json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k');
+ ```
+ ```
+ +-----------------------------------------------------+
+ | json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k') |
+ +-----------------------------------------------------+
+ | [1,2,3] |
+ +-----------------------------------------------------+
+ ```
+ > 使用 `$[*].k` 从数组的每个元素提取字段。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
index f2faa89a320..ba75a7cebdf 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
@@ -67,6 +67,8 @@ JSON_EXTRACT_STRING (<json_str>, <path>)
* '[i]' 代表 json array 中下标为 i 的元素
- 获取 json_array 的最后一个元素可以用'$[last]'，倒数第二个元素可以用'$[last-1]'，以此类推。
+`<path>` 不会在数组上自动广播：如果 JSON 值是数组、`<path>` 为 `$.k`，结果为 NULL，因为 `$.k` 只会遍历
object 的成员。要按下标访问元素，使用 `$[i].k`。通过 `$[*].k` 在数组上广播取值是 Doris 4.0 引入的能力；在 2.1 和
3.x 上请改用 `LATERAL VIEW EXPLODE` 等方式逐元素展开后再 `json_extract`。
+
## 返回值
根据要提取的字段类型不同，返回目标 JSON 中 指定 JSON_PATH 的数据类型。特殊情况处理如下：
* 如果 json_path 指定的字段在 JSON 中不存在，返回 NULL
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
index 3ac08098d0d..d7ef025b6d3 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
@@ -76,6 +76,8 @@ JSON_EXTRACT_STRING (<json_str>, <path>)
* '[i]' 代表 json array 中下标为 i 的元素
- 获取 json_array 的最后一个元素可以用'$[last]'，倒数第二个元素可以用'$[last-1]'，以此类推。
+`<path>` 不会在数组上自动广播：如果 JSON 值是数组、`<path>` 为 `$.k`，结果为 NULL，因为 `$.k` 只会遍历
object 的成员。要按下标访问元素，使用 `$[i].k`。通过 `$[*].k` 在数组上广播取值是 Doris 4.0 引入的能力；在 2.1 和
3.x 上请改用 `LATERAL VIEW EXPLODE` 等方式逐元素展开后再 `json_extract`。
+
## 返回值
根据要提取的字段类型不同，返回目标 JSON 中 指定 JSON_PATH 的数据类型。特殊情况处理如下：
* 如果 json_path 指定的字段在 JSON 中不存在，返回 NULL
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 04bb633631d..d0296536e5b 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
@@ -39,6 +39,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
* `**` 代表通配符，通常和 '$' 一起使用： '$**' 代表所有的路径（以及多层的子路径，见下面的示例 9）。
- 如果 `<path>` 存在通配符(`*`)，匹配的结果会以数组形式返回。
+- `<path>` 不会在数组上自动广播。如果 `<json_object>` 是 JSON 数组，`<path>` 为 `$.k`，结果为 NULL
—— `$.k` 只会遍历 object 的成员。要按下标访问元素，使用 `$[i].k`；要从数组的每个元素中提取字段，使用通配符语法
`$[*].k`，该语法自 Doris 4.0 起支持。
## 示例
1. 一般参数
@@ -185,3 +186,27 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
| null | 0 |
+------+------+
```
+
+11. 从 JSON 数组的每个元素中提取字段（Doris 4.0+）
+ ```sql
+ select json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k');
+ ```
+ ```
+ +--------------------------------------------------+
+ | json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k') |
+ +--------------------------------------------------+
+ | NULL |
+ +--------------------------------------------------+
+ ```
+ > `$.k` 不会遍历数组，只会下钻到对象的成员。
+ ```sql
+ select json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k');
+ ```
+ ```
+ +-----------------------------------------------------+
+ | json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k') |
+ +-----------------------------------------------------+
+ | [1,2,3] |
+ +-----------------------------------------------------+
+ ```
+ > 使用 `$[*].k` 从数组的每个元素提取字段。
diff --git
a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
index fa29fd7ded9..a7e4e981f88 100644
---
a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
+++
b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
@@ -67,6 +67,8 @@ json path syntax:
- '[i]' for element of json array at index i
- Use '$[last]' to get the last element of json_array, and '$[last-1]' to
get the penultimate element, and so on.
+`<path>` does not auto-broadcast over arrays: if the JSON value is an array
and `<path>` is `$.k`, the result is NULL because `$.k` only traverses object
members. To target an element by index use `$[i].k`. Array-wildcard
broadcasting via `$[*].k` was introduced in Doris 4.0; on 2.1 and 3.x, extract
per-element values via `LATERAL VIEW EXPLODE` patterns instead.
+
## Return Values
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:
* If the field specified by json_path does not exist in the JSON, return NULL.
diff --git
a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
index b3ad42edbea..eaa6f4afe76 100644
---
a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
+++
b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md
@@ -76,6 +76,8 @@ json path syntax:
- '[i]' for element of json array at index i
- Use '$[last]' to get the last element of json_array, and '$[last-1]' to
get the penultimate element, and so on.
+`<path>` does not auto-broadcast over arrays: if the JSON value is an array
and `<path>` is `$.k`, the result is NULL because `$.k` only traverses object
members. To target an element by index use `$[i].k`. Array-wildcard
broadcasting via `$[*].k` was introduced in Doris 4.0; on 2.1 and 3.x, extract
per-element values via `LATERAL VIEW EXPLODE` patterns instead.
+
## Return Values
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:
* If the field specified by json_path does not exist in the JSON, return NULL.
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 dd9615a25c0..3f249ddbda6 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
@@ -38,6 +38,7 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
* `*` represents a wildcard, where `$.*` represents all members of the
root object, and `$[*]` represents all elements of the array.
* `**` is used in combination with '$', '$**' represents all paths
(including multi-level subpaths).
- If `<path>` contains wildcards (`*`), the matching results will be returned
in array form.
+- `<path>` does not auto-broadcast over arrays. If `<json_object>` is a JSON
array and `<path>` is `$.k`, the result is NULL — `$.k` only traverses object
members. To target an element by index, use `$[i].k`; to extract a field from
every element of an array, use the wildcard syntax `$[*].k`, which is supported
from Doris 4.0 onward.
## Examples
1. General parameters
@@ -185,3 +186,27 @@ JSON_EXTRACT (<json_object>, <path>[, <path2>, ...])
| null | 0 |
+------+------+
```
+
+11. Extracting a field from each element of a JSON array (Doris 4.0+)
+ ```sql
+ select json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k');
+ ```
+ ```
+ +--------------------------------------------------+
+ | json_extract('[{"k":1},{"k":2},{"k":3}]', '$.k') |
+ +--------------------------------------------------+
+ | NULL |
+ +--------------------------------------------------+
+ ```
+ > `$.k` does not traverse arrays; it only descends into object members.
+ ```sql
+ select json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k');
+ ```
+ ```
+ +-----------------------------------------------------+
+ | json_extract('[{"k":1},{"k":2},{"k":3}]', '$[*].k') |
+ +-----------------------------------------------------+
+ | [1,2,3] |
+ +-----------------------------------------------------+
+ ```
+ > Use `$[*].k` to extract the field from every element of the array.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
