Grafana Loki: structured LogQL queries

Source: src/nosql/loki/logql.ts · src/nosql/loki/index.ts · Tests: tests/nosql/loki-logql.test.ts, tests/nosql/loki-endpoints.test.ts

LokiStore originally exposed query(logql) — the query was a string the caller wrote by hand, which is exactly what this library's public API is not supposed to require. This page documents the structured path that closes that gap.

query() has not gone anywhere. It is the escape hatch for what LogQL can express and this compiler deliberately will not, and every refusal below names the feature and points back at it.

Why the spec is not findAll-shaped

Every other store in this library was closed by mapping onto a findAll-like { where, attributes, order, limit } spec, because they answer the question SQL answers: which rows, projected how. LogQL does not. A LogQL query is:

stream selector  →  pipeline  →  (optionally) an aggregation

The pipeline is ordered and stateful. | json invents labels a later | status >= 400 can filter on; | line_format rewrites the line a later |= "x" searches; | drop removes labels a later by (…) would have grouped by. Swap two stages and you get a different answer. A where map is unordered, and limit is a server-side page size rather than a stage — flattening a pipeline into { where, limit, order } would throw away the one property that makes LogQL what it is.

The aggregation half does not return rows at all: it turns logs into a metric time series, which has no findAll counterpart.

So the spec mirrors LogQL's own grammar:

interface LogQuerySpec {
  selector: StreamSelectorSpec;      // { app="api", env=~"prod|staging" }
  pipeline?: LogqlPipelineStage[];   // ordered; order is meaning
}

type LogqlMetricExpr =              // a small expression tree
  | { type: 'logRange'; … }          //   rate({…}[5m])
  | { type: 'unwrappedRange'; … }    //   quantile_over_time(0.99, {…} | unwrap x [5m])
  | { type: 'vectorAgg'; … }         //   sum by (level) (…)
  | { type: 'binary'; … }            //   … / … , … > bool 0.5
  | { type: 'labelReplace'; … }
  | { type: 'vector' | 'literal'; … };

compile(spec) returns { text, kind }, where kind is 'log' or 'metric' — that is what tells the store which result shape to expect.

The surface

Method	Endpoint	Returns
compileQuery(spec)	—	{ text, kind }, no I/O
queryLogsRange(spec, opts?)	GET /loki/api/v1/query_range	LokiStreamsResult
queryMetricRange(spec, opts?)	GET /loki/api/v1/query_range	LokiMatrixResult
queryLogsInstant(spec, opts?)	GET /loki/api/v1/query	LokiStreamsResult
queryMetricInstant(spec, opts?)	GET /loki/api/v1/query	LokiVectorResult | LokiScalarResult
streams(selector?, opts?)	GET /loki/api/v1/series	label sets
labelValues(name, opts?)	GET /loki/api/v1/label/<name>/values	label values
query(logql, opts?)	GET /loki/api/v1/query_range	raw escape hatch

import { Op } from 'ts-prorm-orm';
import { LokiStore } from 'ts-prorm-orm/nosql/loki';

const store = new LokiStore({ baseURL: 'http://localhost:3100' });
await store.connect();

const logs = await store.queryLogsRange(
  {
    selector: { where: { app: 'api', env: { [Op.in]: ['prod', 'staging'] } } },
    pipeline: [
      { stage: 'line', op: '|=', value: 'error' },
      { stage: 'json' },
      { stage: 'labelFilter', filter: { kind: 'number', label: 'status', op: '>=', value: 500 } },
    ],
  },
  { since: '1h', limit: 100, direction: 'backward' },
);

{app="api", env=~`(?:prod|staging)`} |= "error" | json | status >= 500

How a query flows

A log query stops after the pipeline and returns streams; a metric query wraps it in a range function and, usually, an aggregation, and returns a matrix or vector:

flowchart LR
  SEL["selector {app=api}: picks streams by indexed labels"] --> LF["line filters |= != |~"]
  LF --> PAR["parser: json / logfmt / regexp"]
  PAR --> LBL["label filters: status >= 500"]
  LBL --> FMT["line_format / label_format / drop"]
  FMT -->|"log query"| STREAMS["streams: [ts, line] per stream"]
  FMT -->|"[5m] range"| RF["rate / count_over_time / unwrap + quantile_over_time"]
  RF --> AGG["sum by / max by / topk"]
  AGG --> MATRIX["matrix (range) or vector (instant)"]

Metric queries, side by side

import { Op } from 'ts-prorm-orm';
import { LokiStore } from 'ts-prorm-orm/nosql/loki';

const store = new LokiStore({ baseURL: 'http://localhost:3100' });
await store.connect();

try {
  // 1. 5xx responses per second, per app
  const errorRate = await store.queryMetricRange(
    {
      type: 'vectorAgg', op: 'sum', by: ['app'],
      expr: {
        type: 'logRange', fn: 'rate', range: '5m',
        log: {
          selector: { where: { env: 'prod' } },
          pipeline: [{ stage: 'json' }, { stage: 'labelFilter', filter: { kind: 'number', label: 'status', op: '>=', value: 500 } }],
        },
      },
    },
    { since: '6h', step: '1m' },
  );

  // 2. p99 request duration per route, from a logfmt field
  const p99 = await store.queryMetricInstant({
    type: 'vectorAgg', op: 'max', by: ['route'],
    expr: {
      type: 'unwrappedRange', fn: 'quantile_over_time', param: 0.99, range: '5m',
      log: { selector: { where: { app: 'api' } }, pipeline: [{ stage: 'logfmt' }] },
      unwrap: { label: 'duration', conversion: 'duration_seconds' },
    },
  });

  // 3. the share of lines that mention an error
  const errorShare = await store.queryMetricInstant({
    type: 'binary', op: '/',
    left: { type: 'vectorAgg', op: 'sum', expr: { type: 'logRange', fn: 'count_over_time', range: '5m', log: { selector: { where: { app: 'api' } }, pipeline: [{ stage: 'line', op: '|=', value: 'error' }] } } },
    right: { type: 'vectorAgg', op: 'sum', expr: { type: 'logRange', fn: 'count_over_time', range: '5m', log: { selector: { where: { app: 'api' } } } } },
  });

  // 4. reshape lines, dropping debug noise
  const lines = await store.queryLogsRange(
    {
      selector: { where: { app: 'api', level: { [Op.ne]: 'debug' } } },
      pipeline: [{ stage: 'json' }, { stage: 'lineFormat', template: '{{.method}} {{.path}} {{.status}}' }],
    },
    { since: '15m', limit: 50 },
  );

  console.log(errorRate.result.length, p99.result, errorShare.result, lines.result.length);
} finally {
  await store.disconnect();
}

# 1.
sum by (app) (rate({env="prod"} | json | status >= 500 [5m]))

# 2.
max by (route) (quantile_over_time(0.99, {app="api"} | logfmt | unwrap duration_seconds(duration) [5m]))

# 3.
sum(count_over_time({app="api"} |= "error" [5m])) / sum(count_over_time({app="api"}[5m]))

# 4.
{app="api", level!="debug"} | json | line_format "{{.method}} {{.path}} {{.status}}"

Two endpoints, two parameter sets

Loki's instant and range endpoints do not take the same parameters, and the ones that do not belong are either rejected or silently ignored — the worse of the two failure modes. The option types are split accordingly, and the store refuses a mismatch instead of sending it:

Parameter	Instant (/query)	Range (/query_range)
time	✅	✗ (not in the type)
start / end	✗	✅
since	✗	✅ (mutually exclusive with start)
limit	✅	✅
direction	✅	✅
step	✗	✅ metric queries only
interval	✗	✅ log queries only

step sets the resolution of a returned matrix, so passing it with a log query is refused. interval thins out returned log entries, so passing it with a metric query is refused. Passing start and since is refused too: Loki ignores since when start is set, which hides which window was actually queried.

Two result shapes

The response shape follows the query, not the endpoint:

Query	resultType	Type
log query, either endpoint	streams	{ stream: Record<string,string>; values: [ts, line][] }[]
metric query, range	matrix	{ metric: …; values: [number, string][] }[]
metric query, instant	vector	{ metric: …; value: [number, string] }[]

Each method is typed for the shape it expects and verifies the resultType it actually received, throwing a DatabaseError on a mismatch rather than handing back a value under a type that is a lie. Passing a metric expression to queryLogsRange() is refused up front, naming queryMetricRange() as the method to use.

Escaping is the whole safety story

A LogQL query travels to Loki as one query= HTTP parameter. There is no wire-level parameter binding — the same situation as the SPARQL dialect, and the reason logql.ts is the only place in this layer where a JavaScript value becomes query text.

The two string forms, and which is emitted where

LogQL has two string literals with different rules, and this compiler uses both on purpose:

Position	Form emitted	Why
Label values (=, !=), line filter text (`	=, !=), ip()arguments,json/logfmtexpressions,pattern, line_format/label_formattemplates,label_replace`'s label and replacement arguments	double-quoted "…"
Every regular expression: =~, !~ (selector and label filter), |~, !~ (line filter), | regexp, label_replace's pattern, drop/keep matchers	backtick-quoted `…`	A raw string: no escape sequences exist inside it at all. \d+ reaches RE2 as \d+ rather than needing \\d+, so there is no double-escaping bug to have.

The cost of the raw form is that a backtick has no representation inside one. A pattern containing a backtick is therefore refused, not re-quoted into the double-quoted form — re-quoting would silently change what every other backslash in the pattern means. Write a literal backtick as \x60 in the pattern; a raw string passes that straight through to RE2.

Validated, not escaped

Identifiers have no quoted form in the LogQL this compiler emits, so they are validated and refused:

• Label names — stream selector labels, label filter labels, by/without groupings, drop/keep/unwrap targets, json/logfmt expression names, label_format source and destination, template { label } parts, and the label_replace label arguments (quoted, but still validated). Must match [a-zA-Z_][a-zA-Z0-9_]*.
• Durations ([5m], offset 1h, | latency > 1s, step, since, interval) — whole-number magnitudes with units ns us ms s m h d w y. Fractional durations are refused because Loki's two duration parsers disagree about them.
• Byte sizes (| size > 20MB) — a number plus one of B kB KiB MB MiB GB GiB TB TiB PB PiB EB EiB.
• Numbers — must be finite; exponent notation is refused.

Nothing here is rewritten. safeIdent() elsewhere in this repo turns my-label into my_label, which is right for a generated Cypher variable and wrong here: my_label is a different Loki label, so the query would silently read the wrong stream. Loki 3.0 can quote label names inside a stream selector; this compiler does not emit that form, because it would fail against an older server.

Regular expressions

Loki runs Go's regexp (RE2), which has no backtracking, so classic catastrophic-backtracking ReDoS does not apply server-side — and this compiler never executes a caller's pattern itself. What remains is resource abuse and silent mis-parsing, handled structurally:

• a length cap (4096 characters by default, maxRegexLength to change it);
• RE2's own {n,m} repeat limit of 1000 — a{1001} is refused here rather than at query time;
• balanced-paren and terminated-class checks;
• an outright refusal, naming the construct, of the PCRE features RE2 does not implement: backreferences (\1), lookahead ((?=, (?!), lookbehind ((?<=, (?<!) and atomic groups ((?>).

The pattern is deliberately not compiled with JavaScript's RegExp. The two dialects disagree in both directions: (?P<name>…), which the | regexp parser requires, is a syntax error in JavaScript, while \1 and (?=…) are valid JavaScript and unsupported by RE2. Validating with RegExp would reject exactly the patterns Loki needs.

Coverage

Stream selectors

All four matcher operators, natively:

{ selector: { matchers: [
  { label: 'app',   op: '=',  value: 'api' },
  { label: 'env',   op: '=~', value: 'prod|staging' },
  { label: 'level', op: '!=', value: 'debug' },
  { label: 'host',  op: '!~', value: 'canary-.*' },
] } }
// → {app="api", env=~`prod|staging`, level!="debug", host!~`canary-.*`}

or through the ORM operator surface, folded by the same normalizeWhere() the graph, AQL and N1QL layers use — so there is no second, drifting copy of the operator table:

ORM operator	Compiles to	Note
field: 'v', Op.eq	field="v"
Op.ne	field!="v"
Op.regexp / Op.notRegexp	field=~… / `field!~`…
Op.in / Op.notIn	field=~(?:a|b)``	each value regex-escaped; selector regexes are anchored, so this is exact
Op.startsWith / endsWith / substring (+ not*)	field=~esc.*`` etc.	value regex-escaped
null / Op.isNull	field=""	in Loki, ="" matches streams where the label is not set
Op.isNotNull	field!=""

Everything else is refused by name: $or and $not (a selector is a flat conjunction with no alternation or negation), numeric comparisons (selector labels are indexed strings — parse the value out and filter it in the pipeline), and $like/$iLike (translating SQL wildcards would have to guess how an escaped % was meant; use regexp, or the escaped startsWith/endsWith/substring).

Pipeline stages

Stage	Spec	Compiles to
Line filter	{ stage: 'line', op: '|=' | '!=' | '|~' | '!~', value | regex | ip }	|= "error", |~ \level=\w+`, |= ip("10.0.0.0/8")`
Line filter or chain	or: [{ value }, …]	|= "a" or "b" — gated, Loki 3.0+
JSON	{ stage: 'json', expressions? }	| json, | json path="request.path"
logfmt	{ stage: 'logfmt', expressions?, strict?, keepEmpty? }	| logfmt, | logfmt lvl="level"; flags gated, Loki 3.0+
pattern	{ stage: 'pattern', pattern }	| pattern "<ip> - <_> <status>"
regexp	{ stage: 'regexp', regexp }	| regexp \(?P\w+)``
unpack	{ stage: 'unpack' }	| unpack
decolorize	{ stage: 'decolorize' }	| decolorize
distinct	{ stage: 'distinct', labels }	| distinct a, b — gated, Loki 3.x
Label filter	{ stage: 'labelFilter', filter }	| status >= 400 and level="error"
Label filter from where	{ stage: 'where', where }	same, via normalizeWhere()
line_format	{ stage: 'lineFormat', template | parts }	| line_format "{{.status}} {{.path}}"
label_format	{ stage: 'labelFormat', formats }	| label_format dst=src, other="{{.a}}"
drop / keep	{ stage: 'drop' | 'keep', labels }	| drop level, method="GET"

pattern is validated (at least one <capture>, no two adjacent captures) and regexp is required to contain a named capture group — both turn a Loki query-time error into a compile-time one.

Templates. line_format and label_format take Go templates, the one place LogQL would otherwise still demand a hand-written string. parts covers the common case structurally:

{ stage: 'lineFormat', parts: [{ label: 'status' }, { text: ' -> ' }, { label: 'path' }] }
// → | line_format "{{.status}} -> {{.path}}"

Literal {{ in a { text } part is emitted as {{"{{"}}, so caller text can never become template code. template stays available for {{ if … }}, the __timestamp__ builtins and sprig functions; it is escaped as a string but its contents are the caller's stated intent, exactly like a regex.

Label filters

LabelFilter is a small expression tree, because LogQL's label filters are one — unlike a stream selector, they nest:

{ kind: 'and', items: [
  { kind: 'number',   label: 'status',  op: '>=', value: 400 },
  { kind: 'or', items: [
    { kind: 'string', label: 'level',   op: '=',  value: 'error' },
    { kind: 'duration', label: 'latency', op: '>', value: '250ms' },
  ] },
] }
// → | (status >= 400 and (level = "error" or latency > 250ms))

Kinds: string, regex, number, duration, bytes, ip, and, or, and where (the ORM surface). Through where, $between becomes a bounded conjunction and $or works — the one place normalizeWhere()'s or survives. $not is refused: LogQL has no negation operator to wrap a group in.

Filtering parser errors is just a label filter on __error__:

{ stage: 'labelFilter', filter: { kind: 'string', label: '__error__', op: '=', value: '' } }

Metric queries

Log range aggregations — rate, count_over_time, bytes_rate, bytes_over_time, absent_over_time:

{ type: 'logRange', fn: 'rate', log: { selector, pipeline }, range: '5m', offset: '1h' }
// → rate({app="api"} |= "error" [5m] offset 1h)

Unwrapped range aggregations — rate, rate_counter, sum_over_time, avg_over_time, max_over_time, min_over_time, first_over_time, last_over_time, stdvar_over_time, stddev_over_time, quantile_over_time:

{
  type: 'unwrappedRange',
  fn: 'quantile_over_time',
  param: 0.99,
  log: { selector, pipeline: [{ stage: 'json' }] },
  unwrap: { label: 'latency', conversion: 'duration' },
  range: '5m',
  by: ['path'],
}
// → quantile_over_time(0.99, {app="api"} | json | unwrap duration(latency) [5m]) by (path)

unwrap.conversion is duration / duration_seconds / bytes; unwrap.filters appends post-unwrap label filters. Grouping is accepted only where Loki accepts it — everything except sum_over_time, absent_over_time, rate and rate_counter; asking for it elsewhere raises LogqlCapabilityError and suggests wrapping the result in a vector aggregation instead.

Vector aggregations — sum, avg, min, max, count, stddev, stdvar, topk, bottomk, plus the gated sort / sort_desc (3.0) and approx_topk (3.3). by / without are mutually exclusive; topk/bottomk require a positive whole param; sort/sort_desc take neither.

{ type: 'vectorAgg', op: 'topk', param: 10,
  expr: { type: 'vectorAgg', op: 'sum', by: ['pod'], expr: rate } }
// → topk(10, sum by (pod) (rate({app="api"}[5m])))

Binary operations — arithmetic + - * / % ^, comparison == != > >= < <= with the optional bool modifier, and logical and / or / unless, between two metric expressions or against a literal. Nested binary operands are parenthesized so precedence follows the spec tree the caller wrote, not the emitted text.

{ type: 'binary', op: '/', left: errorRate, right: totalRate }
// → sum(rate({app="api"} |= "error" [5m])) / sum(rate({app="api"}[5m]))

{ type: 'vector', value: 0 } gives vector(0) for … or vector(0) defaults, and label_replace is available with its regex raw-quoted and both label arguments validated.

Version gating

Where the compiler cannot be sure a construct exists in the server it is talking to, it refuses by name rather than emitting something unverified. Opt in per feature, on the compiler or on the store:

const store = new LokiStore({ baseURL, features: { lineFilterOr: true, logfmtFlags: true } });

Flag	Construct	Introduced
lineFilterOr	|= "a" or "b"	Loki 3.0
logfmtFlags	| logfmt --strict --keep-empty	Loki 3.0
sortVector	sort / sort_desc	Loki 3.0
distinct	| distinct a, b	Loki 3.x
approxTopk	approx_topk(k, v)	Loki 3.3

drop, keep and decolorize (Loki 2.9) are not gated — 2.9 predates every currently-supported release.

What is refused, and why

Feature	Reason
$or / $not in a stream selector	A selector is a flat conjunction of matchers; there is no alternation or negation to compile to.
Numeric comparison in a stream selector	Selector labels are indexed strings. Parse the value out (| json, | logfmt, | pattern) and compare it in a label filter.
$like / $iLike anywhere	LogQL has no LIKE, and translating one would have to guess how an escaped % or _ was meant. Use regexp, or the escaped startsWith / endsWith / substring.
$not in a label filter	LogQL combines label filters with and / or only — there is no group negation.
Ordered comparison against a non-numeric string	LogQL's > >= < <= only apply to numbers, durations and byte sizes.
Vector matching modifiers (on, ignoring, group_left, group_right)	Not offered: the compiler cannot verify their behaviour across Loki versions, and emitting an unverified modifier silently changes which series join.
The @ modifier	Not part of LogQL.
Quoted label names in a selector (Loki 3.0)	Would parse-error against an older server; an invalid label name is refused instead.
PromQL's quantile vector aggregation	Does not exist in LogQL — use quantile_over_time on an unwrapped range.
A backtick in a regular expression	The raw-string form has no escape for it. Use \x60 inside the pattern.
An empty stream selector	Loki refuses it; it would mean "every stream in the cluster".
An empty where on a label filter stage	It would emit a filter that matches everything. Drop the stage instead.

Each of these throws LogqlCapabilityError (a DatabaseError subclass carrying feature) or ValidationError, both naming what was refused and pointing at LokiStore.query() where a hand-written query is genuinely the answer.

Verification status

Unit / mock-verified only. The compiler tests are pure string comparisons — every construct asserts its exact compiled LogQL, and a hostile-input suite pushes a quote-breakout payload through every value-carrying position (label value, line filter, label filter, parser expression, pattern, template, drop matcher, label_replace replacement) and pins the whole output, plus a backtick-breakout attempt through every regex position and a quote-breakout attempt through every identifier position. The endpoint tests inject a mock LokiHttpClient and assert the path and query parameters.

There is no live Loki server in the test run. Query syntax is verified against Loki's documented LogQL grammar, not by execution.

Related reading

• LokiStore — the store, its connection options and its ingest/metadata methods
• SPARQL / RDF triplestores — the other language here with no wire-level parameter binding
• Couchbase (N1QL) — the compile-only-module precedent this follows
• Query operators — the Op.* surface normalizeWhere() folds