# GreptimeDB v1.2.0-beta.1：JSON2 首次发布，支持 Prometheus Remote Write v2

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

GreptimeDB v1.2.0-beta.1 已于 2026 年 7 月 31 日发布。这是 v1.2.0 的首个 beta 版本，包含 4 项 breaking change，建议先在测试环境评估。这个版本的主要变化：

- 支持 Prometheus Remote Write v2 协议和原生直方图（native histogram）
- JSON2 类型首次发布，会在 v1.2.0 正式版 GA
- 查询性能：字典编码 series key 带来约 24% 端到端提升，RangeSelect 投影裁剪减少扫描列
- 一批权限与文件访问加固，其中 SQL 本地文件沙箱化是 breaking change
- 新增 Splunk HEC 接入；集群 DDL 与运维事件落表

## 开发数据概览

- 本次 release note 收录了 205 项变更
- 从 v1.1.0 到 v1.2.0-beta.1，22 位贡献者提交了 259 个 commit
- 其中 6 位是第一次为 GreptimeDB 提交代码：@agrawalx、@raphaelroshan、@srivtx、@yimeng、@divyansh-1009、@RitwijParmar

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

主要改进分布如下：

- 73 项功能增强：Prometheus Remote Write v2、Splunk HEC 接入、MySQL object store 后端、Postgres SCRAM 认证等
- 55 项错误修复：PromQL 正确性（NaN 样本、`or` 匹配、range 尾部）、权限检查补漏、JSON2 写入与查询修复等
- 14 项代码重构：JSON2 写入路径优化、compaction 调度模块拆分、端点权限动作命名化等
- 6 项性能优化：字典编码 series key、parquet metadata cache 精简、OTLP trace 写入热路径、异步 compaction picker 等
- 18 项测试增强：Export/Import V2 端到端测试、sqlness 兼容性 runner 和一批兼容性用例
- 3 项文档更新
- 32 项工程与依赖改进：query regression CI、jsonbench、fuzz 测试稳定性等
- 4 项 breaking change（见文末兼容性说明）

## 主要变化

### Prometheus Remote Write v2 与原生直方图

支持 Remote Write v2 协议，原生直方图（native histogram）可以持久化并带写入校验，PromQL 也补上了原生直方图函数。注意 Prometheus 端的 `protobuf_message` 默认是 v1 的 `prometheus.WriteRequest`，只配置 URL 仍会以 v1 发送，需要显式指定 v2 消息格式：

```yaml
remote_write:
  - url: http://greptimedb:4000/v1/prometheus/write
    protobuf_message: io.prometheus.write.v2.Request
```

配置好之后，v2 的 sample 写入就能用了。原生直方图写入在 GreptimeDB 端仍是实验能力，默认关闭，需要在 frontend 配置中开启：

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

### JSON2 类型首次发布

JSON2 是这个版本首次发布的数据类型，它把 JSON 数据结构化存储，而不是整体序列化成 JSON 字符串或 JSONB。这样存下来，查询 JSON 这类嵌套数据的速度和普通列一样，语法也更简单：不用再写 `json_get_int` 这类 UDF，直接用 `.` 就能取到某个字段。

```sql
CREATE TABLE json2_table (
    ts TIMESTAMP TIME INDEX,
    my_json JSON2
) WITH ('append_mode' = 'true');

SELECT my_json.field_a.field_b::INT64 FROM json2_table;
```

这个版本把 JSON2 的存储和写入语义定了下来：

- variant payload 改用 JSONB 编码而不是 serde JSON 字节，深层嵌套值同样如此
- 新增类型提示
- 嵌套路径支持回退读取，同一字段在不同行是标量或对象时都能取到
- 加宽和投影的 cast 语义统一，整列 `SELECT` 的问题也修掉了

写入时有两条约束要注意：JSON2 列要求建表时 `append_mode='true'`，`CREATE TABLE` 和 `ALTER TABLE` 都会校验；顶层不是 object 的 JSON 值（数组、字符串、数字、布尔、null）会被拒绝写入。

v1.2.0-beta.1 是 beta 版本，JSON2 会在 v1.2.0 正式版 GA，现在适合在测试环境试用并反馈问题。关于 JSON2，我们会单独写一篇文章详细介绍。

### 性能优化

内存中的主键列改用 dictionary array，缓解 series key 展开的开销，在 200+ 查询的测试集上获得约 24% 的端到端性能提升。字典编码列上的正则过滤同时修正了语义并恢复了 fast path。

```sql
SELECT * FROM metrics WHERE job = 'node' AND path ~ '/api/.*';
-- 字典编码列上的正则过滤语义正确，且走 fast path
```

Range 查询现在会在 RangeSelect 计划之前裁掉用不到的输入列，减少扫描列数和 I/O。

parquet metadata cache 也做了精简：丢掉用不到的列元数据并引入压缩层，此前需要 1 GB 上限的元数据缓存，现在 64 MB 就够，且没有 cache churn。上面这几个数字都来自对应 PR 的测试场景，不代表所有工作负载。

还有几项没有量化数据的优化：

- OTLP trace 写入热路径：每个 chunk 只解析一次固定列索引、按索引直接写值、用 `hex::encode` 替代逐字节格式化；默认 `otlp.trace_ingest_chunk_size` 从 128 提高到 512
- Prometheus remote read 结果转换减少了标签的分配与拷贝，可直接借用字典编码标签的底层字符串
- Compaction picker 改为异步执行，不再阻塞 region worker 循环，同时修复了一批调度生命周期问题

### Splunk HEC 接入

新增 Splunk HTTP Event Collector 兼容端点。已有的 Splunk 采集链路（Vector 的 `splunk_hec` sink、OTel Collector 的 `splunk_hec` exporter、Fluent Bit）改个 URL 和 token 就能把日志写进 GreptimeDB：

```text
POST /v1/splunk/services/collector/event   # JSON 事件
POST /v1/splunk/services/collector/raw     # 纯文本，一行一条事件
GET  /v1/splunk/services/collector/health  # 健康探针
```

字段映射：`time` 映射到时间戳，`host`/`source`/`sourcetype` 和 `fields` 里的键映射为 tag 列，`event` 及其余键作为数据，`index` 决定表名。默认走 `greptime_identity` pipeline（会展开嵌套的 `event` 对象），可以用 `pipeline_name` query 参数或 `x-greptime-pipeline-name` 请求头覆盖。raw 端点则把每行原样存进 `message` 列，元数据通过 query 参数带入。请求体支持 gzip。

### 集群 DDL 与运维事件落表

事件记录器这次记的东西更全：除了原有的 region migration，现在库、表、Flow、View 的 DDL 以及 repartition、WAL prune、批量 GC 都会作为事件写入系统表，排查“这张表什么时候建的、什么时候改过删过”不用再翻日志。记录范围和保留期可配：

```toml
[event_recorder]
ttl = "90d"                                   # events 表的 TTL，默认 90 天
event_types = ["create_table", "drop_table"]  # 省略表示记录全部，[] 表示关闭
```

### 权限与文件访问加固

这个版本在权限和文件访问上收紧了几处，其中一项是 breaking change：

- SQL 访问本地文件沙箱化，详见文末兼容性说明
- 查询和写入协议全面执行表级权限，数据库 ACL 的检查盲区被补上，受限 HTTP 端点也纳入权限检查
- 非法的密码赋值按失败处理（fail closed），不再静默通过
- Postgres 支持 SCRAM-SHA-256 认证，静态用户文件新增 `pg_scram_sha256` 密码格式
- 创建数据库的用户自动获得该库的访问权限

部署上还有一个配套选项。HTTP 主端口（默认 4000）上还挂着 `/metrics`、`/status`、`/debug/prof/*` 这些运维端点，现在可以额外开一个只放行 `/v1` 和 `/dashboard` 的端口，其他路径一律 404：

```toml
[http]
enable_api_server = true
api_server_addr = "127.0.0.1:4006"
```

这样 4006 对外，4000 只在内网开。默认关闭，其余 `[http]` 配置两个端口共用。

### Export/Import V2：并行与断点续传

基于快照的 Export/Import V2 增加了并发 chunk 导出（`--chunk-parallelism`）、并行导入任务（`--task-parallelism`）和进度显示（`--progress`），并支持断点续传：重跑同一条命令会跳过已完成的 chunk 和任务，不必从头再来。

```bash
greptime cli data export-v2 create \
  --addr 127.0.0.1:4000 \
  --to file:///tmp/greptime-snapshots/demo \
  --chunk-parallelism 4
# 重跑同一条命令即可从已有进度继续
```

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

## 其他改进

- **流式 EXPLAIN ANALYZE**：`POST /v1/sql/analyze/stream` 可以边跑边看各 stage 的指标，不必等整个分布式查询结束；`http.experimental_enable_explain_analyze_stream` 默认开启
- **手动 compaction 支持时间范围**，`start_time` 和 `end_time` 必须成对出现，区间是半开的 `[start_time, end_time)`，不带时区的时间戳按会话时区解释：

  ```sql
  ADMIN COMPACT_TABLE('t', 'regular',
      'parallelism=2,start_time=2026-01-01T00:00:00Z,end_time=2026-02-01T00:00:00Z');
  ```

- **写入与刷写的配置项**：表级 `auto_flush_interval`（建表指定或 `ALTER TABLE SET` 修改）、per-region 写缓冲上限、parquet row group 大小可配、flush job 可取消、file meta cache 扩容
- **Dashboard 更新到 v0.13.10**：仪表盘可保存为自包含快照（只读打开，不查询实时数据源）、结果表格支持列宽调整、PromQL 编辑器修复、支持全部 Perses 插件
- **数据接入**：`/events/logs` 支持 `x-greptime-pipeline-name` 请求头、CSV 导入增加严格表头校验、OTLP trace 按请求协调 schema
- **存储后端**：新增 MySQL object store 后端。目前不支持 repartition，因为 OpenDAL 的 MySQL service 没有原生 `copy`，repartition 触发的 region 文件拷贝会返回 `Unsupported`
- **Flow 稳定性**：eval interval 调度更稳、metric batch flush 之后同步更新 flow 窗口、DirtyWindowRequest 支持时间区间

## 重要修复

查询正确性：

- PromQL 修了三类会造成结果错漏的问题：普通 NaN 样本被误丢弃、`or` 匹配没有正确处理缺失标签和空操作数、查询对齐的 range 尾部被截掉
- join 和子查询中的字面量现在能正确转换类型
- range 时间转换做了加固，异常时间输入不再产生错误结果
- metric engine：校验逻辑投影索引、路由裁剪改用物理分区类型、缺失路由列时不再 panic

稳定性：

- MySQL 协议遇到无法表示的时间戳按错误返回，不再返回错误数据
- 保留了旧版 WAL options 的兼容性
- datanode 客户端 gRPC 消息大小可配置
- 宽行场景会自适应调整 batch 大小
- close 时的 flush 响应不再丢失

## 兼容性说明

### SQL 本地文件访问沙箱化（#8708）

`COPY FROM/TO`、`COPY DATABASE` 和 file engine 外部表访问本地文件时，路径现在被限制在沙箱目录内，默认是 `<storage.data_home>/copy`：相对路径在沙箱下解析，绝对路径只有落在沙箱内才被接受。新的 `storage.copy_root` 配置可以把沙箱指向专门的本地目录；会暴露 GreptimeDB 内部数据、WAL、manifest 或配置目录的取值会被拒绝。分布式部署中，SQL 访问 datanode 本地文件被禁用；对象存储（S3/OSS/GCS/AzBlob）路径不受影响。

升级前：检查引用了沙箱外本地路径的 `COPY` 工作流和外部表，把文件移入沙箱、配置 `storage.copy_root`，或改用对象存储。

### holt_winters 移除，拒绝 fill 修饰符（#8457）

promql-parser 升级到 v0.10.0，废弃的 `holt_winters` 兼容处理被移除；`fill`、`fill_left`、`fill_right` 修饰符在实现所需的 outer-join 语义之前会被直接拒绝，避免生成静默错误的查询计划。

升级前：检查 PromQL 查询和告警规则中是否还在使用 `holt_winters` 或这几个 fill 修饰符。

### sparse_primary_key_encoding 配置移除（#8470）

Metric engine 现在始终使用 sparse 编码，`sparse_primary_key_encoding` 配置退役。已有配置文件里保留这个选项不会报错，可以在方便时清理。

### Pipeline 整数窄化检查（#8589）

Pipeline transform 把整数转换到更窄的声明类型时，现在会先做范围校验：越界值不再静默回绕（此前 `-1` 转 `uint8` 会得到 `255`、`256` 转 `int8` 会得到 `0`），而是走配置的 `on_failure` 策略（ignore、default 或严格报错）；窄数值字符串遵循同样的范围规则。

升级前：如果 pipeline 依赖了回绕行为，需要调整输入数据或 `on_failure` 配置。

## 结语

这个版本适合这几类场景先测一下：用 Prometheus 生态写入、关注原生直方图；大量写入 JSON 日志；series 基数高、对查询性能敏感；需要跨实例迁移和定期备份。

作为 beta 版本，请先在测试环境验证，升级前逐项确认上面 4 项 breaking change。完整变更列表见 [GitHub Release](https://github.com/GreptimeTeam/greptimedb/releases/tag/v1.2.0-beta.1)。

感谢这个周期里的 22 位贡献者。6 位第一次提交代码的开发者：

- [@agrawalx](https://github.com/agrawalx) 贡献了 Splunk HEC 接入
- [@raphaelroshan](https://github.com/raphaelroshan) 贡献了表级 `auto_flush_interval`，以及连接串脱敏、字面量取负 panic 等修复
- [@srivtx](https://github.com/srivtx) 贡献了 `ALTER TABLE SET auto_flush_interval`
- [@yimeng](https://github.com/yimeng) 让 Postgres 的 `intervalstyle` 支持不加引号的写法
- [@divyansh-1009](https://github.com/divyansh-1009) 让时间戳显示精度遵循列 schema
- [@RitwijParmar](https://github.com/RitwijParmar) 把 Prometheus label discovery 改成流式遍历 catalog 里的表，不再按表名逐个查询

v1.2.0 正式版发布前这些能力还会继续打磨，欢迎在测试中反馈问题。
