:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { type Matcher, type PromExpr, PromQLParseError, parsePromQL, unwrapParens } from './promqlParser'
import { printPromQL } from './promqlPrinter'
import { builderRegexToPromRegex } from './regex'
import {
type BuilderClause,
type BuilderQuery,
CLAUSE_LABEL,
type ConversionResult,
clauseAlias,
normalizeClause,
normalizeLabelKey,
} from './types'
const FILTER_OP_TO_MATCH_OP: Record<string, Matcher['op']> = {
eq: '=',
neq: '!=',
regex: '=~',
not_regex: '!~',
}
const SIMPLE_AGGREGATIONS = new Set(['sum', 'avg', 'min', 'max', 'count'])
interface ClauseExpr {
expr: PromExpr
/** Labels the clause groups by, sorted; used to pick vector matching in a formula. */
labels: string[]
}
function clauseToPromExpr(builderClause: BuilderClause, issues: string[]): ClauseExpr {
const clause = normalizeClause(builderClause)
const matchers: Matcher[] = []
for (const filter of clause.filters ?? []) {
if (filter.scope && filter.scope !== 'auto') {
issues.push(
`PromQL cannot limit "${filter.key}" to ${filter.scope} attributes in series ${clause.name}; the filter matches both.`
)
}
const op = FILTER_OP_TO_MATCH_OP[filter.op]
matchers.push({
label: normalizeLabelKey(filter.key),
op,
value: op === '=~' || op === '!~' ? builderRegexToPromRegex(filter.value) : filter.value,
})
}
for (const groupBy of clause.groupBy ?? []) {
if (groupBy.scope && groupBy.scope !== 'auto') {
issues.push(
`PromQL cannot limit the "${groupBy.key}" group-by to ${groupBy.scope} attributes in series ${clause.name}.`
)
}
}
// The pinned OTel type has no PromQL form. It is not reported: the picker sets it on every
// clause, and it only matters for the rare name that exists as more than one type.
const labels = [...new Set((clause.groupBy ?? []).map((groupBy) => normalizeLabelKey(groupBy.key)))]
const grouping = labels.length ? { without: false, labels } : undefined
const selector: PromExpr = { type: 'selector', name: clause.metricName, matchers }
// An omitted range uses the query step, which is how the builder computes per-bucket rates.
const series: PromExpr = clause.rangeFunction
? { type: 'call', func: clause.rangeFunction, args: [selector] }
: selector
let expr: PromExpr
switch (clause.aggregation) {
case undefined:
// Without an aggregation, each series is its own line.
expr = series
break
case 'quantile':
expr = {
type: 'aggregate',
op: 'quantile',
param: { type: 'number', value: clause.quantile ?? 0.95 },
expr: series,
...(grouping ? { grouping } : {}),
}
break
case 'histogram_quantile':
expr = {
type: 'call',
func: 'histogram_quantile',
args: [
{ type: 'number', value: clause.quantile ?? 0.95 },
{
type: 'aggregate',
op: 'sum',
grouping: { without: false, labels: ['le', ...labels.filter((label) => label !== 'le')] },
expr: {
type: 'call',
func: 'rate',
args: [{ ...selector, name: `${clause.metricName}_bucket` }],
},
},
],
}
break
default:
if (!SIMPLE_AGGREGATIONS.has(clause.aggregation)) {
issues.push(`PromQL has no "${clause.aggregation}" aggregation; series ${clause.name} uses sum.`)
}
expr = {
type: 'aggregate',
op: SIMPLE_AGGREGATIONS.has(clause.aggregation) ? clause.aggregation : 'sum',
expr: series,
...(grouping ? { grouping } : {}),
}
}
return { expr, labels: [...labels].sort() }
}
const sameLabels = (a: string[], b: string[]): boolean => a.length === b.length && a.every((label, i) => label === b[i])
/** Replaces the aliases in a parsed builder formula with clause expressions, adding vector matching. */
function substituteFormula(
node: PromExpr,
clauses: Map<string, ClauseExpr>,
used: Set<string>,
issues: string[]
): { expr: PromExpr; labels: string[] | null } {
switch (node.type) {
case 'number':
return { expr: node, labels: null }
case 'paren': {
const inner = substituteFormula(node.expr, clauses, used, issues)
return { expr: { type: 'paren', expr: inner.expr }, labels: inner.labels }
}
case 'unary': {
const inner = substituteFormula(node.expr, clauses, used, issues)
return { expr: { ...node, expr: inner.expr }, labels: inner.labels }
}
case 'selector': {
const clause = node.name !== null ? clauses.get(node.name) : undefined
if (!clause || node.matchers.length) {
throw new Error(`The formula refers to an unknown series "${node.name ?? ''}"`)
}
used.add(node.name as string)
return clause
}
case 'binary': {
const lhs = substituteFormula(node.lhs, clauses, used, issues)
const rhs = substituteFormula(node.rhs, clauses, used, issues)
const binary: PromExpr = { type: 'binary', op: node.op, lhs: lhs.expr, rhs: rhs.expr }
if (lhs.labels === null || rhs.labels === null) {
return { expr: binary, labels: lhs.labels ?? rhs.labels }
}
if (sameLabels(lhs.labels, rhs.labels)) {
return { expr: binary, labels: lhs.labels }
}
// The builder spreads an ungrouped series over every label set of the other side.
if (rhs.labels.length === 0) {
return {
expr: { ...binary, matching: { card: 'many-to-one', on: true, labels: [], include: [] } },
labels: lhs.labels,
}
}
if (lhs.labels.length === 0) {
return {
expr: { ...binary, matching: { card: 'one-to-many', on: true, labels: [], include: [] } },
labels: rhs.labels,
}
}
issues.push('The formula mixes series with different group-by labels.')
return { expr: binary, labels: lhs.labels }
}
default:
throw new Error('The formula has an unsupported term')
}
}
/**
* `histogram_quantiles("clause", 0.5, 0.9, buckets)` for series that are quantiles of the same buckets.
* Snuffle reads the buckets one time for this form; a union of `histogram_quantile` calls reads them
* once for each series, on a much slower path. The label holds the quantile, and the backend maps it
* back to the alias, so this form is only used when the aliases are the defaults a, b, c, ...
*/
function sharedHistogramQuantiles(clauses: BuilderClause[], exprs: Map<string, ClauseExpr>): PromExpr | null {
const quantiles: PromExpr[] = []
let buckets: PromExpr | null = null
for (const [index, clause] of clauses.entries()) {
const expr = exprs.get(clause.name)!.expr
if (clause.name !== clauseAlias(index) || expr.type !== 'call' || expr.func !== 'histogram_quantile') {
return null
}
const [quantile, clauseBuckets] = expr.args
if (quantile.type !== 'number' || quantiles.some((q) => q.type === 'number' && q.value === quantile.value)) {
return null
}
if (buckets && printPromQL(buckets) !== printPromQL(clauseBuckets)) {
return null
}
buckets = clauseBuckets
quantiles.push(quantile)
}
return (
buckets && {
type: 'call',
func: 'histogram_quantiles',
args: [{ type: 'string', value: CLAUSE_LABEL }, ...quantiles, buckets],
}
)
}
export function builderToPromql(query: BuilderQuery): ConversionResult<string> {
const issues: string[] = []
const clauses = query.clauses.filter((clause) => clause.metricName.trim())
if (clauses.length === 0) {
return { value: '', issues }
}
const exprs = new Map(clauses.map((clause) => [clause.name, clauseToPromExpr(clause, issues)]))
const formula = query.formula?.trim()
if (formula) {
let parsed: PromExpr
try {
parsed = parsePromQL(formula)
} catch (error) {
const message = error instanceof PromQLParseError ? error.message : String(error)
return { value: null, issues: [`The formula "${formula}" cannot be read: ${message}`] }
}
const used = new Set<string>()
try {
const result = substituteFormula(parsed, exprs, used, issues)
const unused = clauses.filter((clause) => !used.has(clause.name)).map((clause) => clause.name)
if (unused.length) {
issues.push(
`Series ${unused.join(', ')} ${unused.length > 1 ? 'are' : 'is'} not in the formula and will be removed.`
)
}
return { value: printPromQL(unwrapParens(result.expr)), issues }
} catch (error) {
return { value: null, issues: [error instanceof Error ? error.message : String(error)] }
}
}
if (clauses.length === 1) {
return { value: printPromQL(exprs.get(clauses[0].name)!.expr), issues }
}
const shared = sharedHistogramQuantiles(clauses, exprs)
if (shared) {
return { value: printPromQL(shared), issues }
}
// Several series without a formula: label each one with its alias, so the union keeps them apart.
const labelled: PromExpr[] = clauses.map((clause) => ({
type: 'call',
func: 'label_replace',
args: [
exprs.get(clause.name)!.expr,
{ type: 'string', value: CLAUSE_LABEL },
{ type: 'string', value: clause.name },
{ type: 'string', value: '' },
{ type: 'string', value: '' },
],
}))
const union = labelled.reduce((lhs, rhs) => ({ type: 'binary', op: 'or', lhs, rhs }))
return { value: printPromQL(union), issues }
}