id: tabular_window
name: Window
description: >
  Compute values relative to other rows — rankings, percentiles, running
  totals, row comparisons. Each row keeps its identity (unlike aggregate,
  which collapses rows). Optionally partition so computations reset within groups.
version: 1.0.0
category: transform
type: table-to-table
default_implementation: duckdb

inputs:
  - name: table
    type: table
    format: parquet
    description: Input table
    required: true

requires: {}  # structural — operates on any table

outputs:
  - name: result
    type: table
    format: parquet

params:
  windows:
    type: array
    required: true
    description: >
      List of window computations. Each entry adds a new column.
    items:
      type: object
      properties:
        column:
          type: string
          description: Column to compute over (ignored for row_number/rank)
        function:
          type: string
          enum: [row_number, rank, dense_rank, percent_rank, ntile,
                 lag, lead, sum, avg, cume_dist]
        alias:
          type: string
          description: Output column name (default "{function}_{column}")
        order_by:
          type: array
          description: >
            Ordering for this window computation. Required for lag/lead.
            For ranking functions (row_number, rank, dense_rank, percent_rank,
            cume_dist), defaults to ["{column}"] when omitted.
        ntile_buckets:
          type: integer
          description: Number of buckets (required for ntile)
          min: 1
        offset:
          type: integer
          description: Row offset for lag/lead (default 1)
          default: 1
  partition_by:
    type: array
    description: >
      Columns to partition by. The function resets for each group.
      Example: ["province"] ranks within each province.

# backends: audited 2026-08-14 (defect 50). A key means a runtime that DISPATCHES this op —
# folia-engine `dispatch_op` (products/sdk/folia-engine/src/lib.rs), a `registerOp`/OP_TABLE
# entry in packages/compute, `_BUILTIN_OP_MAP` in folia/compute.py, or a backend manifest
# (folia/backends/*/backend.yaml).
backends:
  js:
    function: tabular_window
    dispatch: packages/compute/src/ops/tabular-sql.ts
  python:
    function: tabular.ops.window
    dispatch: folia/compute.py _BUILTIN_OP_MAP

display_hints:
  table:
    renderer: tanstack-table