Refuse raw output from definition-side semantic expressions

[hussainsultan]

Problem

Executing a bare semantic model returned the complete raw table: every physical column at row grain, undeclared columns included, computed dimensions missing. Nothing about that result is semantic. The same hole existed for every output sink (sql, to_pandas, to_csv, … — 14 in total) and for every pre-aggregation chain:

model.execute()                      # raw SELECT *
model.filter(...).execute()          # raw filtered rows
model.group_by("cust").execute()     # raw UNGROUPED rows — silent-wrong
model.query().execute()              # raw SELECT *

Contract

A semantic model is a definition, not a query (matching Malloy, where run: source without a query stage is a compile error). Output now requires a completed query; raw access stays one explicit call away:

model.group_by("cust").aggregate("revenue").execute()   # query — works
model.query(dimensions=[...], measures=[...]).execute() # query — works
model.to_untagged().execute()                           # explicit raw escape hatch
model.execute()                                         # QueryError with guidance

• All 14 output sinks guard via _ensure_executable(); the error names the model, lists its declared dimensions/measures, and shows the intended spellings.
• group_by without aggregate gets a dedicated error pointing at .aggregate(...) (an empty .aggregate() returns distinct grouped values).
• query() with neither dimensions nor measures fails eagerly.

Post-aggregation mutate

Per the direction that post-aggregate row math belongs on to_untagged() (calc measures are the semantic mechanism), .mutate() chained after filter/order_by/limit on an aggregate now raises instead of materializing a pseudo-model:

agg.mutate(share=lambda t: t.revenue / t.all(t.revenue))  # measure path — still works
agg.order_by("x").mutate(...)                             # raises → use .to_untagged().mutate(...)

The _build_post_aggregate_model wrapper is deleted, along with the now-unreachable non-additive-total refusal machinery (_non_additive_result_columns, NonAdditiveTotalError) — the surviving measure path computes totals from the underlying rows, so it gets the mean case right (verified in test_totals_semantics.py) rather than needing to refuse it.

What stays executable

Results, not definitions: aggregates and their filter/order_by/limit chains, .index() results, as_table() over a completed query, and compare_periods() output — tracked via a new _materialized_result flag on SemanticTableOp that survives metadata rebuilds.

Docs

Agent help topics and the four bsl-query-expert doc copies now teach window functions via .to_untagged() (the old order_by().mutate() recipe raises) plus the two new gotchas; ADR 0001 carries an amendment note.

Tests

• New test_execute_guard.py pins the contract (30 tests).
• Existing tests that inspected raw rows (join alias soundness, unnest, derived-dim filters) now use the explicit .to_untagged() spelling; the post-agg mutate tests assert the refusal and verify the to_untagged equivalent produces the old values.
• Full suite: 1334 passed + 13 integration (Malloy) passed.

Noted while testing (pre-existing, not addressed here)

agg.mutate(share=t.total / t.all(t.total)) over integer measures truncates to 0.0 on the memtable → canonical-backend (xorq/DataFusion) path, while the compiled SQL carries the float cast and duckdb executes it correctly — same family as the ibis/xorq flavor-audit defects. Pinned on duckdb in test_totals_semantics.py with a comment.

🤖 Generated with Claude Code