Documentation
¶
Overview ¶
Package window implements the WIN_* window operators for Pulse.
Window operations evaluate over post-aggregate rows ([]map[string]any), inserted into the processing pipeline after grouped aggregation:
records → filter → attribute → group → aggregate → window → response
The Apply entry point sorts rows once per distinct (PartitionBy, OrderBy) tuple, partitions them, and runs each window's WindowComputer to mutate rows with the operator's output column.
Validation of window specs (frame matrix, alpha bounds) belongs to internal/descriptor/predict_window.go; field existence and order_by orderability (IsOrderableType) to the shared internal/descriptor.FieldRefRefusals rule, which every runtime execution mode applies before Apply. Apply trusts that req.Windows has been validated; runtime errors here surface as PROCESSING_RUNTIME / PROCESSING_CONFIG.
Index ¶
- func Apply(ctx context.Context, rows []map[string]any, windows []*types.Window) error
- func ApplyKeyed(ctx context.Context, rows []map[string]any, windows []*types.Window, ...) error
- func ApplyWithExt(ctx context.Context, rows []map[string]any, windows []*types.Window, ...) error
- func CompareKey(a, b any, desc bool) int
- func CompareKeyOrdered(a, b any, desc bool, less KeyLess) int
- func CompareRows(a, b map[string]any, keys []types.OrderKey, orders KeyOrders) int
- func RegisteredTypes() []types.WindowType
- func Sort(rows []map[string]any, keys []types.OrderKey)
- func SortKeyed(rows []map[string]any, keys []types.OrderKey, orders KeyOrders)
- func SortOrder(rows []map[string]any, keys []types.OrderKey) []int
- type KeyLess
- type KeyOrders
- type Resolver
- type ScaledDecimal
- type SortValuer
- type WindowComputer
- type WindowFactory
- type WindowOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Apply ¶
Apply runs every window in windows over rows. Equivalent to ApplyWithExt with a nil Resolver; preserved so existing callers and per-operator unit tests stay shape-compatible.
func ApplyKeyed ¶
func ApplyKeyed(ctx context.Context, rows []map[string]any, windows []*types.Window, resolve Resolver, orders KeyOrders) error
ApplyKeyed is ApplyWithExt under grouper key orders: an order_by key whose column orders names (a grouped row's grouper key column) sorts by that grouper's intrinsic key order (CompareKeyOrdered), and a keyOrderedComputer (WIN_RANK / WIN_DENSE_RANK) judges ties through the same comparator. Nil orders is ApplyWithExt, byte-identically.
func ApplyWithExt ¶
func ApplyWithExt(ctx context.Context, rows []map[string]any, windows []*types.Window, resolve Resolver) error
ApplyWithExt runs every window in windows over rows. Each window:
- Resolves a (partitionBy, orderBy) sort over the row slice. Sorts are cached by tuple key so multiple windows sharing a partition+order pay one sort cost.
- Builds partitions from the sorted index slice.
- Invokes the operator's Compute to mutate rows with the output column.
resolve is the operator resolver (see Resolver). Nil takes the built-in-only path; an unresolved type fails with the canonical unknown-window error.
func CompareKey ¶
CompareKey orders two cells under one sort key: negative when a sorts before b. Desc reverses the order of NON-NULL values only — a null (nil or missing) trails in BOTH directions. Reversing compareCell wholesale instead flipped the null term too, so every Desc key put its nulls FIRST while the contract (window order_by, Request.Sort, post-test order_by) says nulls last regardless of direction. Every ordering arm in the engine routes through here.
func CompareKeyOrdered ¶
CompareKeyOrdered is CompareKey under a grouper key order: when less is non-nil and both cells are strings (grouper keys), they compare by less — reversed under desc — instead of byte-wise. A null, a non-string cell, or a nil less keeps CompareKey's order exactly, so a key the grouper does not rank (an ISO date) and every numeric column order as before.
func CompareRows ¶
CompareRows orders two rows under keys: the first key whose cells differ decides, each through CompareKeyOrdered with its column's KeyLess (orders[key.Field], nil when orders does not name it). Negative when a sorts before b; 0 when equal on every key. It is the one row comparator of Request.Sort, window ORDER BY and post-test order_by.
func RegisteredTypes ¶
func RegisteredTypes() []types.WindowType
RegisteredTypes returns all registered window types. Order is map iteration order; callers that need determinism must sort the result.
func Sort ¶
Sort orders rows in place by keys. Stable sort; nulls last regardless of each key's Desc direction. Used by the processor for response-level sort (Request.Sort) and reusable by callers who want a top-level reorder.
When keys is empty, Sort is a no-op.
func SortKeyed ¶
SortKeyed is Sort under grouper key orders: a key whose column orders names compares two string cells by that column's KeyLess (CompareKeyOrdered). Nil orders is Sort.
func SortOrder ¶
SortOrder is Sort without the reorder: it returns the permutation Sort applies to rows — out[j] is the index (into rows) of the row Sort places at position j — leaving rows untouched. Same comparator, same stability (ties keep their input order), nulls last in both directions. Nil when keys is empty (the identity order). The materialize path orders source indices with it, so its output rows follow exactly the order Request.Sort gives Process's row set. It takes no key orders: materialize refuses groups, so its rows carry no grouper key column.
Types ¶
type KeyLess ¶
KeyLess orders two string cells of one column ascending: true when a sorts strictly before b. It is a grouper's intrinsic key order — the window package cannot see groupers, so the engine hands the order in as data (KeyOrders). It must be a strict weak order whose ties are exactly equal strings, so a key it does not rank still orders byte-wise.
type KeyOrders ¶
KeyOrders maps a grouper key column (a grouped row's key cell) to its grouper's intrinsic key order: GROUP_DATE day_of_week Monday-first, GROUP_DATE_RANGES / GROUP_NUMERIC_RANGES labels in supplied order, the numeric bucket groupers by value. Every sort here — Request.Sort (SortKeyed), window ORDER BY (ApplyKeyed) and WIN_RANK / DENSE_RANK ties — compares a column it names through CompareKeyOrdered. Nil (or a column it does not name) is the plain CompareKey order.
type Resolver ¶
type Resolver func(t types.WindowType) (WindowFactory, bool)
Resolver resolves a window type to its factory. The engine passes processing.ExtensionRegistry.LookupWindow, which consults the embedder overlay and the instance feature set before the built-in registry. A nil Resolver is the built-in registry alone (Lookup).
type ScaledDecimal ¶
type ScaledDecimal struct {
Value encoding.Decimal128
Scale uint8
}
ScaledDecimal is a decimal128 cell carrying its scale, the SortValue of a decimal aggregate result or record-row decimal cell. Two of the same scale order exactly by Decimal128.Cmp; across scales, or against a plain number (an aggregate that fell back to f64), by Float64.
type SortValuer ¶
type SortValuer interface {
SortValue() any
}
SortValuer is implemented by a cell value whose order is not its own Go value: compareCell orders it by SortValue() instead. A nil SortValue is a null.
type WindowComputer ¶
type WindowComputer interface {
Compute(rows []map[string]any, partitions [][]int, label string) error
}
WindowComputer mutates rows in place to add a window operator's output column.
partitions is a slice of partition row-index slices already sorted by the window's OrderBy keys. label is the pre-computed output column name.
type WindowFactory ¶
type WindowFactory func(w *types.Window, opts WindowOptions) (WindowComputer, error)
WindowFactory creates a WindowComputer from a Window spec.
func Lookup ¶
func Lookup(t types.WindowType) (WindowFactory, bool)
Lookup returns the factory for a window type, if registered.
type WindowOptions ¶
type WindowOptions struct{}
WindowOptions reserves room for future schema-aware operators.
Source Files