v1.3.0-beta.1
Release date: September 29, 2026
GreptimeDB v1.3.0-beta.1 is the first beta of the 1.3 release. This changelog covers changes since v1.3.0-alpha.1.
👍 Highlights
Native histogram ingestion enabled by default
GreptimeDB now accepts Prometheus Remote Write v2 native histograms and cumulative OTLP/HTTP exponential histograms without experimental configuration switches. For Prometheus that already collects native histograms, select Remote Write 2.0 in prometheus.yml:
remote_write:
- url: http://localhost:4000/v1/prometheus/write?db=public
protobuf_message: io.prometheus.write.v2.Request
Query the stored histograms through GreptimeDB's PromQL API. This release also fixes histogram reads from SSTs and scalar batch writes to physical tables shared with histogram metrics. Remote Write v1 native histograms, native histogram Remote Read, and OTel Arrow exponential histograms remain unsupported. See #9301 and #9321.
Series index preview (experimental)
This release introduces an experimental series index for discovering candidate time series in indexed SSTs. See #9085.
To try it in a non-production environment, set experimental_enable_series_index = true in the Mito engine configuration of your standalone instance or datanodes, then restart the affected instances. Update the existing Mito engine entry if one is already configured:
[[region_engine]]
[region_engine.mito]
experimental_enable_series_index = true
Series index is at a very early experimental stage and is unstable. Future releases may introduce breaking changes. It is not recommended for production use.
Trace V2: JSON2 attributes with Jaeger and Semantic Graph support
The opt-in greptime_trace_v2 pipeline stores span, scope, and resource attributes in three JSON2 columns instead of adding a SQL column for every attribute. Its 19-column schema also preserves span events and links as JSON arrays. Jaeger queries and Semantic Graph derivation support the new model.
Select greptime_trace_v2 with the x-greptime-pipeline-name header on OTLP trace ingestion requests and use a separate destination table from Trace V1. After ingesting into a table named traces_v2, query typed attributes directly:
SELECT
trace_id,
span_attributes."http.status_code"::BIGINT AS http_status,
resource_attributes."service.name"::STRING AS service_name
FROM traces_v2;
Existing Trace V1 tables are not automatically migrated. Events and links use JSON in this release; ARRAY(JSON2) is deferred. See #9192, #9232, #9257, and #9278.
Improved compaction algorithms and TWCS tuning
The multiway merge used by compaction now uses a winner tree for its active input streams, reducing comparison work when merging overlapping sorted data. TWCS also applies different selection policies to active and inactive time windows: active windows favor separate merges of newly flushed and previously compacted files to avoid repeated rewrites, while inactive windows have additional consolidation paths. Serial automatic compaction selects one output at a time and replans against the updated SST state before selecting further work.
Three new tuning options accompany the renamed active-window file-count trigger. The following example sets the table-level options to their defaults:
ALTER TABLE my_table SET
'compaction.twcs.active_window.trigger_file_num' = '4',
'compaction.twcs.active_window.l1_merge_trigger' = '16',
'compaction.twcs.inactive_window.trigger_file_num' = '2',
'compaction.twcs.inactive_window.l1_merge_trigger' = '8';
The existing compaction.twcs.trigger_file_num option remains accepted as an alias for compaction.twcs.active_window.trigger_file_num; inactive windows now use their own thresholds. See #8989, #9064, and #9011.
Dashboard
The bundled dashboard advances to v0.13.15. JSON result columns gain a per-column action to show or hide null fields, and the metric query input layout handles overflowing content. See dashboard #653 and #652.
Upgrade notes
- SQL results: The query engine moves to DataFusion 55.1.0. Integer-input
median,approx_median, andapprox_percentile_contreturn floating-point results; exact median interpolates even-sized inputs. Review consumers with fixed result schemas, including views and Flow sinks.REPLACE(s, '', replacement)now returnssunchanged, generated structunnestcolumn names change, and approximate cardinality estimates can differ. PostgreSQL metadata now honors OID-alias annotations. See #8555 and #9177. - JSON2 type hints: Remove
nullableanddefaultoptions from SQL DDL and pipeline configuration. Hinted fields now always allow null, and missing hinted fields become null. See #9213. - Native histograms: Prometheus Remote Write v2 native histograms and cumulative OTLP/HTTP exponential histograms are accepted by default. The removed
experimental_enable_prometheus_native_histogramandexperimental_enable_exponential_histogramoptions are ignored, including when set tofalse. Remote Write v1 native histograms, native histogram Remote Read, and OTel Arrow exponential histograms remain unsupported. See #9301.
Breaking changes
- feat!: upgrade DataFusion to 55 by @discord9 in #8555
- feat(json2)!: remove nullable and default type hint options by @fengys1996 in #9213
- feat!: upgrade DataFusion fork to 55.1.0 by @discord9 in #9177
🚀 Features
- feat: support raw OTLP delta metrics by @shuiyisong in #8970
- feat(flow): support eval schedule offsets by @discord9 in #8878
- feat(client): compress insert transport by @v0y4g3r in #9036
- feat: add scanbench query suites and structured results by @evenyag in #9050
- feat(meta): record logical-table reconciliation events by @dhruvxvaishnav in #8941
- feat: update dashboard to v0.13.15 by @sunchanglong in #9051
- feat(auth): support bearer token authentication over SQL protocols by @shuiyisong in #8899
- feat(mito2): adapt bulk memtable encode threshold to write buffer size by @v0y4g3r in #9056
- feat(telemetry): add log directory size retention by @WenyXu in #8997
- feat(mito2): add series index catalog and lifecycle foundation by @evenyag in #9053
- feat(auth): support per-user MySQL authentication methods by @shuiyisong in #9078
- feat: make the series index resilient to time index unit widening by @sunng87 in #8996
- feat(mito2): introduce TWCS active window compaction by @v0y4g3r in #9011
- feat: add repartition partition count hint by @WenyXu in #9080
- feat(json2): support ALTER syntax for JSON column settings by @fengys1996 in #9094
- feat: support request-level insert WAL skipping by @WenyXu in #9088
- feat(meta): record catalog and database reconciliation events by @dhruvxvaishnav in #8896
- feat(mito2): add series index planning and builders by @evenyag in #9085
- feat(pprof): switch CPU profiler to framehop unwinder by @v0y4g3r in #9125
- feat: support request-level WAL skipping for bulk inserts by @WenyXu in #9110
- feat(mito2): add opt-in byte-stream-split encoding for float SST fields by @discord9 in #9069
- feat(mito2): reconcile series indexes in background by @evenyag in #9086
- feat: export logical tables from Metric physical scans by @fengjiachun in #9159
- feat: allow re-enabling WAL after disabling by @dhruvxvaishnav in #9130
- feat: use exact sequence ranges for incremental Flow reads by @discord9 in #9165
- feat: add prepared batch write primitives by @WenyXu in #9186
- feat(wal): add the object store WAL provider identity and configuration by @fengjiachun in #9203
- feat: add ordinary table batching workers by @WenyXu in #9187
- feat(log-store): add the object store WAL object format by @fengjiachun in #9200
- feat: batch ordinary table writes across HTTP protocols by @WenyXu in #9115
- feat(otlp): add trace v2 ingestion with JSON2 attributes by @MichaelScofield in #9192
- feat(ci): add observability benchmark and lifecycle summaries by @WenyXu in #9215
- feat: prepare and execute database Metric exports by @fengjiachun in #9180
- feat(ci): add long-range metrics benchmark on ECS by @WenyXu in #9218
- feat(flow): expose extension-owned batching execution hooks by @discord9 in #9171
- feat(function): add mergeable binary average states by @discord9 in #9062
- feat(log-store): add the object store WAL batch, catalog and I/O by @fengjiachun in #9216
- feat(otlp): preserve trace v2 events and links as JSON (follow-up to #9192) by @MichaelScofield in #9232
- feat(flow): admit mergeable average states in incremental plans by @discord9 in #9235
- feat(log-store): add object store WAL store construction and recovery by @fengjiachun in #9238
- feat: expose region min/max timestamp in region_statistics by @sainad2222 in #9060
- feat: add status label to datanode failed-insert metric by @dhruvxvaishnav in #9191
- feat(mito2): make range index reads and builds opt-in by @evenyag in #9219
- feat(json2): respect type hints during JSON2 type concretization by @fengys1996 in #9222
- feat(mito2): split SWCS output files by size threshold by @v0y4g3r in #9259
- feat(trace): support Jaeger queries for Trace V2 and optimize writes (follow-up to #9192) by @MichaelScofield in #9257
- feat: update pgwire to 0.41 by @sunng87 in #9025
- feat: add database ingestion admission through metering by @shuiyisong in #9239
- feat: add experimental Metric export to V2 snapshots by @fengjiachun in #9233
- feat: restore packed metric snapshots by @fengjiachun in #9250
- feat(trace): support Semantic Graph for Trace V2 (follow-up to #9192) by @MichaelScofield in #9278
- feat: add experimental Jev SQL filtering by @v0y4g3r in #9265
- feat(log-store): add object store WAL reads and obsolete watermarks by @fengjiachun in #9248
- feat(json2): support altering JSON2 settings by @fengys1996 in #9029
- feat: add AI matching, classification, and scoring functions by @v0y4g3r in #9300
- feat: share logical table batching with OTLP metrics by @WenyXu in #9288
- feat(flow): allow execution hook to rewrite completed plans by @discord9 in #9290
- feat: support pending rows batching for MySQL and PostgreSQL by @WenyXu in #9302
- feat: expose region open failure metrics by @evenyag in #9283
- feat(flow): freeze recovery windows and retention bounds for incremental flows by @discord9 in #9312
- feat: add schema metadata stream to SchemaManager by @shuiyisong in #9325
- feat: enable native histogram ingestion by default by @shuiyisong in #9301
- feat(mito): limit approximate series index disk usage by @evenyag in #9313
- feat(log-store): chain object store WAL objects and recover the latest chain by @fengjiachun in #9334
- feat(otlp): add histogram rejection metrics and compact zero buckets by @shuiyisong in #9321
- feat: add manual series index reconciliation by @evenyag in #9323
- feat(log-store): add the object store WAL durable write path by @fengjiachun in #9320
- feat: allow customized time index unit for metric engine table by @sunng87 in #9236
- feat: add HDFS object storage backend by @Minghan2005 in #8701
- feat(log-store): add the enqueued acknowledgement mode to the object store WAL by @fengjiachun in #9358
- feat(query): implement PromQL @ modifier on vector and matrix selectors by @discord9 in #9224
- feat: support non-millisecond time index units in the logical batcher by @sunng87 in #9346
- feat: export Metric snapshots with packed Parquet objects by @fengjiachun in #9382
🐛 Bug Fixes
- fix(client): isolate query and control transports by @discord9 in #8990
- fix(pipeline): coalesce concurrent pipeline cache misses by @killme2008 in #9022
- fix(json2): keep empty structs in remainder by @MichaelScofield in #9027
- fix(wal): bound Kafka requests and extend latency buckets by @WenyXu in #9026
- fix: match system schema names case-insensitively by @killme2008 in #9040
- fix(frontend): isolate internal Flight authentication by @discord9 in #9045
- fix: re-scan stream-backed tables in recursive CTEs by @killme2008 in #9039
- fix(cli): sanitize store_addrs in kvbackend build log by @LiuQhahah in #8967
- fix(mito2): harden flat merge and use winner_tree by @v0y4g3r in #9064
- fix: prevent catalog testing feature from leaking into production builds by @evenyag in #9063
- fix(ci): avoid cross-references in PR limit comments by @evenyag in #9065
- fix(prometheus): align batch flush deadline with creation by @v0y4g3r in #8802
- fix(servers): return text[] for SELECT array[null] in PostgreSQL protocol by @Tyagiquamar in #9058
- fix(ci): strip pre-release extension when creating nightly release version by @sunng87 in #9081
- fix(flow): drain frontend probe response before selecting peer by @discord9 in #9082
- fix(promql): correct counter reset accumulation in rate windows by @killme2008 in #9089
- fix(query): prevent incomplete aggregate dynamic filtering by @discord9 in #9102
- fix: bump jemalloc crates to 0.7 and patch tikv-jemalloc-sys with tcache init fix by @v0y4g3r in #9103
- fix(ci): check Windows test targets before merge by @WenyXu in #9116
- fix(ci): increase query regression ECS disk to 80 GiB by @discord9 in #9123
- fix(mito): preserve mixed JSON2 types during compaction by @v0y4g3r in #9135
- fix(mito2): prevent JSON2 SWCS data loss from misaligned Parquet statistics due to projection by @v0y4g3r in #9129
- fix(promql): preserve native timestamps through sample selection by @discord9 in #9070
- fix(promql): skip NULL samples and fix counter extrapolation order by @killme2008 in #9118
- fix: configure series indexes with an enable flag by @evenyag in #9141
- fix(mito2): deliver complete WAL entries without waiting for next input by @discord9 in #8916
- fix(servers): resolve port from IPv6 bind addresses by @immanuwell in #9142
- fix(mito2): preserve effective sequences during compaction by @v0y4g3r in #9147
- fix: preserve count correctness after repartition by @WenyXu in #9154
- fix(mysql): strip leading comments before the federated statement filter by @killme2008 in #9156
- fix: support native JSON2 row inserts over gRPC by @MichaelScofield in #9145
- fix: register region migration procedures before returning IDs by @fengjiachun in #9163
- fix: preserve structured query errors through distributed execution by @discord9 in #9161
- fix(promql): skip empty batches in SeriesDivide stream by @discord9 in #9178
- fix(ci): rerun semantic PR checks after pushes by @evenyag in #9190
- fix(mito2): preserve last-non-null values across compaction by @v0y4g3r in #9169
- fix: support exact sequence ranges in two-phase series scans by @discord9 in #9096
- fix(ci): repair agent observability dispatch and runner cleanup by @WenyXu in #9204
- fix(json): fix JSONPath panic with jsonb 0.5.6 (follow-up to #9192) by @MichaelScofield in #9228
- fix(servers): merge duplicate timeseries across RecordBatches in Prometheus remote read by @Tyagiquamar in #9032
- fix(prometheus): honor label matchers in name values query by @killme2008 in #9134
- fix(mito2): hold the bulk compact permit for the whole blocking task by @killme2008 in #9252
- fix: make database export assertions portable on Windows by @fengjiachun in #9256
- fix(mito2): cancel cache construction for incomplete scans by @killme2008 in #9254
- fix(mito2): compare primary key ranges across schema versions by @v0y4g3r in #9205
- fix(query): insert MergeScan into nested scalar subqueries by @discord9 in #9261
- fix(ci): stabilize long-range benchmark execution and artifact collection by @WenyXu in #9241
- fix(promql): keep value-field grouping labels out of matching filter propagation by @discord9 in #9242
- fix: release completed SST write buffers during compaction by @v0y4g3r in #9243
- fix: fail startup on duplicate region engine configs by @v0y4g3r in #9281
- fix(query): stop encoding oversized dynamic filters by @killme2008 in #9267
- fix(meta): populate physical metric table column ids by @dhruvxvaishnav in #9286
- fix(postgres): return empty responses for comment-only SQL by @houyuwushang in #9295
- fix(ci): build tests-integration lib with meta-srv/mock by @killme2008 in #9299
- fix: keep compaction pruning, metadata, and index work on compact runtime by @v0y4g3r in #9304
- fix: serialize struct to json in postgres by @sunng87 in #9170
- fix: address Windows test failures and run full Windows CI by @WenyXu in #9305
- fix(json2): restrict JSON2 type hints by @fengys1996 in #9316
- fix(ci): repair draft PR command dispatch by @WenyXu in #9271
- fix(promql): derive vector matching result labels and reject ambiguous matchings by @killme2008 in #9306
- fix(ci): grant PR write permission for CI command replies by @WenyXu in #9331
- fix: merge every state row in geo_path and json_encode_path by @killme2008 in #9339
- fix: only push down aggregates grouped by the partition columns themselves by @killme2008 in #9337
- fix: align ordered aggregate state type with the accumulator output by @killme2008 in #9340
- fix(query): keep count_values generated label in enclosing expressions by @discord9 in #9223
- fix: make vector aggregates work with GROUP BY and partial aggregation by @killme2008 in #9338
- fix: preserve primary key order when syncing columns by @WenyXu in #9189
- fix(mito2): stop parallel flat scan tasks once the receiver is dropped by @killme2008 in #9368
- fix(query): preserve global limits with DataFusion optimizer fixes by @discord9 in #9071
- fix(auth): follow symlink chains in watch_file_user_provider by @DeviousCardi in #9365
- fix(client): complete transport lane isolation by @discord9 in #9030
- fix(ci): teach check-builder-rust-version.sh to handle stable channels by @sunng87 in #9369
- fix(ci): update the shared Actions runner to v2.337.0 by @WenyXu in #9376
- fix(meta-srv): use NoTls for disabled and Unix socket Postgres KV backends by @Tyagiquamar in #9059