compile

Documentation

Overview

Package compile holds the cross-backend types used by Prism's compile stage: the Backend interface alias, the friendly aggregate alias map, and the expression-passthrough shim that wraps expr-lang/expr exactly the way Pulse's processing/filterer.go does.

The in-memory implementation lives at compile/inmem; future Pulse / Arrow / DuckDB backends drop into the same Backend interface without touching plan/.

Index

• Variables
• func AllAliases() []string
• func PulseBackedAliases() []string
• type AggregateMapping
  • func (m AggregateMapping) IsDeferredFromPulse() bool
• type Backend
• type ExprProgram
  • func CompileExpression(src string) (*ExprProgram, error)
  • func (p *ExprProgram) Eval(env map[string]any) (any, error)
  • func (p *ExprProgram) EvalBool(env map[string]any) (bool, error)
  • func (p *ExprProgram) EvalFloat(env map[string]any) (float64, error)
  • func (p *ExprProgram) Source() string

Variables

var AliasToPulse = map[string]AggregateMapping{
	"count":    {Alias: "count", Type: types.AGG_COUNT},
	"sum":      {Alias: "sum", Type: types.AGG_SUM},
	"mean":     {Alias: "mean", Type: types.AGG_AVERAGE},
	"median":   {Alias: "median", Type: types.AGG_MEDIAN},
	"min":      {Alias: "min", Type: types.AGG_MIN},
	"max":      {Alias: "max", Type: types.AGG_MAX},
	"stdev":    {Alias: "stdev", Type: types.AGG_STDDEV},
	"variance": {Alias: "variance", Type: types.AGG_VARIANCE},
	"mode":     {Alias: "mode", Type: types.AGG_MODE},
	"distinct": {Alias: "distinct", Type: types.AGG_DISTINCT_COUNT},
	"q1":       {Alias: "q1", Type: types.AGG_PERCENTILE, Params: []byte(`{"percentile":25}`)},
	"q3":       {Alias: "q3", Type: types.AGG_PERCENTILE, Params: []byte(`{"percentile":75}`)},

	"ci0":   {Alias: "ci0", Type: types.AGG_CI_LOWER},
	"ci1":   {Alias: "ci1", Type: types.AGG_CI_UPPER},
	"wmean": {Alias: "wmean", Type: types.AGG_WEIGHTED_MEAN},
	"ratio": {Alias: "ratio", Type: types.AGG_RATIO},

	"lift":  {Alias: "lift"},
	"share": {Alias: "share"},
}

AliasToPulse is the single source of truth for friendly aggregate alias resolution. Mirrors validate/rules/agg_compat.go's quantitative-op list verbatim — adding a new alias requires editing both (a TODO in agg_compat.go points here).

Pulse v0.10.0 promoted `wmean`, `ratio`, `ci0`, `ci1` from inmem-only to first-class AGG_* constants. `lift` and `share` remain deferred until Pulse upstreams them.

Functions

func AllAliases

func AllAliases() []string

AllAliases returns the alias names in sorted order. Stable order matters for the enumeration test and for fixup messages.

func PulseBackedAliases

func PulseBackedAliases() []string

PulseBackedAliases returns the subset of aliases whose Type is non-empty (i.e. the parity-test eligible set). Useful for tests that compare Prism output to pulse.Process output.

Types

type AggregateMapping

type AggregateMapping struct {
	// Alias is the friendly spec-level name (`mean`, `sum`, …).
	Alias string
	// Type is the Pulse AggregationType constant; "" when no Pulse
	// equivalent exists in the pinned facade version.
	Type types.AggregationType
	// Params is the JSON-encoded params blob Pulse expects when the
	// alias resolves to a parameterised aggregator and the params are
	// statically derivable from the alias (e.g. `q1` always means
	// percentile=25). Aliases whose params depend on the per-call
	// AggOp (e.g. wmean's weight_field, ratio's numerator_field /
	// denominator_field) leave this nil — callers synthesize Params
	// from the AggOp at request-build time, using the documented
	// sibling-column conventions.
	Params []byte
}

AggregateMapping resolves a Prism alias to its Pulse counterpart (Type) plus any required params. When Type == "" the alias has no Pulse equivalent in the pinned facade version — the in-memory backend implements these (`lift`, `share` as of v0.10.0). See D034.

func (AggregateMapping) IsDeferredFromPulse

func (m AggregateMapping) IsDeferredFromPulse() bool

IsDeferredFromPulse reports whether this alias has no Pulse equivalent in the pinned facade version and so must be executed client-side by the in-memory backend.

type Backend

type Backend = plan.Backend

Backend is re-exported from plan/ so consumers can address it via `compile.Backend` (the natural import for compile-stage callers). See plan/backend.go for the canonical definition.

type ExprProgram

type ExprProgram struct {
	// contains filtered or unexported fields
}

ExprProgram wraps a compiled expr-lang program plus the original source for diagnostics. Use CompileExpression to build one.

func CompileExpression

func CompileExpression(src string) (*ExprProgram, error)

CompileExpression parses src via expr-lang/expr (the same parser Pulse uses internally; see D022) and returns a runnable program. Compile errors wrap as PRISM_COMPILE_002 so the executor surfaces them consistently with runtime errors.

func (*ExprProgram) Eval

func (p *ExprProgram) Eval(env map[string]any) (any, error)

Eval evaluates the program against env and returns the raw result. Runtime errors wrap as PRISM_COMPILE_002 with the env's row-index context (when supplied by the caller as env["__row__"]).

func (*ExprProgram) EvalBool

func (p *ExprProgram) EvalBool(env map[string]any) (bool, error)

EvalBool evaluates the program and coerces the result to bool. Used by Filter. Non-bool results error out as PRISM_COMPILE_002.

func (*ExprProgram) EvalFloat

func (p *ExprProgram) EvalFloat(env map[string]any) (float64, error)

EvalFloat evaluates the program and coerces the result to float64. Used by Calculate. int / int64 / float32 are promoted; everything else errors out as PRISM_COMPILE_002.

func (*ExprProgram) Source

func (p *ExprProgram) Source() string

Source returns the original expression string. Useful for error context where the program was compiled in one place and evaluated in another.