json: update json doc pingcap#11180 (pingcap#10389)

data-type-json.md

@@ -6,10 +6,6 @@ aliases: ['/docs/dev/data-type-json/','/docs/dev/reference/sql/data-types/json/'
 
 # JSON Type
 
-> **Warning:**
->
-> This is still an experimental feature. It is **NOT** recommended that you use it in the production environment.
-
 TiDB supports the `JSON` (JavaScript Object Notation) data type, which is useful for storing semi-structured data.  The `JSON` data type provides the following advantages over storing `JSON`-format strings in a string column:
 
 - Use the Binary format for serialization. The internal format permits quick read access to `JSON` document elements.
@@ -29,3 +25,88 @@ SELECT id FROM city WHERE population >= 100;
 ```
 
 For more information, see [JSON Functions](/functions-and-operators/json-functions.md) and [Generated Columns](/generated-columns.md).
+
+## Restrictions
+
+- Currently, TiDB does not support pushing down `JSON` functions to TiFlash.
+- TiDB does not support using the range selection syntax in JSON PATH. For example, executing the following SQL statements in TiDB will return errors.
+
+    ```sql
+    SELECT j->'$[1 to 2]' FROM t;
+    SELECT j->'$[last]' FROM t;
+    ```
+
+- TiDB Backup & Restore (BR) versions earlier than v6.3.0 do not support recovering data containing JSON columns. No version of BR supports recovering data containing JSON columns to TiDB clusters earlier than v6.3.0.
+- Do not use any replication tool to replicate data containing non-standard `JSON` data types, such as `DATE`, `DATETIME`, and `TIME`.
+
+## MySQL compatibility
+
+- When you create JSON columns with data in the `BINARY` type, MySQL mislabels the data as the `STRING` type currently, while TiDB processes it as the `BINARY` type correctly.
+
+    ```sql
+    CREATE TABLE test(a json);
+    INSERT INTO test SELECT json_objectagg('a', b'01010101');
+
+    -- In TiDB, executing the following SQL statement returns `0, 0`. In MySQL, executing the following SQL statement returns `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)
+    ```
+
+    For more information, see issue [#37443](https://github.com/pingcap/tidb/issues/37443).
+
+- When converting the data type from `ENUM` or `SET` to `JSON`, TiDB checks the correctness of data format. For example, executing the following SQL statements in TiDB will return an error.
+
+    ```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.
+    ```
+
+    For more information, see issue [#9999](https://github.com/pingcap/tidb/issues/9999).
+
+- In TiDB, you can use `ORDER BY` to sort JSON arrays or JSON objects.
+
+    In MySQL, if you use `ORDER BY` to sort JSON arrays or JSON objects, MySQL returns a warning and the sorting result does not match the result of the comparison operation:
+
+    ```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)
+
+    -- In TiDB, executing the following SQL statement returns the correct sorting result. In MySQL, executing the following SQL statement returns the "This version of MySQL doesn't yet support 'sorting of non-scalar JSON values'." warning and the sorting result is inconsistent with the comparison result of `<`.
+    mysql> SELECT j FROM t ORDER BY j;
+    +--------------+
+    | j            |
+    +--------------+
+    | [1, 2, 3, 4] |
+    | [5]          |
+    +--------------+
+    2 rows in set (0.00 sec)
+    ```
+
+    For more information, see issue [#37506](https://github.com/pingcap/tidb/issues/37506).
+
+- When you insert data to a JSON column, TiDB implicitly converts the value of the data to the `JSON` type.
+
+    ```sql
+    CREATE TABLE t(col JSON);
+
+    -- In TiDB, the following INSERT statement is executed successfully. In MySQL, executing the following INSERT statement returns the "Invalid JSON text" error.
+    INSERT INTO t VALUES (3);
+    ```
+
+For more information about the `JSON` data type, see [JSON functions](/functions-and-operators/json-functions.md) and [Generated Columns](/generated-columns.md).

experimental-features.md

@@ -32,7 +32,6 @@ Elastic scheduling feature. It enables the TiDB cluster to dynamically scale out
 + The expression index feature. The expression index is also called the function-based index. When you create an index, the index fields do not have to be a specific column but can be an expression calculated from one or more columns. This feature is useful for quickly accessing the calculation-based tables. See [Expression index](/sql-statements/sql-statement-create-index.md) for details. (Introduced in v4.0)
 + [Generated Columns](/generated-columns.md) (Introduced in v2.1)
 + [User-Defined Variables](/user-defined-variables.md) (Introduced in v2.1)
-+ [JSON data type](/data-type-json.md) and [JSON functions](/functions-and-operators/json-functions.md) (Introduced in v2.1)
 + [Cascades Planner](/system-variables.md#tidb_enable_cascades_planner): a cascades framework-based top-down query optimizer (Introduced in v3.0)
 + [`ALTER TABLE ... COMPACT`](/sql-statements/sql-statement-alter-table-compact.md) (Introduced in v6.1.0)
 

functions-and-operators/aggregate-group-by-functions.md

@@ -151,12 +151,6 @@ from tbl_name
 group by id, val;
 ```
 
-## Unsupported aggregate functions
-
-The following aggregate functions are currently unsupported in TiDB. You can track our progress in [TiDB #7623](https://github.com/pingcap/tidb/issues/7623):
-
-- `JSON_ARRAYAGG`
-
 ## Related system variables
 
 The `group_concat_max_len` variable sets the maximum number of items for the `GROUP_CONCAT()` function.

functions-and-operators/json-functions.md

@@ -6,10 +6,6 @@ aliases: ['/docs/dev/functions-and-operators/json-functions/','/docs/dev/referen
 
 # JSON Functions
 
-> **Warning:**
->
-> This is still an experimental feature. It is **NOT** recommended that you use it in the production environment.
-
 TiDB supports most of the JSON functions that shipped with the GA release of MySQL 5.7.
 
 ## Functions that create JSON values

sql-statements/sql-statement-create-index.md

@@ -142,21 +142,13 @@ You can drop an expression index in the same way as dropping an ordinary index:
 DROP INDEX idx1 ON t1;
 ```
 
-Expression index involves various kinds of expressions. To ensure correctness, only some fully tested functions are allowed for creating an expression index. This means that only these functions are allowed in expressions in a production environment. You can get these functions by querying `tidb_allow_function_for_expression_index` variable.
+Expression index involves various kinds of expressions. To ensure correctness, only some fully tested functions are allowed for creating an expression index. This means that only these functions are allowed in expressions in a production environment. You can get these functions by querying the `tidb_allow_function_for_expression_index` variable. Currently, the allowed functions are as follows:
 
-{{< 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
 ```
 
-For the functions that are not included in the returned result above, those functions are not fully tested and not recommended for a production environment, which can be seen as experimental. Other expressions such as operators, `cast`, and `case when` are also seen as experimental and not recommended for production.
+For the functions that are not included in the above list, those functions are not fully tested and not recommended for a production environment, which can be seen as experimental. Other expressions such as operators, `cast`, and `case when` are also seen as experimental and not recommended for production.
 
 <CustomContent platform="tidb">