Skip to content

Commit 3d86c68

Browse files
authored
Extend JSON function docs (pingcap#17758)
1 parent b2a7bb1 commit 3d86c68

13 files changed

+1692
-60
lines changed

TOC-tidb-cloud.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -526,7 +526,15 @@
526526
- [Encryption and Compression Functions](/functions-and-operators/encryption-and-compression-functions.md)
527527
- [Locking Functions](/functions-and-operators/locking-functions.md)
528528
- [Information Functions](/functions-and-operators/information-functions.md)
529-
- [JSON Functions](/functions-and-operators/json-functions.md)
529+
- JSON Functions
530+
- [Overview](/functions-and-operators/json-functions.md)
531+
- [Functions That Create JSON](/functions-and-operators/json-functions/json-functions-create.md)
532+
- [Functions That Search JSON](/functions-and-operators/json-functions/json-functions-search.md)
533+
- [Functions That Modify JSON](/functions-and-operators/json-functions/json-functions-modify.md)
534+
- [Functions That Return JSON](/functions-and-operators/json-functions/json-functions-return.md)
535+
- [JSON Utility Functions](/functions-and-operators/json-functions/json-functions-utility.md)
536+
- [Functions That Aggregate JSON](/functions-and-operators/json-functions/json-functions-aggregate.md)
537+
- [Functions That Validate JSON](/functions-and-operators/json-functions/json-functions-validate.md)
530538
- [Aggregate (GROUP BY) Functions](/functions-and-operators/aggregate-group-by-functions.md)
531539
- [GROUP BY Modifiers](/functions-and-operators/group-by-modifier.md)
532540
- [Window Functions](/functions-and-operators/window-functions.md)

TOC.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -907,7 +907,15 @@
907907
- [Encryption and Compression Functions](/functions-and-operators/encryption-and-compression-functions.md)
908908
- [Locking Functions](/functions-and-operators/locking-functions.md)
909909
- [Information Functions](/functions-and-operators/information-functions.md)
910-
- [JSON Functions](/functions-and-operators/json-functions.md)
910+
- JSON Functions
911+
- [Overview](/functions-and-operators/json-functions.md)
912+
- [Functions That Create JSON](/functions-and-operators/json-functions/json-functions-create.md)
913+
- [Functions That Search JSON](/functions-and-operators/json-functions/json-functions-search.md)
914+
- [Functions That Modify JSON](/functions-and-operators/json-functions/json-functions-modify.md)
915+
- [Functions That Return JSON](/functions-and-operators/json-functions/json-functions-return.md)
916+
- [JSON Utility Functions](/functions-and-operators/json-functions/json-functions-utility.md)
917+
- [Functions That Aggregate JSON](/functions-and-operators/json-functions/json-functions-aggregate.md)
918+
- [Functions That Validate JSON](/functions-and-operators/json-functions/json-functions-validate.md)
911919
- [Aggregate (GROUP BY) Functions](/functions-and-operators/aggregate-group-by-functions.md)
912920
- [GROUP BY Modifiers](/functions-and-operators/group-by-modifier.md)
913921
- [Window Functions](/functions-and-operators/window-functions.md)

data-type-default-values.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ You can set default values for all data types. Typically, default values must be
1414
- 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.
1515
- 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.
1616
- 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.
17-
- 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.
17+
- 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.
1818

1919
If a column definition includes no explicit `DEFAULT` value, TiDB determines the default value as follows:
2020

data-type-json.md

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ summary: Learn about the JSON data type in TiDB.
44
aliases: ['/docs/dev/data-type-json/','/docs/dev/reference/sql/data-types/json/']
55
---
66

7-
# JSON Type
7+
# JSON Data Type
88

99
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:
1010

@@ -26,6 +26,27 @@ SELECT id FROM city WHERE population >= 100;
2626

2727
For more information, see [JSON Functions](/functions-and-operators/json-functions.md) and [Generated Columns](/generated-columns.md).
2828

29+
## JSON value types
30+
31+
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).
32+
33+
| Type | Example |
34+
|------------------|--------------------------------|
35+
| ARRAY | `[]` |
36+
| BIT | |
37+
| BLOB | `0x616263` |
38+
| BOOLEAN | `true` |
39+
| DATE | `"2025-06-14"` |
40+
| DATETIME | `"2025-06-14 09:05:10.000000"` |
41+
| DOUBLE | `1.14` |
42+
| INTEGER | `5` |
43+
| NULL | `null` |
44+
| OBJECT | `{}` |
45+
| OPAQUE | |
46+
| STRING | `"foobar"` |
47+
| TIME | `"09:10:00.000000"` |
48+
| UNSIGNED INTEGER | `9223372036854776000` |
49+
2950
## Restrictions
3051

3152
- 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
102123
INSERT INTO t VALUES (3);
103124
```
104125

105-
For more information about the `JSON` data type, see [JSON functions](/functions-and-operators/json-functions.md) and [Generated Columns](/generated-columns.md).
126+
For more information about the `JSON` data type, see [JSON functions](/functions-and-operators/json-functions.md) and [Generated Columns](/generated-columns.md).

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

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -12,20 +12,21 @@ This document describes details about the supported aggregate functions in TiDB.
1212

1313
This section describes the supported MySQL `GROUP BY` aggregate functions in TiDB.
1414

15-
| Name | Description |
16-
|:--------------------------------------------------------------------------------------------------------------|:--------------------------------------------------|
15+
| Name | Description |
16+
|:---------------------------------------------------------------------------------------------------------------|:--------------------------------------------------|
1717
| [`COUNT()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_count) | Return a count of the number of rows returned |
1818
| [`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 |
1919
| [`SUM()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_sum) | Return the sum |
2020
| [`AVG()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_avg) | Return the average value of the argument |
2121
| [`MAX()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_max) | Return the maximum value |
2222
| [`MIN()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_min) | Return the minimum value |
23-
| [`GROUP_CONCAT()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_group-concat) | Return a concatenated string |
24-
| [`VARIANCE()`, `VAR_POP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_var-pop) | Return the population standard variance|
25-
| [`STD()`, `STDDEV()`, `STDDEV_POP`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_std) | Return the population standard deviation |
26-
| [`VAR_SAMP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_var-samp) | Return the sample variance |
27-
| [`STDDEV_SAMP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_stddev-samp) | Return the sample standard deviation |
28-
| [`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 |
23+
| [`GROUP_CONCAT()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_group-concat) | Return a concatenated string |
24+
| [`VARIANCE()`, `VAR_POP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_var-pop) | Return the population standard variance |
25+
| [`STD()`, `STDDEV()`, `STDDEV_POP`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_std) | Return the population standard deviation |
26+
| [`VAR_SAMP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_var-samp) | Return the sample variance |
27+
| [`STDDEV_SAMP()`](https://dev.mysql.com/doc/refman/8.0/en/aggregate-functions.html#function_stddev-samp) | Return the sample standard deviation |
28+
| [`JSON_ARRAYAGG()`](/functions-and-operators/json-functions/json-functions-aggregate.md#json_arrayagg) | Return the result set as a single JSON array |
29+
| [`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 |
2930

3031
- Unless otherwise stated, group functions ignore `NULL` values.
3132
- 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:
4041

4142
The following example shows how to calculate the fiftieth percentile of a `INT` column:
4243

43-
{{< copyable "sql" >}}
44-
4544
```sql
46-
drop table if exists t;
47-
create table t(a int);
48-
insert into t values(1), (2), (3);
45+
DROP TABLE IF EXISTS t;
46+
CREATE TABLE t(a INT);
47+
INSERT INTO t VALUES(1), (2), (3);
4948
```
5049

51-
{{< copyable "sql" >}}
52-
5350
```sql
54-
select approx_percentile(a, 50) from t;
51+
SELECT APPROX_PERCENTILE(a, 50) FROM t;
5552
```
5653

5754
```sql
5855
+--------------------------+
59-
| approx_percentile(a, 50) |
56+
| APPROX_PERCENTILE(a, 50) |
6057
+--------------------------+
6158
| 2 |
6259
+--------------------------+
@@ -153,4 +150,4 @@ group by id, val;
153150
154151
## Related system variables
155152
156-
The `group_concat_max_len` variable sets the maximum number of items for the `GROUP_CONCAT()` function.
153+
The [`group_concat_max_len`](/system-variables.md#group_concat_max_len) variable sets the maximum number of items for the `GROUP_CONCAT()` function.

0 commit comments

Comments
 (0)