id: tabular_aggregate
name: Aggregate
description: >
  Group rows and compute aggregate statistics. Supports SQL aggregate
  functions: COUNT, SUM, AVG, MIN, MAX, etc. Optionally filter groups
  with HAVING and order/limit results.
version: 1.0.0
category: summarize
type: table-to-table
default_implementation: duckdb

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

requires: {}  # structural — operates on any table

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

params:
  group_by:
    type: array
    description: >
      Column names to group by. Each unique combination of values
      produces one output row.
    required: true
  aggregations:
    type: object
    description: >
      Map of output_column_name -> SQL aggregate expression.
      Example: {"total_sales": "SUM(amount)", "avg_price": "AVG(price)"}
    required: true
  having:
    type: string
    description: SQL HAVING clause to filter groups (e.g., "SUM(amount) > 100")
  order_by:
    type: array
    description: Columns to sort results by (e.g., ["total_sales DESC"])
  limit:
    type: integer
    description: Maximum number of result rows
    min: 1

# 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:
  rust-engine:
    op: tabular_aggregate
    function: throughput_tabular_host::tabular_aggregate_op
    dispatch: products/sdk/folia-engine/src/lib.rs:854
  js:
    function: tabular_aggregate
    dispatch: packages/compute/src/ops/tabular-aggregate.ts
  python:
    function: tabular.ops.aggregate
    dispatch: folia/compute.py _BUILTIN_OP_MAP

display_hints:
  table:
    renderer: tanstack-table
    sortBy: count
    sortOrder: desc
  chart:
    renderer: observable-plot
    chartType: bar