Extend JSON function docs (#17758)

pingcap · Jul 10, 2024 · 3d86c68 · 3d86c68
1 parent b2a7bb1
commit 3d86c68
Show file tree

Hide file tree

Showing 13 changed files with 1,692 additions and 60 deletions.
diff --git a/TOC-tidb-cloud.md b/TOC-tidb-cloud.md
@@ -526,7 +526,15 @@
       - [Encryption and Compression Functions](/functions-and-operators/encryption-and-compression-functions.md)
       - [Locking Functions](/functions-and-operators/locking-functions.md)
       - [Information Functions](/functions-and-operators/information-functions.md)
-      - [JSON Functions](/functions-and-operators/json-functions.md)
+      - JSON Functions
+        - [Overview](/functions-and-operators/json-functions.md)
+        - [Functions That Create JSON](/functions-and-operators/json-functions/json-functions-create.md)
+        - [Functions That Search JSON](/functions-and-operators/json-functions/json-functions-search.md)
+        - [Functions That Modify JSON](/functions-and-operators/json-functions/json-functions-modify.md)
+        - [Functions That Return JSON](/functions-and-operators/json-functions/json-functions-return.md)
+        - [JSON Utility Functions](/functions-and-operators/json-functions/json-functions-utility.md)
+        - [Functions That Aggregate JSON](/functions-and-operators/json-functions/json-functions-aggregate.md)
+        - [Functions That Validate JSON](/functions-and-operators/json-functions/json-functions-validate.md)
       - [Aggregate (GROUP BY) Functions](/functions-and-operators/aggregate-group-by-functions.md)
       - [GROUP BY Modifiers](/functions-and-operators/group-by-modifier.md)
       - [Window Functions](/functions-and-operators/window-functions.md)

diff --git a/TOC.md b/TOC.md
@@ -907,7 +907,15 @@
       - [Encryption and Compression Functions](/functions-and-operators/encryption-and-compression-functions.md)
       - [Locking Functions](/functions-and-operators/locking-functions.md)
       - [Information Functions](/functions-and-operators/information-functions.md)
-      - [JSON Functions](/functions-and-operators/json-functions.md)
+      - JSON Functions
+        - [Overview](/functions-and-operators/json-functions.md)
+        - [Functions That Create JSON](/functions-and-operators/json-functions/json-functions-create.md)
+        - [Functions That Search JSON](/functions-and-operators/json-functions/json-functions-search.md)
+        - [Functions That Modify JSON](/functions-and-operators/json-functions/json-functions-modify.md)
+        - [Functions That Return JSON](/functions-and-operators/json-functions/json-functions-return.md)
+        - [JSON Utility Functions](/functions-and-operators/json-functions/json-functions-utility.md)
+        - [Functions That Aggregate JSON](/functions-and-operators/json-functions/json-functions-aggregate.md)
+        - [Functions That Validate JSON](/functions-and-operators/json-functions/json-functions-validate.md)
       - [Aggregate (GROUP BY) Functions](/functions-and-operators/aggregate-group-by-functions.md)
       - [GROUP BY Modifiers](/functions-and-operators/group-by-modifier.md)
       - [Window Functions](/functions-and-operators/window-functions.md)

diff --git a/data-type-default-values.md b/data-type-default-values.md
@@ -14,7 +14,7 @@ You can set default values for all data types. Typically, default values must be
 - For integer types, you can use the `NEXT VALUE FOR` function to set the next value of a sequence as the default value for a column, and use the [`RAND()`](/functions-and-operators/numeric-functions-and-operators.md) function to generate a random floating-point value as the default value for a column.
 - For string types, you can use the [`UUID()`](/functions-and-operators/miscellaneous-functions.md) function to generate a [universally unique identifier (UUID)](/best-practices/uuid.md) as the default value for a column.
 - For binary types, you can use the [`UUID_TO_BIN()`](/functions-and-operators/miscellaneous-functions.md) function to convert a UUID to the binary format and set the converted value as the default value for a column.
-- Starting from v8.0.0, TiDB additionally supports [specifying the default values](#specify-expressions-as-default-values) for [`BLOB`](/data-type-string.md#blob-type), [`TEXT`](/data-type-string.md#text-type), and [`JSON`](/data-type-json.md#json-type) data types, but you can only use expressions to set the [default values](#default-values) for them.
+- Starting from v8.0.0, TiDB additionally supports [specifying the default values](#specify-expressions-as-default-values) for [`BLOB`](/data-type-string.md#blob-type), [`TEXT`](/data-type-string.md#text-type), and [`JSON`](/data-type-json.md#json-data-type) data types, but you can only use expressions to set the [default values](#default-values) for them.
 
 If a column definition includes no explicit `DEFAULT` value, TiDB determines the default value as follows:
 

diff --git a/data-type-json.md b/data-type-json.md
@@ -4,7 +4,7 @@ summary: Learn about the JSON data type in TiDB.
 aliases: ['/docs/dev/data-type-json/','/docs/dev/reference/sql/data-types/json/']
 ---
 
-# JSON Type
+# JSON Data Type
 
 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:
 
@@ -26,6 +26,27 @@ 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).
 
+## JSON value types
+
+The values inside a JSON document have types. This is visible in the output of [`JSON_TYPE`()](/functions-and-operators/json-functions/json-functions-return.md#json_type).
+
+| Type             | Example                        |
+|------------------|--------------------------------|
+| 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`          |
+
 ## Restrictions
 
 - Currently, TiDB only supports pushing down limited `JSON` functions to TiFlash. For more information, see [Push-down expressions](/tiflash/tiflash-supported-pushdown-calculations.md#push-down-expressions).
@@ -102,4 +123,4 @@ For more information, see [JSON Functions](/functions-and-operators/json-functio
     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).
+For more information about the `JSON` data type, see [JSON functions](/functions-and-operators/json-functions.md) and [Generated Columns](/generated-columns.md).
diff --git a/functions-and-operators/aggregate-group-by-functions.md b/functions-and-operators/aggregate-group-by-functions.md
@@ -12,20 +12,21 @@ This document describes details about the supported aggregate functions in TiDB.
 
 This section describes the supported MySQL `GROUP BY` aggregate functions in TiDB.
 
-| Name                                                                                                        | Description                                       |
-|:--------------------------------------------------------------------------------------------------------------|:--------------------------------------------------|
+| Name                                                                                                           | Description                                       |
+|:---------------------------------------------------------------------------------------------------------------|:--------------------------------------------------|
 | [`COUNT()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_count)                   | Return a count of the number of rows returned     |
 | [`COUNT(DISTINCT)`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_count-distinct)  | Return the count of a number of different values  |
 | [`SUM()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_sum)                       | Return the sum                                    |
 | [`AVG()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_avg)                       | Return the average value of the argument          |
 | [`MAX()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_max)                       | Return the maximum value                          |
 | [`MIN()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_min)                       | Return the minimum value                          |
-| [`GROUP_CONCAT()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_group-concat)     | Return a concatenated string                     |
-| [`VARIANCE()`, `VAR_POP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_var-pop) | Return the population standard variance|
-| [`STD()`, `STDDEV()`, `STDDEV_POP`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_std) | Return the population standard deviation |
-| [`VAR_SAMP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_var-samp) | Return the sample variance |
-| [`STDDEV_SAMP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_stddev-samp) | Return the sample standard deviation |
-| [`JSON_OBJECTAGG(key, value)`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_json-objectagg) | Return the result set as a single JSON object containing key-value pairs |
+| [`GROUP_CONCAT()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_group-concat)     | Return a concatenated string                      |
+| [`VARIANCE()`, `VAR_POP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_var-pop) | Return the population standard variance           |
+| [`STD()`, `STDDEV()`, `STDDEV_POP`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_std) | Return the population standard deviation      |
+| [`VAR_SAMP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_var-samp)             | Return the sample variance                        |
+| [`STDDEV_SAMP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_stddev-samp)       | Return the sample standard deviation              |
+| [`JSON_ARRAYAGG()`](/functions-and-operators/json-functions/json-functions-aggregate.md#json_arrayagg)         | Return the result set as a single JSON array      |
+| [`JSON_OBJECTAGG()`](/functions-and-operators/json-functions/json-functions-aggregate.md#json_objectagg)       | Return the result set as a single JSON object containing key-value pairs |
 
 - Unless otherwise stated, group functions ignore `NULL` values.
 - If you use a group function in a statement containing no `GROUP BY` clause, it is equivalent to grouping on all rows.
@@ -40,23 +41,19 @@ In addition, TiDB also provides the following aggregate functions:
 
     The following example shows how to calculate the fiftieth percentile of a `INT` column:
 
-    {{< 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 |
     +--------------------------+
@@ -153,4 +150,4 @@ group by id, val;
 
 ## Related system variables
 
-The `group_concat_max_len` variable sets the maximum number of items for the `GROUP_CONCAT()` function.
+The [`group_concat_max_len`](/system-variables.md#group_concat_max_len) variable sets the maximum number of items for the `GROUP_CONCAT()` function.