From 3229b230635f9d36ac135d7280a94f3112da2f06 Mon Sep 17 00:00:00 2001 From: yangj1211 Date: Fri, 25 Oct 2024 15:19:51 +0800 Subject: [PATCH] add doc of json_extract_float64/json_extract_string --- .../Json/json_extract.md | 49 ++++++------- .../Json/json_extract_float64.md | 62 ++++++++++++++++ .../Json/json_extract_string.md | 71 +++++++++++++++++++ .../Json/json_quote.md | 2 +- .../Json/json_unquote.md | 6 +- .../matrixone-function-list.md | 2 + mkdocs.yml | 2 + 7 files changed, 164 insertions(+), 30 deletions(-) create mode 100644 docs/MatrixOne/Reference/Functions-and-Operators/Json/json_extract_float64.md create mode 100644 docs/MatrixOne/Reference/Functions-and-Operators/Json/json_extract_string.md 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..708c7cd50e 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); @@ -161,4 +158,4 @@ mysql> select json_extract(t1.a,'$[1].a') from t1 where t1.b=4; | 4 | +----------------------------+ 1 row in set (0.00 sec) -``` +``` \ No newline at end of file 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..17455a2ff0 --- /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..76d7ccf433 --- /dev/null +++ b/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_extract_string.md @@ -0,0 +1,71 @@ +# **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) + +mysql> select json_extract_float64(n2,'$.age')=19 from student; ++--------------------------------------+ +| json_extract_float64(n2, $.age) = 19 | ++--------------------------------------+ +| false | +| false | +| false | +| true | ++--------------------------------------+ +4 rows in set (0.00 sec) +``` \ No newline at end of file diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_quote.md b/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_quote.md index 6fbaa73050..b2a5b6e53d 100644 --- a/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_quote.md +++ b/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_quote.md @@ -44,4 +44,4 @@ mysql> SELECT JSON_QUOTE('hello world'); 1 row in set (0.00 sec) ``` -可以看到，原始字符串被引号包围并且字符串中的双引号也被转义了。这样，可以将其用作 JSON 格式的值，例如，将其作为 JSON 对象的属性值。 +可以看到，原始字符串被引号包围并且字符串中的双引号也被转义了。这样，可以将其用作 JSON 格式的值，例如，将其作为 JSON 对象的属性值。 \ No newline at end of file diff --git a/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_unquote.md b/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_unquote.md index f6515ee6b8..0ed5ca506c 100644 --- a/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_unquote.md +++ b/docs/MatrixOne/Reference/Functions-and-Operators/Json/json_unquote.md @@ -8,8 +8,8 @@ ## **语法结构** -``` -`select JSON_UNQUOTE(string_value);` +```sql +select JSON_UNQUOTE(string_value); ``` 在字符串中，某些序列具有特殊含义，这些序列都以反斜杠 (\) 开始，称为转义字符，规则如下表。对于所有其他转义序列，反斜杠将被忽略。也就是说，转义字符被解释为没有转义。例如，\x 就是 x。这些序列区分大小写。例如，\b 被解释为退格，而 \B 被解释为 B。 @@ -57,4 +57,4 @@ mysql> SELECT JSON_UNQUOTE('"\\t\\u0032"'); | 2 | +----------------------------+ 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 a953943a25..3daa1be275 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -647,6 +647,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 - 其他函数: