Skip to main content

​
canonic query

Resolve, compile, and execute a semantic query read-only. 
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
FlagDescription
--metricsMetric name(s): comma-separated and/or repeatable (--metrics a,b == --metrics a --metrics b).
--dimensionsDimension name(s): same comma/repeat rules as --metrics.
--filterA filter as field=value or field:op:value (repeatable), e.g. amount:>:100, status:!=:refunded, status:in:paid,refunded.
--file, -fSemantic query JSON file.
--harnessBenchmark/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.
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.

​
canonic sql

Execute a read-only SQL string on a named connection; the escape hatch for when no metric/dimension covers the question. 
canonic sql "SELECT customer_id, SUM(amount) FROM orders GROUP BY 1" --connection warehouse
Argument / FlagDescription
statementA read-only SELECT statement (positional).
--connection, -cConnection 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. 
canonic assert
canonic assert --min-accuracy 0.95
FlagDescription
--min-accuracyAccuracy 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.