promql

Documentation

Overview

Package promql is Coremetry's PromQL query engine (v0.9.111+) — a real lexer + recursive-descent parser + AST that compiles down to the existing chstore metric machinery (QueryMetric / QueryMetricRate / QueryMetricHistogramPercentile — the F1-F3 work). One industry-standard query surface so operators can paste the same PromQL they run in Grafana.

Architecture (approved 2026-07-20 — "hybrid model"):

• LEAF fetches (vector/matrix selectors, rate/increase/histogram_quantile) push down to ClickHouse via the existing bounded chstore methods (LIMIT + max_execution_time + time-bounded WHERE, distributed-safe).
• SERIES-OVER-SERIES ops (aggregations, binary operators) evaluate in Go over the already-bounded fetched series — Prometheus's own model.

Phase 1 (this file + lex.go + parse.go): lexer + parser + AST ONLY. No evaluator yet — the parser is shippable + testable on its own (golden ASTs). Grammar mirrors Prometheus; the eval (eval.go, Phase 2+) reuses F1-F3.

PERFORMANCE IS A HARD CONSTRAINT (operator, 2026-07-20). The AST carries no execution cost; the guards live in the evaluator (series-count caps, reuse of the bounded leaf fetches, complexity limits). This file only shapes the tree — but it is designed so the evaluator can cheaply reject a too-broad query (e.g. a bare `{__name__=~".+"}` with no name) before any CH round trip.

Index

• func Eval(ctx context.Context, store MetricStore, expr Expr, opt EvalOptions) ([]chstore.SpanMetricSeries, error)
• func EvalString(ctx context.Context, store MetricStore, query string, opt EvalOptions) ([]chstore.SpanMetricSeries, error)
• func ParseDuration(s string) (time.Duration, error)
• type AggregateExpr
  • func (a *AggregateExpr) String() string
• type BinaryExpr
  • func (be *BinaryExpr) String() string
• type Call
  • func (c *Call) String() string
• type EvalOptions
• type Expr
  • func Parse(input string) (Expr, error)
• type LabelMatcher
  • func (lm *LabelMatcher) String() string
• type MatchType
  • func (m MatchType) String() string
• type MatrixSelector
  • func (m *MatrixSelector) String() string
• type MetricStore
• type NumberLiteral
  • func (n *NumberLiteral) String() string
• type ParenExpr
  • func (p *ParenExpr) String() string
• type StringLiteral
  • func (s *StringLiteral) String() string
• type SubqueryExpr
  • func (s *SubqueryExpr) String() string
• type UnaryExpr
  • func (u *UnaryExpr) String() string
• type ValueType
• type VectorMatchCardinality
• type VectorMatching
• type VectorSelector
  • func (v *VectorSelector) String() string

Functions

func Eval

func Eval(ctx context.Context, store MetricStore, expr Expr, opt EvalOptions) ([]chstore.SpanMetricSeries, error)

Eval compiles + runs a parsed PromQL expression as a RANGE query, returning time series. Enforces the depth/leaf/series caps.

func EvalString

func EvalString(ctx context.Context, store MetricStore, query string, opt EvalOptions) ([]chstore.SpanMetricSeries, error)

EvalString parses + evaluates in one call (the API entry point).

func ParseDuration

func ParseDuration(s string) (time.Duration, error)

ParseDuration parses a PromQL duration ("5m", "1h30m", "500ms"). Exported so the evaluator + API can reuse it. Weeks/years use fixed 7d / 365d.

Types

type AggregateExpr

type AggregateExpr struct {
	Op       string // sum, avg, min, max, count, stddev, stdvar, quantile, topk, bottomk, count_values, group
	Expr     Expr   // the vector being aggregated
	Param    Expr   // topk/bottomk/quantile/count_values scalar/string param; nil otherwise
	Grouping []string
	Without  bool // `without(…)` vs `by(…)`
}

AggregateExpr: `sum by (le) (rate(x[5m]))`, `topk(5, x)`.

func (*AggregateExpr) String

func (a *AggregateExpr) String() string

type BinaryExpr

type BinaryExpr struct {
	Op             string // + - * / % ^ == != > >= < <= and or unless
	LHS, RHS       Expr
	VectorMatching *VectorMatching // nil for scalar/scalar
	ReturnBool     bool            // `> bool 0.5` — comparison yields 0/1 instead of filtering
}

BinaryExpr: `a / b`, `rate(x) > 0.5`.

func (*BinaryExpr) String

func (be *BinaryExpr) String() string

type Call

type Call struct {
	Func string
	Args []Expr
}

Call is a function application: `rate(x[5m])`, `histogram_quantile(0.95, x)`.

func (*Call) String

func (c *Call) String() string

type EvalOptions

type EvalOptions struct {
	FromNs        int64 // range start (unix ns)
	ToNs          int64 // range end (unix ns)
	Step          int   // bucket seconds; 0 = width-aware auto (via MaxDataPoints)
	MaxDataPoints int   // panel px width ≈ target bucket count (F1)
	MaxSeries     int   // reject a result exceeding this many series (default 1000)
	MaxLeaves     int   // reject a query with more than this many selectors (default 25)
	MaxDepth      int   // reject an AST deeper than this (default 40)
}

EvalOptions bounds one evaluation. Zero values get safe defaults.

type Expr

type Expr interface {

	// String renders the node back to canonical PromQL — used by the API to
	// echo the normalized query (transparency, like DQL's equivalent-SQL).
	String() string
	// contains filtered or unexported methods
}

Expr is any node in a parsed PromQL expression tree.

func Parse

func Parse(input string) (Expr, error)

Parse turns a PromQL string into an AST. Returns a positioned error on syntax failure so the API can underline the offending token.

type LabelMatcher

type LabelMatcher struct {
	Name  string
	Type  MatchType
	Value string
}

LabelMatcher is one `label OP "value"` predicate inside `{…}`. The special label __name__ carries the metric name when written inside the braces.

func (*LabelMatcher) String

func (lm *LabelMatcher) String() string

type MatchType

type MatchType int

MatchType is a label-matcher operator.

const (
	MatchEqual     MatchType = iota // =
	MatchNotEqual                   // !=
	MatchRegexp                     // =~
	MatchNotRegexp                  // !~
)

func (MatchType) String

func (m MatchType) String() string

type MatrixSelector

type MatrixSelector struct {
	VectorSelector *VectorSelector
	Range          time.Duration
}

MatrixSelector wraps a VectorSelector with a range: `metric[5m]`. It is the argument to range functions (rate, increase, delta …).

func (*MatrixSelector) String

func (m *MatrixSelector) String() string

type MetricStore

type MetricStore interface {
	QueryMetric(ctx context.Context, f chstore.MetricQueryFilter) ([]chstore.SpanMetricSeries, error)
	QueryMetricRate(ctx context.Context, f chstore.MetricQueryFilter, mode string) ([]chstore.SpanMetricSeries, error)
	QueryMetricHistogramQuantile(ctx context.Context, f chstore.MetricQueryFilter, q float64) ([]chstore.SpanMetricSeries, error)
	// MetricAttrKeys discovers a metric's datapoint attribute keys — needed for
	// without(L) grouping (v0.9.124).
	MetricAttrKeys(ctx context.Context, metric, service string, since time.Duration) ([]string, error)
}

MetricStore is the subset of *chstore.Store the evaluator needs — an interface so eval is unit-testable with a fake. *chstore.Store satisfies it.

type NumberLiteral

type NumberLiteral struct{ Val float64 }

NumberLiteral is a scalar constant.

func (*NumberLiteral) String

func (n *NumberLiteral) String() string

type ParenExpr

type ParenExpr struct{ Expr Expr }

ParenExpr preserves an explicit `(…)` grouping in the tree (and re-render).

func (*ParenExpr) String

func (p *ParenExpr) String() string

type StringLiteral

type StringLiteral struct{ Val string }

StringLiteral — the string arg to label_replace / label_join / count_values.

func (*StringLiteral) String

func (s *StringLiteral) String() string

type SubqueryExpr

type SubqueryExpr struct {
	Expr    Expr
	Range   time.Duration
	Step    time.Duration // 0 = default resolution
	Offset  time.Duration
	At      *float64
	AtStart bool
	AtEnd   bool
}

SubqueryExpr: `expr[range:step]` — an instant expr sampled over a range. Parsed in Phase 1; the evaluator support lands with the range machinery.

func (*SubqueryExpr) String

func (s *SubqueryExpr) String() string

type UnaryExpr

type UnaryExpr struct {
	Op   string // "-" or "+"
	Expr Expr
}

UnaryExpr: `-x`.

func (*UnaryExpr) String

func (u *UnaryExpr) String() string

type ValueType

type ValueType string

ValueType is the PromQL value kind an expression evaluates to. The parser tags a few nodes; the evaluator uses it for type checks (e.g. the first arg of histogram_quantile is a scalar, the second a vector).

const (
	ValueTypeNone   ValueType = "none"
	ValueTypeScalar ValueType = "scalar"
	ValueTypeVector ValueType = "vector"
	ValueTypeMatrix ValueType = "matrix"
	ValueTypeString ValueType = "string"
)

type VectorMatchCardinality

type VectorMatchCardinality int

const (
	CardOneToOne VectorMatchCardinality = iota
	CardManyToOne
	CardOneToMany
)

type VectorMatching

type VectorMatching struct {
	Card           VectorMatchCardinality
	MatchingLabels []string
	On             bool     // true = on(…), false = ignoring(…)
	Include        []string // group_left(…) / group_right(…) extra labels
}

VectorMatching describes how a binary op lines up two vectors.

type VectorSelector

type VectorSelector struct {
	Name     string
	Matchers []*LabelMatcher
	Offset   time.Duration // `offset 5m` — shifts the window back
	At       *float64      // `@ 1609746000` (unix seconds) — pins the eval time
	AtStart  bool          // `@ start()`
	AtEnd    bool          // `@ end()`
}

VectorSelector selects a set of series: `metric_name{matchers}`. Name may be empty when the metric is given via a __name__ matcher inside the braces.

func (*VectorSelector) String

func (v *VectorSelector) String() string