JSON2 随 GreptimeDB v1.2.0 版本发布。何时应该使用 JSON2 而非 JSON？下文将提供 JSON 与 JSON2 的视觉对比指南。JSON2 目前处于 Beta 阶段，仅支持追加写入。快速入门：https://docs.greptime.com/user-guide/logs/json2/…

JSON2 数据类型 | GreptimeDB 文档

来源：https://docs.greptime.com/user-guide/logs/json2/ JSON2 是 GreptimeDB 中专为日志与半结构化数据设计的 JSON 类型。它将 JSON 中的字段以结构化、列式的形式存储，使常用字段能够像常规列一样被高效读取、过滤和聚合，同时仍保留 JSON 对动态 Schema 的灵活性。

注意

JSON2 目前处于 Beta 阶段，部分功能仍在持续完善中。

快速入门 (https://docs.greptime.com/user-guide/logs/json2/#quick-start)

以下示例将创建一个 API 访问日志表，插入几条请求日志，并查询 JSON2 中的字段。固定字段存储在常规列中，而 attrs 字段使用 JSON2 存储，因为其结构可能变化，但查询频率较高。

创建表 (https://docs.greptime.com/user-guide/logs/json2/#create-a-table)

创建表时，可以使用 JSON2 类型声明一个 JSON2 列。目前，JSON2 只能在仅追加表中使用，因此创建表时必须设置 'append_mode' = 'true'。

CREATE TABLE application_logs (
    ts TIMESTAMP TIME INDEX,
    app_name STRING,
    log_level STRING,
    `message` STRING,
    attrs JSON2
) WITH (
    'append_mode' = 'true'
);

插入 JSON 数据 (https://docs.greptime.com/user-guide/logs/json2/#insert-json-data)

写入 JSON2 列时，可以插入一个 JSON 对象。以下数据包含一个成功的请求、一个慢请求和一个失败的请求：

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}'
    );

自定义管道也可以通过在转换配置中使用 type: json2 来写入 JSON2 列。支持的类型提示选项请参阅管道配置参考 (https://docs.greptime.com/reference/pipeline/pipeline-config/#the-type-field)。

查询 JSON 字段 (https://docs.greptime.com/user-guide/logs/json2/#query-json-fields)

您可以使用点路径直接从 JSON2 中读取字段：

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 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

您也可以选择完整的 JSON2 值：

SELECT ts, attrs
FROM application_logs
ORDER BY ts;

您还可以使用 JSON 函数并显式转换返回类型：

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 NULL /v1/orders 500 71.2 true

您也可以对字段进行聚合，例如统计每个 API 路径的请求数、错误数和平均延迟：

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

语法 (https://docs.greptime.com/user-guide/logs/json2/#syntax)

JSON 字段类型提示 (https://docs.greptime.com/user-guide/logs/json2/#json-field-type-hints)

JSON2 支持类型提示，用于为选定的子路径声明具体的数据类型。推荐对类型已知且稳定、查询频繁的子路径使用类型提示。这些子路径将使用指定的类型存储，提供接近常规列的查询性能。JSON2 在写入时还会验证它们的值。类型提示是可选的。对于没有类型提示的子路径，JSON2 会根据写入列的值推断其类型。

声明类型提示的语法如下：

json_column JSON2 (
    path.to.field DATA_TYPE [NULL | NOT NULL] [DEFAULT literal]
)

类型提示路径使用点表示法。例如，user.id 指的是以下 JSON 路径：{"user":{"id":...}}。

如果 JSON 键本身包含点，请将该路径段用双引号括起来。例如，"service.name" 表示根对象中一个名为 service.name 的键，而不是嵌套路径 service.name。

类型提示目前支持以下数据类型：

• STRING
• BIGINT
• BIGINT UNSIGNED
• DOUBLE
• BOOLEAN

类型提示默认允许 NULL。如果指定 NOT NULL，则写入的 JSON 中必须存在该路径。

您可以在 CREATE TABLE 语句中直接声明类型提示。以下示例为 attrs 列中常用的查询子路径定义了类型提示：

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 用户定义函数 (https://docs.greptime.com/user-guide/logs/json2/#json_get-udf)

json_get 通过路径从 JSON2 读取嵌套字段。它默认返回一个字符串。如果您想直接指定返回类型，请在函数后添加类型转换。

json_get 的语法为：

json_get(json_column, 'path.to.field')::TYPE

json_get 可用于 SELECT、WHERE、GROUP BY 以及其他接受表达式的 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;

类型提取函数 json_get_string、json_get_int、json_get_float 和 json_get_bool 也接受 JSON2 值。详情请参阅 JSON 函数 (https://docs.greptime.com/reference/sql/functions/json/#extraction)。

点语法 (https://docs.greptime.com/user-guide/logs/json2/#dot-syntax)

您可以使用点语法直接读取 JSON2 子路径：

json_column.path.to.field

点语法可用于 SELECT、WHERE、GROUP BY 以及其他接受表达式的 SQL 子句中。例如：

SELECT
    attrs.trace_id,
    attrs.http.status,
    attrs.latency_ms
FROM application_logs
WHERE attrs.http.status >= 500;

控制自动路径展开 (https://docs.greptime.com/user-guide/logs/json2/#control-automatic-path-expansion)

默认情况下，JSON2 会将兼容的未提示叶路径展开为结构化列。使用 max_auto_expanded_paths 可限制展开的路径数量：

CREATE TABLE application_logs (
    ts TIMESTAMP TIME INDEX,
    attrs JSON2 (
        max_auto_expanded_paths = 20,
        trace_id STRING
    )
) WITH (
    'append_mode' = 'true'
);

将该选项设置为 0 可禁用自动展开。带类型提示的路径不计入此限制。超出限制的字段将保留在特殊的 remainder 字段中，仍可查询，因此该选项控制的是存储布局和性能，而非逻辑 JSON Schema。

当前限制 (https://docs.greptime.com/user-guide/logs/json2/#current-limitations)

JSON2 目前处于 Beta 阶段，存在以下限制：

• JSON2 列只能在仅追加表中使用。
• 每个非 NULL 的 JSON 根必须是一个非空对象。不支持根数组、字符串、数字、布尔值、JSON 字面量 null 以及空对象。
• 无法通过下标语法访问数组元素。
• 类型提示仅支持上述列出的类型，且无法遍历数组。
• 结构化展开和类型提示路径最多支持 50 个嵌套路径段。更深的未提示值仍可在特殊的 remainder 字段中查询，因此该选项控制的是存储布局和性能，而非逻辑 JSON Schema。