Metricsql

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

1. 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.

1. No extrapolation. Returns actual measured delta; Prometheus extrapolates to window edges, producing fractional

results from integer counters. Affects alerts comparing increase() to integer thresholds.

1. Scalar = instant vector without labels. Prometheus's scalar/instant-vector distinction collapses.

scalar(metric) coercion rarely needed; arithmetic on aggregation results works.

1. NaN drop. (-1)^0.5 returns empty in MetricsQL; Prometheus returns a NaN series. Grafana renders identically;

programmatic consumers see different shapes.

1. 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 :8481/select//prometheus/api/v1/query

http://:8481/select//prometheus/api/v1/query_range

`` 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==`** — adds `{name="value"}` to every selector. Repeatable. Used by auth proxies for
  tenant scoping.
- **`extra_filters[]=`** — 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//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:

histogramquantile(0.5, sum(histogramover_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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [xobotyi](https://github.com/xobotyi)
- **Source:** [xobotyi/cc-foundry](https://github.com/xobotyi/cc-foundry)
- **License:** MIT

Install and usage instructions live in the source repository linked above.