Getting started — Engine

GridDataEngine is the Polars OLAP engine on its own — the IP behind every surface. Use it headless for server-side aggregation, to feed a custom frontend, or in a notebook.

from dash_tensor_grid import GridDataEngine

# Agnostic ingestion: a list[dict], pandas/Polars DataFrame, or JSON string.
engine = GridDataEngine(sales)

# The full nested aggregation tree (stable ids + subRows), JSON-safe.
tree = engine.get_tree_payload(
    group_by=["region", "country"],
    agg={"revenue": "sum", "cost": "sum"},
    grand_total=True,
)

# Column defs the frontend renders (accessorKey / header / type / formatStr).
cols = engine.make_column_defs(["region", "country"], {"revenue": "sum", "cost": "sum"})

# Drill-through: the source rows behind an aggregated node.
rows = engine.drill_through(["region", "country"], ["EMEA", "Germany"])

# Pivot / cross-tab: rows x cols, both halves computed.
pivot = engine.pivot(rows=["region"], cols=["category"], agg={"revenue": "sum"})

Calculated measures & the formula DSL

from dash_tensor_grid.formula import calc, agg

tree = engine.get_tree_payload(
    ["region"],
    agg={"revenue": "sum", "cost": "sum"},
    calculated={"margin": calc("(revenue - cost) / revenue")},
)

The @tensorgrid/core TypeScript package mirrors this API (treePayload, pivotGrid, drillThrough, calc, agg, …) so a JS backend or a fully custom frontend gets the same, parity-verified results. See the Core engine API reference.