feat: support filtering on table calculations

[jpetey75]

Closes #21

⚠️ Stacked on #22 (base branch is feat/multiple-filters-same-field, not main). Review/merge #22 first, then I'll retarget this to main. The diff here is scoped to #21 only.

Problem

The SDK's filter system was dimension-only — there was no way to filter on table calculations, even though the API supports it via filters.tableCalculations.

Change

• TableCalculation(name, sql, display_name=None) — a SQL table calculation, with the same comparison operators (==, >, between, etc.) and helpers as Dimension.
• TableCalculationFilter — accepts a TableCalculation or a calc-name string; serializes as {target: {fieldId}, operator, values}.
• CompositeFilter.to_dict() now routes dimension vs table-calc rules into filters.dimensions / filters.tableCalculations respectively. The tableCalculations key is omitted when unused, so existing dimension-only payloads are unchanged.
• Query.table_calculations(...) builder method + model.query(table_calculations=...) kwarg.
• Extracted a shared _FieldFilterMixin for the &/| operators rather than duplicating them across filter classes.

from lightdash import TableCalculation

profit_ratio = TableCalculation(name="profit_ratio", sql="${orders.profit} / ${orders.revenue}")

query = (
    model.query()
    .metrics(model.metrics.revenue, model.metrics.profit)
    .table_calculations(profit_ratio)
    .filter(profit_ratio > 0.2)
)

Verification

Shapes were checked against the authoritative lightdash/common source types rather than guessed:

• Filters = { dimensions?, metrics?, tableCalculations? }, each a FilterGroup → confirms the filters.tableCalculations routing.
• FilterRule = { target: {fieldId}, operator, values } (server injects id) → confirms the rule shape. A live API call returning a filter-rule parse confirmed the API accepts exactly this shape.
• SqlTableCalculation = { name, displayName, sql } → confirms TableCalculation.to_dict().

Caveat: I could not produce a fully-green end-to-end run via the available tooling (the MCP query tool doesn't register custom SQL table calculations into the executed query). The serialization is confirmed by source + the API's filter parser; a final confidence check would be running the SDK against a live instance with an API token.

Tests

27 new tests in tests/test_table_calculations.py (calc serialization, operators, filters.tableCalculations routing, mixed dimension+calc filters, builder integration). Full unit suite green (81 passed).

🤖 Generated with Claude Code

[jpetey75]

End-to-end verification (live instance) — found & fixed a real bug

Ran the SDK against a live Lightdash instance with a real token. The first attempt failed with a 400, which source-reading alone hadn't caught:

CompileError: No function has been implemented to render SQL for the filter
operator "greaterThan" on "pv_copy" field of type "string"

Root cause: a table calculation with no declared type is treated as a string by the API, so numeric operators (>, between, …) won't compile. The filters.tableCalculations routing and rule shape were correct — the calc definition was just missing its type.

Fix (latest commit): TableCalculation now has a type field defaulting to "number" (emitted in to_dict(), matching TableCalculationBase). Override for non-numeric calcs (type="string" etc.).

After the fix — verified end-to-end: defined a calc, filtered calc > threshold, and confirmed the server returned exactly the rows a client-side filter would (every returned row satisfies the predicate; count matches). Added as a permanent env-gated acceptance test (test_query_table_calculation_filter), which passes live.

So this PR is now confirmed working end-to-end, not just shape-verified — and the earlier caveat about not being able to run E2E is resolved.