VictoriaMetrics MetricsQL query language as a PromQL superset: rollup extensions, behavioral differences from PromQL (rate/increase semantics, implicit conversions, auto-aligned subqueries), label manipulation, WITH templates, keep_metric_names modifier, multiple-or filters, and query API enhancements. Invoke whenever task involves any interaction with MetricsQL or VictoriaMetrics queries — writing, debugging, optimizing, migrating PromQL to VictoriaMetrics, or reviewing.
Instrucciones de origen · Vista previa de solo lectura
name
metricsql
description
VictoriaMetrics MetricsQL query language as a PromQL superset: rollup extensions, behavioral differences from PromQL (rate/increase semantics, implicit conversions, auto-aligned subqueries), label manipulation, WITH templates, keep_metric_names modifier, multiple-or filters, and query API enhancements. Invoke whenever task involves any interaction with MetricsQL or VictoriaMetrics queries — writing, debugging, optimizing, migrating PromQL to VictoriaMetrics, or reviewing.
MetricsQL
VictoriaMetrics PromQL superset. Syntactically backwards-compatible; semantically different for a subset of queries.
Lead with the diffs — that's where users get burned. PromQL fundamentals live in the sibling promql skill; this covers
only what PromQL doesn't.
References
Behavioral diffs from PromQL — [${CLAUDE_SKILL_DIR}/references/behavioral-diffs.md]
rate/increase/delta/changes diffs, _prometheus-suffixed variants, scalar/instant-vector unification, NaN
handling, name retention, implicit conversions, auto-aligned subqueries, default_rollup lookback, staleness markers.
Full function catalog — [${CLAUDE_SKILL_DIR}/references/functions-catalog.md] All rollup, transform,
label-manipulation, aggregate functions by category, with PromQL/MetricsQL provenance.
Strict syntactic superset of PromQL — every valid PromQL parses as MetricsQL.
Not semantic superset — rate, increase, delta, changes differ.
_prometheus-suffixed variants give byte-parity: rate_prometheus, increase_prometheus, delta_prometheus,
changes_prometheus.
Implemented by vmselect (cluster) or single-node binary; exposed via standard /api/v1/query and
/api/v1/query_range.
The Five Behavioral Diffs That Bite
Lookbehind anchor.rate/increase use the last sample before the window for the first delta; Prometheus
doesn't. For increase(metric[$__interval]) on a slow counter, Prometheus loses one delta per window. Use
rate_prometheus/increase_prometheus for parity.
No extrapolation. Returns actual measured delta; Prometheus extrapolates to window edges, producing fractional
results from integer counters. Affects alerts comparing increase() to integer thresholds.
Scalar = instant vector without labels. Prometheus's scalar/instant-vector distinction collapses.
scalar(metric) coercion rarely needed; arithmetic on aggregation results works.
NaN drop.(-1)^0.5 returns empty in MetricsQL; Prometheus returns a NaN series. Grafana renders identically;
programmatic consumers see different shapes.
Silent behavior change across panels with different steps. For alerting and recording rules, always specify the
window explicitly.
Implicit Query Conversions
VictoriaMetrics rewrites every query before evaluation (unless -search.disableImplicitConversion):
Bare selectors → default_rollup: foo → default_rollup(foo).
Selectors inside transform/aggregate get the same wrap: abs(temperature) → abs(default_rollup(temperature)),
count(up) → count(default_rollup(up)).
Rollups on non-selectors become subqueries: rate(sum(up)) → rate((sum(default_rollup(up)))[1i:1i]).
Subqueries with missing step get 1i: avg_over_time(rate(m[5m])[1h]) → avg_over_time(rate(m[5m])[1h:1i]).
When debugging, mentally apply these first — the actual computation may differ from what was typed.
Full conversion list with disable flags: [${CLAUDE_SKILL_DIR}/references/behavioral-diffs.md].
The Rollup Family — MetricsQL-Only
rollup(m[d]) — min/max/avg with rollup="..." label.
rollup_rate(m[d]) — per-second rate min/max/avg over adjacent samples; better than irate for spike detection.
rollup_increase(m[d]) / rollup_delta(m[d]) / rollup_deriv(m[d]) — same pattern.
rollup_candlestick(m[d]) — OHLC.
aggr_over_time(("func1","func2",...), m[d]) — multiple rollups in one pass.
Pair with keep_metric_names to preserve the original name.
keep_metric_names
Functions and binary ops strip the metric name. This causes duplicate time series errors when distinct names collapse
into the same label set. Suffix with keep_metric_names:
rate({__name__=~"foo|bar"}) keep_metric_names
({__name__=~"foo|bar"} / 10) keep_metric_names
Available on all rollups, transforms, and binary operators.
Multiple or in Series Selectors
PromQL {env="prod",job="a"} is a single AND. MetricsQL adds top-level disjunction:
{env="prod",job="a" or env="dev",job="b"}
Each or-group is an AND of matchers. Compose with comma within a group.
Multi-constant matching: status_code == (300, 301, 304) returns series where status_code is any listed value.
WITH Templates
Reusable named subexpressions:
WITH (
errs = rate(http_requests_total{status=~"5.."}[5m]),
total = rate(http_requests_total[5m]),
)
sum(errs) by (job) / sum(total) by (job)
String concat: WITH (commonPrefix="my_app_") {__name__=commonPrefix+"errors_total"}. Expanded at parse time.
Binary Operators Beyond PromQL
q1 default q2 — fills gaps in q1 from q2.
q1 if q2 — keeps q1 where q2 has a value (conditional masking).
q1 ifnot q2 — keeps q1 where q2 has no value (inverse).
Compose with default-on-missing: (up{job="x"} default 0) == 0 reliably alerts on disappearing targets.
<accountID> is accountID or accountID:projectID (32-bit ints). Single-node uses unprefixed /api/v1/query.
/prometheus/ prefix is optional but explicit.
