Merge pull request #1124 from yangj1211/json_extract

add doc of json_extract_float64 and json_extract_string

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)
-```
+```

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;  
+```

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)
+```

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 对象的属性值。

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)
-```
+```

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 文档|
 

mkdocs.yml

@@ -648,6 +648,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
           - 其他函数: