> ## 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`. |
| `--file`, `-f` | Semantic query JSON file.                                                                                                         |
| `--harness`    | Benchmark/CI mode: run matching assertions and exit `10` (`ASSERTION_FAILED`) on a mismatch.                                      |

`--metrics`/`--dimensions`/`--filter` and `-f` are mutually exclusive; pick one way to build the query per invocation; passing both is a usage error. The flags build the identical `SemanticQuery` a JSON file would deserialize: `{"metrics": [...], "dimensions": [...], "filters": [...], "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).
</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`). |

Non-`SELECT` statements are rejected with `READ_ONLY_VIOLATION` (exit `11`).

## `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
```

| Flag             | Description                                                                                                           |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--min-accuracy` | Accuracy floor for the CI gate (default `1.0`; every assertion must hold). Below it, exits `10` (`ASSERTION_FAILED`). |

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.