From 977662e8df570c9f844f71bda216b1508c55c3bd Mon Sep 17 00:00:00 2001 From: xiongjiwei Date: Fri, 16 Sep 2022 17:56:59 +0800 Subject: [PATCH] json: update json doc (#11180) --- data-type-json.md | 89 +++++++++++++++++-- experimental-features.md | 1 - .../aggregate-group-by-functions.md | 6 -- functions-and-operators/json-functions.md | 4 - sql-statements/sql-statement-create-index.md | 16 +--- 5 files changed, 88 insertions(+), 28 deletions(-) diff --git a/data-type-json.md b/data-type-json.md index 83e61cbdd71c..829a477b2054 100644 --- a/data-type-json.md +++ b/data-type-json.md @@ -5,16 +5,12 @@ aliases: ['/docs-cn/dev/data-type-json/','/docs-cn/dev/reference/sql/data-types/ # JSON 类型 -> **警告：** -> -> 当前该功能为实验特性，不建议在生产环境中使用。 - JSON 类型可以存储 JSON 这种半结构化的数据，相比于直接将 JSON 存储为字符串，它的好处在于： 1. 使用 Binary 格式进行序列化，对 JSON 的内部字段的查询、解析加快； 2. 多了 JSON 合法性验证的步骤，只有合法的 JSON 文档才可以放入这个字段中； -JSON 字段本身上，并不能创建索引。相反，可以对 JSON 文档中的某个子字段创建索引。例如： +JSON 字段本身上，并不能创建索引，但是可以对 JSON 文档中的某个子字段创建索引。例如： {{< copyable "sql" >}} @@ -29,4 +25,87 @@ INSERT INTO city (id,detail) VALUES (1, '{"name": "Beijing", "population": 100}' SELECT id FROM city WHERE population >= 100; ``` +## 使用限制 + +- 暂不支持将 JSON 函数下推至 TiFlash。 +- TiDB 暂不支持 JSON PATH 中范围选取的语法，以下 SQL 语句会在 TiDB 中报错: + + ```sql + SELECT j->'$[1 to 2]' FROM t; + SELECT j->'$[last]' FROM t; + ``` + +- TiDB Backup & Restore（BR）在 v6.3.0 之前不支持恢复包含 JSON 列的数据。另外，任何版本的 BR 都不支持恢复包含 JSON 列的数据到 v6.3.0 之前的 TiDB 集群。 +- 请勿使用任何同步工具同步非标准 JSON 类型（例如 DATE、DATETIME、TIME 等）的数据。 + +## MySQL 兼容性 + +- 当使用二进制类型数据创建 JSON 时，目前 MySQL 会将其误标记为 STRING 类型，而 TiDB 会保持正确的二进制类型。 + + ```sql + CREATE TABLE test(a json); + INSERT INTO test SELECT json_objectagg('a', b'01010101'); + + -- 在 TiDB 中，执行以下 SQL 语句返回结果如下所示。在 MySQL 中，执行以下 SQL 语句的结果为 `0, 1`。 + mysql> SELECT JSON_EXTRACT(JSON_OBJECT('a', b'01010101'), '$.a') = "base64:type15:VQ==" AS r1, JSON_EXTRACT(a, '$.a') = "base64:type15:VQ==" AS r2 FROM test; + +------+------+ + | r1 | r2 | + +------+------+ + | 0 | 0 | + +------+------+ + 1 row in set (0.01 sec) + ``` + + 详情可见此 [issue](https://github.com/pingcap/tidb/issues/37443)。 + +- 当将 ENUM 或 SET 数据类型转换为 JSON 时，TiDB 会检查其格式正确性。例如，当执行下面的 SQL 语句时，TiDB 中会报错： + + ```sql + CREATE TABLE t(e ENUM('a')); + INSERT INTO t VALUES ('a'); + mysql> SELECT CAST(e AS JSON) FROM t; + ERROR 3140 (22032): Invalid JSON text: The document root must not be followed by other values. + ``` + + 详情可见此 [issue](https://github.com/pingcap/tidb/issues/9999)。 + +- TiDB 支持使用 `ORDER BY` 对 JSON Array 或 JSON Object 进行排序。 + + 当使用 `ORDER BY` 对 JSON Array 或 JSON Object 进行排序时，MySQL 会返回一个警告，且排序结果与比较运算结果不一致： + + ```sql + CREATE TABLE t(j JSON); + INSERT INTO t VALUES ('[1,2,3,4]'); + INSERT INTO t VALUES ('[5]'); + + mysql> SELECT j FROM t WHERE j < JSON_ARRAY(5); + +--------------+ + | j | + +--------------+ + | [1, 2, 3, 4] | + +--------------+ + 1 row in set (0.00 sec) + + -- 在 TiDB 中，执行以下 SQL 语句返回结果如下所示。在 MySQL 中，执行以下 SQL 语句会返回警告 “This version of MySQL doesn't yet support 'sorting of non-scalar JSON values'. ”，且排序结果与 `<` 比较结果不一致。 + mysql> SELECT j FROM t ORDER BY j; + +--------------+ + | j | + +--------------+ + | [1, 2, 3, 4] | + | [5] | + +--------------+ + 2 rows in set (0.00 sec) + ``` + + 详情可见此 [issue](https://github.com/pingcap/tidb/issues/37506)。 + +- 在 INSERT JSON 列时，TiDB 会将值隐式转换为 JSON： + + ```sql + CREATE TABLE t(col JSON); + + -- 在 TiDB 中，执行以下 INSERT 语句成功。在 MySQL 中，执行以下 INSERT 语句将返回 Invalid JSON text 错误。 + INSERT INTO t VALUES (3); + ``` + 有关 JSON 的更多信息，可以参考 [JSON 函数](/functions-and-operators/json-functions.md)和[生成列](/generated-columns.md)。 diff --git a/experimental-features.md b/experimental-features.md index 39091b16e58f..1db44e3191fb 100644 --- a/experimental-features.md +++ b/experimental-features.md @@ -34,7 +34,6 @@ aliases: ['/docs-cn/dev/experimental-features-4.0/','/zh/tidb/dev/experimental-f + 表达式索引 (Expression Index) 功能。表达式索引也叫函数索引，在创建索引时索引的字段不一定是一个具体的列，也可以是由一个或者多个列计算出来的表达式。对于快速访问那些基于计算结果的表非常有用。详情参阅：[表达式索引](/sql-statements/sql-statement-create-index.md)。（v4.0 实验特性） + [生成列](/generated-columns.md#生成列)。（v2.1 实验特性） + [自定义变量](/user-defined-variables.md#用户自定义变量)。（v2.1 实验特性） -+ [JSON 数据类型](/data-type-json.md)及 [JSON 函数](/functions-and-operators/json-functions.md)。（v2.1 实验特性） + [Cascades Planner](/system-variables.md#tidb_enable_cascades_planner)：基于 Cascades 框架的自顶向下查询优化器。（v3.0 实验特性） + [`ALTER TABLE ... COMPACT`](/sql-statements/sql-statement-alter-table-compact.md)。（v6.1.0 实验特性） diff --git a/functions-and-operators/aggregate-group-by-functions.md b/functions-and-operators/aggregate-group-by-functions.md index 3b0697c863af..94ae64aa8bb4 100644 --- a/functions-and-operators/aggregate-group-by-functions.md +++ b/functions-and-operators/aggregate-group-by-functions.md @@ -184,9 +184,3 @@ select id, floor(value/100) as val from tbl_name group by id, val; ``` - -## TiDB 不支持的聚合函数 - -TiDB 目前不支持的聚合函数如下所示，相关进展参阅 [TiDB #7623](https://github.com/pingcap/tidb/issues/7623)。 - -- `JSON_ARRAYAGG` diff --git a/functions-and-operators/json-functions.md b/functions-and-operators/json-functions.md index 7c03a9888e43..837f7b19ce0c 100644 --- a/functions-and-operators/json-functions.md +++ b/functions-and-operators/json-functions.md @@ -5,10 +5,6 @@ aliases: ['/docs-cn/dev/functions-and-operators/json-functions/','/docs-cn/dev/r # JSON 函数 -> **警告：** -> -> 当前该功能为实验特性，不建议在生产环境中使用。 - TiDB 支持 MySQL 5.7 GA 版本发布的大多数 JSON 函数。 ## 创建 JSON 值的函数 diff --git a/sql-statements/sql-statement-create-index.md b/sql-statements/sql-statement-create-index.md index ac9e7a907477..fa06491d8fb6 100644 --- a/sql-statements/sql-statement-create-index.md +++ b/sql-statements/sql-statement-create-index.md @@ -191,21 +191,13 @@ DROP INDEX idx1 ON t1; > **注意：** > -> 表达式索引涉及众多表达式。为了确保正确性，当前仅允许经充分测试的一部分函数用于创建表达式索引，即生产环境中仅允许表达式中包含这些函数。这些函数可以通过查询变量 `tidb_allow_function_for_expression_index` 得到。在后续版本中，这些函数会持续增加。 +> 表达式索引涉及众多表达式。为了确保正确性，当前仅允许经充分测试的一部分函数用于创建表达式索引，即生产环境中仅允许表达式中包含这些函数。这些函数可以通过查询变量 `tidb_allow_function_for_expression_index` 得到。在后续版本中，这些函数会持续增加。目前允许的函数如下: > -> {{< copyable "sql" >}} -> -> ```sql -> mysql> select @@tidb_allow_function_for_expression_index; -> +--------------------------------------------+ -> | @@tidb_allow_function_for_expression_index | -> +--------------------------------------------+ -> | lower, md5, reverse, upper, vitess_hash | -> +--------------------------------------------+ -> 1 row in set (0.00 sec) +> ``` +> json_array, json_array_append, json_array_insert, json_contains, json_contains_path, json_depth, json_extract, json_insert, json_keys, json_length, json_merge_patch, json_merge_preserve, json_object, json_pretty, json_quote, json_remove, json_replace, json_search, json_set, json_storage_size, json_type, json_unquote, json_valid, lower, md5, reverse, tidb_shard, upper, vitess_hash > ``` > -> 对于以上变量返回结果之外的函数，由于未完成充分测试，当前仍为实验特性，不建议在生产环境中使用。其他的表达式例如运算符、`cast` 和 `case when` 也同样为实验特性，不建议在生产环境中使用。如果仍然希望使用，可以在 [TiDB 配置文件](/tidb-configuration-file.md#allow-expression-index-从-v400-版本开始引入)中进行以下设置： +> 对于以上列表之外的函数，由于未完成充分测试，当前仍为实验特性，不建议在生产环境中使用。其他的表达式例如运算符、`cast` 和 `case when` 也同样为实验特性，不建议在生产环境中使用。如果仍然希望使用，可以在 [TiDB 配置文件](/tidb-configuration-file.md#allow-expression-index-从-v400-版本开始引入)中进行以下设置： > > {{< copyable "sql" >}} >