Execute verbatim Cypher through the virtual-cypher engine, synchronously, watched, or in the background
const url = 'http://localhost:11044/api/v1/admin/kg/execute?background=false';const options = { method: 'POST', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>', 'Content-Type': 'application/json'}, body: '{"args":{"additionalProperty":"example"},"captureAs":"example","cypher":"example","params":{"additionalProperty":{"choices":["example"],"default":"example","description":"example","required":true,"type":"string"}},"surface":"studio"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'http://localhost:11044/api/v1/admin/kg/execute?background=false' \ --header 'Content-Type: application/json' \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \ --data '{ "args": { "additionalProperty": "example" }, "captureAs": "example", "cypher": "example", "params": { "additionalProperty": { "choices": [ "example" ], "default": "example", "description": "example", "required": true, "type": "string" } }, "surface": "studio" }'Three modes: background=true returns a run handle immediately and may park awaiting input; waitSeconds=N watches for that long then returns a run handle; with neither, the call is fully synchronous.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Optional, and never needed: the call always acts as the signed-in principal. Naming the principal changes nothing; naming anyone else is refused with 403.
Return a run handle immediately instead of waiting, and allow the run to park awaiting input.
Watch the run for this many seconds, then return a handle if it has not finished. Omitted with background=false means wait indefinitely.
Request Bodyrequired
Section titled “Request Bodyrequired”The Cypher to run, in cypher, scoped to the acting user. With params, each $name is first substituted from args merged over its default (a bad argument or declaration is a 400). captureAs also keeps the result set as that named scope and is synchronous-only: sent with background=true or waitSeconds it is a 400. surface: studio records the statement in the query log as one written in Query Studio, which is what counts toward retiring its starter examples
Cypher to run through the virtual-cypher engine — the body of /execute, and of /validate, which reads only cypher.
object
Arguments for params. A blank value means not supplied, so the default applies.
object
Capture the result set as this named scope; reference it later as (x:$name). The statement must RETURN one labelled node variable. Synchronous mode only.
The statement, run verbatim — or, when params is given, a view body whose $name references are substituted first.
Declared parameters for the cypher, as a view declares them. Each $name is substituted from args merged over its default, exactly as when a saved view runs.
object
A declared bind variable of a saved view, referenced as $name in its Cypher and supplied per invocation, keyed by that name wherever a view’s params are declared or listed
object
The fixed set of values this param accepts — rendered as a select, enforced at invocation. Absent = any value of the declared type.
Used when an invocation omits this param. Absent = required on invocation, unless required: false.
What the argument means — rendered verbatim as the field’s hint.
False lets an invocation omit a param that has no default; it is then bound to null.
The coercion applied to supplied values, and the form control a UI renders (int/number a number field, boolean a checkbox, date a date picker). float and double are aliases of number.
Where the statement was written, recorded in the query log: studio for a query written in Query Studio’s editor. Omitted, it is logged as query. Any other value is a 400.
Responses
Section titled “Responses”A finished result, or a run handle when background=true
The outcome of a virtual-cypher query: rows, the cypher that produced them, and what it cost.
object
The rows are supporting context only, not a match for the original question.
object
What the rows are instead of an answer. Only SUPPORTING_CONTEXT_ONLY exists.
The question the rows do not answer: the asked question on /ask, view:<name> on a view run. Null on /execute, which has no question.
The actual calls as producer(keys), in order — fan-out is visible here.
External fetches the executor made. 0 means everything was cached or local.
The scope this result set froze into — present only on a capturing execute.
object
When the membership froze, ISO-8601.
When the scope lapses, ISO-8601 — null means PINNED (kept until deleted).
How many members the capture froze. Membership is frozen; values stay live.
The name the scope was captured under, unique per user; a later query binds it as (x:$name).
The node label later references bind with.
The statement that produced the capture — the scope’s provenance.
Each column -> the expression that computed it, traced back through WITH and UNWIND, e.g. {“total”: “sum(b.amount)”}; an unwound column reads “UNWIND ”. Where the origin cannot be traced with certainty, the column’s own RETURN expression is given unchanged. A column name is the query’s label for a value, not evidence of what it is.
object
The cypher that actually ran, after scope rewriting.
The pinned ODCS identity and invocation verdict, for a contracted named view only.
object
The ODCS apiVersion the contract declares, such as v3.1.0; v3.1.0 when the view was refused before it ran
False when the view could not run under its contract: the pinned contract or its object is missing, or its status forbids it. Then no rows are returned, whatever the mode
ISO-8601 instant the result was checked
Each check made, in the order it was made
One check made when a view’s result was evaluated against its data contract
object
schema, quality, freshness, status, binding or execution
What it found, in words, naming rows and fields but never their values; null when there is nothing to say
The contract’s own id for a quality or freshness rule, or an embabel: id for a check the runtime makes itself, such as embabel:schema, embabel:binding or embabel:status
invocation for the schema check, which covers this one result; null for every other check
PASS, WARN, FAIL, or UNKNOWN when the check could not be made
Id of the governing contract, as the view’s binding pins it
observe or enforce, from the view’s binding
The contract object the rows were checked against, as the binding names it
The contract’s ODCS status, such as active, deprecated or retired; unavailable when the pinned contract is not in the world
The worst of the checks: FAIL if any failed, else UNKNOWN if any could not be made, else WARN if any warned, else PASS
The pinned contract version
Total: bridge-resolve plus materialize plus read.
Why the query failed, or null when it did not.
What the models behind an /ask answer were shown: resolved schema groups and prompt sizes.
object
Characters in the Cypher-generation prompt. Absent when no query was generated.
The schema groups rendered in full for generation, and whose views view selection was offered.
Groups named to the generator by one index line only — no labels, properties or examples.
Each named group -> the words that named it, tier first: name:, label:, weak: or keyword:.
object
How the groups were chosen: WHOLE (nothing to narrow), SCOPE, QUESTION, UNRESOLVED or SELECTOR.
True when the always-on core was cut to the spine anchors (the user, Person, Organization).
Characters in the view-selection prompt. Absent when no view selection ran.
Saved views in the world.
Saved views offered to view selection, of viewsInWorld.
Source records fetched before query-side filtering, cache-served included. Absent when none.
What to try instead. Accompanies an empty result only.
The actual LLM calls (kg-ask and agg-*), in order.
LLM calls: the generation plus any aggregate reductions. Reasoning only — a semantic anchor’s embedding is on semanticCalls.
Graph nodes materialized from fetched records in this execution. Absent when none.
The question asked, echoed back. Present only for /ask.
Typed outcome when this was not a clean answer — UNBOUNDED, NOT_IN_GRAPH, MISSING_ATTRIBUTE, FETCHED_NOT_MATCHED, PARTIAL_NOT_MATCHED, UNPUSHED_FILTER, DISCONNECTED or INTERNAL_ERROR. May accompany rows when a source failed, a read was refused, or a filter was not applied; absent on a clean answer, including a genuine zero.
How many rows rows holds.
One map per row, keyed by RETURN column. Empty and meaningless while run is present — the run has not finished, which is not the same as no data. From a synchronous /execute, a node is its properties plus __type, __labels and __elementId; a relationship its properties plus __type (the relationship type), __elementId, __startElementId and __endElementId (the __elementIds of the nodes it joins); a path its nodes and relationships in traversal order. Elsewhere a node carries __type and __labels and a relationship its properties alone.
object
Present only when /execute with waitSeconds gave up waiting: the run is still going (or parked), and this is how to follow it. Absent on every answer that finished in the call.
object
Where to send the owner’s pick for a parked run. Absent while running.
The {kind, question, options, context} payload when parked.
object
Where to stop the run. Absent when parked — nothing is executing to kill.
Where to poll for state and, once settled, the result.
The run’s id, for /runs/{runId}, /kill/{runId} and /runs/{runId}/answer.
RUNNING (materializing now) or WAITING_INPUT (parked on choices).
The actual searches as producer: mode search on index (k=…), in order.
Relevance searches behind a semantic anchor: one embedding plus one similarity scan per anchor. The third call axis — a search of an index is neither a producer fetch nor a reduction, and a semantic query spends here and nowhere else.
Caveats on this result that do not make it an error — a producer that failed, rows that are partial or supporting context, an aggregate over mixed units. Absent when there are none.
A handle to a run started in the background.
object
The question a parked run poses to its owner. Absent while running.
object
RUNNING, or WAITING_INPUT when the run parked on choices.
Example
{ "answerBoundary": { "kind": "SUPPORTING_CONTEXT_ONLY" }, "dataContract": { "checks": [ { "verdict": "PASS" } ], "mode": "observe", "verdict": "PASS" }}Bad params or args, or captureAs with background/waitSeconds
A refusal carrying only a human-readable reason.
object
What went wrong, in the terms the caller can act on.
Example generated
{ "error": "example"}No authenticated principal
A refusal carrying only a human-readable reason.
object
What went wrong, in the terms the caller can act on.
Example generated
{ "error": "example"}username names someone other than the signed-in principal
A refusal carrying only a human-readable reason.
object
What went wrong, in the terms the caller can act on.
Example generated
{ "error": "example"}