dql

Documentation

Overview

Package dql is Coremetry's unified query language (v0.5.265) — a Kusto/Dynatrace-DQL-flavoured pipe shape that compiles down to the existing chstore aggregations. One syntax across spans / metrics, no per-signal context switch.

MVP grammar:

query   := table ('|' pipe)*
table   := "spans" | "metrics"
pipe    := "filter" predicate
         | "summarize" agg ("by" group)?
predicate := ident op value
op      := "==" | "!=" | "contains" | "startswith" | "endswith"
agg     := "count()"
         | "rate()"
         | "error_rate()"
         | ("p50" | "p95" | "p99" | "avg" | "max" | "min") "(" ident ")"
group   := "bin(time," duration ")"  (optional — defaults to auto)
value   := quoted-string | number
duration := <int> ("s"|"m"|"h"|"d")

Logs (KQL-backed) deferred to Phase 2 — the parser knows the table name but the executor errors with a clear message.

Design notes:

• Parser is a hand-rolled token stream — ~250 lines, no external dep, no codegen. The grammar is small enough that a parser-generator would be more weight than it's worth.
• Compile() returns a structured Plan that the API layer dispatches to existing chstore methods. Keeps the execution paths uniform with /metrics and /explore so a DQL query and a UI-built query hit the SAME cache + the SAME CH MV when applicable.
• The plan exposes the equivalent SQL the executor will run so /admin/query can surface it in the UI for transparency + audit.

Index

• type Plan
  • func Compile(q string) (*Plan, error)
  • func (p *Plan) SQLPreview(from, to time.Time) string
• type Table

Types

type Plan

type Plan struct {
	Table       Table
	Filters     []chstore.FilterExpr // AND-joined predicates (target side, post-join)
	Aggregation string               // count, rate, error_rate, p50/p95/p99/avg/max/min
	Field       string               // empty for count/rate/error_rate; the column for quantile/avg
	MetricName  string               // metrics-table-only — the metric being queried
	StepSeconds int                  // 0 = auto-pick from window width
	// GroupBy — attribute keys to split the series by (Kusto-style
	// `summarize count() by service.name`). Each group becomes a
	// distinct line in the result series. bin(time, N) is handled
	// separately via StepSeconds; the GroupBy list excludes it.
	GroupBy []string

	// JoinTarget (v0.5.271) — when set, the query is a
	// cross-signal join. The flow becomes:
	//
	//   1. Run a trace_id discovery query against `Table` with
	//      `SourceFilters` (the filters that appear BEFORE the
	//      `join` operator).
	//   2. Re-query `JoinTarget` with `Filters` (the AFTER
	//      filters) + WHERE trace_id IN (discovered set).
	//   3. Aggregate the target rows.
	//
	// The join key is fixed at "trace.id" for the MVP — the
	// only cross-signal key OTel actually carries everywhere.
	JoinTarget    Table
	JoinKey       string               // defaults to "trace.id"
	SourceFilters []chstore.FilterExpr // pre-join filters on Table
}

Plan is the structured form of a parsed query. The API dispatcher reads this and calls the matching chstore method.

func Compile

func Compile(q string) (*Plan, error)

Compile parses a DQL string into a Plan. Returns a wrapped parse error with the column number on syntax failure so the /admin/query UI can underline the offending token.

func (*Plan) SQLPreview

func (p *Plan) SQLPreview(from, to time.Time) string

SQLPreview returns a representative ClickHouse query string for the Plan — strictly for the operator-visible "show the SQL" affordance in /admin/query. The actual execution runs through the typed chstore methods (which build parameterised queries); this preview is illustrative, not executed.

type Table

type Table string

Table — the OTel signal kind a query operates on.

const (
	TableSpans   Table = "spans"
	TableMetrics Table = "metrics"
	TableLogs    Table = "logs"
)