Virtual Cypher federated graph queries with the model inside · the spec is the authority

What is new here Three things ordinary Cypher does not do. Everything below is detail.

One MATCH spans stored and live

A virtual label is not in the database. It is fetched the moment the query reaches it, spliced in for the life of that query, and rolled back. You do not know which labels are which.

MATCH (me:AssistantUser)-[:EMAILED]->(p:Person)
MATCH (p)-[:HAS_GITHUB]->(g:GitHubIdentity)
MATCH (g)-[:RAISED]->(i:GitHubIssue)
RETURN p.name, i.title

Your graph, your CRM and a REST API in one pattern — no export, no sync, no mirror to go stale. Federation is the point; the rest of this page is how it is declared and paid for.

onceEach producer is called ONCE with every anchor key at a time — batched, never N+1.
goneMaterialization runs in a transaction that always rolls back. Nothing fetched persists.

The model is inside the query

Not a step before it or after it. A judgement no property and no embedding captures is written where the predicate goes, and the query keeps its shape.

MATCH (c:Concept {value:'Acme'})-[:RELEVANT_TO]->(d:Document)
WHERE ai.relevant(d, 'our funding round, not the sector')
RETURN d.title, ai.classify(d, 'sentiment')
ORDER BY ai.score(d, 'bears on renewal risk') DESC
PositionReads as
WHEREfilter — is this row actually about it?
ORDER BYrerank — which fits best?
RETURNlabel — where does it sit on this dimension?
edgeRetrieval mode is chosen AT the edge: no via is vector, via:'keyword' lexical, via:'agentic-rag' a bounded judging loop. Three questions, one shape.
neverai is a reserved engine primitive, never data. A realm cannot ship a property called ai.

A query can run for minutes

It is a fetch, not a scan. A cold join waits on somebody else's API, and an agentic-rag edge waits on a model loop. Tens of seconds is ordinary, and not a fault.

So it is bounded on every axis, and a bound that bites is always surfaced — never a silently short answer.

BoundDefaultWhat it protects
maxAnchors200fan-out from an unpinned anchor
maxFanoutTotal5 000materializing more than you meant
cost:per bucketsomebody else's rate limit
beforeRefusals happen BEFORE anything runs, and carry advice — pin the anchor, push a predicate, add a LIMIT.
cachecache: is the lever that makes the second ask fast. Declare freshness per producer; it is the difference between a live source and a slow one.
neverA zero-row result that meant "the source failed" — every producer failure is classified and returned as a warning.
Writing a query Ordinary Cypher, and why one gets refused.

The shape of a query

Ordinary Cypher. A virtual label is reached by traversing to it from something already bound.

MATCH (me:AssistantUser)
      -[:HAS_GITHUB]->(g:GitHubIdentity)
MATCH (g)-[:RAISED]->(i:GitHubIssue)
WHERE i.state = 'open'
RETURN i.title, i.repository
LIMIT 20
mustBind an anchor first — a real node, or one pinned by its identity.
neverMATCH (i:GitHubIssue) RETURN i — a naked virtual scan has nothing to fetch from.

Why a query is refused

Refusals happen before anything runs, and always say which alias is at fault.

RefusalWhat it means
Naked virtual scanThe label was matched bare, with no anchor to fetch it for.
Unbound anchorThe anchor exists but nothing narrows it — it would fetch for everyone.
Too many anchorsThe probe bound more than maxAnchors (default 200).
Fan-out too largeMaterialization would exceed maxFanoutTotal (default 5 000).
fixPin the anchor, push a predicate to the source, or add a LIMIT.
Reducing rows Turning many rows into the one thing you asked for.

Aggregations — a group → one cell

Neo4j's grouping supplies the group for free; the function reduces it. The model sibling of count().

MATCH (t:ResearchTopic {name:'RAG'})
      -[:HAS_NEWS]->(n:NewsItem)
RETURN t.name,
       summarize(n.description,
                 'what is newest') AS digest
FunctionReturns
summarize(text[, instruction])prose overview
synthesize(text, goal)prose, argued toward a goal
classify(text, 'a,b,c')one label from the set
extract(text, what)list of distinct things
themes(text[, focus][, n])recurring topics (labels only)
cluster(text[, k])groups with counted sizes + examples
score(text, rubric)one number 0–1
holds(text, claim)true / false / null
relevant(text, criterion)only the matching items
relevant(node, criterion)the matching nodes — they flow on through WITH/UNWIND
argmax(key, text, criterion)the winner
render(text[, instruction])prose keeping every item, in order, hedges intact
correlate(x, y)Pearson r with CI + detectable — arithmetic, no model call
regress([x1, …], y, label)OLS fit: r², named betas, above/below-prediction rows — deterministic
neverORDER BY score(...) — an aggregation is finalized after ordering, so it cannot be ordered by.
nodesrelevant, classify, holds, score take a node too: the model reads its labels, properties and their declared descriptions. A kept node is one of the group's own — the model cannot cite anything it was not shown.
per groupThe criterion may be an expression of the grouping key: WITH i, relevant(c, 'the same problem as: ' + i.summary) AS tracked. Reading an aggregated variable there is refused.

cluster — groups you can count

Returns {label, size, share, examples} per group. Its cost does not grow per batch the way the other reductions do, so it suits large groups.

MATCH (s:DiseaseScope {registryQuery:'sleep'})
      -[:HAS_TRIAL_SEARCH]->(r:TrialSearchRun)
MATCH (r)-[:RETURNED]->(t:ClinicalTrial)
RETURN cluster(t.title, 6) AS clusters
truesize is a count of the rows, not a model's estimate.
trueSame rows → same groups, every run.
pickthemes when membership doesn't matter; cluster when "how many" does.

Per-row judgement — the ai namespace

Judges rows the query already fetched. Reserved: never a stored property.

MATCH (p:Person)-[:AUTHORED]->(d:Document)
WHERE ai.relevant(d, 'a decision, not a status')
RETURN d.title, ai.classify(d, 'urgency')
PositionCall
filterWHERE ai.relevant(n, '…')
rerankORDER BY ai.score(n, '…') DESC
labelRETURN ai.classify(n, '…')
steer a fetch{ai: {hint: '…'}} on the edge
noteNon-deterministic and fail-open: a model error keeps rows rather than dropping them.
From text, and one query as a pipeline Project a typed shape out of prose, build on it, ask the spine for keys — all in ordinary Cypher.

ai.fromText — a graph out of prose

The pattern is the shape; its labels come from realm types marked projected: true, and their descriptions are what the model reads.

CALL ai.fromText($email,
  '(p:Attendee)-[:RAISED]->(i:Issue),
   (p)-[:WORKS_FOR]->(a:CustomerAccount)')
  YIELD p, i, a
RETURN p.name, i.summary, a.name
A variable in the pattern…is
already boundan anchor — attached to, never created
of a projected typecreated for this run only
of a world typeresolved by its spine — never invented
trueNothing it creates is stored or seen by another run.
modelRole vc_extraction; one call may name another role: ai.fromText(t, pattern, {role: 'chat_best'}) — a role, never a model.
saidDeclined (a freemail sender), unresolved and ambiguous come back as PROJECTION_* warnings — never as a silent empty.

ai.terms — the model suggests, the data decides

Terms a person's words could mean, for the query to look up. Yields words, never records; a term the data does not hold reaches no row.

CALL ai.terms($q, 'disease names, synonyms and abbreviations',
  {ai: {confidence: 0.6, maxTerms: 5}}) YIELD term, kind, confidence
MATCH (s:DiseaseSearch {query: term})-[:MATCHES]->(h:DiseaseHit)
RETURN DISTINCT h.id, term AS suggestedBy
{ai: …} keymeans
modela role (default vc_execution), never a model
hinta soft steer beside the instruction
confidencefloor 0–1: weaker terms are never looked up
freshask again; the answer is still kept
maxTermsat most this many per input (8; 1–25)
saidEvery call is in AI_TERMS: role, model, input, terms. Same question, same terms (cached).
failsNo model, no terms: TERMS_UNAVAILABLE, and the rest of the query answers. A null input asks nothing.

One query is a pipeline

CREATE/MERGE of projected types write the run's scratch: the rest of the query sees them, nothing else does. Read-only means read-only with respect to the store.

CALL ai.fromText($notes, '(t:Attendee)-[:RAISED]->(i:Issue),
  (t)-[:WORKS_FOR]->(a:CustomerAccount)') YIELD t, i, a
WITH DISTINCT i, a
MATCH (a)-[:HAS_CASE]->(c:SupportCase)
WHERE c.status IN ['open','pending']
WITH i, relevant(c, 'the same problem as: ' + i.summary) AS tracked
UNWIND tracked AS tc
CREATE (i)-[:TRACKED_BY]->(tc)
WITH count(*) AS linked
MATCH (t2:Attendee)-[:RAISED]->(untracked:Issue)
WHERE NOT EXISTS { (untracked)-[:TRACKED_BY]->() }
RETURN untracked.summary, t2.name
neverA world type created, or an edge between two stored nodes — every written relationship has a projected end.
namesFresh names across stages (tc, t2, untracked): a name dropped and rebound, or reused across CALL {} bodies, is refused.
limitA judgement after a CREATE that a later clause reads is refused; one only returned at the end may read what the statement wrote.

canonicalize — ask the spine for a key

A spine's normalize is the one definition of "the same entity". Never re-normalise by hand: split(url,'//')[1] misses www. and the join silently drops rows.

MATCH (i:LagoInvoice)
MATCH (a:CustomerAccount {accountKey:
  canonicalize(i.customerUrl, 'CustomerAccount')})
RETURN a.name
CallReturns
canonicalize(v, 'Spine')the key, or null
canonicalize(n)the key from the node's hub: property
canonicalization(v, 'Spine'){key, outcome, rule} — ok / excluded / invalid
trueSame normalisation as hub: — a query and a hub can never disagree.
noteReads nothing: it says what the key would be, not that the entity exists.
Planning Write only the final query; the world's own views and rules are the steps, chosen by a deterministic planner and compiled to one ordinary query.

A goal view — the answer, not the steps

goal: in place of cypher:. The world plans the steps, compiles them to unit CALL {} subqueries ahead of the goal, and pins the result.

# views/untracked-issues.yml
- name: UntrackedFromEmail
  description: Issues a customer's email raises
    that no open support case already tracks.
  params:
    email: { type: string, description: "The email, as text." }
  goal: |
    MATCH (raisedBy:Attendee)-[:RAISED]->(untracked:Issue)
    WHERE NOT EXISTS { (untracked)-[:TRACKED_BY]->() }
    RETURN untracked.summary AS issue, raisedBy.name AS person
neverShip compiled: or plan: in a realm — the server writes them, per world. Validation errors.
trueAn invocation runs the pin and never plans. Replan is explicit: re-save, or view_replan.
staleA pinned step removed or changed: refused, naming the step. The views listing shows goalStatus.
validateUnreachable is an error at the goal; a tie is a warning.

plan — explain, then run

Over MCP, or POST /api/v1/admin/kg/plan (never executes) and …/plan/run. Give a goal or a question.

plan({goal: "MATCH (raisedBy:Attendee)-[:RAISED]->(untracked:Issue) …",
      inputs: {email: {type: "text", value: "…"}},
      run: false})
OutcomeCarries
plannedsteps (adds, requires, reaches, cost), compiled, quote
unreachablethe missing fact, by name
tieboth rival plans — never broken
refusedreasons: what to change
needsInputquestion only: the input's type and why
declinedquestion only: what nothing makes
truerun: false runs no step, reads no source, calls no model — a question costs the one call that writes its goal.
costStored < API < model, from what a step reaches. Pluggable; a cost outside 0..1 is refused, not clamped.
neverA step through a view the caller could not invoke directly.

What makes a view plannable

Nothing declares a step's signature: what it needs and makes is read off its Cypher. A realm author makes sure of four things.

MustBecause
make a named factprojected types, a declared projected relationship, a derives: label, a new outputLabel. Types say what, not which: world rows alone are a question, not a step
describe every factEnglish mode chooses facts by description, and never offers one without
type params by useai.fromText($x) → text; a spine key or canonicalize → identity; anything else needs a default
use distinct namesvariables and RETURN columns across the plan — the compiler refuses a clash, never renames
trueNOT EXISTS { (x)-[:R]->() } in a goal is a need: the step that makes R is planned in.
noteA body the pass cannot type is left out with a diagnostic, never guessed.
Narrowing and cost Asking the source for less, and asking it less often.

Your WHERE reaches the source

Write the filter you mean. Where the source can answer it, the fetch is narrowed there instead of after — so a filtered query costs less, not the same.

MATCH (s:DiseaseScope {registryQuery:'sleep'})
      -[:RETURNED]->(t:ClinicalTrial)
WHERE t.overallStatus = 'RECRUITING'
  AND 'OLDER_ADULT' IN t.ageGroups
RETURN t.title, t.phase
truePushdown changes cost, never rows. Anything the source cannot answer is still filtered here, so the same query returns the same answer either way.
care'X' IN n.list asks whether the record's list holds X. n.prop IN [...] asks whether its value is in a list you wrote. Different questions.
neverFetch everything and filter in your client. That is the one shape this engine is built to avoid.

Asking twice, and asking fresh

A realm declares how long an answer stays good. The second identical ask is usually free — which is why a slow first query is not a slow surface.

MATCH (c:Concept {value:'Acme'})
      -[:RELEVANT_TO {ai: {fresh: true}}]->(d:Doc)
RETURN d.title
You getBecause the realm declared
a reused fetchcache: ttl — an answer up to N seconds old is fine
rows already in the graphcache: graph — the fetch was kept
a re-fetchnothing, or your fresh: true
carefresh costs a real call every time. Reach for it when staleness would be wrong, not by habit.
Similarity When the join IS the resemblance.

Vector edges — similarity IS the join

The key is embeddable text rather than an id; the score rides on the edge.

MATCH (p:Person {name:'Ada Lovelace'})
      -[r:RELEVANT_TO]->(t:EmailThread)
RETURN t.subject, r.score
ORDER BY r.score DESC
careA minScore floor can return nothing when the anchor text is short. Prefer top-k + ORDER BY r.score.
What holds The promises that survive every path above.

What you are promised

trueNothing is mirrored: fetched rows live for the query and are rolled back.
trueA refusal happens before any source is called, and names the alias.
trueA capped or partial result says so — it is never silently truncated.
noteAnything model-backed (ai.*, reductions, keyTransform) is not bit-identical run to run, except cluster, which is.
Where these labels come from Not written in a query — declared in a realm. Shut by default; open it if you are authoring one.

A realm declares it; you traverse it

Nothing on this page needed you to know how GitHubIssue becomes reachable. That is the design: a realm author writes the declaration once, in YAML, and every query after it is ordinary Cypher.

MATCH (p:Person)
      -[:HAS_HUBSPOT_CONTACT]->(c:Contact)
RETURN c.company

That traversal works because a realm declared a virtual join — which anchor it hangs off, which field is the key on each side, and which producer fetches it — plus the producer's own paging, pushdown rules and cache.

If you are…Read
writing queriesthis page, then the guide
authoring a realmREADME.md — the declarative surface
settling an argumentthe spec
oneThe record's key must equal the anchor's keyField, or no edge forms and every row vanishes. The commonest realm bug, and it looks like an empty source.

Nothing matches that filter.