expr

package
v0.1.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 25, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package expr defines the golars expression AST.

Expressions are immutable values. Users build them through package-level constructors and fluent methods: 

expr.Col("price").Mul(expr.Col("qty")).Alias("revenue")
expr.Col("x").GtLit(int64(10)).And(expr.Col("y").IsNotNull())

Expressions describe a computation on a DataFrame. They are executed either eagerly through Eval or indirectly through the lazy planner. The same AST drives both paths.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Columns 

func Columns(e Expr) []string

Columns returns the set of distinct column names referenced by e. OverNode partition keys count as references even though they don't appear as ColNode children.

func ContainsAgg 

func ContainsAgg(e Expr) bool

ContainsAgg reports whether e contains an AggNode anywhere in its subtree.

func Equal 

func Equal(a, b Expr) bool

Equal reports whether two expressions are structurally identical.

func OutputName 

func OutputName(e Expr) string

OutputName returns the inferred name of the expression's output column. An Alias defines the name explicitly; otherwise the first referenced column name is used (mirroring polars).

func Walk 

func Walk(e Expr, fn func(Expr) bool)

Walk visits every sub-expression depth-first. Returning false from fn prunes the subtree.

Types

type AggNode 

type AggNode struct {
	Op    AggOp
	Inner Expr
}

AggNode aggregates an expression to a single scalar or one value per group.

func (AggNode) String 

func (a AggNode) String() string

type AggOp 

type AggOp uint8

AggOp names an aggregation. 

const (
	AggSum AggOp = iota
	AggMin
	AggMax
	AggMean
	AggCount
	AggNullCount
	AggFirst
	AggLast
)

func (AggOp) String 

func (o AggOp) String() string

String returns the polars-style short name for the aggregation.

type AliasNode 

type AliasNode struct {
	Inner Expr
	Name  string
}

AliasNode attaches a name to an expression.

func (AliasNode) String 

func (a AliasNode) String() string

type BinaryNode 

type BinaryNode struct {
	Op    BinaryOp
	Left  Expr
	Right Expr
}

BinaryNode combines two sub-expressions with an operator.

func (BinaryNode) String 

func (b BinaryNode) String() string

type BinaryOp 

type BinaryOp uint8

BinaryOp is the set of binary operators the AST carries. 

const (
	OpAdd BinaryOp = iota
	OpSub
	OpMul
	OpDiv
	OpEq
	OpNe
	OpLt
	OpLe
	OpGt
	OpGe
	OpAnd
	OpOr
)

type CastNode 

type CastNode struct {
	Inner Expr
	To    dtype.DType
}

CastNode coerces an expression to a target dtype.

func (CastNode) String 

func (c CastNode) String() string

type ColNode 

type ColNode struct{ Name string }

ColNode is a reference to a named column.

func (ColNode) String 

func (c ColNode) String() string

type Expr 

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

Expr is the public expression value. It wraps an internal Node and carries fluent builder methods.

func All 

func All(preds ...Expr) Expr

func Any 

func Any(preds ...Expr) Expr

func Children 

func Children(e Expr) []Expr

Children returns the direct sub-expressions of e, in a stable order.

func Coalesce 

func Coalesce(exprs ...Expr) Expr

Coalesce returns the first non-null value across the given expressions at each row. Mirrors polars' pl.coalesce(...).

func Col 

func Col(name string) Expr

Col returns an expression that references a column by name.

The name is resolved at execution time against the frame's schema, so a typo or missing column surfaces when the lazy plan runs, not when the expression is built. Col is the starting point of almost every expression: arithmetic, predicates, string methods, aggregates, and window functions all chain off of it.

Parameters

  • name: column name in the frame under evaluation.

Returns

An Expr that, at eval time, produces the referenced column.

Examples

Build a predicate from a column: 

expr.Col("age").Gt(expr.LitInt64(18))

Project and alias: 

expr.Col("salary").Mul(expr.LitFloat64(12)).Alias("annual")

Use in a full pipeline: 

df.Lazy().
    Filter(expr.Col("salary").Gt(expr.LitInt64(100_000))).
    GroupBy("dept").
    Agg(expr.Col("salary").Mean().Alias("avg"))

func ConcatStr 

func ConcatStr(sep string, exprs ...Expr) Expr

ConcatStr concatenates the string representations of each expr row-wise, using sep as the delimiter. Nulls in any input propagate to the output (strictest polars behaviour). Mirrors pl.concat_str(..., separator=sep).

func IntRange 

func IntRange(start, end, step int64) Expr

IntRange returns a new int64 Series of [start, end) with the given step. Produces a length-mismatched column which callers typically wrap in pl.int_range(...).alias("idx"). step may not be zero.

func Lit 

func Lit(v any) Expr

Lit is a type-inferring literal constructor.

The Go type of v decides the dtype: `int` / `int32` / `int64` become i64, `float32` / `float64` become f64, plus `bool`, `string`, and `nil` (typed null). Anything else panics, so reach for LitInt64 / LitFloat64 / LitString when the exact dtype matters for a mixed-type comparison.

Parameters

  • v: Go scalar value; see above for supported types.

Returns

An Expr producing the literal when evaluated.

Examples

Scalar literals inline: 

expr.Col("qty").Mul(expr.Lit(2))           // int inferred as i64
expr.Col("tag").Eq(expr.Lit("priority"))   // string literal
expr.Lit(nil)                              // typed null

Prefer a typed constructor when the RHS dtype matters: 

expr.Col("score_f64").Gt(expr.LitFloat64(80)) // f64 != i64(80)

func LitBool 

func LitBool(v bool) Expr

LitBool returns a typed bool scalar literal.

func LitFloat64 

func LitFloat64(v float64) Expr

LitFloat64 returns a typed float64 scalar literal. See LitInt64 for when to prefer this over Lit.

func LitInt64 

func LitInt64(v int64) Expr

LitInt64 returns a typed int64 scalar literal.

Use Lit for Go-idiomatic type inference; reach for LitInt64 directly when you need to pin the dtype (e.g. comparing against an i64 column where the Go source would otherwise infer int).

Example: 

expr.Col("score").Gt(expr.LitInt64(80))

func LitNull 

func LitNull(dt dtype.DType) Expr

LitNull returns a null literal carrying dt as its declared dtype. Useful inside When / Coalesce where the branches must agree on a concrete type.

Example: 

expr.Coalesce(expr.Col("primary"), expr.LitNull(dtype.String()))

func LitOf 

func LitOf[T Scalar](v T) Expr

LitOf is a type-safe variant of Lit. The literal's Go type must be one of the supported scalar types; non-scalar values fail at build time rather than panicking at evaluation. 

expr.LitOf(int64(2))   // or expr.LitOf[int64](2)
expr.LitOf("USD")      // T inferred as string

func LitString 

func LitString(v string) Expr

LitString returns a typed utf8 scalar literal.

func Not 

func Not(e Expr) Expr

Not, All, Any are top-level helpers that read well in predicate chains: 

expr.All(a.Gt(0), b.Lt(10), c.IsNotNull())
expr.Any(a.IsNull(), b.Eq(0))
expr.Not(a.Eq("x"))

Not is a thin passthrough; All / Any fold a variadic list into And / Or chains.

func Ones 

func Ones(n int) Expr

Ones returns a fresh float64 Series of length n filled with 1.0.

func WithChildren 

func WithChildren(e Expr, children []Expr) Expr

WithChildren constructs a new expression with the given children replacing the originals. Panics if len(children) does not match the expected arity of the node.

func Zeros 

func Zeros(n int) Expr

Zeros returns a fresh float64 Series of length n filled with 0.0.

func (Expr) Abs 

func (e Expr) Abs() Expr

Abs returns |e|, preserving integer dtypes and promoting nothing.

func (Expr) Add 

func (e Expr) Add(other Expr) Expr

Add returns `e + other`, computed element-wise.

Null propagation: if either operand is null at a row, the result is null. Numeric dtype promotion mirrors polars (i64 + f64 → f64).

Parameters

  • other: right-hand side Expr; must be numeric.

Returns

An Expr producing the sum.

Examples 

// Two columns:
expr.Col("base").Add(expr.Col("bonus"))

// Column + scalar:
expr.Col("price").Add(expr.LitFloat64(1.0))

See also Expr.AddLit for scalar RHS, Expr.Sub, Expr.Mul, Expr.Div.

func (Expr) AddLit 

func (e Expr) AddLit(v any) Expr

AddLit is sugar for e.Add(Lit(v)). Use it when the RHS is a plain Go value so you don't have to write the constructor twice.

func (Expr) Alias 

func (e Expr) Alias(name string) Expr

Alias renames the expression's output column.

The renamed expression is still a valid right-hand side for another op, so aliases can chain. Repeated Alias calls collapse: `e.Alias("a").Alias("b")` is equivalent to `e.Alias("b")`.

Parameters

  • name: new column name for the result.

Returns

An Expr that renames this one's output.

Examples 

// Derive a yearly salary column:
expr.Col("salary").Mul(expr.LitFloat64(12)).Alias("annual")

// Assign a human-friendly name to a predicate:
expr.Col("age").Ge(expr.LitInt64(18)).Alias("adult")

func (Expr) All 

func (e Expr) All() Expr

All returns true if every non-null value is truthy (vacuous true on empty).

func (Expr) And 

func (e Expr) And(other Expr) Expr

And returns the element-wise logical AND of two boolean expressions. Null in either operand yields null.

Parameters

  • other: boolean Expr.

Returns

A boolean Expr.

Examples 

expr.Col("age").Ge(expr.LitInt64(18)).And(
    expr.Col("active").Eq(expr.LitBool(true)),
)

See also Expr.Or, Expr.Not.

func (Expr) Any 

func (e Expr) Any() Expr

Any returns true if any non-null value is truthy.

func (Expr) ApproxNUnique 

func (e Expr) ApproxNUnique() Expr

ApproxNUnique estimates the number of distinct values using HLL.

func (Expr) Arccos 

func (e Expr) Arccos() Expr

Arccos / Arcsin / Arctan: inverse trig.

func (Expr) Arccosh 

func (e Expr) Arccosh() Expr

func (Expr) Arcsin 

func (e Expr) Arcsin() Expr

func (Expr) Arcsinh 

func (e Expr) Arcsinh() Expr

Arcsinh / Arccosh / Arctanh: inverse hyperbolics.

func (Expr) Arctan 

func (e Expr) Arctan() Expr

func (Expr) Arctan2 

func (e Expr) Arctan2(other Expr) Expr

Arctan2 returns atan2(e, other) element-wise.

func (Expr) Arctanh 

func (e Expr) Arctanh() Expr

func (Expr) BackwardFill 

func (e Expr) BackwardFill(limit int) Expr

BackwardFill propagates the next non-null value backward into nulls.

func (Expr) Between 

func (e Expr) Between(lo, hi any) Expr

Between is sugar for (e >= lo) and (e <= hi).

func (Expr) Cast 

func (e Expr) Cast(to dtype.DType) Expr

Cast coerces the expression result to the target dtype.

func (Expr) Cbrt 

func (e Expr) Cbrt() Expr

Cbrt returns cube root element-wise.

func (Expr) Ceil 

func (e Expr) Ceil() Expr

Ceil returns the least integer ≥ e (float output).

func (Expr) Clip 

func (e Expr) Clip(lo, hi float64) Expr

Clip bounds e to [lo, hi]. Use +/-math.Inf for one-sided.

func (Expr) Cos 

func (e Expr) Cos() Expr

func (Expr) Cosh 

func (e Expr) Cosh() Expr

func (Expr) Cot 

func (e Expr) Cot() Expr

Cot returns 1/tan element-wise.

func (Expr) Count 

func (e Expr) Count() Expr

Count returns the number of non-null values.

func (Expr) CumCount 

func (e Expr) CumCount() Expr

CumCount returns the running count of non-null values.

func (Expr) CumMax 

func (e Expr) CumMax() Expr

CumMax returns the running maximum.

func (Expr) CumMin 

func (e Expr) CumMin() Expr

CumMin returns the running minimum.

func (Expr) CumProd 

func (e Expr) CumProd() Expr

CumProd returns the running product (always float64 output).

func (Expr) CumSum 

func (e Expr) CumSum() Expr

CumSum returns the running sum of the column.

func (Expr) Degrees 

func (e Expr) Degrees() Expr

Degrees converts radians to degrees.

func (Expr) Diff 

func (e Expr) Diff(periods int) Expr

Diff returns element-wise differences between periods-step neighbours.

func (Expr) Div 

func (e Expr) Div(other Expr) Expr

Div returns e / other. Integer operands divide as integers; mix a float operand to force float output.

func (Expr) DivLit 

func (e Expr) DivLit(v any) Expr

DivLit is sugar for e.Div(Lit(v)).

func (Expr) EWMMean 

func (e Expr) EWMMean(alpha float64) Expr

EWMMean / EWMVar / EWMStd return the adjusted exponentially- weighted moving statistic with the given alpha. Alpha must be in (0, 1]; values outside trigger a runtime error at eval time.

func (Expr) EWMStd 

func (e Expr) EWMStd(alpha float64) Expr

func (Expr) EWMVar 

func (e Expr) EWMVar(alpha float64) Expr

func (Expr) Entropy 

func (e Expr) Entropy(base float64) Expr

Entropy returns Shannon entropy in the given base (natural log by default when base=0 or omitted in callers).

func (Expr) Eq 

func (e Expr) Eq(other Expr) Expr

Eq returns the element-wise equality test (`e == other`).

The result is a boolean Expr suitable for [lazy.LazyFrame.Filter] or as the predicate of When.

Parameters

  • other: right-hand side Expr; dtypes must be compatible.

Returns

A boolean Expr.

Examples 

expr.Col("status").Eq(expr.LitString("active"))

// Compose predicates:
expr.Col("dept").Eq(expr.LitString("eng")).
    And(expr.Col("active").Eq(expr.LitBool(true)))

See also Expr.Ne, Expr.EqLit.

func (Expr) EqLit 

func (e Expr) EqLit(v any) Expr

EqLit is sugar for e.Eq(Lit(v)).

func (Expr) Exp 

func (e Expr) Exp() Expr

Exp returns e**x.

func (Expr) Expm1 

func (e Expr) Expm1() Expr

Expm1 returns exp(x)-1 element-wise.

func (Expr) FillNan 

func (e Expr) FillNan(v float64) Expr

FillNan replaces NaN values in float columns with v. Integer and string columns are returned unchanged (mirrors polars).

func (Expr) FillNull 

func (e Expr) FillNull(v any) Expr

FillNull replaces nulls with the given scalar value. The value is wrapped in a literal Expr internally so the planner can fold.

func (Expr) FillNullExpr 

func (e Expr) FillNullExpr(other Expr) Expr

FillNullExpr replaces nulls with the result of another expression (polars allows a full expression here).

func (Expr) First 

func (e Expr) First() Expr

First returns the first value (aggregation).

func (Expr) Floor 

func (e Expr) Floor() Expr

Floor returns the greatest integer ≤ e (float output).

func (Expr) ForwardFill 

func (e Expr) ForwardFill(limit int) Expr

ForwardFill propagates the last non-null value forward into nulls. limit=0 means unlimited; otherwise at most limit consecutive nulls are filled before a run is left untouched.

func (Expr) Ge 

func (e Expr) Ge(other Expr) Expr

Ge returns the element-wise greater-than-or-equal test (`e >= other`).

func (Expr) GeLit 

func (e Expr) GeLit(v any) Expr

GeLit is sugar for e.Ge(Lit(v)).

func (Expr) Gt 

func (e Expr) Gt(other Expr) Expr

Gt returns the element-wise greater-than test (`e > other`).

Parameters

  • other: right-hand side Expr; dtypes must be comparable.

Returns

A boolean Expr.

Examples 

// Filter rows where age > 18:
df.Lazy().Filter(expr.Col("age").Gt(expr.LitInt64(18)))

// Chain on another op:
expr.Col("salary").Gt(expr.LitFloat64(100_000)).Alias("bulk")

func (Expr) GtLit 

func (e Expr) GtLit(v any) Expr

GtLit is sugar for e.Gt(Lit(v)).

func (Expr) Hash 

func (e Expr) Hash() uint64

Hash returns a stable 64-bit hash of the expression structure. Used for common subexpression elimination.

func (Expr) HashValues 

func (e Expr) HashValues() Expr

HashValues returns a per-row FNV-64a hash as a uint64 column. Nulls propagate to nulls. Named HashValues (not Hash) because Expr.Hash already exists on the structural-hash side for CSE.

func (Expr) Head 

func (e Expr) Head(n int) Expr

Head takes the first n rows of the column (per group when inside groupby).

func (Expr) IsDuplicated 

func (e Expr) IsDuplicated() Expr

IsDuplicated is true where the value occurs more than once.

func (Expr) IsFirstDistinct 

func (e Expr) IsFirstDistinct() Expr

IsFirstDistinct / IsLastDistinct mark the first/last occurrence of each distinct value.

func (Expr) IsIn 

func (e Expr) IsIn(values ...any) Expr

IsIn returns a boolean predicate: true iff e is one of `values`. Implemented via an OR-chain of equality; for a handful of values this is as fast as a hash lookup, and avoids a new evaluator node.

func (Expr) IsLastDistinct 

func (e Expr) IsLastDistinct() Expr

func (Expr) IsNotNull 

func (e Expr) IsNotNull() Expr

IsNotNull returns a boolean expression that is true where the input is not null.

func (Expr) IsNull 

func (e Expr) IsNull() Expr

IsNull returns a boolean expression that is true where the input is null.

func (Expr) IsUnique 

func (e Expr) IsUnique() Expr

IsUnique is true where the value occurs exactly once.

func (Expr) Kurtosis 

func (e Expr) Kurtosis() Expr

Kurtosis returns the excess kurtosis as a scalar aggregation.

func (Expr) Last 

func (e Expr) Last() Expr

Last returns the last value (aggregation).

func (Expr) Le 

func (e Expr) Le(other Expr) Expr

Le returns the element-wise less-than-or-equal test (`e <= other`).

func (Expr) LeLit 

func (e Expr) LeLit(v any) Expr

LeLit is sugar for e.Le(Lit(v)).

func (Expr) List 

func (e Expr) List() ListOps

List opens the list namespace.

func (Expr) Log 

func (e Expr) Log() Expr

Log returns natural log.

func (Expr) Log1p 

func (e Expr) Log1p() Expr

Log1p returns log(1+x) element-wise.

func (Expr) Log2 

func (e Expr) Log2() Expr

Log2 returns log₂.

func (Expr) Log10 

func (e Expr) Log10() Expr

Log10 returns log₁₀.

func (Expr) Lt 

func (e Expr) Lt(other Expr) Expr

Lt returns the element-wise less-than test (`e < other`).

func (Expr) LtLit 

func (e Expr) LtLit(v any) Expr

LtLit is sugar for e.Lt(Lit(v)).

func (Expr) Max 

func (e Expr) Max() Expr

Max aggregates with max.

func (Expr) Mean 

func (e Expr) Mean() Expr

Mean aggregates with arithmetic mean.

func (Expr) Median 

func (e Expr) Median() Expr

Median is sugar for Quantile(0.5).

func (Expr) Min 

func (e Expr) Min() Expr

Min aggregates with min.

func (Expr) Mul 

func (e Expr) Mul(other Expr) Expr

Mul returns e * other.

func (Expr) MulLit 

func (e Expr) MulLit(v any) Expr

MulLit is sugar for e.Mul(Lit(v)).

func (Expr) NUnique 

func (e Expr) NUnique() Expr

NUnique aggregates to the count of distinct non-null values.

func (Expr) Ne 

func (e Expr) Ne(other Expr) Expr

Ne returns the element-wise inequality test (`e != other`).

func (Expr) NeLit 

func (e Expr) NeLit(v any) Expr

NeLit is sugar for e.Ne(Lit(v)).

func (Expr) Neg 

func (e Expr) Neg() Expr

Neg returns the element-wise arithmetic negation (`-e`).

func (Expr) Node 

func (e Expr) Node() Node

Node returns the underlying AST node for pattern matching by internal consumers (the evaluator and the optimizer).

func (Expr) Not 

func (e Expr) Not() Expr

Not returns the element-wise logical negation. Operand must be bool.

func (Expr) NullCount 

func (e Expr) NullCount() Expr

NullCount returns the number of null values.

func (Expr) Or 

func (e Expr) Or(other Expr) Expr

Or returns the element-wise logical OR. Operands must be bool.

func (Expr) Over 

func (e Expr) Over(keys ...string) Expr

Over wraps e so it is evaluated separately per group defined by keys, then broadcast back to the original row order. Mirrors polars' expr.over(*keys).

func (Expr) PctChange 

func (e Expr) PctChange(periods int) Expr

PctChange returns element-wise percent change against periods-ago.

func (Expr) PeakMax 

func (e Expr) PeakMax() Expr

PeakMax / PeakMin return boolean Series marking local extrema.

func (Expr) PeakMin 

func (e Expr) PeakMin() Expr

func (Expr) Pow 

func (e Expr) Pow(exponent float64) Expr

Pow raises e to the given power.

func (Expr) Product 

func (e Expr) Product() Expr

Product is the multiplicative aggregate.

func (Expr) Quantile 

func (e Expr) Quantile(q float64) Expr

Quantile returns the q-th quantile (linear interpolation).

func (Expr) Radians 

func (e Expr) Radians() Expr

Radians converts degrees to radians.

func (Expr) Rank 

func (e Expr) Rank(method string) Expr

Rank returns a float64 rank column using the given method. method is the polars-style string: "average", "min", "max", "dense", "ordinal".

func (Expr) Reverse 

func (e Expr) Reverse() Expr

Reverse reverses the order of the column.

func (Expr) RollingMax 

func (e Expr) RollingMax(windowSize, minPeriods int) Expr

func (Expr) RollingMean 

func (e Expr) RollingMean(windowSize, minPeriods int) Expr

func (Expr) RollingMin 

func (e Expr) RollingMin(windowSize, minPeriods int) Expr

func (Expr) RollingStd 

func (e Expr) RollingStd(windowSize, minPeriods int) Expr

func (Expr) RollingSum 

func (e Expr) RollingSum(windowSize, minPeriods int) Expr

RollingSum / Mean / Min / Max / Std / Var apply a fixed-size window reduction. minPeriods=0 defaults to windowSize. Mirrors polars' rolling_* Expr methods.

func (Expr) RollingVar 

func (e Expr) RollingVar(windowSize, minPeriods int) Expr

func (Expr) Round 

func (e Expr) Round(decimals int) Expr

Round rounds to the given number of decimal places (0 = integer). Integers pass through unchanged.

func (Expr) Shift 

func (e Expr) Shift(periods int) Expr

Shift shifts values by periods positions.

func (Expr) Sign 

func (e Expr) Sign() Expr

Sign returns -1/0/+1 per element, preserving integer dtype.

func (Expr) Sin 

func (e Expr) Sin() Expr

Sin / Cos / Tan are trig wrappers.

func (Expr) Sinh 

func (e Expr) Sinh() Expr

Sinh / Cosh / Tanh: hyperbolics.

func (Expr) Skew 

func (e Expr) Skew() Expr

Skew returns the sample skewness as a scalar aggregation.

func (Expr) Slice 

func (e Expr) Slice(offset, length int) Expr

Slice returns [offset, offset+length) per column.

func (Expr) Sort 

func (e Expr) Sort(descending bool) Expr

Sort returns the sorted values of the column. Ascending is the polars default; pass descending=true for reverse order.

func (Expr) Sqrt 

func (e Expr) Sqrt() Expr

Sqrt returns √e as a float64 column.

func (Expr) Std 

func (e Expr) Std() Expr

Std (sample) standard deviation.

func (Expr) Str 

func (e Expr) Str() StrOps

Str returns a string-ops view over e. This mirrors polars' `col("x").str.*` namespace: every method returns a new Expr that plugs back into the normal expression algebra.

Allocation-free wrapper; the actual work happens inside the kernel that evaluates the returned Expr.

Examples 

// Case fold:
expr.Col("name").Str().ToUpper()

// Regex predicate:
expr.Col("email").Str().ContainsRegex(`@example\.com$`)

// Chain with the list namespace:
expr.Col("csv").Str().SplitExact(",").List().Len()

func (Expr) String 

func (e Expr) String() string

String returns a polars-style repr: col("a"), col("a") + 1, col("a").sum().

func (Expr) Struct 

func (e Expr) Struct() StructOps

Struct opens the struct namespace.

func (Expr) Sub 

func (e Expr) Sub(other Expr) Expr

Sub returns e - other. See Expr.Add for null semantics.

func (Expr) SubLit 

func (e Expr) SubLit(v any) Expr

SubLit is sugar for e.Sub(Lit(v)).

func (Expr) Sum 

func (e Expr) Sum() Expr

Sum aggregates the expression with sum.

func (Expr) Tail 

func (e Expr) Tail(n int) Expr

Tail takes the last n rows.

func (Expr) Tan 

func (e Expr) Tan() Expr

func (Expr) Tanh 

func (e Expr) Tanh() Expr

func (Expr) Unique 

func (e Expr) Unique() Expr

Unique returns the distinct non-null values of the column, first- occurrence order, with a single trailing null if the input has nulls.

func (Expr) Var 

func (e Expr) Var() Expr

Var (sample) variance.

type FunctionNode 

type FunctionNode struct {
	Name string
	Args []Expr
	// Params carries non-Expr scalar arguments (e.g. the decimals arg
	// of round, or the low/high bounds of clip). Encoded as opaque any
	// so the evaluator can type-assert per function.
	Params []any
}

FunctionNode applies a named unary/multi-arg function to one or more inner expressions. Keeps the AST small while letting us add new scalar kernels (abs, sqrt, log, round, floor, ceil, …) without a new Node type each time.

The name is the canonical lower-case function name (polars-style). The evaluator and optimiser switch on Name to dispatch.

func (FunctionNode) String 

func (f FunctionNode) String() string

type IsNullNode 

type IsNullNode struct {
	Inner  Expr
	Negate bool
}

IsNullNode tests for null, or (with Negate) non-null.

func (IsNullNode) String 

func (n IsNullNode) String() string

type ListOps 

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

ListOps is the expression-level mirror of series.ListOps. Reach it via Expr.List(); every method returns a fresh Expr so the kernel runs at evaluation time.

func (ListOps) Contains 

func (o ListOps) Contains(needle any) Expr

Contains tests list membership for a literal needle.

func (ListOps) First 

func (o ListOps) First() Expr

First / Last / Get extract positional elements.

func (ListOps) Get 

func (o ListOps) Get(idx int) Expr

func (ListOps) Join 

func (o ListOps) Join(sep string) Expr

Join concatenates string lists with sep.

func (ListOps) Last 

func (o ListOps) Last() Expr

func (ListOps) Len 

func (o ListOps) Len() Expr

Len returns the length of each inner list.

func (ListOps) Max 

func (o ListOps) Max() Expr

func (ListOps) Mean 

func (o ListOps) Mean() Expr

func (ListOps) Min 

func (o ListOps) Min() Expr

func (ListOps) Sum 

func (o ListOps) Sum() Expr

Sum / Mean / Min / Max reduce each inner list.

type LitNode 

type LitNode struct {
	DType dtype.DType
	// Value is a typed Go value. Supported types: int64, float64, bool,
	// string. Use the Lit* constructors to build a LitNode safely.
	Value any
}

LitNode is a typed literal value.

func (LitNode) String 

func (l LitNode) String() string

type Node 

type Node interface {
	fmt.Stringer
	// contains filtered or unexported methods
}

Node is the tag interface for AST nodes. Users do not construct Nodes directly; they work with Expr values returned by constructors.

type OverNode 

type OverNode struct {
	Inner Expr
	Keys  []string
}

OverNode wraps an inner expression with a list of partition keys, turning `pl.col("x").sum()` into `pl.col("x").sum().over("k")`: the reduction is computed per-group and broadcast back to every row of the original frame.

func (OverNode) String 

func (o OverNode) String() string

type Scalar 

type Scalar interface {
	~int | ~int32 | ~int64 | ~float32 | ~float64 | ~bool | ~string
}

Scalar is the set of Go scalar types that can be promoted to a literal expression. It mirrors the cases the untyped Lit function accepts, but as a type constraint so generic helpers can be compile-time checked.

type StrOps 

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

StrOps is the expression-level mirror of series.StrOps: a namespace of string-column operations reachable from an Expr via .Str(). Methods return new Exprs so they compose with the rest of the algebra; the concrete kernel runs when eval dispatches on the FunctionNode's Name.

Every name here is prefixed with "str." so the eval switch can separate string kernels from the general function table. Polars uses the same mental model: `pl.col("x").str.contains(...)` is a namespaced op, not a global function.

func (StrOps) Contains 

func (o StrOps) Contains(needle string) Expr

Contains tests each row for a literal substring needle. Empty needle matches every non-null row; use StrOps.ContainsRegex for regex behaviour.

Examples 

// "foo" anywhere in the value:
expr.Col("msg").Str().Contains("foo")

func (StrOps) ContainsRegex 

func (o StrOps) ContainsRegex(pattern string) Expr

ContainsRegex runs a compiled regexp against each row and returns a boolean Expr.

Examples 

// Email addresses on example.com:
expr.Col("email").Str().ContainsRegex(`@example\.com$`)

func (StrOps) CountMatches 

func (o StrOps) CountMatches(needle string) Expr

CountMatches counts non-overlapping occurrences of needle per row.

func (StrOps) EndsWith 

func (o StrOps) EndsWith(suffix string) Expr

EndsWith is a byte-suffix predicate. See StrOps.StartsWith.

func (StrOps) Find 

func (o StrOps) Find(needle string) Expr

Find returns the byte offset of the first occurrence of needle, or -1 when missing.

func (StrOps) Head 

func (o StrOps) Head(n int) Expr

Head returns the first n characters (runes) of each row. Negative n means "all but the last |n|".

func (StrOps) LenBytes 

func (o StrOps) LenBytes() Expr

LenBytes returns the byte-length of each row as int64.

func (StrOps) LenChars 

func (o StrOps) LenChars() Expr

LenChars returns the rune-count of each row as int64.

func (StrOps) Like 

func (o StrOps) Like(pattern string) Expr

Like is a SQL-style wildcard predicate.

Wildcards

  • `%` matches any sequence of characters (including empty)
  • `_` matches exactly one character
  • `\` escapes the following character literal

Examples 

// Names starting with "a" followed by anything:
expr.Col("name").Str().Like("a%")

// Three-letter codes starting with "F":
expr.Col("code").Str().Like("F__")

func (StrOps) NotLike 

func (o StrOps) NotLike(pattern string) Expr

NotLike is the logical negation of StrOps.Like.

func (StrOps) Replace 

func (o StrOps) Replace(old, new string) Expr

Replace swaps the first occurrence of old with new in each row.

func (StrOps) ReplaceAll 

func (o StrOps) ReplaceAll(old, new string) Expr

ReplaceAll swaps every occurrence of old.

func (StrOps) Slice 

func (o StrOps) Slice(start, length int) Expr

Slice is a two-argument variant: start, length. Length -1 means "to end". Mirrors polars str.slice.

func (StrOps) SplitExact 

func (o StrOps) SplitExact(sep string) Expr

SplitExact splits each cell by sep and returns a list column (dtype List<String>). Compose with the list.* namespace, e.g. `col("x").Str().SplitExact(",").List().Len()`.

func (StrOps) StartsWith 

func (o StrOps) StartsWith(prefix string) Expr

StartsWith is a byte-prefix predicate. Compare the row's raw bytes against prefix; nulls stay null.

Examples 

expr.Col("sku").Str().StartsWith("US-")

func (StrOps) StripPrefix 

func (o StrOps) StripPrefix(prefix string) Expr

StripPrefix drops one occurrence of prefix from the start of each row; unmatched rows pass through unchanged.

func (StrOps) StripSuffix 

func (o StrOps) StripSuffix(suffix string) Expr

StripSuffix is the symmetric counterpart.

func (StrOps) Tail 

func (o StrOps) Tail(n int) Expr

Tail returns the last n characters.

func (StrOps) ToLower 

func (o StrOps) ToLower() Expr

ToLower folds letters to lowercase (ASCII fast path, UTF-8 fallback).

func (StrOps) ToUpper 

func (o StrOps) ToUpper() Expr

ToUpper folds letters to uppercase.

func (StrOps) Trim 

func (o StrOps) Trim() Expr

Trim strips leading + trailing whitespace.

type StructOps 

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

StructOps is the expression-level mirror of series.StructOps.

func (StructOps) Field 

func (o StructOps) Field(name string) Expr

Field projects a single named field out of a struct column.

type TCol 

type TCol[T Scalar] struct{ Expr }

TCol is a typed column reference. It wraps an Expr with a phantom type that represents the column's Go-level scalar type, so the comparison/arithmetic helpers can take a bare T instead of an Expr wrapped around a Lit. 

expr.C[int64]("qty").Gt(2).Alias("bulk")

The type parameter is an intent hint, not a proof. If the runtime schema disagrees, evaluation panics with the same message that the untyped path produces. Use C when the column dtype is statically known; stick with Col when it is dynamic (config-driven, user-supplied, etc.).

func Bool 

func Bool(name string) TCol[bool]

func C 

func C[T Scalar](name string) TCol[T]

C constructs a typed column reference.

func Float 

func Float(name string) TCol[float64]

func Float32 

func Float32(name string) TCol[float32]

func Int 

func Int(name string) TCol[int64]

Int, Float, Str, Bool, Int32, Float32 are ergonomic aliases for the common C[T] instantiations. They read more naturally at the call site: `expr.Int("qty").Gt(2)` vs `expr.C[int64]("qty").Gt(2)`.

func Int32 

func Int32(name string) TCol[int32]

func Str 

func Str(name string) TCol[string]

func (TCol[T]) Abs 

func (c TCol[T]) Abs() TCol[T]

Abs returns the absolute value. Numeric dtypes only.

func (TCol[T]) Add 

func (c TCol[T]) Add(v T) TCol[T]

Add, Sub, Mul, Div take a literal of the column's type and preserve T on the output. Promotion rules (e.g. int + float -> float) are not expressible at the type level; callers that need cross-type arithmetic should drop to the embedded Expr and .Cast explicitly.

func (TCol[T]) AddCol 

func (c TCol[T]) AddCol(o TCol[T]) TCol[T]

AddCol, SubCol, MulCol, DivCol combine two same-typed columns and preserve T on the output.

func (TCol[T]) Alias 

func (c TCol[T]) Alias(name string) TCol[T]

func (TCol[T]) ApproxNUnique 

func (c TCol[T]) ApproxNUnique() TCol[int64]

func (TCol[T]) As 

func (c TCol[T]) As(name string) TCol[T]

As renames the expression output, returning a typed column so further typed operations can chain. Alias is a drop-in synonym that matches the untyped Expr's naming.

func (TCol[T]) BackwardFill 

func (c TCol[T]) BackwardFill(limit int) TCol[T]

func (TCol[T]) Between 

func (c TCol[T]) Between(lo, hi T) Expr

Between returns a boolean expression: lo <= c <= hi. Polars' pl.col().is_between(lo, hi) equivalent.

func (TCol[T]) CastBool 

func (c TCol[T]) CastBool() TCol[bool]

func (TCol[T]) CastFloat64 

func (c TCol[T]) CastFloat64() TCol[float64]

func (TCol[T]) CastInt64 

func (c TCol[T]) CastInt64() TCol[int64]

CastInt64, CastFloat64, CastBool, CastString are convenience wrappers over CastTo that also re-tag the returned TCol so the type parameter stays meaningful.

func (TCol[T]) CastString 

func (c TCol[T]) CastString() TCol[string]

func (TCol[T]) CastTo 

func (c TCol[T]) CastTo(to dtype.DType) Expr

CastTo drops the typed wrapper and coerces to the target dtype at evaluation. Use this to bridge typed columns of different T into a common dtype before combining them.

func (TCol[T]) Count 

func (c TCol[T]) Count() TCol[int64]

func (TCol[T]) CumCount 

func (c TCol[T]) CumCount() TCol[int64]

func (TCol[T]) CumMax 

func (c TCol[T]) CumMax() TCol[T]

func (TCol[T]) CumMin 

func (c TCol[T]) CumMin() TCol[T]

func (TCol[T]) CumProd 

func (c TCol[T]) CumProd() TCol[T]

func (TCol[T]) CumSum 

func (c TCol[T]) CumSum() TCol[T]

Cumulative and shift operations preserve T.

func (TCol[T]) Diff 

func (c TCol[T]) Diff(periods int) TCol[T]

func (TCol[T]) Div 

func (c TCol[T]) Div(v T) TCol[T]

func (TCol[T]) DivCol 

func (c TCol[T]) DivCol(o TCol[T]) TCol[T]

func (TCol[T]) Eq 

func (c TCol[T]) Eq(v T) Expr

Eq, Ne, Lt, Le, Gt, Ge compare against a literal of the column's type. They return an untyped boolean Expr because downstream use (And/Or/Filter) is dtype-agnostic.

func (TCol[T]) EqCol 

func (c TCol[T]) EqCol(o TCol[T]) Expr

EqCol, NeCol, LtCol, LeCol, GtCol, GeCol compare two typed columns of the same T. Mixed-type comparisons go through the untyped API: `c.Expr.Gt(other.Expr)`.

func (TCol[T]) FillNull 

func (c TCol[T]) FillNull(v T) TCol[T]

FillNull replaces nulls with a literal of the column's type. For cross-type fill (e.g. fill an int64 column with a float default) use the embedded Expr.FillNull(any).

func (TCol[T]) First 

func (c TCol[T]) First() TCol[T]

func (TCol[T]) ForwardFill 

func (c TCol[T]) ForwardFill(limit int) TCol[T]

func (TCol[T]) Ge 

func (c TCol[T]) Ge(v T) Expr

func (TCol[T]) GeCol 

func (c TCol[T]) GeCol(o TCol[T]) Expr

func (TCol[T]) Gt 

func (c TCol[T]) Gt(v T) Expr

func (TCol[T]) GtCol 

func (c TCol[T]) GtCol(o TCol[T]) Expr

func (TCol[T]) Head 

func (c TCol[T]) Head(n int) TCol[T]

func (TCol[T]) IsIn 

func (c TCol[T]) IsIn(values ...T) Expr

IsIn returns a boolean expression: c in {values}. Membership is evaluated with equality on the column's scalar type.

func (TCol[T]) IsNotNull 

func (c TCol[T]) IsNotNull() Expr

func (TCol[T]) IsNull 

func (c TCol[T]) IsNull() Expr

IsNull and IsNotNull return boolean expressions. Null checks apply to every dtype, so the output is untyped for downstream logic.

func (TCol[T]) Kurtosis 

func (c TCol[T]) Kurtosis() TCol[float64]

func (TCol[T]) Last 

func (c TCol[T]) Last() TCol[T]

func (TCol[T]) Le 

func (c TCol[T]) Le(v T) Expr

func (TCol[T]) LeCol 

func (c TCol[T]) LeCol(o TCol[T]) Expr

func (TCol[T]) Lt 

func (c TCol[T]) Lt(v T) Expr

func (TCol[T]) LtCol 

func (c TCol[T]) LtCol(o TCol[T]) Expr

func (TCol[T]) Max 

func (c TCol[T]) Max() TCol[T]

func (TCol[T]) Mean 

func (c TCol[T]) Mean() TCol[float64]

Mean always promotes to float64. Count and NullCount always produce int64. Median/Std/Var similarly promote to float64 for every numeric input.

func (TCol[T]) Median 

func (c TCol[T]) Median() TCol[float64]

func (TCol[T]) Min 

func (c TCol[T]) Min() TCol[T]

func (TCol[T]) Mul 

func (c TCol[T]) Mul(v T) TCol[T]

func (TCol[T]) MulCol 

func (c TCol[T]) MulCol(o TCol[T]) TCol[T]

func (TCol[T]) NUnique 

func (c TCol[T]) NUnique() TCol[int64]

func (TCol[T]) Ne 

func (c TCol[T]) Ne(v T) Expr

func (TCol[T]) NeCol 

func (c TCol[T]) NeCol(o TCol[T]) Expr

func (TCol[T]) Neg 

func (c TCol[T]) Neg() TCol[T]

Neg negates the column (valid for numeric dtypes; behaviour on non-numeric is inherited from the untyped Neg).

func (TCol[T]) NullCount 

func (c TCol[T]) NullCount() TCol[int64]

func (TCol[T]) Over 

func (c TCol[T]) Over(keys ...string) TCol[T]

Over broadcasts an aggregation over the given partition keys. The output keeps T because the underlying aggregation's dtype is preserved across the partition.

func (TCol[T]) Product 

func (c TCol[T]) Product() TCol[T]

func (TCol[T]) Quantile 

func (c TCol[T]) Quantile(q float64) TCol[float64]

func (TCol[T]) Reverse 

func (c TCol[T]) Reverse() TCol[T]

func (TCol[T]) RollingMax 

func (c TCol[T]) RollingMax(windowSize, minPeriods int) TCol[T]

func (TCol[T]) RollingMean 

func (c TCol[T]) RollingMean(windowSize, minPeriods int) TCol[float64]

func (TCol[T]) RollingMin 

func (c TCol[T]) RollingMin(windowSize, minPeriods int) TCol[T]

func (TCol[T]) RollingStd 

func (c TCol[T]) RollingStd(windowSize, minPeriods int) TCol[float64]

func (TCol[T]) RollingSum 

func (c TCol[T]) RollingSum(windowSize, minPeriods int) TCol[T]

RollingSum/Min/Max preserve T. RollingMean/Std/Var promote to float64 since they introduce fractional values even for integer inputs.

func (TCol[T]) RollingVar 

func (c TCol[T]) RollingVar(windowSize, minPeriods int) TCol[float64]

func (TCol[T]) Shift 

func (c TCol[T]) Shift(periods int) TCol[T]

func (TCol[T]) Skew 

func (c TCol[T]) Skew() TCol[float64]

func (TCol[T]) Slice 

func (c TCol[T]) Slice(off, length int) TCol[T]

func (TCol[T]) Sort 

func (c TCol[T]) Sort(descending bool) TCol[T]

func (TCol[T]) Std 

func (c TCol[T]) Std() TCol[float64]

func (TCol[T]) Sub 

func (c TCol[T]) Sub(v T) TCol[T]

func (TCol[T]) SubCol 

func (c TCol[T]) SubCol(o TCol[T]) TCol[T]

func (TCol[T]) Sum 

func (c TCol[T]) Sum() TCol[T]

Sum, Min, Max, First, Last preserve T because their output dtype matches the input dtype for every scalar the constraint admits.

func (TCol[T]) Tail 

func (c TCol[T]) Tail(n int) TCol[T]

func (TCol[T]) Unique 

func (c TCol[T]) Unique() TCol[T]

func (TCol[T]) Var 

func (c TCol[T]) Var() TCol[float64]

type UnaryNode 

type UnaryNode struct {
	Op  UnaryOp
	Arg Expr
}

UnaryNode applies a unary operator.

func (UnaryNode) String 

func (u UnaryNode) String() string

type UnaryOp 

type UnaryOp uint8

UnaryOp is the set of unary operators the AST carries. 

const (
	OpNot UnaryOp = iota
	OpNeg
)

type WhenBuilder 

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

WhenBuilder captures a predicate awaiting Then().

func When 

func When(pred Expr) WhenBuilder

When starts a conditional expression, polars-style. Always chain exactly one WhenBuilder.Then and one WhenThenBuilder.Otherwise; the resulting Expr carries the promoted dtype of both branches.

Example: 

// Clamp salary to a grade bucket.
bucket := expr.When(expr.Col("salary").Gt(expr.LitInt64(150_000))).
    Then(expr.LitString("senior")).
    Otherwise(
        expr.When(expr.Col("salary").Gt(expr.LitInt64(80_000))).
            Then(expr.LitString("mid")).
            Otherwise(expr.LitString("junior")),
    ).Alias("grade")

func (WhenBuilder) Then 

func (w WhenBuilder) Then(v Expr) WhenThenBuilder

Then records the value taken when the predicate is true.

type WhenThenBuilder 

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

WhenThenBuilder captures pred+then awaiting Otherwise().

func (WhenThenBuilder) Otherwise 

func (w WhenThenBuilder) Otherwise(v Expr) Expr

Otherwise closes the conditional and returns an Expr.

type WhenThenNode 

type WhenThenNode struct {
	Pred      Expr
	Then      Expr
	Otherwise Expr
}

WhenThenNode is a conditional: when(pred).then(a).otherwise(b).

func (WhenThenNode) String 

func (w WhenThenNode) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.