json: update json doc (pingcap#11180)

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)。

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 实验特性）
 

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`

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 值的函数

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" >}}
 >