TarskiTarski/ docsJoin the waitlist

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.
  • description and parameter doc strings flow verbatim to discovery surfaces: Studio’s schema browser, MCP tool descriptions, and GET /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.
  • head and result: 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.