diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_extract.md b/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_extract.md index a5268ba1ee..06bc746478 100644 --- a/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_extract.md +++ b/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_extract.md @@ -2,7 +2,14 @@ ## **函数说明** -`JSON EXTRACT` 是一个 JSON 查询函数，可用于查询 JSON 文档。 +`JSON EXTRACT()` 是一个 JSON 查询函数，可用于查询 JSON 文档。 + +- 如果在 select 后面作为列，建议使用函数 [JSON_EXTRACT_STRING()](./json_extract_string.md) 和 [JSON_EXTRACT_FLOAT64()](./json_extract_float64.md)； + +- 如果在 where 条件中进行比较： + - 如果类型为 json 对象比较，使用 `JSON EXTRACT()` + - 如果类型是字符串类型，使用 [JSON_EXTRACT_STRING()](./json_extract_string.md)； + - 如果类型为 float 或者 int，使用 [JSON_EXTRACT_FLOAT64()](./json_extract_float64.md)。 ## **语法结构** @@ -12,23 +19,14 @@ select json_extract(jsonDoc, pathExpression); ## **参数释义** -`pathExpression` 是 JSON 路径表达式，即在 JSON 文档中选择一个值。 - -路径表达式对于提取部分 JSON 文档或修改 JSON 文档的函数很有用，指定在该文档中的哪个位置进行操作。例如，以下查询从 JSON 文档中提取具有 name 键的成员的值： - -```sql -mysql> SELECT JSON_EXTRACT('{"id": 14, "name": "Aztalan"}', '$.name'); -+-----------------------------------------------------+ -| json_extract({"id": 14, "name": "Aztalan"}, $.name) | -+-----------------------------------------------------+ -| "Aztalan" | -+-----------------------------------------------------+ -1 row in set (0.00 sec) -``` +| 参数 | 说明 | +| ---- | ---- | +| jsonDoc | 这是包含 JSON 数据的表达式。| +| pathExpression | 表示在 JSON 文档中访问某个值的路径。路径以 `$` 开始，表示 JSON 文档的根，后面可以跟随点号 `.` 和键名或用方括号 [ ] 访问数组的元素。| 路径表达式必须以 `$` 字符开头： -- `,` 后跟键名，使用给定键命名对象中的成员。键名需要使用双引号包含。 +- `.` 后跟键名，使用给定键命名对象中的成员。键名需要使用引号包含。 - `[N]`：选择数组的 *path* 后，将数组中位置 `N` 处的值命名。数组位置是从零开始的整数。如果数组是负数，则产生报错。 @@ -42,8 +40,6 @@ mysql> SELECT JSON_EXTRACT('{"id": 14, "name": "Aztalan"}', '$.name'); - 文档中不存在的路径（或不存在的数据）评估为 `NULL`。 -## **示例** - 如下一组 JSON 数组： ``` @@ -80,7 +76,7 @@ mysql> SELECT JSON_EXTRACT('{"id": 14, "name": "Aztalan"}', '$.name'); - `$."a bird"` 表示 `sparrow`。 -使用通配符 `$` 的路径可以为包含多个值的数组： +## **示例** ```sql mysql> select JSON_EXTRACT('{"a": 1, "b": 2, "c": [3, 4, 5]}', '$.*'); @@ -96,22 +92,23 @@ mysql> SELECT JSON_EXTRACT('{"a": 1, "b": 2, "c": [3, 4, 5]}', '$.c[*]'); +------------------------------------------------------------+ | [3, 4, 5] | +------------------------------------------------------------+ -``` -在下述示例中，路径 `$**.b` 计算为多个路径 (`$.a.b` 和 `$.c.b`) 并生成匹配路径值的数组： +mysql> select json_extract('{"a":{"q":[1,2,3]}}','$.a.q[1]'); ++---------------------------------------------+ +| json_extract({"a":{"q":[1,2,3]}}, $.a.q[1]) | ++---------------------------------------------+ +| 2 | ++---------------------------------------------+ +1 row in set (0.00 sec) -```sql mysql> select JSON_EXTRACT('{"a": {"b": 1}, "c": {"b": 2}}', '$**.b'); +---------------------------------------------------------+ | JSON_EXTRACT('{"a": {"b": 1}, "c": {"b": 2}}', '$**.b') | +---------------------------------------------------------+ | [null, 1, 2] | +---------------------------------------------------------+ -``` - -在下述示例中，将展示从列中查询 JSON 值： -```sql +#在下述示例中，将展示从列中查询 JSON 值： create table t1 (a json,b int); insert into t1(a,b) values ('{"a":1,"b":2,"c":3}',1); diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_extract_float64.md b/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_extract_float64.md new file mode 100644 index 0000000000..06037f5507 --- /dev/null +++ b/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_extract_float64.md @@ -0,0 +1,62 @@ +# **JSON_EXTRACT_FLOAT64()** + +## **函数说明** + +`JSON_EXTRACT_FLOAT64()` 用于从 JSON 数据中提取指定路径的数值的值。 + +如果在 where 条件中进行比较： + +- 如果类型为 json 对象比较，使用 [JSON EXTRACT()](./json_extract.md)； +- 如果类型是字符串类型，使用 [JSON_EXTRACT_STRING()](./json_extract_string.md)； +- 如果类型为 float 或者 int，使用 `JSON_EXTRACT_FLOAT64()`。 + +## **语法结构** + +```sql +select col_name from tab_name where json_extract_float64(jsonDoc, pathExpression)= number; +``` + +## **参数释义** + +| 参数 | 说明 | +| ---- | ---- | +| jsonDoc | 这是包含 JSON 数据的列或表达式。| +| pathExpression | 表示在 JSON 文档中访问某个值的路径。路径以 `$` 开始，表示 JSON 文档的根，后面可以跟随点号 `.` 和键名或用方括号 [ ] 访问数组的元素。| +| number | 指定 JSON 数据中要提取的值，为数值类型。 | + +路径表达式必须以 `$` 字符开头： + +- `,` 后跟键名，使用给定键命名对象中的成员。键名需要使用双引号包含。 + +- `[N]`：选择数组的 *path* 后，将数组中位置 `N` 处的值命名。数组位置是从零开始的整数。如果数组是负数，则产生报错。 + +- 路径可以包含 `*` 或 `**` 通配符： + + + `.[*]` 计算 JSON 对象中所有成员的值。 + + + `[*]` 计算 JSON 数组中所有元素的值。 + + + `prefix**suffix`：计算以命名前缀开头并以命名后缀结尾的所有路径。 + +- 文档中不存在的路径（或不存在的数据）评估为 `NULL`。 + +## **示例** + +```sql +create table student(n1 int,n2 json); +insert into student values + (1,'{"name": "tom", "age": 18, "score": 90,"gender": "male"}'), + (2,'{"name": "bob", "age": 20, "score": 80,"gender": "male"}'), + (3,'{"name": "jane", "age": 17, "score": 95,"gender": "female"}'), + (4,'{"name": "lily", "age": 19, "score": 79,"gender": "female"}'); + +mysql> select n1 from student where json_extract_float64(n2,'$.age')=19; ++------+ +| n1 | ++------+ +| 4 | ++------+ +1 row in set (0.00 sec) + +select json_extract_float64(n2,'$.age')=19; +``` \ No newline at end of file diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_extract_string.md b/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_extract_string.md new file mode 100644 index 0000000000..ee80bd0df1 --- /dev/null +++ b/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_extract_string.md @@ -0,0 +1,60 @@ +# **JSON_EXTRACT_STRING()** + +## **函数说明** + +`JSON_EXTRACT_STRING()` 用于从 JSON 数据中提取指定路径的字符串值。 + +如果在 where 条件中进行比较： + +- 如果类型为 json 对象比较，使用 [JSON EXTRACT()](./json_extract.md)； +- 如果类型是字符串类型，使用 `JSON_EXTRACT_STRING()`； +- 如果类型为 float 或者 int，使用 [JSON_EXTRACT_FLOAT64()](./json_extract_float64.md)。 + +## **语法结构** + +```sql +select col_name from tab_name where json_extract_string(jsonDoc, pathExpression)= str; +``` + +## **参数释义** + +| 参数 | 说明 | +| ---- | ---- | +| jsonDoc | 这是包含 JSON 数据的列或表达式。| +| pathExpression | 表示在 JSON 文档中访问某个值的路径。路径以 `$` 开始，表示 JSON 文档的根，后面可以跟随点号 `.` 和键名或用方括号 [ ] 访问数组的元素| +| str | 指定 JSON 数据中要提取的值，为字符串类型。 | + +路径表达式必须以 `$` 字符开头： + +- `,` 后跟键名，使用给定键命名对象中的成员。键名需要使用双引号包含。 + +- `[N]`：选择数组的 *path* 后，将数组中位置 `N` 处的值命名。数组位置是从零开始的整数。如果数组是负数，则产生报错。 + +- 路径可以包含 `*` 或 `**` 通配符： + + + `.[*]` 计算 JSON 对象中所有成员的值。 + + + `[*]` 计算 JSON 数组中所有元素的值。 + + + `prefix**suffix`：计算以命名前缀开头并以命名后缀结尾的所有路径。 + +- 文档中不存在的路径（或不存在的数据）评估为 `NULL`。 + +## **示例** + +```sql +create table student(n1 json); +insert into student values + ('{"name": "tom", "age": 18, "score": 90,"gender": "male"}'), + ('{"name": "bob", "age": 20, "score": 80,"gender": "male"}'), + ('{"name": "jane", "age": 17, "score": 95,"gender": "female"}'), + ('{"name": "lily", "age": 19, "score": 79,"gender": "female"}'); + +mysql> select n1 from student where json_extract_string(n1,'$.name')='tom'; ++-----------------------------------------------------------+ +| n1 | ++-----------------------------------------------------------+ +| {"age": 18, "gender": "male", "name": "tom", "score": 90} | ++-----------------------------------------------------------+ +1 row in set (0.00 sec) +``` \ No newline at end of file diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/matrixone-function-list.md b/docs/MatrixOne/Reference/Functions-and-Operators/matrixone-function-list.md index f9b6a42893..dc04e7a74c 100644 --- a/docs/MatrixOne/Reference/Functions-and-Operators/matrixone-function-list.md +++ b/docs/MatrixOne/Reference/Functions-and-Operators/matrixone-function-list.md @@ -175,6 +175,8 @@ | 函数名称 | 作用 | | --------------------------------------------- | --------------------------------------- | | [JSON_EXTRACT()](./Json/json_extract.md) | 从 JSON 文档返回数据| +| [JSON_EXTRACT_FLOAT64()](./Json/json_extract_float64.md) | 从 JSON 数据中提取指定路径的数值的值| +| [JSON_EXTRACT_STRING()](./Json/json_extract_string.md) | 从 JSON 数据中提取指定路径的字符串的值| | [JSON_QUOTE()](./Json/json_quote.md) | 引用 JSON 文档| | [JSON_UNQUOTE()](./Json/json_unquote.md) | 取消引用 JSON 文档| diff --git a/mkdocs.yml b/mkdocs.yml index 5291edc150..7490ec4aa1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -646,6 +646,8 @@ nav: - ROW_NUMBER(): MatrixOne/Reference/Functions-and-Operators/Window-Functions/row_number.md - JSON 函数: - JSON_EXTRACT(): MatrixOne/Reference/Functions-and-Operators/Json/json_extract.md + - JSON_EXTRACT_FLOAT64(): MatrixOne/Reference/Functions-and-Operators/Json/json_extract_float64.md + - JSON_EXTRACT_STRING(): MatrixOne/Reference/Functions-and-Operators/Json/json_extract_string.md - JSON_QUOTE(): MatrixOne/Reference/Functions-and-Operators/Json/json_quote.md - JSON_UNQUOTE(): MatrixOne/Reference/Functions-and-Operators/Json/json_unquote.md - 其他函数: