From 24ad9b3d98eeb7049fa594985fae524b1355f3d7 Mon Sep 17 00:00:00 2001 From: fys Date: Wed, 8 Jul 2026 18:56:12 +0800 Subject: [PATCH 1/9] docs: json2 data type --- docs/user-guide/logs/json2.md | 135 ++++++++++++++++++++++++++++++++++ sidebars.ts | 1 + 2 files changed, 136 insertions(+) create mode 100644 docs/user-guide/logs/json2.md diff --git a/docs/user-guide/logs/json2.md b/docs/user-guide/logs/json2.md new file mode 100644 index 000000000..6b8432295 --- /dev/null +++ b/docs/user-guide/logs/json2.md @@ -0,0 +1,135 @@ +--- +keywords: [JSON2, JSON, logs, structured logs, type hints, json_get] +description: 介绍 GreptimeDB 中 JSON2 类型的使用方式，包括建表、type hint、JSON 字段读取以及当前限制。 +--- + +# JSON2 类型 + +JSON2 是 GreptimeDB 为日志和半结构化数据设计的 JSON 类型。 +它会将 JSON 中的字段以结构化、列式的方式存储，使常用字段能够像普通列一样被高效读取、过滤和聚合，同时保留 JSON 对动态结构的表达能力。 + +:::note +JSON2 目前处于 Beta 阶段。我们会保持向后兼容，并在后续版本中继续完善功能、改进当前限制。 +::: + +## 创建 JSON2 列 + +在建表时，可以使用 `JSON2` 类型声明 JSON2 列。 +当前 JSON2 只能在 append-only 表中使用，因此建表时需要设置 `'append_mode' = 'true'`。 + +```sql +CREATE TABLE application_logs ( + ts TIMESTAMP TIME INDEX, + message STRING, + attrs JSON2 +) WITH ( + 'append_mode' = 'true' +); +``` + +写入 JSON2 列时，可以写入 JSON 数据。目前暂不支持写入非 object 类型的 JSON 值： + +```sql +INSERT INTO application_logs +VALUES + ( + 1, + 'request completed', + '{"user":{"id":1001},"http":{"status":200},"success":true}' + ), + ( + 2, + 'request failed', + '{"user":{"id":1002},"http":{"status":500},"success":false}' + ); +``` + +## 使用 type hint + +Type hint 用于为 JSON2 中的子路径声明确定的数据类型。声明后，这些子路径会按指定类型存储和读取，从而获得接近普通列的查询性能，并在写入时进行类型校验。 + +当某些 JSON 子路径类型明确，并且会被频繁查询、过滤或聚合时，建议在建表语句中定义 type hint。 + +```sql +CREATE TABLE application_logs ( + ts TIMESTAMP TIME INDEX, + message STRING, + attrs JSON2 ( + user.id BIGINT NOT NULL, + user.name STRING DEFAULT 'unknown', + http.status BIGINT, + success BOOLEAN NULL, + duration DOUBLE NULL DEFAULT 0.0 + ) +) WITH ( + 'append_mode' = 'true' +); +``` + +Type hint 的基本语法如下： + +```sql +json_column JSON2 ( + path.to.field DATA_TYPE [NULL | NOT NULL] [DEFAULT literal] +) +``` + +Type hint 的路径使用点号分隔，例如 `user.id` 对应 JSON 中的 +`{"user":{"id":...}}`。 + +如果某个 JSON key 本身包含点号，需要用双引号包住该路径段。 +例如 `"service.name"` 表示读取 root object 中名为 `service.name` +的 key，而不是读取 `service.name` 这条嵌套路径。 + +当前 type hint 支持以下类型： + +| Type hint 类型 | 说明 | +| --- | --- | +| `STRING` | 字符串类型。`TEXT`、`VARCHAR`、`CHAR` 等别名会归一为 `STRING`。 | +| `BIGINT` | 有符号整数类型。`INT`、`INTEGER`、`SMALLINT` 等整数类型会归一为 `BIGINT`。 | +| `BIGINT UNSIGNED` | 无符号整数类型。无符号整数类型会归一为 `BIGINT UNSIGNED`。 | +| `DOUBLE` | 浮点类型。`FLOAT`、`REAL` 等类型会归一为 `DOUBLE`。 | +| `BOOLEAN` | 布尔类型。 | + +Type hint 默认允许 `NULL`。如果设置 `NOT NULL`，写入的 JSON 中必须存在该路径。 + +## 查询 JSON2 字段 + +可以使用 `json_get` 读取 JSON2 中的嵌套字段： + +```sql +SELECT + json_get(attrs, 'user.id'), + json_get(attrs, 'user.name'), + json_get(attrs, 'http.status'), + json_get(attrs, 'success') +FROM application_logs; +``` + +`json_get` 的基本语法如下： + +```sql +json_get(json_column, 'path.to.field') +``` + +如果你希望直接指定返回类型，也可以使用 JSON 函数： + +```sql +SELECT + json_get_int(attrs, 'user.id'), + json_get_string(attrs, 'user.name'), + json_get_bool(attrs, 'success'), + json_get_float(attrs, 'duration') +FROM application_logs; +``` + +## 未来规划 + +JSON2 目前处于 Beta 阶段。后续版本会继续完善以下能力： + +- 支持在非 append-only 表中使用 JSON2。 +- 支持写入 array、string、number、boolean 和 `null` 等非 object 类型的 + JSON root 值。 +- 支持通过 `json_get` 查询 JSON2 根列本身。 +- 扩展 type hint 支持的类型，例如 `TIMESTAMP` 等时间类型。 +- 为 type hint 支持 `INVERTED INDEX`、`SKIPPING INDEX` 等索引选项。 diff --git a/sidebars.ts b/sidebars.ts index beca2a627..63db3a087 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -238,6 +238,7 @@ const sidebars: SidebarsConfig = { label: 'Overview', }, 'user-guide/logs/quick-start', + 'user-guide/logs/json2', 'user-guide/logs/use-custom-pipelines', 'user-guide/logs/fulltext-search', 'user-guide/logs/manage-pipelines', From f6672ce0b1a94291c949d3349400bf56a7df8ead Mon Sep 17 00:00:00 2001 From: fys Date: Thu, 9 Jul 2026 17:45:30 +0800 Subject: [PATCH 2/9] refactor doc --- docs/user-guide/logs/json2.md | 144 +++++++++++++++++++++++++--------- 1 file changed, 106 insertions(+), 38 deletions(-) diff --git a/docs/user-guide/logs/json2.md b/docs/user-guide/logs/json2.md index 6b8432295..49990cf45 100644 --- a/docs/user-guide/logs/json2.md +++ b/docs/user-guide/logs/json2.md @@ -12,60 +12,132 @@ JSON2 是 GreptimeDB 为日志和半结构化数据设计的 JSON 类型。 JSON2 目前处于 Beta 阶段。我们会保持向后兼容，并在后续版本中继续完善功能、改进当前限制。 ::: -## 创建 JSON2 列 +## 快速入门 + +下面的示例创建一张 API 访问日志表，写入几条请求日志，并查询 JSON2 中的字段。固定字段放在普通列中，结构可能变化但经常查询的字段放在 JSON2 列 `attrs` 中。 + +### 创建表 在建表时，可以使用 `JSON2` 类型声明 JSON2 列。 当前 JSON2 只能在 append-only 表中使用，因此建表时需要设置 `'append_mode' = 'true'`。 +JSON2 支持 type hint，用于为子路径声明确定的数据类型。声明后，这些子路径会按指定类型存储，从而获得接近普通列的查询性能，并在写入时进行类型校验。下面的 `attrs` 列为 `http.status`、`latency_ms`、`error` 等常用路径定义了 type hint。 + ```sql +DROP TABLE IF EXISTS application_logs; + CREATE TABLE application_logs ( ts TIMESTAMP TIME INDEX, + service STRING, + log_level STRING, message STRING, - attrs JSON2 + attrs JSON2 ( + trace_id STRING, + user.id BIGINT, + user.name STRING DEFAULT 'anonymous', + http.method STRING, + http.path STRING, + http.status BIGINT, + latency_ms DOUBLE, + error BOOLEAN DEFAULT false + ) ) WITH ( 'append_mode' = 'true' ); ``` -写入 JSON2 列时，可以写入 JSON 数据。目前暂不支持写入非 object 类型的 JSON 值： +例如，`user.name STRING DEFAULT 'anonymous'` 表示当写入的 JSON 中缺少 `user.name` 时，查询结果使用默认值 `anonymous`。`error BOOLEAN DEFAULT false` 表示缺少 `error` 字段的日志会被视为非错误日志。 + +### 写入 JSON 数据 + +写入 JSON2 列时，可以写入 JSON object。下面的数据包含一次成功请求、一次慢请求和一次失败请求： ```sql INSERT INTO application_logs VALUES ( 1, + 'checkout', + 'INFO', 'request completed', - '{"user":{"id":1001},"http":{"status":200},"success":true}' + '{"trace_id":"8f3a1c","user":{"id":1001,"name":"Alice"},"http":{"method":"POST","path":"/v1/orders","status":200},"latency_ms":42.8}' ), ( 2, + 'checkout', + 'WARN', + 'slow request', + '{"trace_id":"8f3a1d","user":{"id":1002,"name":"Bob"},"http":{"method":"POST","path":"/v1/orders","status":200},"latency_ms":386.4}' + ), + ( + 3, + 'checkout', + 'ERROR', 'request failed', - '{"user":{"id":1002},"http":{"status":500},"success":false}' + '{"trace_id":"8f3a1e","user":{"id":1003},"http":{"method":"POST","path":"/v1/orders","status":500},"latency_ms":71.2,"error":true}' ); ``` -## 使用 type hint +### 查询 JSON 字段 + +可以直接通过点号路径读取 JSON2 中的字段： + +```sql +SELECT + ts, + service, + attrs.trace_id, + attrs.user.name, + attrs.http.status, + attrs.latency_ms, + attrs.error +FROM application_logs +ORDER BY ts; +``` + +查询结果如下： -Type hint 用于为 JSON2 中的子路径声明确定的数据类型。声明后，这些子路径会按指定类型存储和读取，从而获得接近普通列的查询性能，并在写入时进行类型校验。 +| ts | service | trace_id | user.name | http.status | latency_ms | error | +| --- | --- | --- | --- | --- | --- | --- | +| 1970-01-01 00:00:00.001 | checkout | 8f3a1c | Alice | 200 | 42.8 | false | +| 1970-01-01 00:00:00.002 | checkout | 8f3a1d | Bob | 200 | 386.4 | false | +| 1970-01-01 00:00:00.003 | checkout | 8f3a1e | anonymous | 500 | 71.2 | true | -当某些 JSON 子路径类型明确，并且会被频繁查询、过滤或聚合时，建议在建表语句中定义 type hint。 +也可以使用 JSON 函数直接指定返回类型： ```sql -CREATE TABLE application_logs ( - ts TIMESTAMP TIME INDEX, - message STRING, - attrs JSON2 ( - user.id BIGINT NOT NULL, - user.name STRING DEFAULT 'unknown', - http.status BIGINT, - success BOOLEAN NULL, - duration DOUBLE NULL DEFAULT 0.0 - ) -) WITH ( - 'append_mode' = 'true' -); +SELECT + json_get_string(attrs, 'http.path') AS path, + json_get_int(attrs, 'http.status') AS status, + json_get_float(attrs, 'latency_ms') AS latency_ms, + json_get_bool(attrs, 'error') AS error +FROM application_logs +WHERE json_get_int(attrs, 'http.status') >= 500 + OR json_get_float(attrs, 'latency_ms') > 300 +ORDER BY ts; +``` + +查询结果如下： + +| path | status | latency_ms | error | +| --- | --- | --- | --- | +| /v1/orders | 200 | 386.4 | false | +| /v1/orders | 500 | 71.2 | true | + +你也可以对 type hint 字段做聚合，例如统计每个 API 路径的请求量、错误数和平均延迟： + +```sql +SELECT + attrs.http.path AS path, + COUNT(*) AS requests, + SUM(CASE WHEN attrs.error THEN 1 ELSE 0 END) AS errors, + AVG(attrs.latency_ms) AS avg_latency_ms +FROM application_logs +GROUP BY attrs.http.path; ``` +## Type hint 语法 + Type hint 的基本语法如下： ```sql @@ -93,17 +165,16 @@ Type hint 的路径使用点号分隔，例如 `user.id` 对应 JSON 中的 Type hint 默认允许 `NULL`。如果设置 `NOT NULL`，写入的 JSON 中必须存在该路径。 -## 查询 JSON2 字段 - -可以使用 `json_get` 读取 JSON2 中的嵌套字段： +除了点号路径，也可以使用 `json_get` 读取嵌套字段： ```sql SELECT - json_get(attrs, 'user.id'), + json_get(attrs, 'trace_id'), json_get(attrs, 'user.name'), json_get(attrs, 'http.status'), - json_get(attrs, 'success') -FROM application_logs; + json_get(attrs, 'latency_ms') +FROM application_logs +ORDER BY ts; ``` `json_get` 的基本语法如下： @@ -112,24 +183,21 @@ FROM application_logs; json_get(json_column, 'path.to.field') ``` -如果你希望直接指定返回类型，也可以使用 JSON 函数： +## 当前限制 -```sql -SELECT - json_get_int(attrs, 'user.id'), - json_get_string(attrs, 'user.name'), - json_get_bool(attrs, 'success'), - json_get_float(attrs, 'duration') -FROM application_logs; -``` +JSON2 目前有以下限制： + +- JSON2 列只能用于 append-only 表，因此建表时必须设置 `'append_mode' = 'true'`。 +- 写入 JSON2 列的 root 值必须是非空 JSON object。例如，`{"key":"value"}` 可以写入，`[]`、`"text"`、`1`、`true`、`null` 和 `{}` 暂不支持。 +- 目前不支持直接查询 JSON2 root 列本身，请查询具体子路径，例如 `attrs.http.status` 或 `json_get(attrs, 'http.status')`。 +- 目前不支持通过下标访问 JSON array 中的元素。例如，可以查询 `attrs.items`，但暂不支持 `attrs.items[0]` 或 `json_get(attrs, 'items[0]')` 这类访问方式。 ## 未来规划 JSON2 目前处于 Beta 阶段。后续版本会继续完善以下能力： - 支持在非 append-only 表中使用 JSON2。 -- 支持写入 array、string、number、boolean 和 `null` 等非 object 类型的 - JSON root 值。 +- 支持写入 array、string、number、boolean、`null` 和 `{}` 等非 object 或空 object 的 JSON root 值。 - 支持通过 `json_get` 查询 JSON2 根列本身。 - 扩展 type hint 支持的类型，例如 `TIMESTAMP` 等时间类型。 - 为 type hint 支持 `INVERTED INDEX`、`SKIPPING INDEX` 等索引选项。 From 0695399a356bb7107b714ae430ebb66aa8dca5c9 Mon Sep 17 00:00:00 2001 From: fys Date: Thu, 9 Jul 2026 18:17:35 +0800 Subject: [PATCH 3/9] update --- docs/user-guide/logs/json2.md | 65 ++++++++++++++++++++++++----------- 1 file changed, 45 insertions(+), 20 deletions(-) diff --git a/docs/user-guide/logs/json2.md b/docs/user-guide/logs/json2.md index 49990cf45..00478f260 100644 --- a/docs/user-guide/logs/json2.md +++ b/docs/user-guide/logs/json2.md @@ -24,13 +24,11 @@ JSON2 目前处于 Beta 阶段。我们会保持向后兼容，并在后续版 JSON2 支持 type hint，用于为子路径声明确定的数据类型。声明后，这些子路径会按指定类型存储，从而获得接近普通列的查询性能，并在写入时进行类型校验。下面的 `attrs` 列为 `http.status`、`latency_ms`、`error` 等常用路径定义了 type hint。 ```sql -DROP TABLE IF EXISTS application_logs; - CREATE TABLE application_logs ( ts TIMESTAMP TIME INDEX, - service STRING, + app_name STRING, log_level STRING, - message STRING, + `message` STRING, attrs JSON2 ( trace_id STRING, user.id BIGINT, @@ -85,19 +83,19 @@ VALUES ```sql SELECT ts, - service, - attrs.trace_id, - attrs.user.name, - attrs.http.status, - attrs.latency_ms, - attrs.error + app_name, + attrs.trace_id AS trace_id, + attrs.user.name AS user_name, + attrs.http.status AS status, + attrs.latency_ms AS latency_ms, + attrs.error AS error FROM application_logs ORDER BY ts; ``` 查询结果如下： -| ts | service | trace_id | user.name | http.status | latency_ms | error | +| ts | app_name | trace_id | user_name | status | latency_ms | error | | --- | --- | --- | --- | --- | --- | --- | | 1970-01-01 00:00:00.001 | checkout | 8f3a1c | Alice | 200 | 42.8 | false | | 1970-01-01 00:00:00.002 | checkout | 8f3a1d | Bob | 200 | 386.4 | false | @@ -136,7 +134,15 @@ FROM application_logs GROUP BY attrs.http.path; ``` -## Type hint 语法 +查询结果如下： + +| path | requests | errors | avg_latency_ms | +| --- | --- | --- | --- | +| /v1/orders | 3 | 1 | 166.8 | + +## 语法 + +### Type hint Type hint 的基本语法如下： @@ -155,17 +161,17 @@ Type hint 的路径使用点号分隔，例如 `user.id` 对应 JSON 中的 当前 type hint 支持以下类型： -| Type hint 类型 | 说明 | -| --- | --- | -| `STRING` | 字符串类型。`TEXT`、`VARCHAR`、`CHAR` 等别名会归一为 `STRING`。 | -| `BIGINT` | 有符号整数类型。`INT`、`INTEGER`、`SMALLINT` 等整数类型会归一为 `BIGINT`。 | -| `BIGINT UNSIGNED` | 无符号整数类型。无符号整数类型会归一为 `BIGINT UNSIGNED`。 | -| `DOUBLE` | 浮点类型。`FLOAT`、`REAL` 等类型会归一为 `DOUBLE`。 | -| `BOOLEAN` | 布尔类型。 | +- `STRING` +- `BIGINT` +- `BIGINT UNSIGNED` +- `DOUBLE` +- `BOOLEAN` Type hint 默认允许 `NULL`。如果设置 `NOT NULL`，写入的 JSON 中必须存在该路径。 -除了点号路径，也可以使用 `json_get` 读取嵌套字段： +### `json_get` + +除了点号路径，也可以使用 `json_get` 读取 JSON2 中的嵌套字段： ```sql SELECT @@ -183,6 +189,25 @@ ORDER BY ts; json_get(json_column, 'path.to.field') ``` +如果希望直接指定返回类型，也可以使用以下 JSON 函数： + +- `json_get_string(json_column, 'path.to.field')` +- `json_get_int(json_column, 'path.to.field')` +- `json_get_float(json_column, 'path.to.field')` +- `json_get_bool(json_column, 'path.to.field')` + +例如： + +```sql +SELECT + json_get_string(attrs, 'http.path') AS path, + json_get_int(attrs, 'http.status') AS status, + json_get_float(attrs, 'latency_ms') AS latency_ms, + json_get_bool(attrs, 'error') AS error +FROM application_logs +ORDER BY ts; +``` + ## 当前限制 JSON2 目前有以下限制： From 7fa583fdb2fee620758bbf056f40eb0123aa1f0c Mon Sep 17 00:00:00 2001 From: fys Date: Thu, 9 Jul 2026 18:48:21 +0800 Subject: [PATCH 4/9] update --- docs/user-guide/logs/json2.md | 56 ++++++++++++++--------------------- 1 file changed, 22 insertions(+), 34 deletions(-) diff --git a/docs/user-guide/logs/json2.md b/docs/user-guide/logs/json2.md index 00478f260..bab1146cf 100644 --- a/docs/user-guide/logs/json2.md +++ b/docs/user-guide/logs/json2.md @@ -9,7 +9,7 @@ JSON2 是 GreptimeDB 为日志和半结构化数据设计的 JSON 类型。 它会将 JSON 中的字段以结构化、列式的方式存储，使常用字段能够像普通列一样被高效读取、过滤和聚合，同时保留 JSON 对动态结构的表达能力。 :::note -JSON2 目前处于 Beta 阶段。我们会保持向后兼容，并在后续版本中继续完善功能、改进当前限制。 +JSON2 目前处于 Beta 阶段，部分功能仍在持续完善中。 ::: ## 快速入门 @@ -105,13 +105,13 @@ ORDER BY ts; ```sql SELECT - json_get_string(attrs, 'http.path') AS path, - json_get_int(attrs, 'http.status') AS status, - json_get_float(attrs, 'latency_ms') AS latency_ms, - json_get_bool(attrs, 'error') AS error + json_get(attrs, 'http.path')::STRING AS path, + json_get(attrs, 'http.status')::INT8 AS status, + json_get(attrs, 'latency_ms')::DOUBLE AS latency_ms, + json_get(attrs, 'error')::BOOLEAN AS error FROM application_logs -WHERE json_get_int(attrs, 'http.status') >= 500 - OR json_get_float(attrs, 'latency_ms') > 300 +WHERE json_get(attrs, 'http.status')::INT8 >= 500 + OR json_get(attrs, 'latency_ms')::DOUBLE > 300 ORDER BY ts; ``` @@ -119,19 +119,19 @@ ORDER BY ts; | path | status | latency_ms | error | | --- | --- | --- | --- | -| /v1/orders | 200 | 386.4 | false | -| /v1/orders | 500 | 71.2 | true | +| /v1/orders | 200 | 386.4 | 0 | +| /v1/orders | 500 | 71.2 | 1 | 你也可以对 type hint 字段做聚合，例如统计每个 API 路径的请求量、错误数和平均延迟： ```sql SELECT - attrs.http.path AS path, + json_get(attrs, 'http.path')::STRING AS path, COUNT(*) AS requests, - SUM(CASE WHEN attrs.error THEN 1 ELSE 0 END) AS errors, - AVG(attrs.latency_ms) AS avg_latency_ms + SUM(CASE WHEN json_get(attrs, 'error')::BOOLEAN THEN 1 ELSE 0 END) AS errors, + ROUND(AVG(json_get(attrs, 'latency_ms')::DOUBLE), 1) AS avg_latency_ms FROM application_logs -GROUP BY attrs.http.path; +GROUP BY json_get(attrs, 'http.path')::STRING; ``` 查询结果如下： @@ -189,40 +189,28 @@ ORDER BY ts; json_get(json_column, 'path.to.field') ``` -如果希望直接指定返回类型，也可以使用以下 JSON 函数： - -- `json_get_string(json_column, 'path.to.field')` -- `json_get_int(json_column, 'path.to.field')` -- `json_get_float(json_column, 'path.to.field')` -- `json_get_bool(json_column, 'path.to.field')` +如果希望直接指定返回类型，可以使用类型转换： 例如： ```sql SELECT - json_get_string(attrs, 'http.path') AS path, - json_get_int(attrs, 'http.status') AS status, - json_get_float(attrs, 'latency_ms') AS latency_ms, - json_get_bool(attrs, 'error') AS error + json_get(attrs, 'http.path')::STRING AS path, + json_get(attrs, 'http.status')::INT8 AS status, + json_get(attrs, 'latency_ms')::DOUBLE AS latency_ms, + json_get(attrs, 'error')::BOOLEAN AS error FROM application_logs ORDER BY ts; ``` -## 当前限制 - -JSON2 目前有以下限制： - -- JSON2 列只能用于 append-only 表，因此建表时必须设置 `'append_mode' = 'true'`。 -- 写入 JSON2 列的 root 值必须是非空 JSON object。例如，`{"key":"value"}` 可以写入，`[]`、`"text"`、`1`、`true`、`null` 和 `{}` 暂不支持。 -- 目前不支持直接查询 JSON2 root 列本身，请查询具体子路径，例如 `attrs.http.status` 或 `json_get(attrs, 'http.status')`。 -- 目前不支持通过下标访问 JSON array 中的元素。例如，可以查询 `attrs.items`，但暂不支持 `attrs.items[0]` 或 `json_get(attrs, 'items[0]')` 这类访问方式。 - ## 未来规划 -JSON2 目前处于 Beta 阶段。后续版本会继续完善以下能力： +JSON2 目前处于 Beta 阶段，仍有以下限制。后续版本会继续完善相关能力： - 支持在非 append-only 表中使用 JSON2。 - 支持写入 array、string、number、boolean、`null` 和 `{}` 等非 object 或空 object 的 JSON root 值。 -- 支持通过 `json_get` 查询 JSON2 根列本身。 +- 支持查询 JSON2 root 列本身。目前请查询具体子路径，例如 `attrs.http.status` 或 `json_get(attrs, 'http.status')`。 +- 支持通过下标访问 JSON array 中的元素。目前可以查询 `attrs.items`，但暂不支持 `attrs.items[0]` 或 `json_get(attrs, 'items[0]')`。 +- 支持 `json_get_string`、`json_get_int`、`json_get_float` 和 `json_get_bool` 等函数处理 JSON2 类型。目前可以使用 `json_get(...)::TYPE` 指定返回类型。 - 扩展 type hint 支持的类型，例如 `TIMESTAMP` 等时间类型。 - 为 type hint 支持 `INVERTED INDEX`、`SKIPPING INDEX` 等索引选项。 From 6f695e941ffecffe9e654e07afa9f7a07a0e8a0c Mon Sep 17 00:00:00 2001 From: fys Date: Thu, 9 Jul 2026 18:58:59 +0800 Subject: [PATCH 5/9] minor refactor --- docs/user-guide/logs/json2.md | 30 +++--------------------------- 1 file changed, 3 insertions(+), 27 deletions(-) diff --git a/docs/user-guide/logs/json2.md b/docs/user-guide/logs/json2.md index bab1146cf..b2985239e 100644 --- a/docs/user-guide/logs/json2.md +++ b/docs/user-guide/logs/json2.md @@ -171,36 +171,12 @@ Type hint 默认允许 `NULL`。如果设置 `NOT NULL`，写入的 JSON 中必 ### `json_get` -除了点号路径，也可以使用 `json_get` 读取 JSON2 中的嵌套字段： - -```sql -SELECT - json_get(attrs, 'trace_id'), - json_get(attrs, 'user.name'), - json_get(attrs, 'http.status'), - json_get(attrs, 'latency_ms') -FROM application_logs -ORDER BY ts; -``` +`json_get` 用于按路径读取 JSON2 中的嵌套字段。默认返回字符串类型；如果希望直接指定返回类型，可以在函数后使用类型转换。 `json_get` 的基本语法如下： ```sql -json_get(json_column, 'path.to.field') -``` - -如果希望直接指定返回类型，可以使用类型转换： - -例如： - -```sql -SELECT - json_get(attrs, 'http.path')::STRING AS path, - json_get(attrs, 'http.status')::INT8 AS status, - json_get(attrs, 'latency_ms')::DOUBLE AS latency_ms, - json_get(attrs, 'error')::BOOLEAN AS error -FROM application_logs -ORDER BY ts; +json_get(json_column, 'path.to.field')::TYPE ``` ## 未来规划 @@ -211,6 +187,6 @@ JSON2 目前处于 Beta 阶段，仍有以下限制。后续版本会继续完 - 支持写入 array、string、number、boolean、`null` 和 `{}` 等非 object 或空 object 的 JSON root 值。 - 支持查询 JSON2 root 列本身。目前请查询具体子路径，例如 `attrs.http.status` 或 `json_get(attrs, 'http.status')`。 - 支持通过下标访问 JSON array 中的元素。目前可以查询 `attrs.items`，但暂不支持 `attrs.items[0]` 或 `json_get(attrs, 'items[0]')`。 -- 支持 `json_get_string`、`json_get_int`、`json_get_float` 和 `json_get_bool` 等函数处理 JSON2 类型。目前可以使用 `json_get(...)::TYPE` 指定返回类型。 +- 支持 `json_get_string`、`json_get_int`、`json_get_float` 和 `json_get_bool` 等函数处理 JSON2 类型。 - 扩展 type hint 支持的类型，例如 `TIMESTAMP` 等时间类型。 - 为 type hint 支持 `INVERTED INDEX`、`SKIPPING INDEX` 等索引选项。 From eb656f1549f13990c0c40f22bc67e8cbe8ead95c Mon Sep 17 00:00:00 2001 From: fengys1996 Date: Fri, 10 Jul 2026 16:08:17 +0800 Subject: [PATCH 6/9] added an english version --- docs/user-guide/logs/json2.md | 83 ++++---- .../current/user-guide/logs/json2.md | 192 ++++++++++++++++++ 2 files changed, 233 insertions(+), 42 deletions(-) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/user-guide/logs/json2.md diff --git a/docs/user-guide/logs/json2.md b/docs/user-guide/logs/json2.md index b2985239e..9199fae8b 100644 --- a/docs/user-guide/logs/json2.md +++ b/docs/user-guide/logs/json2.md @@ -1,27 +1,27 @@ --- keywords: [JSON2, JSON, logs, structured logs, type hints, json_get] -description: 介绍 GreptimeDB 中 JSON2 类型的使用方式，包括建表、type hint、JSON 字段读取以及当前限制。 +description: Learn how to use the JSON2 type in GreptimeDB, including table creation, type hints, JSON field access, and current limitations. --- -# JSON2 类型 +# JSON2 Type -JSON2 是 GreptimeDB 为日志和半结构化数据设计的 JSON 类型。 -它会将 JSON 中的字段以结构化、列式的方式存储，使常用字段能够像普通列一样被高效读取、过滤和聚合，同时保留 JSON 对动态结构的表达能力。 +JSON2 is a JSON type in GreptimeDB designed for logs and semi-structured data. +It stores fields inside JSON in a structured, columnar form so that frequently used fields can be read, filtered, and aggregated efficiently like regular columns, while still preserving the flexibility of JSON for dynamic schemas. :::note -JSON2 目前处于 Beta 阶段，部分功能仍在持续完善中。 +JSON2 is currently in Beta, and some capabilities are still being improved. ::: -## 快速入门 +## Quick Start -下面的示例创建一张 API 访问日志表，写入几条请求日志，并查询 JSON2 中的字段。固定字段放在普通列中，结构可能变化但经常查询的字段放在 JSON2 列 `attrs` 中。 +The following example creates an API access log table, inserts a few request logs, and queries fields from JSON2. Fixed fields are stored in regular columns, while fields in `attrs` use JSON2 because their structure may vary but they are still queried frequently. -### 创建表 +### Create a table -在建表时，可以使用 `JSON2` 类型声明 JSON2 列。 -当前 JSON2 只能在 append-only 表中使用，因此建表时需要设置 `'append_mode' = 'true'`。 +When creating a table, you can declare a JSON2 column with the `JSON2` type. +Currently, JSON2 can only be used in append-only tables, so you must set `'append_mode' = 'true'` when creating the table. -JSON2 支持 type hint，用于为子路径声明确定的数据类型。声明后，这些子路径会按指定类型存储，从而获得接近普通列的查询性能，并在写入时进行类型校验。下面的 `attrs` 列为 `http.status`、`latency_ms`、`error` 等常用路径定义了 type hint。 +JSON2 supports type hints, which let you declare concrete data types for subpaths. Once declared, these subpaths are stored using the specified types, which provides query performance close to regular columns and enforces type validation during writes. In the following example, the `attrs` column defines type hints for common paths such as `http.status`, `latency_ms`, and `error`. ```sql CREATE TABLE application_logs ( @@ -44,11 +44,11 @@ CREATE TABLE application_logs ( ); ``` -例如，`user.name STRING DEFAULT 'anonymous'` 表示当写入的 JSON 中缺少 `user.name` 时，查询结果使用默认值 `anonymous`。`error BOOLEAN DEFAULT false` 表示缺少 `error` 字段的日志会被视为非错误日志。 +For example, `user.name STRING DEFAULT 'anonymous'` means that if `user.name` is missing from the written JSON, query results use the default value `anonymous`. `error BOOLEAN DEFAULT false` means that logs without an `error` field are treated as non-error logs. -### 写入 JSON 数据 +### Insert JSON data -写入 JSON2 列时，可以写入 JSON object。下面的数据包含一次成功请求、一次慢请求和一次失败请求： +When writing to a JSON2 column, you can insert a JSON object. The following data includes one successful request, one slow request, and one failed request: ```sql INSERT INTO application_logs @@ -76,9 +76,9 @@ VALUES ); ``` -### 查询 JSON 字段 +### Query JSON fields -可以直接通过点号路径读取 JSON2 中的字段： +You can read fields from JSON2 directly with dot paths: ```sql SELECT @@ -93,7 +93,7 @@ FROM application_logs ORDER BY ts; ``` -查询结果如下： +The query result is: | ts | app_name | trace_id | user_name | status | latency_ms | error | | --- | --- | --- | --- | --- | --- | --- | @@ -101,7 +101,7 @@ ORDER BY ts; | 1970-01-01 00:00:00.002 | checkout | 8f3a1d | Bob | 200 | 386.4 | false | | 1970-01-01 00:00:00.003 | checkout | 8f3a1e | anonymous | 500 | 71.2 | true | -也可以使用 JSON 函数直接指定返回类型： +You can also use JSON functions and cast the return type explicitly: ```sql SELECT @@ -115,14 +115,14 @@ WHERE json_get(attrs, 'http.status')::INT8 >= 500 ORDER BY ts; ``` -查询结果如下： +The query result is: | path | status | latency_ms | error | | --- | --- | --- | --- | | /v1/orders | 200 | 386.4 | 0 | | /v1/orders | 500 | 71.2 | 1 | -你也可以对 type hint 字段做聚合，例如统计每个 API 路径的请求量、错误数和平均延迟： +You can also aggregate type-hinted fields, for example to count requests, errors, and average latency for each API path: ```sql SELECT @@ -134,17 +134,17 @@ FROM application_logs GROUP BY json_get(attrs, 'http.path')::STRING; ``` -查询结果如下： +The query result is: | path | requests | errors | avg_latency_ms | | --- | --- | --- | --- | | /v1/orders | 3 | 1 | 166.8 | -## 语法 +## Syntax -### Type hint +### Type hints -Type hint 的基本语法如下： +The basic syntax for a type hint is: ```sql json_column JSON2 ( @@ -152,14 +152,13 @@ json_column JSON2 ( ) ``` -Type hint 的路径使用点号分隔，例如 `user.id` 对应 JSON 中的 -`{"user":{"id":...}}`。 +Type hint paths use dot notation. For example, `user.id` refers to the following JSON path: +`{"user":{"id":...}}`. -如果某个 JSON key 本身包含点号，需要用双引号包住该路径段。 -例如 `"service.name"` 表示读取 root object 中名为 `service.name` -的 key，而不是读取 `service.name` 这条嵌套路径。 +If a JSON key itself contains a dot, wrap that path segment in double quotes. +For example, `"service.name"` means a key named `service.name` in the root object, not a nested path `service.name`. -当前 type hint 支持以下类型： +Type hints currently support the following data types: - `STRING` - `BIGINT` @@ -167,26 +166,26 @@ Type hint 的路径使用点号分隔，例如 `user.id` 对应 JSON 中的 - `DOUBLE` - `BOOLEAN` -Type hint 默认允许 `NULL`。如果设置 `NOT NULL`，写入的 JSON 中必须存在该路径。 +Type hints allow `NULL` by default. If you specify `NOT NULL`, that path must exist in the written JSON. ### `json_get` -`json_get` 用于按路径读取 JSON2 中的嵌套字段。默认返回字符串类型；如果希望直接指定返回类型，可以在函数后使用类型转换。 +`json_get` reads a nested field from JSON2 by path. It returns a string by default. If you want to specify the return type directly, add a cast after the function. -`json_get` 的基本语法如下： +The basic syntax of `json_get` is: ```sql json_get(json_column, 'path.to.field')::TYPE ``` -## 未来规划 +## Roadmap -JSON2 目前处于 Beta 阶段，仍有以下限制。后续版本会继续完善相关能力： +JSON2 is currently in Beta and still has the following limitations. Future releases will continue to improve these capabilities: -- 支持在非 append-only 表中使用 JSON2。 -- 支持写入 array、string、number、boolean、`null` 和 `{}` 等非 object 或空 object 的 JSON root 值。 -- 支持查询 JSON2 root 列本身。目前请查询具体子路径，例如 `attrs.http.status` 或 `json_get(attrs, 'http.status')`。 -- 支持通过下标访问 JSON array 中的元素。目前可以查询 `attrs.items`，但暂不支持 `attrs.items[0]` 或 `json_get(attrs, 'items[0]')`。 -- 支持 `json_get_string`、`json_get_int`、`json_get_float` 和 `json_get_bool` 等函数处理 JSON2 类型。 -- 扩展 type hint 支持的类型，例如 `TIMESTAMP` 等时间类型。 -- 为 type hint 支持 `INVERTED INDEX`、`SKIPPING INDEX` 等索引选项。 +- Support JSON2 in non-append-only tables. +- Support writing non-object or empty-object JSON root values such as arrays, strings, numbers, booleans, `null`, and `{}`. +- Support querying the JSON2 root column itself. For now, query specific subpaths such as `attrs.http.status` or `json_get(attrs, 'http.status')`. +- Support subscript access to elements inside JSON arrays. For now, you can query `attrs.items`, but not `attrs.items[0]` or `json_get(attrs, 'items[0]')`. +- Support functions such as `json_get_string`, `json_get_int`, `json_get_float`, and `json_get_bool` for JSON2. +- Extend supported type hint data types, such as time-related types like `TIMESTAMP`. +- Support index options such as `INVERTED INDEX` and `SKIPPING INDEX` for type hints. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/logs/json2.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/logs/json2.md new file mode 100644 index 000000000..b2985239e --- /dev/null +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/logs/json2.md @@ -0,0 +1,192 @@ +--- +keywords: [JSON2, JSON, logs, structured logs, type hints, json_get] +description: 介绍 GreptimeDB 中 JSON2 类型的使用方式，包括建表、type hint、JSON 字段读取以及当前限制。 +--- + +# JSON2 类型 + +JSON2 是 GreptimeDB 为日志和半结构化数据设计的 JSON 类型。 +它会将 JSON 中的字段以结构化、列式的方式存储，使常用字段能够像普通列一样被高效读取、过滤和聚合，同时保留 JSON 对动态结构的表达能力。 + +:::note +JSON2 目前处于 Beta 阶段，部分功能仍在持续完善中。 +::: + +## 快速入门 + +下面的示例创建一张 API 访问日志表，写入几条请求日志，并查询 JSON2 中的字段。固定字段放在普通列中，结构可能变化但经常查询的字段放在 JSON2 列 `attrs` 中。 + +### 创建表 + +在建表时，可以使用 `JSON2` 类型声明 JSON2 列。 +当前 JSON2 只能在 append-only 表中使用，因此建表时需要设置 `'append_mode' = 'true'`。 + +JSON2 支持 type hint，用于为子路径声明确定的数据类型。声明后，这些子路径会按指定类型存储，从而获得接近普通列的查询性能，并在写入时进行类型校验。下面的 `attrs` 列为 `http.status`、`latency_ms`、`error` 等常用路径定义了 type hint。 + +```sql +CREATE TABLE application_logs ( + ts TIMESTAMP TIME INDEX, + app_name STRING, + log_level STRING, + `message` STRING, + attrs JSON2 ( + trace_id STRING, + user.id BIGINT, + user.name STRING DEFAULT 'anonymous', + http.method STRING, + http.path STRING, + http.status BIGINT, + latency_ms DOUBLE, + error BOOLEAN DEFAULT false + ) +) WITH ( + 'append_mode' = 'true' +); +``` + +例如，`user.name STRING DEFAULT 'anonymous'` 表示当写入的 JSON 中缺少 `user.name` 时，查询结果使用默认值 `anonymous`。`error BOOLEAN DEFAULT false` 表示缺少 `error` 字段的日志会被视为非错误日志。 + +### 写入 JSON 数据 + +写入 JSON2 列时，可以写入 JSON object。下面的数据包含一次成功请求、一次慢请求和一次失败请求： + +```sql +INSERT INTO application_logs +VALUES + ( + 1, + 'checkout', + 'INFO', + 'request completed', + '{"trace_id":"8f3a1c","user":{"id":1001,"name":"Alice"},"http":{"method":"POST","path":"/v1/orders","status":200},"latency_ms":42.8}' + ), + ( + 2, + 'checkout', + 'WARN', + 'slow request', + '{"trace_id":"8f3a1d","user":{"id":1002,"name":"Bob"},"http":{"method":"POST","path":"/v1/orders","status":200},"latency_ms":386.4}' + ), + ( + 3, + 'checkout', + 'ERROR', + 'request failed', + '{"trace_id":"8f3a1e","user":{"id":1003},"http":{"method":"POST","path":"/v1/orders","status":500},"latency_ms":71.2,"error":true}' + ); +``` + +### 查询 JSON 字段 + +可以直接通过点号路径读取 JSON2 中的字段： + +```sql +SELECT + ts, + app_name, + attrs.trace_id AS trace_id, + attrs.user.name AS user_name, + attrs.http.status AS status, + attrs.latency_ms AS latency_ms, + attrs.error AS error +FROM application_logs +ORDER BY ts; +``` + +查询结果如下： + +| ts | app_name | trace_id | user_name | status | latency_ms | error | +| --- | --- | --- | --- | --- | --- | --- | +| 1970-01-01 00:00:00.001 | checkout | 8f3a1c | Alice | 200 | 42.8 | false | +| 1970-01-01 00:00:00.002 | checkout | 8f3a1d | Bob | 200 | 386.4 | false | +| 1970-01-01 00:00:00.003 | checkout | 8f3a1e | anonymous | 500 | 71.2 | true | + +也可以使用 JSON 函数直接指定返回类型： + +```sql +SELECT + json_get(attrs, 'http.path')::STRING AS path, + json_get(attrs, 'http.status')::INT8 AS status, + json_get(attrs, 'latency_ms')::DOUBLE AS latency_ms, + json_get(attrs, 'error')::BOOLEAN AS error +FROM application_logs +WHERE json_get(attrs, 'http.status')::INT8 >= 500 + OR json_get(attrs, 'latency_ms')::DOUBLE > 300 +ORDER BY ts; +``` + +查询结果如下： + +| path | status | latency_ms | error | +| --- | --- | --- | --- | +| /v1/orders | 200 | 386.4 | 0 | +| /v1/orders | 500 | 71.2 | 1 | + +你也可以对 type hint 字段做聚合，例如统计每个 API 路径的请求量、错误数和平均延迟： + +```sql +SELECT + json_get(attrs, 'http.path')::STRING AS path, + COUNT(*) AS requests, + SUM(CASE WHEN json_get(attrs, 'error')::BOOLEAN THEN 1 ELSE 0 END) AS errors, + ROUND(AVG(json_get(attrs, 'latency_ms')::DOUBLE), 1) AS avg_latency_ms +FROM application_logs +GROUP BY json_get(attrs, 'http.path')::STRING; +``` + +查询结果如下： + +| path | requests | errors | avg_latency_ms | +| --- | --- | --- | --- | +| /v1/orders | 3 | 1 | 166.8 | + +## 语法 + +### Type hint + +Type hint 的基本语法如下： + +```sql +json_column JSON2 ( + path.to.field DATA_TYPE [NULL | NOT NULL] [DEFAULT literal] +) +``` + +Type hint 的路径使用点号分隔，例如 `user.id` 对应 JSON 中的 +`{"user":{"id":...}}`。 + +如果某个 JSON key 本身包含点号，需要用双引号包住该路径段。 +例如 `"service.name"` 表示读取 root object 中名为 `service.name` +的 key，而不是读取 `service.name` 这条嵌套路径。 + +当前 type hint 支持以下类型： + +- `STRING` +- `BIGINT` +- `BIGINT UNSIGNED` +- `DOUBLE` +- `BOOLEAN` + +Type hint 默认允许 `NULL`。如果设置 `NOT NULL`，写入的 JSON 中必须存在该路径。 + +### `json_get` + +`json_get` 用于按路径读取 JSON2 中的嵌套字段。默认返回字符串类型；如果希望直接指定返回类型，可以在函数后使用类型转换。 + +`json_get` 的基本语法如下： + +```sql +json_get(json_column, 'path.to.field')::TYPE +``` + +## 未来规划 + +JSON2 目前处于 Beta 阶段，仍有以下限制。后续版本会继续完善相关能力： + +- 支持在非 append-only 表中使用 JSON2。 +- 支持写入 array、string、number、boolean、`null` 和 `{}` 等非 object 或空 object 的 JSON root 值。 +- 支持查询 JSON2 root 列本身。目前请查询具体子路径，例如 `attrs.http.status` 或 `json_get(attrs, 'http.status')`。 +- 支持通过下标访问 JSON array 中的元素。目前可以查询 `attrs.items`，但暂不支持 `attrs.items[0]` 或 `json_get(attrs, 'items[0]')`。 +- 支持 `json_get_string`、`json_get_int`、`json_get_float` 和 `json_get_bool` 等函数处理 JSON2 类型。 +- 扩展 type hint 支持的类型，例如 `TIMESTAMP` 等时间类型。 +- 为 type hint 支持 `INVERTED INDEX`、`SKIPPING INDEX` 等索引选项。 From e6c532eb3725b108e30764149b0d76141a92ca22 Mon Sep 17 00:00:00 2001 From: fys Date: Mon, 13 Jul 2026 14:55:33 +0800 Subject: [PATCH 7/9] fix: cr for english version --- docs/user-guide/logs/json2.md | 135 +++++++++++++++++++++++++--------- 1 file changed, 102 insertions(+), 33 deletions(-) diff --git a/docs/user-guide/logs/json2.md b/docs/user-guide/logs/json2.md index 9199fae8b..25efde4eb 100644 --- a/docs/user-guide/logs/json2.md +++ b/docs/user-guide/logs/json2.md @@ -6,7 +6,9 @@ description: Learn how to use the JSON2 type in GreptimeDB, including table crea # JSON2 Type JSON2 is a JSON type in GreptimeDB designed for logs and semi-structured data. -It stores fields inside JSON in a structured, columnar form so that frequently used fields can be read, filtered, and aggregated efficiently like regular columns, while still preserving the flexibility of JSON for dynamic schemas. +It stores fields inside JSON in a structured, columnar form so that frequently +used fields can be read, filtered, and aggregated efficiently like regular +columns, while still preserving the flexibility of JSON for dynamic schemas. :::note JSON2 is currently in Beta, and some capabilities are still being improved. @@ -14,14 +16,16 @@ JSON2 is currently in Beta, and some capabilities are still being improved. ## Quick Start -The following example creates an API access log table, inserts a few request logs, and queries fields from JSON2. Fixed fields are stored in regular columns, while fields in `attrs` use JSON2 because their structure may vary but they are still queried frequently. +The following example creates an API access log table, inserts a few request +logs, and queries fields from JSON2. Fixed fields are stored in regular columns, +while fields in `attrs` use JSON2 because their structure may vary but they are +still queried frequently. ### Create a table When creating a table, you can declare a JSON2 column with the `JSON2` type. -Currently, JSON2 can only be used in append-only tables, so you must set `'append_mode' = 'true'` when creating the table. - -JSON2 supports type hints, which let you declare concrete data types for subpaths. Once declared, these subpaths are stored using the specified types, which provides query performance close to regular columns and enforces type validation during writes. In the following example, the `attrs` column defines type hints for common paths such as `http.status`, `latency_ms`, and `error`. +Currently, JSON2 can only be used in append-only tables, so you must set +`'append_mode' = 'true'` when creating the table. ```sql CREATE TABLE application_logs ( @@ -29,26 +33,16 @@ CREATE TABLE application_logs ( app_name STRING, log_level STRING, `message` STRING, - attrs JSON2 ( - trace_id STRING, - user.id BIGINT, - user.name STRING DEFAULT 'anonymous', - http.method STRING, - http.path STRING, - http.status BIGINT, - latency_ms DOUBLE, - error BOOLEAN DEFAULT false - ) + attrs JSON2, ) WITH ( 'append_mode' = 'true' ); ``` -For example, `user.name STRING DEFAULT 'anonymous'` means that if `user.name` is missing from the written JSON, query results use the default value `anonymous`. `error BOOLEAN DEFAULT false` means that logs without an `error` field are treated as non-error logs. - ### Insert JSON data -When writing to a JSON2 column, you can insert a JSON object. The following data includes one successful request, one slow request, and one failed request: +When writing to a JSON2 column, you can insert a JSON object. The following data +includes one successful request, one slow request, and one failed request: ```sql INSERT INTO application_logs @@ -122,7 +116,8 @@ The query result is: | /v1/orders | 200 | 386.4 | 0 | | /v1/orders | 500 | 71.2 | 1 | -You can also aggregate type-hinted fields, for example to count requests, errors, and average latency for each API path: +You can also aggregate fields, for example to count requests, errors, and average +latency for each API path: ```sql SELECT @@ -142,7 +137,12 @@ The query result is: ## Syntax -### Type hints +### JSON Field Type hints + +JSON2 supports type hints, which let you declare concrete data types for +subpaths. Once declared, these subpaths are stored using the specified types, +which provides query performance close to regular columns and enforces type +validation during writes. The basic syntax for a type hint is: @@ -152,11 +152,12 @@ json_column JSON2 ( ) ``` -Type hint paths use dot notation. For example, `user.id` refers to the following JSON path: -`{"user":{"id":...}}`. +Type hint paths use dot notation. For example, `user.id` refers to the following +JSON path: `{"user":{"id":...}}`. If a JSON key itself contains a dot, wrap that path segment in double quotes. -For example, `"service.name"` means a key named `service.name` in the root object, not a nested path `service.name`. +For example, `"service.name"` means a key named `service.name` in the root object, +not a nested path `service.name`. Type hints currently support the following data types: @@ -166,11 +167,39 @@ Type hints currently support the following data types: - `DOUBLE` - `BOOLEAN` -Type hints allow `NULL` by default. If you specify `NOT NULL`, that path must exist in the written JSON. +Type hints allow `NULL` by default. If you specify `NOT NULL`, that path must +exist in the written JSON. + +As shown in the quick start example above, type hints can be declared directly +in the `CREATE TABLE` statement. For example, you can define the `attrs` JSON2 +column with type hints for commonly queried subpaths: + +```sql +CREATE TABLE application_logs ( + ts TIMESTAMP TIME INDEX, + app_name STRING, + log_level STRING, + `message` STRING, + attrs JSON2 ( + trace_id STRING, + user.id BIGINT, + user.name STRING DEFAULT 'anonymous', + http.method STRING, + http.path STRING, + http.status BIGINT, + latency_ms DOUBLE, + error BOOLEAN DEFAULT false + ) +) WITH ( + 'append_mode' = 'true' +); +``` -### `json_get` +### `json_get` UDF -`json_get` reads a nested field from JSON2 by path. It returns a string by default. If you want to specify the return type directly, add a cast after the function. +`json_get` reads a nested field from JSON2 by path. It returns a string by +default. If you want to specify the return type directly, add a cast after the +function. The basic syntax of `json_get` is: @@ -178,14 +207,54 @@ The basic syntax of `json_get` is: json_get(json_column, 'path.to.field')::TYPE ``` +`json_get` can be used in `SELECT`, `WHERE`, `GROUP BY`, and other SQL clauses +that accept expressions. For example: + +```sql +SELECT + json_get(attrs, 'trace_id')::STRING AS trace_id, + json_get(attrs, 'http.status')::BIGINT AS status, + json_get(attrs, 'latency_ms')::DOUBLE AS latency_ms +FROM application_logs +WHERE json_get(attrs, 'http.status')::BIGINT >= 500; +``` + +### Dot syntax + +You can read JSON2 subpaths directly with dot syntax: + +```sql +json_column.path.to.field +``` + +Dot syntax can be used in `SELECT`, `WHERE`, `GROUP BY`, and other SQL clauses +that accept expressions. For example: + +```sql +SELECT + attrs.trace_id, + attrs.http.status, + attrs.latency_ms +FROM application_logs +WHERE attrs.http.status >= 500; +``` + ## Roadmap -JSON2 is currently in Beta and still has the following limitations. Future releases will continue to improve these capabilities: +JSON2 is currently in Beta and still has the following limitations. Future +releases will continue to improve these capabilities: - Support JSON2 in non-append-only tables. -- Support writing non-object or empty-object JSON root values such as arrays, strings, numbers, booleans, `null`, and `{}`. -- Support querying the JSON2 root column itself. For now, query specific subpaths such as `attrs.http.status` or `json_get(attrs, 'http.status')`. -- Support subscript access to elements inside JSON arrays. For now, you can query `attrs.items`, but not `attrs.items[0]` or `json_get(attrs, 'items[0]')`. -- Support functions such as `json_get_string`, `json_get_int`, `json_get_float`, and `json_get_bool` for JSON2. -- Extend supported type hint data types, such as time-related types like `TIMESTAMP`. -- Support index options such as `INVERTED INDEX` and `SKIPPING INDEX` for type hints. +- Support writing non-object or empty-object JSON root values such as arrays, + strings, numbers, booleans, `null`, and `{}`. +- Support querying the JSON2 root column itself. For now, query specific + subpaths such as `attrs.http.status` or `json_get(attrs, 'http.status')`. +- Support subscript access to elements inside JSON arrays. For now, you can + query `attrs.items`, but not `attrs.items[0]` or `json_get(attrs, 'items[0]')`. +- Support functions such as `json_get_string`, `json_get_int`, + `json_get_float`, and `json_get_bool` for JSON2. +- Extend supported type hint data types, such as time-related types like + `TIMESTAMP`. +- Support index options such as `INVERTED INDEX` and `SKIPPING INDEX` for type + hints. +- Support writing JSON2 through OTLP and other ingestion paths. From 7eb77ea5c38b94ee4d2d9a3876e8dfd0f25e4e09 Mon Sep 17 00:00:00 2001 From: fys Date: Mon, 13 Jul 2026 15:00:52 +0800 Subject: [PATCH 8/9] fix: query result --- docs/user-guide/logs/json2.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/logs/json2.md b/docs/user-guide/logs/json2.md index 25efde4eb..489fb99c9 100644 --- a/docs/user-guide/logs/json2.md +++ b/docs/user-guide/logs/json2.md @@ -91,9 +91,9 @@ The query result is: | ts | app_name | trace_id | user_name | status | latency_ms | error | | --- | --- | --- | --- | --- | --- | --- | -| 1970-01-01 00:00:00.001 | checkout | 8f3a1c | Alice | 200 | 42.8 | false | -| 1970-01-01 00:00:00.002 | checkout | 8f3a1d | Bob | 200 | 386.4 | false | -| 1970-01-01 00:00:00.003 | checkout | 8f3a1e | anonymous | 500 | 71.2 | true | +| 1970-01-01 00:00:00.001 | checkout | 8f3a1c | Alice | 200 | 42.8 | NULL | +| 1970-01-01 00:00:00.002 | checkout | 8f3a1d | Bob | 200 | 386.4 | NULL | +| 1970-01-01 00:00:00.003 | checkout | 8f3a1e | NULL | 500 | 71.2 | true | You can also use JSON functions and cast the return type explicitly: @@ -113,7 +113,7 @@ The query result is: | path | status | latency_ms | error | | --- | --- | --- | --- | -| /v1/orders | 200 | 386.4 | 0 | +| /v1/orders | 200 | 386.4 | NULL | | /v1/orders | 500 | 71.2 | 1 | You can also aggregate fields, for example to count requests, errors, and average From d8e4a54b0573ba6e280e452489194e055f8ebd6c Mon Sep 17 00:00:00 2001 From: fys Date: Mon, 13 Jul 2026 15:05:58 +0800 Subject: [PATCH 9/9] fix: cr --- .../current/user-guide/logs/json2.md | 85 ++++++++++++++----- 1 file changed, 64 insertions(+), 21 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/logs/json2.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/logs/json2.md index b2985239e..51f0dd8eb 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/logs/json2.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/logs/json2.md @@ -21,31 +21,18 @@ JSON2 目前处于 Beta 阶段，部分功能仍在持续完善中。 在建表时，可以使用 `JSON2` 类型声明 JSON2 列。 当前 JSON2 只能在 append-only 表中使用，因此建表时需要设置 `'append_mode' = 'true'`。 -JSON2 支持 type hint，用于为子路径声明确定的数据类型。声明后，这些子路径会按指定类型存储，从而获得接近普通列的查询性能，并在写入时进行类型校验。下面的 `attrs` 列为 `http.status`、`latency_ms`、`error` 等常用路径定义了 type hint。 - ```sql CREATE TABLE application_logs ( ts TIMESTAMP TIME INDEX, app_name STRING, log_level STRING, `message` STRING, - attrs JSON2 ( - trace_id STRING, - user.id BIGINT, - user.name STRING DEFAULT 'anonymous', - http.method STRING, - http.path STRING, - http.status BIGINT, - latency_ms DOUBLE, - error BOOLEAN DEFAULT false - ) + attrs JSON2, ) WITH ( 'append_mode' = 'true' ); ``` -例如，`user.name STRING DEFAULT 'anonymous'` 表示当写入的 JSON 中缺少 `user.name` 时，查询结果使用默认值 `anonymous`。`error BOOLEAN DEFAULT false` 表示缺少 `error` 字段的日志会被视为非错误日志。 - ### 写入 JSON 数据 写入 JSON2 列时，可以写入 JSON object。下面的数据包含一次成功请求、一次慢请求和一次失败请求： @@ -97,9 +84,9 @@ ORDER BY ts; | ts | app_name | trace_id | user_name | status | latency_ms | error | | --- | --- | --- | --- | --- | --- | --- | -| 1970-01-01 00:00:00.001 | checkout | 8f3a1c | Alice | 200 | 42.8 | false | -| 1970-01-01 00:00:00.002 | checkout | 8f3a1d | Bob | 200 | 386.4 | false | -| 1970-01-01 00:00:00.003 | checkout | 8f3a1e | anonymous | 500 | 71.2 | true | +| 1970-01-01 00:00:00.001 | checkout | 8f3a1c | Alice | 200 | 42.8 | NULL | +| 1970-01-01 00:00:00.002 | checkout | 8f3a1d | Bob | 200 | 386.4 | NULL | +| 1970-01-01 00:00:00.003 | checkout | 8f3a1e | NULL | 500 | 71.2 | true | 也可以使用 JSON 函数直接指定返回类型： @@ -119,10 +106,10 @@ ORDER BY ts; | path | status | latency_ms | error | | --- | --- | --- | --- | -| /v1/orders | 200 | 386.4 | 0 | +| /v1/orders | 200 | 386.4 | NULL | | /v1/orders | 500 | 71.2 | 1 | -你也可以对 type hint 字段做聚合，例如统计每个 API 路径的请求量、错误数和平均延迟： +你也可以对字段做聚合，例如统计每个 API 路径的请求量、错误数和平均延迟： ```sql SELECT @@ -142,7 +129,9 @@ GROUP BY json_get(attrs, 'http.path')::STRING; ## 语法 -### Type hint +### JSON 字段 Type hint + +JSON2 支持 type hint，用于为子路径声明确定的数据类型。声明后，这些子路径会按指定类型存储，从而获得接近普通列的查询性能，并在写入时进行类型校验。 Type hint 的基本语法如下： @@ -169,7 +158,30 @@ Type hint 的路径使用点号分隔，例如 `user.id` 对应 JSON 中的 Type hint 默认允许 `NULL`。如果设置 `NOT NULL`，写入的 JSON 中必须存在该路径。 -### `json_get` +如上面的快速入门示例所示，type hint 可以直接在 `CREATE TABLE` 语句中声明。例如，可以为 `attrs` 这个 JSON2 列中经常查询的子路径定义 type hint： + +```sql +CREATE TABLE application_logs ( + ts TIMESTAMP TIME INDEX, + app_name STRING, + log_level STRING, + `message` STRING, + attrs JSON2 ( + trace_id STRING, + user.id BIGINT, + user.name STRING DEFAULT 'anonymous', + http.method STRING, + http.path STRING, + http.status BIGINT, + latency_ms DOUBLE, + error BOOLEAN DEFAULT false + ) +) WITH ( + 'append_mode' = 'true' +); +``` + +### `json_get` UDF `json_get` 用于按路径读取 JSON2 中的嵌套字段。默认返回字符串类型；如果希望直接指定返回类型，可以在函数后使用类型转换。 @@ -179,6 +191,36 @@ Type hint 默认允许 `NULL`。如果设置 `NOT NULL`，写入的 JSON 中必 json_get(json_column, 'path.to.field')::TYPE ``` +`json_get` 可以用于 `SELECT`、`WHERE`、`GROUP BY` 等接受表达式的 SQL 子句。例如： + +```sql +SELECT + json_get(attrs, 'trace_id')::STRING AS trace_id, + json_get(attrs, 'http.status')::BIGINT AS status, + json_get(attrs, 'latency_ms')::DOUBLE AS latency_ms +FROM application_logs +WHERE json_get(attrs, 'http.status')::BIGINT >= 500; +``` + +### 点号语法 + +可以直接通过点号语法读取 JSON2 中的子路径： + +```sql +json_column.path.to.field +``` + +点号语法可以用于 `SELECT`、`WHERE`、`GROUP BY` 等接受表达式的 SQL 子句。例如： + +```sql +SELECT + attrs.trace_id, + attrs.http.status, + attrs.latency_ms +FROM application_logs +WHERE attrs.http.status >= 500; +``` + ## 未来规划 JSON2 目前处于 Beta 阶段，仍有以下限制。后续版本会继续完善相关能力： @@ -190,3 +232,4 @@ JSON2 目前处于 Beta 阶段，仍有以下限制。后续版本会继续完 - 支持 `json_get_string`、`json_get_int`、`json_get_float` 和 `json_get_bool` 等函数处理 JSON2 类型。 - 扩展 type hint 支持的类型，例如 `TIMESTAMP` 等时间类型。 - 为 type hint 支持 `INVERTED INDEX`、`SKIPPING INDEX` 等索引选项。 +- 支持通过 OTLP 和其他 ingestion path 写入 JSON2。