Extend JSON function docs (#17784) (#17909)

pingcap · Jul 10, 2024 · 4882443 · 4882443
1 parent 716cd71
commit 4882443
Show file tree

Hide file tree

Showing 12 changed files with 1,674 additions and 72 deletions.
diff --git a/TOC.md b/TOC.md
@@ -908,7 +908,15 @@
  - [加密和压缩函数](/functions-and-operators/encryption-and-compression-functions.md)
  - [锁函数](/functions-and-operators/locking-functions.md)
  - [信息函数](/functions-and-operators/information-functions.md)
- - [JSON 函数](/functions-and-operators/json-functions.md)
+ - JSON 函数
+ - [概览](/functions-and-operators/json-functions.md)
+ - [创建 JSON 的函数](/functions-and-operators/json-functions/json-functions-create.md)
+ - [搜索 JSON 的函数](/functions-and-operators/json-functions/json-functions-search.md)
+ - [修改 JSON 的函数](/functions-and-operators/json-functions/json-functions-modify.md)
+ - [返回 JSON 的函数](/functions-and-operators/json-functions/json-functions-return.md)
+ - [JSON 效用函数](/functions-and-operators/json-functions/json-functions-utility.md)
+ - [聚合 JSON 的函数](/functions-and-operators/json-functions/json-functions-aggregate.md)
+ - [验证 JSON 的函数](/functions-and-operators/json-functions/json-functions-validate.md)
  - [GROUP BY 聚合函数](/functions-and-operators/aggregate-group-by-functions.md)
  - [GROUP BY 修饰符](/functions-and-operators/group-by-modifier.md)
  - [窗口函数](/functions-and-operators/window-functions.md)

diff --git a/data-type-default-values.md b/data-type-default-values.md
@@ -13,7 +13,7 @@ summary: 数据类型的默认值描述了列的默认值设置规则。默认
 - 对于整数类型，可以使用 `NEXT VALUE FOR` 函数将序列的下一个值作为列的默认值，使用 [`RAND()`](/functions-and-operators/numeric-functions-and-operators.md) 函数生成随机浮点值作为列的默认值。
 - 对于字符串类型，可以使用 [`UUID()`](/functions-and-operators/miscellaneous-functions.md) 函数生成[通用唯一标识符 (UUID)](/best-practices/uuid.md) 作为列的默认值。
 - 对于二进制类型，可以使用 [`UUID_TO_BIN()`](/functions-and-operators/miscellaneous-functions.md) 函数将 UUID 转换为二进制格式后作为列的默认值。
-- 从 v8.0.0 开始，新增支持 [`BLOB`](/data-type-string.md#blob-类型)、[`TEXT`](/data-type-string.md#text-类型) 以及 [`JSON`](/data-type-json.md#json-类型) 这三种数据类型设置默认值，但仅支持使用表达式设置[默认值](#表达式默认值)。
+- 从 v8.0.0 开始，新增支持 [`BLOB`](/data-type-string.md#blob-类型)、[`TEXT`](/data-type-string.md#text-类型) 以及 [`JSON`](/data-type-json.md#json-数据类型) 这三种数据类型设置默认值，但仅支持使用表达式设置[默认值](#表达式默认值)。
 
 如果一个列的定义中没有 `DEFAULT` 的设置。TiDB 按照如下的规则决定：
 

diff --git a/data-type-json.md b/data-type-json.md
@@ -3,7 +3,7 @@ title: JSON 类型
 summary: JSON 类型存储半结构化数据，使用 Binary 格式序列化，加快查询和解析速度。JSON 字段不能创建索引，但可以对 JSON 文档中的子字段创建索引。TiDB 仅支持下推部分 JSON 函数到 TiFlash，不建议使用 BR 恢复包含 JSON 列的数据到 v6.3.0 之前的 TiDB 集群。请勿同步非标准 JSON 类型的数据。MySQL 误标记二进制类型数据为 STRING 类型，TiDB 保持正确的二进制类型。ENUM 或 SET 数据类型转换为 JSON 时，TiDB 会检查格式正确性。TiDB 支持使用 ORDER BY 对 JSON Array 或 JSON Object 进行排序。在 INSERT JSON 列时，TiDB 会将值隐式转换为 JSON。
 ---
 
-# JSON 类型
+# JSON 数据类型
 
 JSON 类型可以存储 JSON 这种半结构化的数据，相比于直接将 JSON 存储为字符串，它的好处在于：
 
@@ -12,8 +12,6 @@ JSON 类型可以存储 JSON 这种半结构化的数据，相比于直接将 JS
 
 JSON 字段本身上，并不能创建索引，但是可以对 JSON 文档中的某个子字段创建索引。例如：
 
-{{< copyable "sql" >}}
-
 ```sql
 CREATE TABLE city (
  id INT PRIMARY KEY,
@@ -25,6 +23,29 @@ INSERT INTO city (id,detail) VALUES (1, '{"name": "Beijing", "population": 100}'
 SELECT id FROM city WHERE population >= 100;
 ```
 
+更多信息，请参考 [JSON 函数](/functions-and-operators/json-functions.md)和[生成列](/generated-columns.md)。
+
+## JSON 值的类型
+
+JSON 文档中的每个值都属于一种特定的数据类型。可以通过 [`JSON_TYPE`()](/functions-and-operators/json-functions/json-functions-return.md#json_type) 的输出结果查看。
+
+| 类型 | 示例 |
+|------------------|--------------------------------|
+| ARRAY | `[]` |
+| BIT | |
+| BLOB | `0x616263` |
+| BOOLEAN | `true` |
+| DATE | `"2025-06-14"` |
+| DATETIME | `"2025-06-14 09:05:10.000000"` |
+| DOUBLE | `1.14` |
+| INTEGER | `5` |
+| NULL | `null` |
+| OBJECT | `{}` |
+| OPAQUE | |
+| STRING | `"foobar"` |
+| TIME | `"09:10:00.000000"` |
+| UNSIGNED INTEGER | `9223372036854776000` |
+
 ## 使用限制
 
 - 目前 TiDB 仅支持下推部分 JSON 函数到 TiFlash。详情请参考 [TiFlash 支持下推的表达式](/tiflash/tiflash-supported-pushdown-calculations.md#支持下推的表达式)。

diff --git a/functions-and-operators/aggregate-group-by-functions.md b/functions-and-operators/aggregate-group-by-functions.md
@@ -24,7 +24,8 @@ TiDB 支持的 MySQL `GROUP BY` 聚合函数如下所示：
 | [`STD()`，`STDDEV()`，`STDDEV_POP`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_std) | 返回总体标准差 |
 | [`VAR_SAMP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_var-samp) | 返回采样方差 |
 | [`STDDEV_SAMP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_stddev-samp) | 返回采样标准方差 |
-| [`JSON_OBJECTAGG(key, value)`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_json-objectagg) | 将结果集返回为单个含 (key, value) 键值对的 JSON object |
+| [`JSON_ARRAYAGG()`](/functions-and-operators/json-functions/json-functions-aggregate.md#json_arrayagg) | 将结果集返回为单个 JSON 数组 |
+| [`JSON_OBJECTAGG()`](/functions-and-operators/json-functions/json-functions-aggregate.md#json_objectagg) | 将结果集返回为单个含 (key, value) 键值对的 JSON 对象 |
 
 > **注意：**
 >
@@ -41,23 +42,19 @@ TiDB 支持的 MySQL `GROUP BY` 聚合函数如下所示：
 
  以下是一个计算第 50 百分位数的例子：
 
- {{< copyable "sql" >}}
-
  ```sql
- drop table if exists t;
- create table t(a int);
- insert into t values(1), (2), (3);
+ DROP TABLE IF EXISTS t;
+ CREATE TABLE t(a INT);
+ INSERT INTO t VALUES(1), (2), (3);
  ```
 
- {{< copyable "sql" >}}
-
  ```sql
- select approx_percentile(a, 50) from t;
+ SELECT APPROX_PERCENTILE(a, 50) FROM t;
  ```
 
  ```sql
  +--------------------------+
- | approx_percentile(a, 50) |
+ | APPROX_PERCENTILE(a, 50) |
  +--------------------------+
  | 2 |
  +--------------------------+
@@ -74,16 +71,12 @@ TiDB 支持的 MySQL `GROUP BY` 聚合函数如下所示：
 
 TiDB 支持 SQL 模式 `ONLY_FULL_GROUP_BY`，当启用该模式时，TiDB 拒绝不明确的非聚合列的查询。例如，以下查询在启用 `ONLY_FULL_GROUP_BY` 时是不合规的，因为 `SELECT` 列表中的非聚合列 "b" 在 `GROUP BY` 语句中不显示：
 
-{{< copyable "sql" >}}
-
 ```sql
 drop table if exists t;
 create table t(a bigint, b bigint, c bigint);
 insert into t values(1, 2, 3), (2, 2, 3), (3, 2, 3);
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 select a, b, sum(c) from t group by a;
 ```
@@ -99,8 +92,6 @@ select a, b, sum(c) from t group by a;
 3 rows in set (0.01 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 set sql_mode = 'ONLY_FULL_GROUP_BY';
 ```
@@ -109,8 +100,6 @@ set sql_mode = 'ONLY_FULL_GROUP_BY';
 Query OK, 0 rows affected (0.00 sec)
 ```
 
-{{< copyable "sql" >}}
-
 ```sql
 select a, b, sum(c) from t group by a;
 ```
@@ -125,8 +114,6 @@ ERROR 1055 (42000): Expression #2 of SELECT list is not in GROUP BY clause and c
 
 TiDB 目前实现的 `ONLY_FULL_GROUP_BY` 没有 MySQL 5.7 严格。例如，假设我们执行以下查询，希望结果按 "c" 排序：
 
-{{< copyable "sql" >}}
-
 ```sql
 drop table if exists t;
 create table t(a bigint, b bigint, c bigint);
@@ -145,8 +132,6 @@ select distinct a, b from t order by c;
 
 TiDB 中另一个标准 SQL 的扩展允许 `HAVING` 子句中的引用使用 `SELECT` 列表中的别名表达式。例如：以下查询返回在 `orders` 中只出现一次的 `name` 值
 
-{{< copyable "sql" >}}
-
 ```sql
 select name, count(name) from orders
 group by name
@@ -155,8 +140,6 @@ having count(name) = 1;
 
 这个 TiDB 扩展允许在聚合列的 `HAVING` 子句中使用别名：
 
-{{< copyable "sql" >}}
-
 ```sql
 select name, count(name) as c from orders
 group by name
@@ -165,8 +148,6 @@ having c = 1;
 
 标准 SQL 只支持 `GROUP BY` 子句中的列表达式，以下语句不合规，因为 `FLOOR(value/100)` 是一个非列表达式：
 
-{{< copyable "sql" >}}
-
 ```sql
 select id, floor(value/100)
 from tbl_name
@@ -177,8 +158,6 @@ TiDB 对标准 SQL 的扩展支持 `GROUP BY` 子句中非列表达式，认为
 
 标准 SQL 也不支持 `GROUP BY` 子句中使用别名。TiDB 对标准 SQL 的扩展支持使用别名，查询的另一种写法如下：
 
-{{< copyable "sql" >}}
-
 ```sql
 select id, floor(value/100) as val
 from tbl_name
@@ -187,4 +166,4 @@ group by id, val;
 
 ## 相关系统变量
 
-`group_concat_max_len` 变量设置 `GROUP_CONCAT()` 函数缓冲区的最大长度。
+[`group_concat_max_len`](/system-variables.md#group_concat_max_len) 变量设置 `GROUP_CONCAT()` 函数缓冲区的最大长度。