| 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.
- MetricsQL-only extensions — [
${CLAUDE_SKILL_DIR}/references/extensions.md] Rollup family, WITH templates,
multiple-or filters, default/if/ifnot ops, group_left(*) prefix, keep_metric_names, [Ni] step, numeric
suffixes, aggregate limit N, boundsLabel, fractional durations, Graphite, multi-line.
- Full function catalog — [
${CLAUDE_SKILL_DIR}/references/functions-catalog.md] All rollup, transform,
label-manipulation, aggregate functions by category, with PromQL/MetricsQL provenance.
- Query API enhancements — [
${CLAUDE_SKILL_DIR}/references/api-enhancements.md] extra_label, extra_filters[],
round_digits, limit, timestamp formats, stats response, cluster vmselect URL layout, multi-tenancy.
Read the relevant reference before proceeding.
What MetricsQL Is
- 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.
- Metric names retained for safe functions.
min_over_time(foo), round(foo), abs(foo) keep foo. Prometheus
strips.
Full mechanics, edge cases, implicit-conversion pipeline, per-function table:
[${CLAUDE_SKILL_DIR}/references/behavioral-diffs.md].
Lookbehind Window — Auto-Selection
Omitting [d] is allowed:
default_rollup and rate: max(step, scrape_interval) — prevents gaps when step < scrape_interval.
- All other rollups:
step ($__interval in Grafana, 1i).
rate(node_network_receive_bytes_total) ≡ rate(node_network_receive_bytes_total[$__interval]).
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.
group_left(*) and Label Copy
kube_pod_info * on(namespace) group_left(*) prefix "ns_" kube_namespace_labels
Copies all labels from right side except those in on(...), prefixed with ns_. group_right(*) mirrors. Without
prefix, collisions error.
Aggregate limit N
sum(http_requests_total) by (path) limit 10
Returns 10 paths total. Other series dropped silently. Distinct from topk(10, ...): limit N is order-arbitrary;
topk keeps the top by value.
Grafana $__interval and [Ni] Syntax
1i = one step (Grafana step arg).
[10i] = lookbehind covering ten steps.
offset 5i = shift back five steps.
- Works in rollup windows, offsets, subquery step:
rate(metric[10i] offset 5i).
- Use over hard-coded durations so panels scale with the time range.
Cluster Endpoint Structure
http://<vmselect>:8481/select/<accountID>/prometheus/api/v1/query
http://<vmselect>:8481/select/<accountID>/prometheus/api/v1/query_range
<accountID> is accountID or accountID:projectID (32-bit ints). Single-node uses unprefixed /api/v1/query.
/prometheus/ prefix is optional but explicit.
Full URL layout (ingestion, federation, Graphite, vmstorage admin, vmalert proxy):
[${CLAUDE_SKILL_DIR}/references/api-enhancements.md].
Query API Enhancements
extra_label=<name>=<value> — adds {name="value"} to every selector. Repeatable. Used by auth proxies for
tenant scoping.
extra_filters[]=<selector> — adds a full selector with regex support: extra_filters[]={env=~"prod|staging"}.
round_digits=N — rounds response values to N decimals.
limit=N on /api/v1/labels, /api/v1/label/<name>/values, /api/v1/series.
Responses include stats with executionTimeMsec and seriesFetched. seriesFetched is approximate; vmalert uses it
to flag never-firing rules.
Syntax Conveniences
- Underscore in numbers —
1_234_567_890 ≡ 1234567890
- Numeric suffixes —
8K (8000), 1.2Mi (1.2×1024²), supports K Ki M Mi G Gi T Ti
- Fractional durations —
[1.5m], offset 0.5d
- Optional duration suffix —
[300] is seconds: rate(m[300] offset 1800) ≡ rate(m[5m]) offset 30m
- Duration anywhere —
sum_over_time(m[1h]) / 1h ≡ sum_over_time(m[1h]) / 3600
- Trailing commas —
m{foo="bar",}, f(a, b,), WITH (x=y,) x all valid. Use in multi-line queries.
- Unicode in names —
ტემპერატურა{πόλη="Київ"} is valid
- Escape sequences —
foo\-bar{baz\=aa="b"}, \xXX, \uXXXX
@ modifier anywhere — sum(foo) @ end(), foo @ (end() - 1h)
Histogram Extensions
histogram_quantile(phi, buckets, boundsLabel?) — optional third arg returns lower/upper bounds in boundsLabel.
For plotting quantile confidence intervals.
histogram_over_time(gauge[d]) produces VictoriaMetrics-format histograms from gauge values:
histogram_quantile(0.5, sum(histogram_over_time(temperature[24h])) by (vmrange,country))
Computes quantiles over gauge distributions without re-instrumenting.
Application
When writing:
- Omit lookbehind only when panel-wide
$__interval is appropriate. Otherwise use [5m] or [Ni] explicitly.
- For alerting/recording rules: always specify the lookbehind window. Implicit selection couples rule behavior to
evaluation interval.
- Prefer
default over or vector(0) — more readable, handles labels correctly.
- Use
rollup_rate for counter spike detection over irate — min/max/avg in one query.
When migrating from Prometheus:
- Audit alerts comparing
increase() to integer thresholds — exact integers may fire differently.
- Use
*_prometheus variants only when byte-parity is required (cross-backend SLO consistency).
- Enable
-search.logImplicitConversion to see rewrites.
When reviewing:
- Flag missing lookbehind windows in alerting/recording rules.
- Flag
rate(sum(...)) — silent subquery formation.
- Flag bare selectors in arithmetic — silent
default_rollup wrap.
- Cite the specific diff and show the fix inline.
Integration
promql — shared fundamentals (selectors, operators, aggregations, vector matching). This skill — MetricsQL
extensions and diffs.
prometheus — instrumentation; this skill — query-time behavior.