Querying

Those are five keys and four things. Meridian Line carries two of them — meri canonical and meridian short — so the trigram query returns a row per matching key, and a caller that hydrates each one fetches the same operator twice. LOOKUP answers "which nodes match this string", which is the question that was actually asked, so it returns the operator once and reports which key matched, and nothing is hidden by the deduplication.

The mode is also a cascade rather than a query: exact canonical first, then short and alias, then a soft node by its bare name, and only then trigram, each stage short-circuiting if it found anything. You can watch it short-circuit — FUZZY LOOKUP "meridian" comes back with "match_kind": "short" and "score": 1, having never reached the trigram stage, because the string it was given is a key that exists. Fuzzy matching a name that is spelled correctly is a way to get a worse answer slowly, and that ordering is the sort of thing you write once rather than in every prompt.

Each mode stands over a different Postgres feature — pg_trgm here, pgvector under SEMANTIC, tsvector under TEXT, joins and WITH RECURSIVE over aiq.edges_current under GRAPH — and a model writing raw SQL has to pick the right one, with the operator that matches the index, and an embedding from the same model the column was written with. The failures there are quiet ones: a distance operator that does not match the opclass returns rows in the wrong order rather than an error, and a vector from the wrong model returns a number rather than an error. The dialect turns those into refusals — SEMANTIC will not run against a space written by a different model, and a modifier that means nothing for a mode is rejected rather than ignored.

Two things in the response are there for the same reason. plan is what the parser understood, so a model can see that its query meant what it thought before reading a single row, and unresolved names which of the keys it asked for came back with nothing — the difference between "no such company" and "that company has no edges", which is the distinction an agent most often gets wrong.

None of this is an attempt to stop anyone writing SQL. Plain SQL is a mode of the dialect precisely because these seven will not cover a real question, and the escape hatch is the floor everything else sits on.

Related every mode and modifier · the mode that describes the others · how an agent reaches this over MCP

SCHEMA is the mode an agent reads before writing its first query, and it is a versioned capability document rather than a dump. Anything the catalog can prove is read from it — entity types off the registry, relations off the edge catalogue, models off aiq.embedding_models. Anything a catalog cannot express is written by hand, and then every hand-written example is run back through the compiler on each read.

That last part is what makes it trustworthy. A spelling this deployment no longer accepts reports itself instead of being served to an agent as authoritative, which a static document cannot do.

Related the `SCHEMA` syntax · the same mechanism for workflows

Registration records how to read your table as nodes rather than copying rows into a parallel store. The projection is kept in step by a statement-level trigger, so writing ten thousand included rows costs one set INSERT into nodes and node_keys rather than ten thousand trigger firings, and a bulk COPY disables it and pays one rebuild pass instead.

Letting chunks in would put the registry on the wrong side of the scale argument: a chunk is machine-generated volume that joins in after identity is already known. The same rule is why a workflow artefact gets the stored resource status rather than ready — step output is machine-generated too.

include_where is why a scrapped vessel stays in your table and stops being an identity anybody can look up. Nothing is deleted; it simply stops being findable by name.

org_expr is what keeps a tenant's vessel its tenant's. This is the sample's own registration, repeated, and registering again replaces the whole row — so an argument you leave out goes back to its default rather than keeping what was there. Without p_org_expr the default is null, and the next rebuild projects every vessel with no org and visibility = public, readable by every tenant.

There is a second way in. An uploaded file can be read by a structured-output extractor whose nodes and edges land through aiq.upsert_graph, so the things your documents mention sit in the graph beside the things your tables hold. That is a flag on the ingestion pipeline and it is off by default, because an embedding per chunk is cheap and a completion per window is a different order of money.

A node an extractor named is a soft node, keyed by its kind and name — project/harbour rewrite — because the same word can name two kinds of thing. LOOKUP finds it by the name alone once no typed node of that name exists, and the key it returns tells you which kind it was found under (REM-995):

select aiq.upsert_graph('{"nodes":[{"k":"project","n":"Harbour Rewrite"}],"edges":[]}',
                        '{"agent":"docs"}');
select r->>'key' as key, r->>'match_kind' as match_kind
  from jsonb_array_elements(aiq.query('LOOKUP "Harbour Rewrite"')->'rows') r;
-- project/harbour rewrite | soft

Related the extraction path · a fixture where the inclusion policy is visible

aiq.upsert_graph takes valid_from in its context, so a fact loaded today about January holds from January; when two sources state different starts, the earliest wins. aiq.close_edge ends exactly one current edge at a stated time, named by its id or by the memory that asserted it and its relation, and records who closed it; a close that names no edge, or several, is refused. Both are the worker's calls: run here as the owner, they are what an extractor or a reconciler writes. The rows stay, so the history is a query over aiq.edge_periods, each period with the provenance that began it.

GRAPH at depth 1 is a join over aiq.edges_current in both directions, and at depth 2 or more a WITH RECURSIVE over it, capped by depth and degree. There is no separate graph store, no migration to adopt it, and no second copy of anything to keep in step. Earlier releases walked it through SQL/PGQ's GRAPH_TABLE; SQL/PGQ was withdrawn from PostgreSQL 19 before GA, so the walk now uses nothing newer than 18.

A path length is written with DEPTH n.

Related what pins you to PG19 · the `GRAPH` mode

RLS applies, so results come back filtered to what the caller can see. Two things make results look like they are missing, and neither is a bug.

Querying as a superuser bypasses RLS unconditionally, so you see more rather than less, and the filtered views start behaving oddly around you. This is the failure this collection refuses to install into: every schema checks at load time that its owner is not a superuser, because an owner-privileged view owned by one disables RLS for every caller of that view, without a word.

No token at all is not narrow visibility, it is a wall: PostgREST falls back to web_anon, which holds no table grants and no usage on aiq, so /rpc/query answers permission denied for schema aiq with a 401. That is a different failure from the one below and it says so.

A token whose orgs claim names an org you are not a member of is the quiet one. It authenticates, RLS applies, and that org's rows are simply not there — so the query succeeds, returns zero rows, and LOOKUP reports the name unresolved. Nothing distinguishes that from data you never loaded. The claim can only narrow what your memberships in rbac.org_members already grant, so a token with no orgs claim at all sees every org you belong to:

percolate auth token --email you@example.com              # every org you are in
percolate auth token --email you@example.com --orgs <org-uuid>   # just that one

The fix in both cases is the identity, not a policy change.

Reading a base table over REST is also a 403 by design — authenticated holds grants on the _api views, not on agentic.agents or aiq.nodes themselves. GET /agents_api is the readable surface; the base tables are reached through the SECURITY DEFINER functions and nothing else.

Row-level security here is inside the ranking rather than a filter applied after it, which is worth seeing once — the cookbook runs one SEARCH under two claims and the order of the results changes, not only their number.

Related the same query under two claims · what to watch in production

aiq.iterated_join(seed, target_type, max_rounds, …) walks out from one node a round at a time until it reaches nodes of the target type. Each hop is one of four kinds of link, and path names which: a stored edge of any relation, walked either way; a key two nodes share; a name similar above a threshold (p_similarity, never "the nearest k", so a weak match is not promoted for being the best of a bad lot); or a judge's verdict. The judged kind needs a function named in percolate.link_judge, and asking for it without one is refused by name, because a model call cannot run inside the statement.

The bound is part of the call. max_rounds must be between 1 and 5, a round that has more candidates than p_budget defers the rest to the next round rather than dropping them, and a walk that reaches nothing returns one row with resolved false saying so, instead of an empty result that looks like a missing fixture. The seed must name exactly one node: a key two nodes hold is refused, rather than walked from whichever came first.

It is a function, so P8QL reaches it through its SQL mode, which aiq.query plans and aiq.sql_passthrough runs as the caller.

Related SQL as a mode · graph algorithms

A question's text, its phrasing or else its frame's subject and outcome, is registered as the semantic source questions, so its vectors live in a model's embedding space keyed by the question's id, beside the chunks and claims. claims.find_question(vector, max_distance, limit, model, at) returns the nearest questions the caller may read, each with within, whether it falls inside the distance the caller set. The floor has no default, because what counts as close depends on the model, and "nothing close enough" is an answer: the nearest question is still shown, so the caller sees what it missed.

The vectors above are written by hand so the page runs without a model. On a deployment, claims.install_question_embed_workflow(model) defines a workflow that embeds every question a space lacks, through the model's HTTP endpoint, and the query vector is embedded the same way, as for SEMANTIC. A question is readable only when a work the caller may read answers it, so a question nobody has answered is not found at all, by meaning or by words.

Related the search modes · sending a vector over REST

claims.bears_on records who proposed a link and with what probability, and later whether a person confirmed or disputed it, as new rows rather than edits. It carries no stance: what the fact says about the question is read from the fact by whoever reads it, and a stored stance would be a conclusion the graph drew for them. An agent's proposal and a person's both land proposed, and only a person can confirm one, with claims.review_bears_on.

A link is visible only to a caller who may read the fact and the question, so a link can never disclose either. On a deployment the proposals come from a workflow, claims.install_fact_question_workflow, which offers each unlinked fact its nearest questions by distance and lets a decider choose among them or "none of these": distance says where to look, and never makes the link.

Related a fact's visibility · finding a question