bv.col — column expressions

Overview

Every predicate in beava — every where= kwarg, every filter clause, every derived-column expression — is built from two primitives: bv.col(name) for a field reference, and bv.lit(value) for a constant. Combine them with Python operators (==, >, &, |, ~) to produce an _Expr AST node. The AST is inert at construction time; the server's expression parser evaluates it at push time.

bv.count(
    window="1h",
    where=bv.col("amount") > 100,
)

pv.with_columns(
    is_premium=bv.col("plan") == bv.lit("premium"),
)

Both helpers return _Expr nodes (subclasses _Col and _Literal). _Expr overloads Python's comparison, arithmetic, and bitwise operators to grow the AST; you never construct nodes by hand.

Reference a schema field by name. Returns an _Expr — an unbound expression node that participates in operator overloads. The lookup is unresolved until the expression reaches the server; bv.col("nonexistent") only fails at register / push time when the schema check runs.

Args

• name — the field name as declared on the upstream event class. Composite keys are addressed by their per-column names; there is no nested-field accessor.

Returns

_Col — a frozen-dataclass _Expr node. Hashable, immutable, safe to reuse across multiple chain expressions.

Example

import beava as bv

amount = bv.col("amount")
expr = amount > 100
print(expr.to_expr_string())  # → '(amount > 100)'

Wrap a Python constant as an explicit literal expression. The implicit form (bv.col("a") > 100) and the explicit form (bv.col("a") > bv.lit(100)) are wire-equivalent inside operator overloads — Python's dispatch coerces the right-hand side automatically. bv.lit is required when the literal stands on its own (a constant column in with_columns, the left-hand side of an arithmetic expression, or the only operand of a derivation).

bv.lit is the canonical way to write a comparison-against-constant in any where= kwarg — bare strings are rejected (see the where= contract).

Args

• value — a Python scalar. Accepted types: int, float, str, bool, None. Other types (e.g. list, dict, custom classes) are not supported by the server's expression grammar.

Returns

_Literal — a frozen-dataclass _Expr node. Renders to the wire-grammar form: single-quoted strings, true/false for booleans, null for None.

Example

import beava as bv

bv.lit(42).to_expr_string()     # → '42'
bv.lit("web").to_expr_string()  # → "'web'"
bv.lit(None).to_expr_string()   # → 'null'
bv.lit(True).to_expr_string()   # → 'true'

Expression DSL

An _Expr grows by operator overload. Every overload returns a new _Expr — the AST is immutable, so re-using a node in multiple chains is safe.

Comparison

Each comparison operator emits a _BinOp node. Both operands are _Expr; bare Python literals on either side are auto-wrapped via _coerce.

Logical combinators

Python's and / or can't be overloaded — they short-circuit on truthiness. Beava overloads & / | instead and serializes them as the server-grammar keywords and / or. Always parenthesize — Python's bitwise operators bind tighter than comparison.

expr = (bv.col("amount") > 100) & (bv.col("plan") == "premium")
expr.to_expr_string()
# → "((amount > 100) and (plan == 'premium'))"

negated = ~(bv.col("path") == "/health")
negated.to_expr_string()
# → "!((path == '/health'))"

Methods

The where= contract

Every kwarg that takes a predicate — every aggregation operator's where=, every filter clause — accepts an _Expr and only an _Expr. Bare strings are rejected. The check lives in _serialize_where on every aggregation operator: anything that isn't None or an _Expr raises TypeError client-side, before a single byte hits the wire.

bv.count(where="amount > 0")
# TypeError: where= must be an _Expr or None;
#   got str

bv.count(where=bv.col("amount") > 0)
# wire: where = "(amount > 0)"

Why bare strings are blocked. A free-form predicate string would force the SDK to either ship a Python-side parser (hidden complexity, divergence risk against the server grammar) or pass the string through unchecked (typos surface only at push-time on the server). The _Expr AST removes both failure modes: it parses at construction, renders deterministically, and refactors statically.

Common questions

Where to go next

You know how to reference and constrain. The next thing to learn is what to apply expressions to: