docs: add doc for json datatype (#1232)

Co-authored-by: Yiran <[email protected]>
GreptimeTeam · Oct 24, 2024 · 380da7c · 380da7c
1 parent 5ec26e1
commit 380da7c
Show file tree

Hide file tree

Showing 4 changed files with 212 additions and 0 deletions.
diff --git a/docs/reference/sql/data-types.md b/docs/reference/sql/data-types.md
@@ -194,6 +194,59 @@ Supported abbreviations include:
 | us    | microseconds  |
 | ns    | nanoseconds   |
 
+## JSON Type
+GreptimeDB supports the JSON type, allowing users to store and query JSON-formatted data. The JSON type is highly flexible and can store various forms of structured or unstructured data, making it suitable for use cases such as logging, analytics, and semi-structured data storage.
+
+```sql
+CREATE TABLE json_data(
+    my_json JSON, 
+    ts TIMESTAMP TIME INDEX
+);
+
+INSERT INTO json_data VALUES ('{"key1": "value1", "key2": 10}', 1000), 
+                             ('{"name": "GreptimeDB", "open_source": true}', 2000);
+
+SELECT * FROM json_data;
+```
+
+Output:
+
+```
++------------------------------------------+---------------------+
+| my_json                                  | ts                  |
++------------------------------------------+---------------------+
+| {"key1":"value1","key2":10}              | 1970-01-01 00:00:01 |
+| {"name":"GreptimeDB","open_source":true} | 1970-01-01 00:00:02 |
++------------------------------------------+---------------------+
+```
+
+:::warning Limitation
+
+1. The gRPC protocol does not support inserting JSON data through automatic table creation. However, you can manually create a table and insert JSON data by defining the JSON column as a String type.
+2. The insertion of JSON data using MySQL protocol prepared statements is not supported.
+
+:::
+
+### Query JSON data
+
+You can query the JSON data directly or extract specific fields using [JSON functions](./functions/overview.md#json-functions) provided by GreptimeDB. Here's an example:
+
+```sql
+SELECT json_get_string(my_json, '$.name') as name FROM json_data;
+```
+
+Output:
+
+```
++---------------------------------------------------+
+| name                                              |
++---------------------------------------------------+
+| NULL                                              |
+| GreptimeDB                                        |
++---------------------------------------------------+
+```
+
+
 ## Boolean Type
 
 | Type Name | Description | Size |

diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/data-types.md b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/data-types.md
@@ -194,6 +194,60 @@ SELECT '-1h5m'::INTERVAL;
 | us    | microseconds  |
 | ns    | nanoseconds   |
 
+## JSON 类型
+GreptimeDB 支持 JSON 类型，允许用户存储和查询 JSON 格式的数据。JSON 类型非常灵活，可以存储各种形式的结构化或非结构化数据，适合日志记录、分析和半结构化数据存储等场景。
+
+```sql
+CREATE TABLE json_data(
+    my_json JSON, 
+    ts TIMESTAMP TIME INDEX
+);
+
+INSERT INTO json_data VALUES ('{"key1": "value1", "key2": 10}', 1000), 
+                             ('{"name": "GreptimeDB", "open_source": true}', 2000);
+
+SELECT * FROM json_data;
+```
+
+输出:
+
+```
++------------------------------------------+---------------------+
+| my_json                                  | ts                  |
++------------------------------------------+---------------------+
+| {"key1":"value1","key2":10}              | 1970-01-01 00:00:01 |
+| {"name":"GreptimeDB","open_source":true} | 1970-01-01 00:00:02 |
++------------------------------------------+---------------------+
+```
+
+:::warning 限制说明 
+
+1. gRPC 协议不支持通过自动建表写入 JSON 数据。不过，您可以手动创建表，并将 JSON 数据列设置为 String 类型进行写入。
+2. 不支持通过 MySQL 协议预处理语句插入 JSON 数据。
+
+:::
+
+
+### 查询 JSON 数据
+
+您可以直接查询 JSON 数据，也可以使用 GreptimeDB 提供的 [JSON 函数](./functions/overview.md#json-functions) 提取特定字段。以下是一个示例：
+
+```sql
+SELECT json_get_string(my_json, '$.name') as name FROM json_data;
+```
+
+输出:
+
+```
++---------------------------------------------------+
+| name                                              |
++---------------------------------------------------+
+| NULL                                              |
+| GreptimeDB                                        |
++---------------------------------------------------+
+```
+
+
 ## 布尔类型
 
 | 类型名称 | 描述 | 大小 |

diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-0.9/reference/sql/data-types.md b/i18n/zh/docusaurus-plugin-content-docs/version-0.9/reference/sql/data-types.md
@@ -194,6 +194,59 @@ SELECT '-1h5m'::INTERVAL;
 | us    | microseconds  |
 | ns    | nanoseconds   |
 
+## JSON 类型
+GreptimeDB 支持 JSON 类型，允许用户存储和查询 JSON 格式的数据。JSON 类型非常灵活，可以存储各种形式的结构化或非结构化数据，适合日志记录、分析和半结构化数据存储等场景。
+
+```sql
+CREATE TABLE json_data(
+    my_json JSON, 
+    ts TIMESTAMP TIME INDEX
+);
+
+INSERT INTO json_data VALUES ('{"key1": "value1", "key2": 10}', 1000), 
+                             ('{"name": "GreptimeDB", "open_source": true}', 2000);
+
+SELECT * FROM json_data;
+```
+
+输出:
+
+```
++------------------------------------------+---------------------+
+| my_json                                  | ts                  |
++------------------------------------------+---------------------+
+| {"key1":"value1","key2":10}              | 1970-01-01 00:00:01 |
+| {"name":"GreptimeDB","open_source":true} | 1970-01-01 00:00:02 |
++------------------------------------------+---------------------+
+```
+
+:::warning 限制说明 
+
+1. gRPC 协议不支持通过自动建表写入 JSON 数据。不过，您可以手动创建表，并将 JSON 数据列设置为 String 类型进行写入。
+2. 不支持通过 MySQL 协议预处理语句插入 JSON 数据。
+
+:::
+
+
+### 查询 JSON 数据
+
+您可以直接查询 JSON 数据，也可以使用 GreptimeDB 提供的 [JSON 函数](./functions/overview.md#json-functions) 提取特定字段。以下是一个示例：
+
+```sql
+SELECT json_get_string(my_json, '$.name') as name FROM json_data;
+```
+
+输出:
+
+```
++---------------------------------------------------+
+| name                                              |
++---------------------------------------------------+
+| NULL                                              |
+| GreptimeDB                                        |
++---------------------------------------------------+
+```
+
 ## 布尔类型
 
 | 类型名称 | 描述 | 大小 |

diff --git a/versioned_docs/version-0.9/reference/sql/data-types.md b/versioned_docs/version-0.9/reference/sql/data-types.md
@@ -194,6 +194,58 @@ Supported abbreviations include:
 | us    | microseconds  |
 | ns    | nanoseconds   |
 
+## JSON Type
+GreptimeDB supports the JSON type, allowing users to store and query JSON-formatted data. The JSON type is highly flexible and can store various forms of structured or unstructured data, making it suitable for use cases such as logging, analytics, and semi-structured data storage.
+
+```sql
+CREATE TABLE json_data(
+    my_json JSON, 
+    ts TIMESTAMP TIME INDEX
+);
+
+INSERT INTO json_data VALUES ('{"key1": "value1", "key2": 10}', 1000), 
+                             ('{"name": "GreptimeDB", "open_source": true}', 2000);
+
+SELECT * FROM json_data;
+```
+
+Output:
+
+```
++------------------------------------------+---------------------+
+| my_json                                  | ts                  |
++------------------------------------------+---------------------+
+| {"key1":"value1","key2":10}              | 1970-01-01 00:00:01 |
+| {"name":"GreptimeDB","open_source":true} | 1970-01-01 00:00:02 |
++------------------------------------------+---------------------+
+```
+
+:::warning Limitation
+
+1. The gRPC protocol does not support inserting JSON data through automatic table creation. However, you can manually create a table and insert JSON data by defining the JSON column as a String type.
+2. The insertion of JSON data using MySQL protocol prepared statements is not supported.
+
+:::
+
+### Query JSON data
+
+You can query the JSON data directly or extract specific fields using [JSON functions](./functions/overview.md#json-functions) provided by GreptimeDB. Here's an example:
+
+```sql
+SELECT json_get_string(my_json, '$.name') as name FROM json_data;
+```
+
+Output:
+
+```
++---------------------------------------------------+
+| name                                              |
++---------------------------------------------------+
+| NULL                                              |
+| GreptimeDB                                        |
++---------------------------------------------------+
+```
+
 ## Boolean Type
 
 | Type Name | Description | Size |