[fix](doc) document json_extract no-auto-broadcast over arrays

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.

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` 从数组的每个元素提取字段。

i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md

@@ -20,7 +20,7 @@
 ## 别名
 * JSONB_EXTRACT 同 `JSON_EXTRACT`
 * JSONB_EXTRACT_ISNULL 同 `JSON_EXTRACT_ISNULL`
 * JSONB_EXTRACT_BOOL 同 `JSON_EXTRACT_BOOL`
 * JSONB_EXTRACT_INT 同 `JSON_EXTRACT_INT`
 * JSONB_EXTRACT_BIGINT 同 `JSON_EXTRACT_BIGINT`
 * JSONB_EXTRACT_LARGEINT 同 `JSON_EXTRACT_LARGEINT`
@@ -67,6 +67,8 @@
 * '[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

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

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 @@
     * `**` 代表通配符，通常和 '$' 一起使用： '$**' 代表所有的路径（以及多层的子路径，见下面的示例 9）。
 
 - 如果 `<path>` 存在通配符(`*`)，匹配的结果会以数组形式返回。
+- `<path>` 不会在数组上自动广播。如果 `<json_object>` 是 JSON 数组，`<path>` 为 `$.k`，结果为 NULL —— `$.k` 只会遍历 object 的成员。要按下标访问元素，使用 `$[i].k`；要从数组的每个元素中提取字段，使用通配符语法 `$[*].k`，该语法自 Doris 4.0 起支持。
 
 ## 示例
 1. 一般参数
@@ -50,7 +51,7 @@
     | JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k1') |
     +-----------------------------------------------+
     | "v31"                                         |
     +-----------------------------------------------+
     ```
     > 注意：返回的结果是`"v31"` 不是 `v31`。
 2. NULL 参数
@@ -61,7 +62,7 @@
     +----------------------------+
     | JSON_EXTRACT(null, '$.k1') |
     +----------------------------+
     | NULL                       |
     +----------------------------+
     ```
 3. `<path>` 为 NULL
@@ -72,7 +73,7 @@
     +---------------------------------------------+
     | JSON_EXTRACT('{"k1":"v31","k2":300}', NULL) |
     +---------------------------------------------+
     | NULL                                        |
     +---------------------------------------------+
     ```
 4. 多级路径
@@ -83,7 +84,7 @@
     +------------------------------------------------------------------------+
     | JSON_EXTRACT('{"k1":"v31","k2":{"sub_key": 1234.56}}', '$.k2.sub_key') |
     +------------------------------------------------------------------------+
     | 1234.56                                                                |
     +------------------------------------------------------------------------+
     ```
 5. 数组路径
@@ -94,7 +95,7 @@
     +----------------------------------------------------------------------+
     | JSON_EXTRACT(json_array("abc", 123, cast(now() as string)), '$.[2]') |
     +----------------------------------------------------------------------+
     | "2025-07-16 18:35:25"                                                |
     +----------------------------------------------------------------------+
     ```
 6. 不存在的 path
@@ -105,7 +106,7 @@
     +-----------------------------------------------+
     | JSON_EXTRACT('{"k1":"v31","k2":300}', '$.k3') |
     +-----------------------------------------------+
     | NULL                                          |
     +-----------------------------------------------+
     ```
 7. 多个路径参数
@@ -116,7 +117,7 @@
     +--------------------------------------------------------------------------------+
     | JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id', '$.not_exists') |
     +--------------------------------------------------------------------------------+
     | ["doris",123]                                                                  |
     +--------------------------------------------------------------------------------+
     ```
     > 即使只有一个匹配也会以数组形式返回
@@ -127,7 +128,7 @@
     +---------------------------------------------------------------------------------+
     | JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.name', '$.id2', '$.not_exists') |
     +---------------------------------------------------------------------------------+
     | ["doris"]                                                                       |
     +---------------------------------------------------------------------------------+
     ```
     ```sql
@@ -139,7 +140,7 @@
     | JSON_EXTRACT('{"id": 123, "name": "doris"}', '$.k1', '$.k2', '$.not_exists') |
     +------------------------------------------------------------------------------+
     | NULL                                                                         |
     +------------------------------------------------------------------------------+
     ```
 
 8. 通配符路径
@@ -185,3 +186,27 @@
     | 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` 从数组的每个元素提取字段。

versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md

@@ -21,7 +21,7 @@
 ## Alias
 * JSONB_EXTRACT is the same as JSON_EXTRACT.
 * JSONB_EXTRACT_ISNULL is the same as JSON_EXTRACT_ISNULL.
 * JSONB_EXTRACT_BOOL is the same as JSON_EXTRACT_BOOL.
 * JSONB_EXTRACT_INT is the same as JSON_EXTRACT_INT.
 * JSONB_EXTRACT_BIGINT is the same as JSON_EXTRACT_BIGINT.
 * JSONB_EXTRACT_LARGEINT is the same as JSON_EXTRACT_LARGEINT.
@@ -67,6 +67,8 @@
 - '[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.

versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md

@@ -1,4 +1,4 @@
 ---
 {
     "title": "JSON_EXTRACT",
     "language": "en",
@@ -76,6 +76,8 @@
 - '[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.

versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/json-functions/json-extract.md

@@ -1,4 +1,4 @@
 ---
 {
     "title": "JSON_EXTRACT",
     "language": "en",
@@ -38,6 +38,7 @@
     * `*` 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 @@
     | 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.