Declared queries
The named, typed, parameterized read surface over your derived worldview, covering authoring, exposure, validation, and the query engine that runs it.
Declared queries are Tarski’s read surface. Each queries/*.ta file declares one named,
typed, parameterized query over the app’s derived worldview. Queries are validated at load
time against relation declarations, projections, and decision-rule coverage. They are the
only query form that agent models may request; free-form Datalog is reserved for
authorized humans and dev surfaces.
Authoring a query
query "impacted-services"
description "Services inside one root cause's blast radius, joined with whether each service is itself reporting degraded health."
parameter root_service: text "The root-cause service whose blast radius to read."
expose agent, studio
head (service_id: text, health: text)
relation radius_member(service_id: text)
rule radius_member(service_id) :-
triage.blast_radius(service_id, root_service).
rule result(service_id, "degraded") :-
radius_member(service_id),
infra.degraded(service_id).
query "name": quoted kebab-case, mapped to a snake_case relation name; collisions fail the load.descriptionand parameter doc strings flow verbatim to discovery surfaces: Studio’s schema browser, MCP tool descriptions, andGET /v1/queries. They are not part of query identity.parameter: typed binding sites. Executions with missing, unknown, or mis-typed bindings are rejected before evaluation.expose: which doors can reach the query (agent,api,studio,mcp). A query with no exposure is private: it loads and is validated, but no door can reach it.headandresult: the typed result signature and the reserved relation your rules derive into.
Queries are full Datalog programs, so you can collapse chained lookups into one
pre-joined compound query. Prefer that pattern to multiple round trips. Wire query files
in the manifest with [paths] queries = ["queries/*.ta"]. Load-time validation uses
stable diagnostics (E1040–E1047 parse, E2601–E2611 validation), and edits
hot-reload under tarski dev.
Agent exposure requires decision coverage
A model can request an agent-exposed query, so the query needs an explicit policy: a
decision.approved.* rule with a positive dependency on the query’s typed proposal
relation (proposal.query_requested.<mapped_name>). A deny-only policy must be
acknowledged in the manifest ([queries."name"] deny_only = true). The full read loop,
including budgets, denials, and result gating, is documented on
the agent query relay.
The engine underneath
Every query, declared or ad-hoc, compiles into an isolated micro-program that runs against an immutable snapshot of committed facts at a pinned head. The micro-program uses the evaluator’s own compilation and rule machinery, so query semantics match ontology semantics.
- Reads are projection-scoped. Scoping happens when the query’s input database is constructed: rows outside the caller’s projection are left out of it, so nothing is redacted in place. Negation cannot probe hidden rows, and explain output never reveals hidden counts.
- Reads run at a pinned head. The default is the current committed head, and historical committed heads re-materialize deterministically. A never-committed head fails closed with a typed diagnostic; the query never runs silently at a different head.
- Result envelopes are deterministic. Results carry canonical rows in a stable order plus the full identity stamp: snapshot identity, projection identity, and query, binding, and result digests. You can drill into row provenance: positive supports appear as committed fact ids, aggregates carry input-set witnesses, and negation-dependent rows carry re-checkable absence witnesses.
- Explain output is a deterministic artifact that names strata, per-rule plans, join order, index selection, and relation row counts. It is digest-stable for the same query at the same head.
- Bounds on result rows, evaluation steps, memory, and wall-clock time all fail closed with typed diagnostics. Windowed pagination uses continuation tokens bound to execution identity, and at a pinned head the pages are disjoint and exhaustive.
Running queries
tarski query booking-status --bindings '{"date":"2026-07-22"}'
tarski query impacted-services --bindings '{"root_service":"payments"}' --explain
tarski query --adhoc-file exploration.ta --head 41
The CLI door runs audited, unpaginated, complete canonical results. Over HTTP,
tarski serve exposes GET /v1/queries (discovery),
POST /v1/queries/{name}/execute, POST /v1/queries/{name}/explain, and scope-gated
POST /v1/queries/adhoc. For coding agents, tarski mcp serves a read-only MCP server
over stdio. It refuses to start without --actor-id and --projection. Every door, its
authorization ladder, and the access-audit plane are documented in
Identity & tenancy and the
CLI reference.
Identity discipline
Full query files join the package digest. Only an agent-exposed query’s result
relation signature (name, head columns, parameters) joins the evaluator digest, because
result observations must be interpreted into atoms, which makes their shape semantic.
Body and description edits never rotate the evaluator identity, and spectator-only
queries do not affect it at all. See Worldviews & lineages.