window

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, orderable types) belongs to descriptor/predict_window.go and must run 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 RegisteredTypes() []types.WindowType
• func Sort(rows []map[string]any, keys []types.OrderKey)
• type WindowComputer
• type WindowFactory
  • func Lookup(t types.WindowType) (WindowFactory, bool)
• type WindowOptions

Functions

func Apply

func Apply(ctx context.Context, rows []map[string]any, windows []*types.Window) error

Apply runs every window in windows over rows. Equivalent to ApplyWithExt with a nil overlay; 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, extFactories map[types.WindowType]WindowFactory) error

ApplyWithExt runs every window in windows over rows. Each window:

1. 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.
2. Builds partitions from the sorted index slice.
3. Invokes the operator's Compute to mutate rows with the output column.

extFactories is an optional embedder-registered overlay. Nil takes the built-in-only path; non-nil consults the overlay before falling through to the package-level registry.

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

func Sort(rows []map[string]any, keys []types.OrderKey)

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.

Types

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.