> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcanonic.app/llms.txt
> Use this file to discover all available pages before exploring further.

# canonic query / sql / assert

> Execute queries, run raw read-only SQL, and gate on accuracy.

## `canonic query`

Resolve, compile, and execute a semantic query read-only.

```bash theme={null}
canonic query --metrics revenue --dimensions order_date
canonic query --metrics revenue --filter "status=paid"
canonic query --file query.json
canonic query --file query.json --harness
```

| Flag           | Description                                                                                                                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--metrics`    | Metric name(s): comma-separated and/or repeatable (`--metrics a,b` == `--metrics a --metrics b`).                                                                                                  |
| `--dimensions` | Dimension name(s): same comma/repeat rules as `--metrics`.                                                                                                                                         |
| `--filter`     | A filter as `field=value` or `field:op:value` (repeatable), e.g. `amount:>:100`, `status:!=:refunded`, `status:in:paid,refunded`.                                                                  |
| `--via`        | Join-path alias prefix (comma-separated and/or repeatable) to disambiguate an `ambiguous_join_path` error.                                                                                         |
| `--limit`      | Row cap injected by the dialect adapter.                                                                                                                                                           |
| `--file`, `-f` | Semantic query JSON file.                                                                                                                                                                          |
| `--harness`    | Benchmark/CI mode: run matching assertions and exit `10` (`ASSERTION_FAILED`) on a mismatch.                                                                                                       |
| `--tenant`     | Bind a fixed, roleless principal for local development / platform-operator use. Always logs a warning. See [Tenancy & access control](/concepts/tenancy-and-access-control#--tenant-cli-override). |

`--metrics`/`--dimensions`/`--filter`/`--via`/`--limit` and `-f` are mutually exclusive: pick one way to build the query per invocation, since passing both is a usage error. The flags build the identical `SemanticQuery` a JSON file would deserialize: `{"metrics": [...], "dimensions": [...], "filters": [...], "via": [...], "limit": null}`. Use `-f` once a query grows more filters or joins than is comfortable inline. Without `--harness`, any matching assertions are informational only and never block. With `--json`, the output matches the MCP `query` tool's payload byte-for-byte.

<Note>
  If a `--dimensions` name exists on more than one join-reachable source, the query fails with `ambiguous` and a `candidates` list of `alias.dimension` values to qualify with. See [Resolving `ambiguous`](/reference/error-codes#resolving-ambiguous). If a metric's join path to a dimension's source is itself ambiguous (more than one route through declared `joins`), the query instead fails with `ambiguous_join_path` and a `candidates` list of alias sequences: pass one as `--via` (e.g. `--via dim_customer,dim_sales_rep`) to select that path.
</Note>

## `canonic sql`

Execute a read-only SQL string on a named connection, the escape hatch for when no metric/dimension covers the question.

```bash theme={null}
canonic sql "SELECT customer_id, SUM(amount) FROM orders GROUP BY 1" --connection warehouse
```

| Argument / Flag      | Description                                                                                                                                                                                        |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `statement`          | A read-only `SELECT` statement (positional).                                                                                                                                                       |
| `--connection`, `-c` | Connection id (defaults to `project.default_connection`).                                                                                                                                          |
| `--tenant`           | Bind a fixed, roleless principal for local development / platform-operator use. Always logs a warning. See [Tenancy & access control](/concepts/tenancy-and-access-control#--tenant-cli-override). |

Non-`SELECT` statements are rejected with `READ_ONLY_VIOLATION` (exit `11`). Raw SQL bypasses the compiler entirely, so under an active tenancy policy `canonic sql` is additionally gated by the [`run_sql` gate](/concepts/tenancy-and-access-control#the-run_sql-gate): refused with `TENANT_FORBIDDEN` (exit `24`) unless the caller's role allows `run_sql` and the target connection attests `rls_enforced: true`.

## `canonic assert`

Run the accuracy harness over all loaded assertions and gate on the result. This is the CI integration that turns ">90% accuracy" from aspirational into measured.

```bash theme={null}
canonic assert
canonic assert --min-accuracy 0.95
canonic assert --baseline
```

| Flag             | Description                                                                                                           |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--min-accuracy` | Accuracy floor for the CI gate (default `1.0`, every assertion must hold). Below it, exits `10` (`ASSERTION_FAILED`). |
| `--baseline`     | Also run the same assertions against a schema-only resolver and report the accuracy lift.                             |

Every executable assertion in `contracts/assertions/` is compiled, executed read-only, and compared to its expected value within tolerance. The harness reports `accuracy = passed / total` and prints any diverging checks. The `--min-accuracy` gate always applies to the canon accuracy, never the baseline.

With `--baseline`, the same assertions are also compiled against a resolver that only knows the raw physical schema: no curated bindings, aliases, or guardrails, so a metric name reachable only through an alias or composite binding fails to resolve. The gap between the two accuracy numbers (`lift`) is a measured, reproducible number for how much canon's curated context is worth, rather than an asserted one.