How Orion writes SQL

When you ask Orion a data question, it does not just guess a SELECT and run it. Orion is built semantic-layer-first: it always checks your governed reveals before writing any SQL, prefers running a reveal when one matches, and falls back to raw SQL only when nothing in the semantic layer covers your question.

This page explains exactly what Orion does under the hood, the guardrails that keep its queries safe and governed, and the two supporting features — the optional SQL reviewer and the "Explain the SQL" helper.

Overview

Every analytical answer Orion produces follows a fixed routing order:

1. Call get_reveals first — before writing any SQL, for every analytical question, Orion searches your reveals for one that covers the concept you asked about (revenue, orders, customers, returns, products, inventory, and so on).
2. Run the reveal if one matches — when a relevant reveal exists, Orion calls run_reveal instead of writing SQL. Reveals carry the correct metric definitions, joins, and warehouse SQL dialect, so the answer matches your governed numbers.
3. Raw SQL only as a last resort — if and only if no reveal covers the question, Orion writes raw SQL with run_sql. When it does, it tells you so plainly with a line like "No reveal covers this — using raw SQL."

This order is not a suggestion to the model — it is enforced by hard guardrails described below. Raw SQL is read-only, and ungoverned raw SQL is restricted to Luminary so your row- and field-level security still applies to everyone else.

When to use it

You do not invoke this behavior directly — it runs every time Orion answers a data question. Understanding it helps when you want to:

• Trust a number. Read Orion's provenance footer to see whether the answer came from a governed reveal or from raw SQL.
• Diagnose a "wrong" answer. If a figure looks off, knowing whether it was reveal-backed tells you whether to fix a reveal definition or whether Orion fell back to ad-hoc SQL.
• Understand a permission message. If Orion tells you raw SQL is restricted to admins, this page explains why and what to do instead.

Concepts

Getting started

Nothing to set up. Open the Orion chat panel and ask a data question — for example, "What was revenue last week?" Orion handles reveal lookup, execution, and provenance automatically.

A few things determine what Orion can do:

• Reveals must exist for Orion to answer from the semantic layer. The more of your key metrics are modeled as reveals, the more answers stay governed. See Reveals and Accuracy.
• Your role determines whether Orion can fall back to raw SQL on your behalf. Only Luminary can run ungoverned raw SQL.
• The SQL reviewer is off by default and is enabled per workspace by a Luminary.

Step-by-step

get_reveals({ search: "revenue" })
→ run_reveal({ domain_name: "bigquery_ecommerce", reveal_name: "orders_analysis", date_from: "...", date_to: "..." })

> Source: orders_analysis (semantic layer) · Freshness: 2024-12-22 · Confidence: high

-- Orion: "No reveal covers this — using raw SQL."
SELECT status, COUNT(*) AS n
FROM orders
WHERE created_at > (SELECT MAX(created_at) FROM orders) - INTERVAL 7 DAY
GROUP BY status

Orion can only execute read queries. "UPDATE" statements are not permitted.