GreptimeDB v1.3.0 已于 2026 年 10 月 28 日发布。

本次发布的主要更新：

• 原生直方图默认开放接入，支持 PromQL 分位数与区间占比查询。
• 新增可选的 Trace V2 模型（实验性），使用 JSON2 保存属性；实验性语义实体图支持从指标与链路中查询服务、主机和容器之间的关系。
• 分布式写入默认自动重试，TWCS 支持分别调整活跃和非活跃时间窗口的合并策略。
• Dashboard 更新到 v0.14.2，新增统一浏览指标、日志与链路的 Signals Explore。

开发数据概览

• 本次发布收录 466 项 PR 变更
• 28 位贡献者参与了本次发布
• 其中 14 位是首次贡献

主要改进分布如下：

• 9 项不兼容变更：原生直方图配置与 prom_validation_mode 移到 [prom_store] 下、VRL 默认限制访问主机资源、SST 解码计入扫描内存限额等
• 142 项功能增强：原生直方图写入与查询、Trace V2（实验性）、分布式写入自动重试等
• 169 项错误修复：SQL 与 PromQL 查询正确性、全文索引匹配、存储与恢复等
• 23 项代码重构：查询回归工具迁移到 Rust、PromQL 规划器模块拆分、JSON2 Parquet 投影与 schema 对齐等
• 48 项性能优化：PromQL 滑动窗口求值、字典编码主键排序、存储扫描与索引读取等
• 12 项测试增强：跳过 WAL 写入的端到端测试、Flow 异步镜像写入测试、PromQL label_replace 回归等
• 11 项文档更新：README 与跨信号 SQL 示例、Rust 代码风格指南、Metric 导入导出优化 RFC 等
• 51 项工程与依赖改进：自动回移 PR、基准测试的版本对比与诊断、Rust 工具链和构建依赖更新等
• 1 项回退

最值得关注的变化

原生直方图默认开放接入与查询

v1.2.0 的原生直方图写入仍处于实验阶段，PromQL 查询支持也不完整。v1.3.0 默认接受 Prometheus Remote Write v2 原生直方图和 OTLP/HTTP 累积型指数直方图。写入后可以用 PromQL 聚合，并用 histogram_quantile、histogram_fraction 查询分位数和区间占比。

原生直方图的实验开关已失效，设为 false 也不会关闭这项能力。Prometheus Remote Write v1 的原生直方图、原生直方图 Remote Read，以及 OTel Arrow 指数直方图仍不支持。OTLP 指数直方图只接受累积型数据，不支持 delta 类型。

Trace V2 使用 JSON2 保存属性

Trace V2 将 span、scope 和 resource 属性分别保存在三个 JSON2 列中，新增属性时不需要增加表列。表结构共 19 列，保留 span events 和 links，支持 Jaeger 查询与语义实体图。Trace V2 需要显式启用，Trace 功能整体仍处于实验阶段。

在 OTLP trace 写入请求中指定以下请求头，并使用一张独立于 Trace V1 的新表：

x-greptime-pipeline-name: greptime_trace_v2
x-greptime-trace-table-name: traces_v2

写入后，可以直接读取带类型的属性：

SELECT
    trace_id,
    span_attributes."http.status_code"::BIGINT AS http_status,
    resource_attributes."service.name"::STRING AS service_name
FROM traces_v2;

属性名含有点时，需要用双引号包住整个属性名，例如 "http.status_code"。已有 Trace V1 表不会自动迁移；本版 events 和 links 仍使用 JSON 数组。配置方法见 Trace 接入与查询文档。

实验性语义实体图

语义实体图内置了 OpenTelemetry、Prometheus 和 Kubernetes 的语义约定。查询时，它从符合约定的指标与链路数据中推导出服务、主机、容器及 Kubernetes 对象等实体及其关系，也可以通过表级语义声明补充实体信息。以下系统表可以直接用 SQL 查询（字段和查询示例见语义图文档）：

• greptime_private.semantic_entities：实体信息。
• greptime_private.semantic_relationships：实体之间的关系。
• information_schema.table_semantics：各张表提供的语义信息。

例如，查看最近 15 分钟出现过的实体：

SELECT DISTINCT entity_type, entity_id
FROM greptime_private.semantic_entities
WHERE observed_at >= now() - INTERVAL '15' MINUTE
ORDER BY entity_type, entity_id;

表级语义选项可以通过 ALTER TABLE ... SET/UNSET 调整。GreptimeDB MCP Server v0.6.0 及以上版本提供 query_semantic_graph 和 search_table_semantics 两个工具，供 AI Agent 查询实体关系、按概念查找数据表。语义实体图仍是实验能力，后续版本可能调整表结构和推导规则。

PromQL 查询语义与兼容性改进

v1.3.0 修正了 @ 修饰符、未对齐时间戳的子查询、聚合结果上的 group_left / group_right 匹配，以及 label_replace 的部分误报。有歧义的多对多匹配和重复结果序列现在会返回错误。NaN 比值比较也已修正，不再因此误触发告警。

使用 promql-compat 对照 Prometheus v3.15.0 的测试结果如下，比较的是标签和值：

测试集	v1.2.1	v1.3.0
Prometheus 测试集中的 852 个用例	6.7%	88.5%
PromQL compliance tester 的 539 个用例	88.7%	94.8%
1,999 条随机查询，seed 为 1	79.0%	93.4%

上表不比较 __name__。Prometheus 在部分运算后会去掉指标名，GreptimeDB 的结果仍保留 __name__（例如 sum(x > 0)），数值和其他标签一致。日常看面板、配告警阈值基本不受影响；依赖 __name__ 做图例或分组时需要注意。把 __name__ 也计入时，v1.3.0 在三套测试中的通过率分别为 53.5%、54.2% 和 63.8%。

以上通过率不含 1,391 个测试集用例和 1 条随机查询，它们涉及原生直方图、实验能力、起始时间戳、延迟移除指标名及不确定结果等场景。完整测试范围见 PromQL 兼容性结果，剩余差异见 v1.3.0 已知差异。

Dashboard 新增 Signals Explore

内置 Dashboard 更新到 v0.14.2。Signals Explore 把指标、日志和链路放在同一个探索入口中，支持按标签过滤，并可以在日志与链路之间跳转。原生直方图和 gauge histogram 暂不支持图表展示。

时区设置同时作用于结果展示和 SQL 请求；选择 Browser 时，使用浏览器的 IANA 时区。这个版本还修复了日志滚动、加载状态与 trace ID 查询的问题，JSON 结果列可以单独控制是否显示 null 字段。

性能优化

我们在相同硬件、相同数据上对比了 v1.3.0 与 v1.2.1 的查询性能。缓存预热后，各查询的中位耗时变化如下：

场景	数据规模	v1.3.0 相对 v1.2.1 的中位耗时
PromQL 范围查询	30 天、1,720 条时间序列、1.585 亿样本，step 为 30 分钟	5 条查询中 4 条降低 9.9%–41.8%
Agent 可观测性 SQL	1 亿条记录	16 条查询全部降低 6.3%–32.8%
Trace 查询	约 1.001 亿个 span	8 条查询中 6 条降低 6.0%–94.0%

PromQL 与 Agent SQL 测试使用 AWS c7i.2xlarge（8 vCPU、16 GiB 内存），Trace 使用 m7i.2xlarge（8 vCPU、32 GiB 内存）。以上为单轮诊断测试，Trace 组耗时包含客户端处理，表中的最高降幅不代表整体 Trace 性能。测试详情见 性能测试结果。

本版还减少了 PromQL 滑动窗口求值中的重复扫描和简单范围函数中的逐窗口分配，并优化了字典编码主键排序和存储扫描路径。

写入与运维改进

OTLP delta 指标接入

OTLP delta sum 和显式直方图可以保留各采集区间的增量值。对于带有 otlp_aggregation_temporality="delta" 标签的浮点序列，rate() 和 increase() 按原始 delta 语义计算。Delta 指数直方图仍不支持。

分布式写入自动重试

Frontend 遇到暂时性分布式写入错误时，默认最多额外重试 3 次，并在 Region 迁移或分区变化后刷新路由。收到明确的部分失败响应时，只重试失败条目，已确认成功的条目不会重复发送。

[write_retry]
max_retries = 3
initial_backoff = "1500ms"
max_backoff = "10s"
backoff_multiplier = 2.0

设置 max_retries = 0 可关闭重试。这组配置只作用于分布式 Frontend。整个 RPC 失败时，写入结果仍可能不确定，因此自动重试不提供 exactly-once 保证。

TWCS：分别配置活跃与非活跃窗口

TWCS 减少了持续写入时反复重写数据的开销，并支持为活跃和非活跃时间窗口分别配置文件数阈值及 L1 合并阈值。compaction.twcs.trigger_file_num 继续作为活跃窗口参数的别名；非活跃窗口使用独立阈值。参数说明见 TWCS 参数。

未显式配置时，Mito 自动 flush 的默认间隔从 30 分钟缩短为 10 分钟。已有的全局与表级显式配置保持有效。

协议认证

HTTP、MySQL 和 PostgreSQL 协议支持 Bearer token 认证，需要认证提供方实现 token 校验并解析用户身份。MySQL 认证方式也可以由认证提供方按用户选择。

重要修复

• SQL 与 PromQL 结果正确性：修正漏行、排序、IGNORE NULLS、折叠直方图运算及逻辑指标表排序等问题。
• 全文索引：修复 bloom 索引对带下划线文本、汉字与 ASCII 混合文本的漏匹配；符合条件的大小写敏感 LIKE 查询也可以利用索引裁剪。
• 存储与恢复：批量合并保留较新的写入；Region 正常关闭时，会对跳过 WAL 的写入执行 flush；manifest 保存结果不确定时，flush 和 compaction 会保留可能已被引用的 SST，避免误删。

升级前需要检查什么

v1.2 用户可以直接升级到 v1.3。请先备份数据与配置，并在目标版本上验证代表性查询、写入和告警规则。升级前请检查以下 8 项变化。

1. 分布式集群的升级顺序。 滚动升级开始前启用 Metasrv 维护模式，整个升级过程保持开启，全部组件升级完成且健康后再关闭，避免 Batch GC 在新旧版本混用时运行。先升级全部 Datanode，再升级 Frontend；回退时先回退 Frontend，再回退 Datanode。新 Frontend 与旧 Datanode 混用时，可能重放已经成功的写入，在 append 表中产生重复行。

2. 扫描内存限制。 region_engine.mito.scan_memory_limit 默认改为内存基准的 25%：优先使用 cgroup 内存上限，没有有效的 cgroup 限制时使用主机内存。scan_memory_mode 默认为 basic，计入 Parquet 行组解码内存；extended 还会计入流式批次。原先显式设置的限额也需要按新口径复核。scan_memory_on_exhausted 的旧配置值 wait 和 wait(<duration>) 改为立即失败，应更新为 fail 并检查应用的错误处理。升级前按预期并发压测代表性查询，同时复核 query.memory_pool_size；显式设置 scan_memory_limit = "unlimited" 只关闭扫描内存限额。

3. VRL Pipeline 的主机访问。 访问环境变量、文件、网络、本机时区等主机资源的能力默认受限，已有 Pipeline 在重新加载时也会检查。升级前移除受限调用；确有需要且所有 Pipeline 作者可信时，在每个 Frontend 或单机节点设置 pipeline.allow_vrl_host_access = true 并重启。可以用 POST /v1/pipelines/_dryrun 在目标配置下验证 Pipeline。

4. OTLP 标签与告警规则。 存在非空 service.namespace 时，指标的 job 改为 <namespace>/<service.name>。历史数据不会重新打标签，跨升级时间段的查询可能需要同时匹配新旧值。Delta 指标使用保留标签 otlp_aggregation_temporality="delta"，固定 schema 的表需要有可空的对应 tag 列。

5. PromQL 与 SQL 客户端。 未指定 step 的 PromQL 子查询改用固定 1 分钟 step，需要其他间隔时显式写 [range:step]。整数输入的 median、approx_median 和 approx_percentile_cont 改为返回浮点结果，需要检查视图和 Flow 目标表的列类型。MySQL 协议输出的时间戳文本截断到微秒，存储精度不变；需要纳秒时显式转为字符串或整数。

6. 索引与配置迁移。 旧的全文 bloom 索引会被跳过，需要通过 compaction 或 ADMIN BUILD_INDEX 重建才能恢复裁剪，表数据仍可正常读取。删除已失效的原生直方图开关。prom_validation_mode 需要保持原值移到 [prom_store] 下，留在旧位置会被忽略并回到默认值 strict。

7. JSON2 与聚合状态。 JSON2 type hint 不再接受 nullable 和 default，缺失字段返回 NULL；JSON2 仍不支持 bulk insert。uddsketch_state 和 uddsketch_merge 产生新的二进制格式，v1.3 可以读取旧状态，v1.2.1 不能读取新状态；如果可能回退，请保留升级前的状态数据。

8. Flow 镜像写入。 待处理预算为 100 万行，发往不同 Flownode 的副本分别计数。超过预算时，普通表写入可能成功，但 Flow 镜像批次会被丢弃；instant-TTL 写入会在发往 Datanode 前被拒绝。请监控 greptime_table_operator_mirror_pending_rows 和 greptime_operator_dist_mirror_dropped_rows，并拆分过大的批次。

维护模式的操作步骤及其他兼容性事项见 v1.3 升级指南和 完整升级说明。

获取 v1.3.0

安装包和完整变更列表见 GitHub Release。使用中遇到问题，欢迎到 GitHub Issues 反馈。

感谢所有参与本次发布的贡献者，完整名单见 贡献者致谢。