Prompt
"Revenue by store last month"
Govern your data; don't constrain it.
Authoring governed packages, putting an agent or UI in front of the API, and debugging why the planner picked the path it did. Check out the workflows below.
Author graph-first packages without flattening the semantic model.
For teams moving from ad hoc metrics files or SQL-first marts toward explicit semantic packages with entities, model-level measures, time roles, and thin curated metric layers.
- Directory packages:
package.yml,graph.yml,models/**,metrics/**. - Measures live close to the tables that own their grain.
- Keep derived metrics thin so the planner has strong primitives.
package.yml
-> graph.yml -> models/ -> metrics/
| Authoring concern | Runtime support | Why it matters |
|---|---|---|
| Graph-first identity | Strongly supported | Stable roots and safe traversal policy |
| Historical joins | Supported with guardrails | Preserve semantic meaning across validity windows |
| Clock variants and comparison families | Supported natively |
Helps callers compare ordered versus delivered or peer metrics cleanly |
Build agent and UI query flows on top of the same public API.
A guided builder path for internal apps, exploration tools, and LLM agents — without turning each caller into a mini planner. The same engine serves HTTP/JSON and MCP.
- Start from business language:
discoverranks object matches, and empty terms list the catalog. - Inspect stable object cards before suggesting dimensions, values, or clocks.
plandrafts the query andvalid-valueskeeps filters legal; over HTTP,build-optionsalso lists the next legal edits.
Discovery
discover ranks candidate metrics,
measures, and dimensions.
Builder
plan drafts Query IR and
valid-values returns legal filter
values.
Execution
execute validates, compiles, and runs;
its validate and sql modes
stop early, and sql at compact verbosity
includes the explain payload.
Debug semantic behavior with concrete planner artifacts.
When the problem is not just returning rows but understanding why a query was legal, illegal, rewritten, or blocked.
inspect— semantic provenance and starter query patches.compile’s explain payload (over MCP,executeinsqlmode) — chosen paths, rewrites, rendered SQL.- Anchor product discussions in inspectable planner output, not screenshots.
Inspect
Check object summaries, clocks, comparison metadata, and recommended next actions.
Explain
Trace alias resolution, path selection, rewrite strategy, and SQL lowering.
Compare
Use the comparison pack to see how six layers express the same questions. Five were checked on current data against an independent answer key; Snowflake's older capture is reported separately. One published rubric assigns every support label and explains its limits.