This is an automated email from the ASF dual-hosted git repository.
mrhhsg 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 26a1965e377 update json_search (#2626)
26a1965e377 is described below
commit 26a1965e3778d397902c671bc149ff0acf5ae30b
Author: Jerry Hu <[email protected]>
AuthorDate: Tue Jul 15 15:47:58 2025 +0800
update json_search (#2626)
## Versions
- [x] dev
- [ ] 3.0
- [ ] 2.1
- [ ] 2.0
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../scalar-functions/json-functions/json-search.md | 179 +++++++++++----------
.../scalar-functions/json-functions/json-search.md | 176 +++++++++++---------
2 files changed, 194 insertions(+), 161 deletions(-)
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-search.md
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-search.md
index 06eb705186b..2fe68beba05 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-search.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/json-functions/json-search.md
@@ -7,96 +7,113 @@
## Description
-The `JSON_SEARCH` function is used to search for a specified value within a
JSON document. If the value is found, it returns the path to the value. If the
value is not found, it returns `NULL`. This function can recursively search
through the JSON data structure.
+The `JSON_SEARCH` function is used to search for specified values in a JSON
document. If the value is found, it returns the path to the value. If the value
is not found, it returns NULL. This function can recursively search within JSON
data structures.
## Syntax
```sql
-JSON_SEARCH(<str>, <one_or_all>, <search_value> [, <start_path> [,
<escape_char>]])
+JSON_SEARCH( <json_object>, <one_or_all>, <search_value> )
```
-
-## Required Parameters
-
-| parameters| described|
-|------|------|
-| `<str>`| The JSON document to search (can be a JSON string or JSON object). |
-| `<one_or_all>` | Specifies whether to find all matching values. It can be
'one' or 'all'. |
-|`<search_value>`|The value to search for.|
-
-## Optional Parameters
-
-| parameters| described|
-|------|------|
-| `<start_path>`| Specifies the path to start searching from. If not provided,
the search starts from the entire JSON document. |
-| `<escape_char>` | Specifies the character to escape special characters in
the path. |
+## Parameters
+- `<json_object>`: JSON type, the JSON document to be searched.
+- `<one_or_all>`: String type, specifies whether to find all matching values.
Can be 'one' or 'all'.
+- `<search_value>`: String type, the value to search for, the search target.
## Return Value
+Nullable(JSON): Depending on the `<one_or_all>` parameter, there are two cases:
-- If a matching value is found, it returns a JSON path (as a string) pointing
to the matched value.
-- If no matching value is found, it returns NULL.
+ 1. 'one': If a matching value is found, returns a JSON path pointing to
the matching value. If no matching value is found, returns NULL.
+ 2. 'all': Returns paths to all matching values. If there are multiple
values, returns them as a JSON array. If no matches are found, returns NULL.
-## Usage Notes
-The one_or_all parameter determines whether to find all matching values. 'one'
returns the first matching path, while 'all' returns all matching paths.
-If no matching values are found, the function returns NULL.
-The start_path parameter can limit the search range, making the query more
efficient.
+## Notes
+- The `one_or_all` parameter determines whether to find all matching values.
'one' returns the first matching path, 'all' returns all matching paths. If
it's any other value, an error will be reported.
+- If no matching value is found, the function returns NULL.
+- If any of `<json_object>`, `<one_or_all>`, `<search_value>` is NULL, returns
NULL.
## Examples
-1. Search for a value (one):
-
-```sql
-SELECT JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'John');
-
-```
-```sql
-+-----------------------------------------------+
-| JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'John') |
-+-----------------------------------------------+
-| $.name |
-+-----------------------------------------------+
-
-```
-2. Search for multiple matching values (all):
-
-```sql
-SELECT JSON_SEARCH('{"person": {"name": "John", "age": 30}, "name": "John"}',
'all', 'John');
-
-
-```
-```sql
-+---------------------------------------------------------------+
-| JSON_SEARCH('{"person": {"name": "John", "age": 30}, "name": "John"}',
'all', 'John') |
-+---------------------------------------------------------------+
-| $.name |
-| $.person.name |
-+---------------------------------------------------------------+
-```
-3. No matching value found:
-
-```sql
-SELECT JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'Alice');
-
-```
-```sql
-+-----------------------------------------------+
-| JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'Alice') |
-+-----------------------------------------------+
-| NULL |
-+-----------------------------------------------+
-
-```
-
-4. Specify the starting search path:
-
-```sql
-SELECT JSON_SEARCH('{"person": {"name": "John", "age": 30}}', 'one', 'John',
'$.person');
-
-```
-```sql
-+---------------------------------------------------------------+
-| JSON_SEARCH('{"person": {"name": "John", "age": 30}}', 'one', 'John',
'$.person') |
-+---------------------------------------------------------------+
-| $.name |
-+---------------------------------------------------------------+
-
-```
\ No newline at end of file
+1. Search for a single value (one)
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'John');
+ ```
+ ```text
+ +-----------------------------------------------------------+
+ | JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'John') |
+ +-----------------------------------------------------------+
+ | "$.name" |
+ +-----------------------------------------------------------+
+
+ ```
+2. Search for a single value (one), returns only one path even if there are
multiple matches
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30, "alias": "John"}', 'one',
'John');
+ ```
+ ```text
+
+----------------------------------------------------------------------------+
+ | JSON_SEARCH('{"name": "John", "age": 30, "alias": "John"}', 'one',
'John') |
+
+----------------------------------------------------------------------------+
+ | "$.name"
|
+
+----------------------------------------------------------------------------+
+ ```
+3. Search for all matching values (all)
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30, "alias": "John"}', 'all',
'John');
+ ```
+ ```text
+
+----------------------------------------------------------------------------+
+ | JSON_SEARCH('{"name": "John", "age": 30, "alias": "John"}', 'all',
'John') |
+
+----------------------------------------------------------------------------+
+ | ["$.alias","$.name"]
|
+
+----------------------------------------------------------------------------+
+ ```
+4. No matching value found
+
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'Alice');
+ ```
+ ```text
+ +------------------------------------------------------------+
+ | JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'Alice') |
+ +------------------------------------------------------------+
+ | NULL |
+ +------------------------------------------------------------+
+ ```
+
+5. NULL parameters
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30}', NULL, 'Alice');
+ ```
+ ```text
+ +-----------------------------------------------------------+
+ | JSON_SEARCH('{"name": "John", "age": 30}', NULL, 'Alice') |
+ +-----------------------------------------------------------+
+ | NULL |
+ +-----------------------------------------------------------+
+ ```
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30}', 'one', NULL);
+ ```
+ ```text
+ +---------------------------------------------------------+
+ | JSON_SEARCH('{"name": "John", "age": 30}', 'one', NULL) |
+ +---------------------------------------------------------+
+ | NULL |
+ +---------------------------------------------------------+
+ ```
+ ```sql
+ SELECT JSON_SEARCH(NULL, 'one', 'Alice');
+ ```
+ ```
+ +-----------------------------------+
+ | JSON_SEARCH(NULL, 'one', 'Alice') |
+ +-----------------------------------+
+ | NULL |
+ +-----------------------------------+
+ ```
+6. Invalid `<one_or_all>` parameter
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30}', 'three', 'Alice');
+ ```
+ ```text
+ ERROR 1105 (HY000): errCode = 2, detailMessage = [INVALID_ARGUMENT]the
one_or_all argument three is not 'one' not 'all'
+ ```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-search.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-search.md
index 4d980a8d03c..1b8e6d960e2 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-search.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/json-functions/json-search.md
@@ -7,97 +7,113 @@
## 描述
-`JSON_SEARCH` 函数用于在 JSON 文档中查找指定的值。如果找到该值，则返回值的路径。如果没有找到该值，则返回 `NULL`。该函数可以在
JSON 数据结构中递归查找。
-
+`JSON_SEARCH` 函数用于在 JSON 文档中查找指定的值。如果找到该值，则返回值的路径。如果没有找到该值，则返回 NULL。该函数可以在
JSON 数据结构中递归查找。
## 语法
```sql
-JSON_SEARCH(<str>, <one_or_all>, <search_value> [, <start_path> [,
<escape_char>]])
+JSON_SEARCH( <json_object>, <one_or_all>, <search_value> )
```
## 必选参数
-
-| 参数 | 描述 |
-|------|------|
-| `<str>` | 需要搜索的 JSON 文档（可以是 JSON 字符串或 JSON 对象）。 |
-| `<one_or_all>` | 指定是否查找所有匹配的值。可以取值 'one' 或 'all'。 |
-| `<search_value>` | 需要查找的值，搜索目标。 |
-
-
-## 可选参数
-
-| 参数 | 描述 |
-|------|------|
-| `<start_path>` | 指定开始搜索的路径。如果没有提供，则从整个 JSON 文档开始搜索。 |
-| `<escape_char>` | 指定用于转义路径中的特殊字符。 |
+- `<json_object>`: JSON 类型，需要搜索的 JSON 文档。
+- `<one_or_all>`: String 类型，指定是否查找所有匹配的值。可以取值 'one' 或 'all'。
+- `<search_value>`: String 类型，需要查找的值，搜索目标。
## 返回值
+Nullable(JSON)： 根据参数 `<one_or_all>` 不同有两种情况：
-如果找到匹配的值，返回一个 JSON 路径（字符串类型），指向匹配的值。
-如果没有找到匹配的值，返回 NULL。
+ 1. 'one' 如果找到匹配的值，返回一个 JSON 路径，指向匹配的值。 如果没有找到匹配的值，返回 NULL。
+ 2. 'all' 返回所有匹配值的路径，如果有多个值，以 JSON 数组的形式返回，如果没有匹配返回 NULL。
## 注意事项
-`one_or_all` 参数决定了是否查找所有匹配的值。'one' 会返回第一个匹配的路径，'all' 会返回所有匹配的路径。
-如果没有找到匹配值，函数会返回 NULL。
-使用 `start_path` 参数可以限制搜索的范围，使得查询更加高效。
+- `one_or_all` 参数决定了是否查找所有匹配的值。'one' 会返回第一个匹配的路径，'all' 会返回所有匹配的路径。
如果是其他值，会得到报错。
+- 如果没有找到匹配值，函数会返回 NULL。
+- `<json_object>`, `<one_or_all>`, `<search_value>` 任意一个为 NULL 值时返回 NULL.
## 示例
-1. 查找一个值（one）：
-```sql
-SELECT JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'John');
-
-```
-```sql
-+-----------------------------------------------+
-| JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'John') |
-+-----------------------------------------------+
-| $.name |
-+-----------------------------------------------+
-
-```
-2. 查找多个匹配值（all）：
-
-```sql
-SELECT JSON_SEARCH('{"person": {"name": "John", "age": 30}, "name": "John"}',
'all', 'John');
-
-
-```
-```sql
-+---------------------------------------------------------------+
-| JSON_SEARCH('{"person": {"name": "John", "age": 30}, "name": "John"}',
'all', 'John') |
-+---------------------------------------------------------------+
-| $.name |
-| $.person.name |
-+---------------------------------------------------------------+
-```
-3. 没有找到匹配值：
-
-```sql
-SELECT JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'Alice');
-
-```
-```sql
-+-----------------------------------------------+
-| JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'Alice') |
-+-----------------------------------------------+
-| NULL |
-+-----------------------------------------------+
-
-```
-
-4. 指定搜索起始路径：
-
-```sql
-SELECT JSON_SEARCH('{"person": {"name": "John", "age": 30}}', 'one', 'John',
'$.person');
-
-```
-```sql
-+---------------------------------------------------------------+
-| JSON_SEARCH('{"person": {"name": "John", "age": 30}}', 'one', 'John',
'$.person') |
-+---------------------------------------------------------------+
-| $.name |
-+---------------------------------------------------------------+
-
-
-```
\ No newline at end of file
+1. 查找一个值（one）
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'John');
+ ```
+ ```text
+ +-----------------------------------------------------------+
+ | JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'John') |
+ +-----------------------------------------------------------+
+ | "$.name" |
+ +-----------------------------------------------------------+
+
+ ```
+2. 查找一个值（one），即使有多个匹配也只返回一个路径
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30, "alias": "John"}', 'one',
'John');
+ ```
+ ```text
+
+----------------------------------------------------------------------------+
+ | JSON_SEARCH('{"name": "John", "age": 30, "alias": "John"}', 'one',
'John') |
+
+----------------------------------------------------------------------------+
+ | "$.name"
|
+
+----------------------------------------------------------------------------+
+ ```
+3. 查找所有匹配的值（all）
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30, "alias": "John"}', 'all',
'John');
+ ```
+ ```text
+
+----------------------------------------------------------------------------+
+ | JSON_SEARCH('{"name": "John", "age": 30, "alias": "John"}', 'all',
'John') |
+
+----------------------------------------------------------------------------+
+ | ["$.alias","$.name"]
|
+
+----------------------------------------------------------------------------+
+ ```
+4. 没有找到匹配值
+
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'Alice');
+ ```
+ ```text
+ +------------------------------------------------------------+
+ | JSON_SEARCH('{"name": "John", "age": 30}', 'one', 'Alice') |
+ +------------------------------------------------------------+
+ | NULL |
+ +------------------------------------------------------------+
+ ```
+
+5. NULL 参数
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30}', NULL, 'Alice');
+ ```
+ ```text
+ +-----------------------------------------------------------+
+ | JSON_SEARCH('{"name": "John", "age": 30}', NULL, 'Alice') |
+ +-----------------------------------------------------------+
+ | NULL |
+ +-----------------------------------------------------------+
+ ```
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30}', 'one', NULL);
+ ```
+ ```text
+ +---------------------------------------------------------+
+ | JSON_SEARCH('{"name": "John", "age": 30}', 'one', NULL) |
+ +---------------------------------------------------------+
+ | NULL |
+ +---------------------------------------------------------+
+ ```
+ ```sql
+ SELECT JSON_SEARCH(NULL, 'one', 'Alice');
+ ```
+ ```
+ +-----------------------------------+
+ | JSON_SEARCH(NULL, 'one', 'Alice') |
+ +-----------------------------------+
+ | NULL |
+ +-----------------------------------+
+ ```
+6. 非法的 `<one_or_all>` 参数
+ ```sql
+ SELECT JSON_SEARCH('{"name": "John", "age": 30}', 'three', 'Alice');
+ ```
+ ```text
+ ERROR 1105 (HY000): errCode = 2, detailMessage = [INVALID_ARGUMENT]the
one_or_all argument three is not 'one' not 'all'
+ ```
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
