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 ApplyWithExt(ctx context.Context, rows []map[string]any, windows []*types.Window, ...) error
- func CompareKey(a, b any, desc bool) int
- func RegisteredTypes() []types.WindowType
- func Sort(rows []map[string]any, keys []types.OrderKey)
- func SortOrder(rows []map[string]any, keys []types.OrderKey) []int
- 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 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 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 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.
Types ¶
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