Schema migration Feb ’26

We’re unifying how we store user-defined metrics extracted from logs and spans alongside Prometheus metrics.

Going forward, there’s just one way to query your metrics.

Schema overview

Our new row-based schema stores all data in a unified format:

• Metrics stored as named values with labels in a tags map
• Original log data accessible via _row_type = 'log'
• Aggregated metric functions for efficient querying

Accessing tags and labels

All non-aggregated columns that were previously accessed directly must now use the label() function. Labels are always strings, so toString(label(...)) is redundant.

-- Before:
-- SELECT response_status, request_method, user_agent
-- FROM {{source}}
-- WHERE response_status >= 500

-- After:
SELECT label('response_status'), label('request_method'), label('user_agent')
FROM {{source}}
WHERE toUInt16OrNull(label('response_status')) >= 500

Standard columns

The following columns are part of the schema itself and don't need the label() wrapper.

dt, name, _row_type, 
series_id, tags, events_count, 
value_avg, value_min, value_max, rate_avg, 
bucket_bounds, bucket_counts, bucket_sum, bucket_count, 
bucket_min, bucket_max, bucket_quantiles

Row type filtering

Each ingested event creates multiple rows. One row for the original event (_row_type = 'log' or 'span'), and multiple for extracted metrics (_row_type = 'extracted_metric').

Count log events

SELECT {{time}} AS time, countMerge(events_count) AS value
FROM {{source}}
WHERE dt BETWEEN {{start_time}} AND {{end_time}}
  AND _row_type = 'log'
GROUP BY time

Don't use _row_type = 'log' or 'span' when querying named metrics

-- WRONG: name = 'duration' is an extracted metric, not a span
-- SELECT histogramQuantile(0.95) AS p95
-- FROM {{source}}
-- WHERE dt BETWEEN {{start_time}} AND {{end_time}}
--   AND _row_type = 3
--   AND name = 'duration'
-- GROUP BY time

-- CORRECT: Filter by metric name
SELECT histogramQuantile(0.95) AS p95
FROM {{source}}
WHERE dt BETWEEN {{start_time}} AND {{end_time}}
  AND name = 'duration'
GROUP BY time

Type handling for labels

Since labels are always strings, you must handle type conversions explicitly when comparing to numbers.

Numeric comparison

-- Range check
WHERE toUInt16OrNull(label('response_status')) BETWEEN 200 AND 299

-- Inequality
WHERE toFloat64OrNull(label('response_status')) >= 500
AND toFloat64OrNull(label('response_status')) <= 599

Histograms and buckets

The new schema uses bucket_bounds and bucket_counts, with the counts storing deltas. sumForEachMerge() is used to sum these deltas.

-- Old pattern:
-- arrayJoin(anyLastMerge(buckets)) AS bucket

-- New pattern:
SELECT
  time,
  arrayJoin(arrayZip(bounds, counts)) AS bucket,
  bucket.1 AS bound,
  bucket.2 AS count
FROM
(
  SELECT
    {{time}} AS time,
    anyLastMerge(bucket_bounds) AS bounds,
    sumForEachMerge(bucket_counts) AS counts
  FROM {{source}}
  WHERE ...
  GROUP BY time
)

Quantiles and percentiles Use the histogramQuantile(p) helper function for single metrics, or quantilePrometheusHistogramArrayMergeIf(p)(bucket_quantiles, condition) for multiple metrics.

SELECT
  {{time}} AS time,
  histogramQuantile(0.95) AS p95
FROM {{source}}
WHERE dt BETWEEN {{start_time}} AND {{end_time}}
  AND name = 'http_request_duration_seconds'
GROUP BY time

Event counting

For aggregated metrics queries, use countMerge(events_count). Because a single event can be represented as multiple metric rows, you need to add the AND _row_type = 'log' filter to get accurate event counts.

SELECT
  {{time}} AS time,
  countMerge(events_count) AS value
FROM {{source}}
WHERE dt BETWEEN {{start_time}} AND {{end_time}}
  AND _row_type = 'log'
GROUP BY time

This change will go in effect for existing organizations during February ’26.

Let us know at hello@betterstack.com if you have any feedback. We hope this change will make the product more straightforward and intuitive going forward.