# The SQL runner

> A governed, read-only SQL surface for writing SQL by hand — SELECT-only, entitlement-gated, off by default, and fully audited.

*[View this page in the Flax docs](https://flax-analytics.com/docs/exploring/sql-runner)*

Most questions belong in the point-and-click builder, where every query is
generated from governed models. Some are faster to express directly in SQL. The
governed SQL runner is a controlled way to do that — a "SQL island" that runs raw
SQL under strict guardrails rather than through the trusted semantic compiler.

> [!IMPORTANT]
> The SQL runner is an entitlement-gated capability that is **off by default**. An
> administrator must turn it on for a team before anyone can use it. If you do not
> see it, your organization has not enabled it.

## Why it is separate from the builder

Flax's compiler is *generation-only*: every normal query is generated from the
semantic model and never accepts raw SQL, which is the foundation of its
access-filter and row-level-security guarantees. Free-form SQL cannot pass through
that path, so it runs on a separate, constrained surface instead.

Do not confuse the SQL runner with the **SQL** tab in the Explore result view —
that tab only *displays* the compiled SQL of a generated query, read-only.

## How it stays governed

The runner is deliberately narrow:

- **Read-only.** Only `SELECT` statements are allowed. Writes and DDL are rejected,
  and queries run under a warehouse role scoped to read access, with a statement
  timeout and a row cap.
- **Scoped per team.** The runner uses a connection scoped to the caller's team, so
  you can only reach data your team is entitled to reach at all.
- **Results are flagged as raw.** Unlike generated queries, raw SQL results do not
  inherit the model's [row-access filters](/docs/modeling/row-access-filters). They
  are labelled as raw, not access-filtered, in the UI and in the audit log so the
  distinction is never lost.
- **Audited.** Every run is recorded in the [audit log](/docs/administration/audit-log)
  as a query with a raw-SQL source.

> [!WARNING]
> Because raw-SQL results are not row-filtered by the model, administrators should
> only grant the runner to teams whose connection is already scoped to data they
> may see in full.

## Working with results

Run your SQL to see the returned rows. From there you can inspect what executed in
[query detail](/docs/exploring/query-detail), turn the result into a
[chart](/docs/visualizations/overview), or continue in a [sheet](/docs/sheets/overview).

## Next steps

- [Building queries](/docs/exploring/building-queries)
- [Row-access filters](/docs/modeling/row-access-filters)
- [Data entitlements](/docs/administration/data-entitlements)
- [Audit log](/docs/administration/audit-log)