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

主要改进分布如下：

• 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 消息格式：

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

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

[http]
experimental_enable_prometheus_native_histogram = true

JSON2 类型首次发布

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

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。

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：

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 都会作为事件写入系统表，排查“这张表什么时候建的、什么时候改过删过”不用再翻日志。记录范围和保留期可配：

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

[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 和任务，不必从头再来。

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

完整用法见 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)，不带时区的时间戳按会话时区解释：

  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。

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

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

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