# GreptimeDB v1.2.0 发布：为日志和 Agent 事件设计的 JSON2 类型

Source: https://greptime.cn/blogs/2026-09-08-greptimedb-v1-2-0-release

经过两个 beta 版本之后，GreptimeDB v1.2.0 已于 2026 年 9 月 8 日发布。从 v1.1.0 到 v1.2.0 共合并 331 个提交，25 位贡献者参与，其中 7 位是第一次为 GreptimeDB 提交代码。主要更新：

- JSON2 类型的 SQL 查询支持嵌套路径、列表下标和 Pipeline 转换
- Import/Export V2 支持并行导入导出、进度显示和断点续传
- Prometheus Remote Write v2 支持普通指标样本接入
- 新增 Flow 运行状态查询，内置 Dashboard 更新到 v0.13.13

## 最值得关注的变化

### JSON2 类型：结构化存储与 SQL 查询

GreptimeDB 原有的 JSON 类型把整个对象编码为 JSONB 二进制值保存，结构完整，适合低频读取整个对象或 schema 难以预知的数据。但日志、Trace、事件流，以及 AI 应用（尤其是 Agent）产生的大量事件，其中的 JSON 大多结构相近，一次查询通常只访问其中几条路径。JSONB 把字段封在二进制里，查询引擎只能读出整个值再取其中一小部分，存储带宽和计算都花在了用不到的数据上。JSON2 针对这类数据设计：对用户仍然是一个完整的 JSON 对象，对存储和查询引擎则是可以按路径裁剪的结构化数据。

v1.2.0 补齐了 JSON2 类型的 SQL 路径访问和函数支持、列表下标访问，以及空值和 null 的处理。Pipeline 能识别目标表中的 JSON2 列，并转换输入数据。

例如，把 HTTP 请求信息写入日志表后，可以直接读取状态码和请求路径：

```sql
CREATE TABLE application_logs (
    ts TIMESTAMP TIME INDEX,
    attrs JSON2
) WITH (
    'append_mode' = 'true'
);
INSERT INTO application_logs VALUES
    (1, '{"http":{"status":200,"path":"/api/orders"}}');
SELECT
    attrs.http.status::BIGINT AS status,
    json_get(attrs, 'http.path')::STRING AS path
FROM application_logs;
```

嵌套字段可以像普通列一样用点路径访问；需要把路径作为参数传入时，用 `json_get`。

新建带 JSON2 列的表需要开启 `append_mode`。v1.2.0 同时切换了 JSON2 的物理存储布局，在 v1.2.0-beta.1 或 v1.2.0-beta.2 上建过 JSON2 表的用户，升级前请先看文末的兼容性说明。

JSON2 的存储格式、写入路径和查询裁剪的实现，我们会另写一篇文章详细介绍。

### Import/Export V2：并行迁移、进度显示和断点续传

导出时用 `--chunk-parallelism` 并行处理数据分块，导入时用 `--task-parallelism` 控制任务并发。任务中断后，保留导出快照和导入状态文件，重新执行相同命令即可跳过已完成的分块或任务，继续处理剩余数据。

`--progress` 控制进度输出：交互终端默认显示进度条，其他环境输出日志。

完整用法见 [Import/Export V2 文档](https://docs.greptime.cn/1.2/user-guide/deployments-administration/disaster-recovery/export-import-v2)。

### Splunk HEC：新增一条日志接入路径

兼容 Splunk HTTP Event Collector（HEC）的采集客户端现在可以直接把数据发送到 GreptimeDB：

- 结构化事件发送到 `/v1/splunk/services/collector/event`
- 原始日志发送到 `/v1/splunk/services/collector/raw`

`/events/logs` 也支持用 `x-greptime-pipeline-name` 请求头指定处理日志的 Pipeline。

### Flow：用 SQL 查看运行状态

创建 Flow 后，可以通过 `SHOW FLOW STATUS` 和 `information_schema.flow_statistics` 查询运行统计：

```sql
SHOW FLOW STATUS LIKE 'my%';
SELECT * FROM information_schema.flow_statistics;
```

当前分布式 Flow 的 `start_time` 和 `uptime_seconds` 仍返回 `NULL`，依赖这两个字段做监控时需要注意。

### Dashboard：查询结果更容易查看和分享

内置 Dashboard 从 v1.1.0 附带的 v0.12.2 更新到 v0.13.13，主要变化：

- 支持保存 Dashboard 快照
- 结果表格可以调整列宽、展开内容，也可以全屏查看
- 支持选择 Trace 表，并显示版本和构建信息
- 新增命令面板，切换连接地址后可以重新连接

完整更新见发布说明中的 [Dashboard 章节](https://github.com/GreptimeTeam/greptimedb/releases/tag/v1.2.0#dashboard)。

## 性能优化

- 保留字典编码的 series key，减少字符串展开开销。PR 作者本地 200 多条查询的测试中，端到端查询性能提升约 24%，实际收益取决于工作负载（[测试记录](https://github.com/GreptimeTeam/greptimedb/pull/8541)）。同时修正了字典编码列的正则过滤语义。
- RangeSelect 更早裁剪用不到的输入列。
- Prometheus remote read 的结果转换减少了标签分配和复制。
- Compaction picker 改为异步执行，不再阻塞 Region worker。
- 优化 OTLP trace 写入路径。
- 精简 Parquet 元数据缓存，减少内存占用。

## 其他改进

### 数据接入

**Prometheus Remote Write v2 普通样本接入。** Prometheus 端需要显式配置 `protobuf_message: io.prometheus.write.v2.Request`。本版本暂不保存 metadata、exemplar 和普通样本的 created timestamp；v2 请求中的 Pipeline 参数会被忽略，样本直接写入。

**实验性原生直方图写入。** 默认关闭，PromQL 查询链路尚未完整支持。测试时需要在 GreptimeDB 的 HTTP 配置中开启：

```toml
[http]
experimental_enable_prometheus_native_histogram = true
```

使用早期 beta 写入过原生直方图的用户，升级前需要安排迁移或重新写入，见文末兼容性说明。

### 运维

- 支持表级 `auto_flush_interval`，建表时指定，或用 `ALTER TABLE SET` 修改。
- 支持设置每个 Region 的写缓冲上限。
- 手动 compaction 支持指定时间范围。

### 协议与认证

PostgreSQL 协议支持 SCRAM 认证。

## 重要修复

- PromQL 查询正确性：保留普通 NaN 样本，修正 `or` 匹配对缺失标签和空操作数的处理，保留与查询对齐的 range 尾部。
- Flow：修复运行统计聚合和名称引用问题。
- 权限检查：补齐数据库 ACL、查询和写入协议的表级权限，以及受限 HTTP 接口的权限检查。

## 兼容性说明

升级前请注意以下 7 项不兼容变更或限制。从 v1.2 beta 升级的用户，重点检查 soft-drop、原生直方图和 JSON2 类型三项。

1. **本地 SQL 文件访问受目录限制。** 单机部署中，本地 `COPY` 和外部表只能访问允许的 copy root；分布式部署中，这些 SQL 的本地路径被禁用。已有流程需要迁移文件、配置专用目录，或改用对象存储。步骤见[本地 SQL 文件访问迁移指南](https://docs.greptime.cn/1.2/user-guide/deployments-administration/migrate-local-sql-file-access)。

2. **`holt_winters` 已移除。** 相关 PromQL 查询和告警规则请改为 `double_exponential_smoothing`。

3. **`sparse_primary_key_encoding` 配置已移除。** Metric engine 的数据 Region 默认采用 sparse 主键编码。旧配置仍能加载，但这一选项会被忽略，更新配置时可以删除。

4. **Pipeline 整数转换会检查范围。** 整数转换到更窄的类型时，系统会校验目标类型的取值范围，越界值按配置的 `on_failure` 策略处理。依赖旧版回绕行为的 Pipeline 需要调整输入或失败处理配置。

5. **Soft-drop 和恢复转为企业版功能。** beta1 中这些操作在开源版可用；从 beta2 开始，开源版 metasrv 会拒绝 `gc.experimental_soft_drop.enable = true`。从 beta1 升级前，先恢复还需要的 soft-drop 表。已经在 beta1 上 soft-drop 的表，开源版既不能恢复也不能清除，其过期 tombstone 也不会被清理，继续这套生命周期需要企业版。

6. **早期 beta 的原生直方图数据格式发生变化。** 部分持久化字段由无符号整数改为有符号整数，并调整了字段名。用旧 schema 写入的原生直方图可能无法读取，当前没有迁移、降级或混合版本兼容层，需要在升级前安排数据迁移或重新写入。这项限制只针对实验性的原生直方图，不涉及普通 v1.1 指标表。

7. **v1.2 beta 上创建的 JSON2 表存在已知限制。** v1.2.0 切换了 JSON2 的物理存储布局。在 beta 上创建的非 append 表使用的是更早的 `greptime.json` 类型，升级后可能在 flush 或 compaction 时失败，v1.2.0 尚未修复。

   受影响的表应推迟升级，或者按以下方式迁移：

   - 在兼容的旧版本环境中逻辑导出数据，再导入新建的 v1.2.0 表；不要复制旧表目录或元数据。
   - 迁移前保留备份，用有代表性的数据验证。
   - 切换前检查数据完整性，并在新表上实际执行一次 flush 和 compaction。

   仅设置 `append_mode` 不能保证解决问题。另外，旧版本无法读取新布局写出的 SST，升级前也要评估回退方案。

适用范围和完整说明见 [v1.2.0 的 Breaking changes](https://github.com/GreptimeTeam/greptimedb/releases/tag/v1.2.0#breaking-changes)。

## 获取 v1.2.0

安装包和完整变更列表见 [GitHub Release](https://github.com/GreptimeTeam/greptimedb/releases/tag/v1.2.0)，升级步骤见[升级文档](https://docs.greptime.cn/user-guide/deployments-administration/upgrade/)。使用中遇到问题，欢迎到 [GitHub Issues](https://github.com/GreptimeTeam/greptimedb/issues) 反馈。

## 开发数据概览

331 个提交（不含自动依赖升级）按类型分布如下：

- 92 项功能增强：JSON2 类型、Import/Export V2、Flow 状态查询、Splunk HEC 接入等
- 138 项错误修复：PromQL 查询正确性、JSON2 读写、权限检查、存储稳定性等
- 19 项代码重构：JSON2 写入路径、compaction 调度模块拆分、端点权限动作命名化等
- 8 项性能优化：字典编码 series key、Parquet 元数据缓存、OTLP trace 写入、异步 compaction picker 等
- 24 项测试增强：导入导出、版本兼容性、查询回归等
- 3 项文档更新：项目及各模块的开发指引与架构约束，新增实体关系与图查询 RFC
- 47 项工程与其他改进：query regression CI、jsonbench、远程 WAL fuzz 测试稳定性等

<p align="center">
  <img src="/zh/blogs/2026-09-08-greptimedb-v1-2-0-release/contributors.png" alt="GreptimeDB 从 v1.1.0 到 v1.2.0 的贡献者" width="820"/>
</p>

感谢参与本次发布的 25 位贡献者，也欢迎首次贡献者：[@agrawalx](https://github.com/agrawalx)、[@raphaelroshan](https://github.com/raphaelroshan)、[@srivtx](https://github.com/srivtx)、[@yimeng](https://github.com/yimeng)、[@grezzko](https://github.com/grezzko)、[@fzlzjerry](https://github.com/fzlzjerry) 和 [@wy471x](https://github.com/wy471x)。
