Skip to main content
Handlers are the ontology’s API. Every handler has a name, a zod input and output, and declares what it reads and edits. Tilde turns each read and action into an agent tool, and a typed RPC for spaces and apps.

Transactional views

A transactional view groups the objects that change together under one key. Customer with key acme holds that customer, its invoices, tickets, and notes. Reads and actions on a view instance see a consistent, up-to-date state, and an action’s edits commit together.
ontology/customer.ts
Each table is a model with materialized: "cell" and a column named after the view key. The root table is keyed by it. An object lives in at most one view. Ontology-owned objects, like CustomerNote, belong to the view that lists them in dependsOn.

Reads

A read in a view gets the view instance as view, keyed by view.key.
  • reads is a hard limit. A handler sees only the objects and properties it declares.
  • prop(Customer.internalNotes) tags an output field with its property. Callers who may not read that property get it unset. See Field masking.
  • ctx.sql runs read-only SQL over the view instance, with objects as tables: ctx.sql('SELECT sum(amount) AS total FROM Invoice WHERE status = ?', "open").
A read without a view queries across all data with ctx.lake.query. It is eventually consistent, seconds behind actions. It must scope its own rows, from ctx.principal, when that matters.
Objects are tables named after the object, with a column per property. N:M links are tables too, such as AccountTeam(from_key, to_key).

Actions

An action changes one view instance in a transaction.
edits is a hard limit, like reads. With idempotency, a repeat with the same key by the same caller replays the first outcome. An action ends as succeeded, failed, denied, or pending approval. See Approvals.

Call third parties

Actions never call third parties during the transaction. ctx.deferredFetch records the request, and Tilde sends it after the action commits. It retries with backoff, in order per origin, with an Idempotency-Key header. Name a connection slot as auth. Tilde adds the account’s current credentials when it sends the request. Handlers never see them.
ctx.deferredFetch is fetch-compatible, so you can pass it to an SDK as its fetch. Reads can make live calls with ctx.fetch(url, init, { auth: slot }). Options of ctx.deferredFetch:

Pending values

When an action changes a value the source owns, such as a tier in Stripe, declare the property in pending. Reads then show the expected value until the change comes back through the pipeline.

Secrets and settings

Declare per-environment values in env, and read them from ctx.secrets and ctx.settings.
Prefer connection slots for third-party accounts. Settings keep their defaults unless an environment overrides them, which lets a test environment point at a stand-in API. See Secrets and settings.

Realtime views

A realtime view is a read whose result is pushed to subscribers whenever it changes. A view-scoped one re-runs after every commit in its view instance. One with watch runs across all data, and re-runs when a watched object changes.
List them in ontology({ realtime }). Spaces subscribe with useRealtime. See Spaces.

Handlers as agent tools

Every read and action becomes an agent tool with the handler’s name, description, and input schema. A tool for a handler in a view takes { "key": "<view key>", "input": { ... } }. Other tools take { "input": { ... } }. Write each description for the agent that calls it. Give agents a view-less read that lists keys, such as topCustomers, so they can find the instance to act on. To connect an agent, see Give an agent the ontology.