Execute Cypher with a caller-supplied DERIVE rule set evaluated for this query only
const url = 'http://localhost:11044/api/v1/admin/kg/derive';const options = { method: 'POST', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>', 'Content-Type': 'application/json'}, body: '{"cypher":"example","derives":"example","description":"example","name":"example","paramSpecs":{"additionalProperty":{"choices":["example"],"default":"example","description":"example","required":true,"type":"string"}},"params":{"additionalProperty":"example"},"requires":[{"description":"example","materialize":"example"}],"rules":[{"derive":"example","from":"example"}]}'};
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/derive \ --header 'Content-Type: application/json' \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \ --data '{ "cypher": "example", "derives": "example", "description": "example", "name": "example", "paramSpecs": { "additionalProperty": { "choices": [ "example" ], "default": "example", "description": "example", "required": true, "type": "string" } }, "params": { "additionalProperty": "example" }, "requires": [ { "description": "example", "materialize": "example" } ], "rules": [ { "derive": "example", "from": "example" } ] }'The rule set’s derived label is visible to the query as an ordinary label; nothing persists. Invalid rule sets are refused with the validator’s messages.
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.
Request Bodyrequired
Section titled “Request Bodyrequired”The rule set to evaluate for this one query, and the query that reads it: cypher (sees the derived label as an ordinary label), derives (the label the rules conclude), rules (each a derive head pattern and a RETURN-less Cypher from body), and optionally name (default adhoc/<derives>), description, paramSpecs (declared bind variables, referenced as $name in rule bodies), params (values for them; the whole map also binds the outer query) and requires (materialization demands run before the rules). Rule bodies are scoped to the acting user and nothing persists. An invalid rule set, a body label the world does not know, or a param that does not resolve answers 400
Body of POST /admin/kg/derive: a DERIVE rule set to evaluate for this one query, and the Cypher that reads what it derives. Nothing persists; the world’s installed rule sets are evaluated alongside it.
object
The Cypher query to run with the derived label or relationship type visible like any other
The label the rules derive, or the relationship type when the heads are relationship patterns: letters, digits and _, starting with a letter
One-line description of the rule set; empty when omitted
Qualified name for the rule set, realm/ruleset style; validator messages and traces name it. Defaults to adhoc/ followed by derives. An installed rule set of the same name is shadowed for this query
Bind variables the rule set declares, by name, in the view-param vocabulary (type, default, description); referenced as $name in rule bodies and demands. A param with no default must be given in params
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.
Invocation values: keys declared in paramSpecs bind the rule bodies, coerced to their declared types; the whole map also binds the query as ordinary params
object
Materialization demands run before the rules; an unsatisfiable one does not fail the query. Empty when omitted
A materialization demand in an ad-hoc rule set: facts fetched into the query before the rules run, as an installed rule set’s requires: entry
object
Why the rule set needs these facts; empty when omitted
Read-only Cypher, MATCH clauses and one RETURN (RETURN 1 is enough), run after the query has materialized its anchors to deepen what it fetched, e.g. MATCH (r:NpmRelease)-[:HAS_DEPENDENCY*1..3]->(:NpmDependency) RETURN 1. May reference the rule set’s declared params
The rules: unordered clauses of one definition, at least one, all concluding derives and all of the same kind
One DERIVE rule in an ad-hoc rule set sent to POST /admin/kg/derive: what it concludes (the head) and when (the body)
object
The head: a Cypher node pattern, or a relationship pattern for a rule set deriving a relationship, whose variable names the body binding that becomes a member, whose label or type is the rule set’s derives, and whose property map defines derived properties from body-bound expressions, e.g. (e:Blocked {blockedStake: stake})
The body: read-only Cypher that binds the head’s variables and has no RETURN. It may match the derived label itself
Responses
Section titled “Responses”The query result over the derived overlay
Answer of POST /admin/kg/derive: the query result, plus every rule set evaluated for it with its derivations
object
Each rule set evaluated for the query, the ad-hoc one and any installed ones it reached, with members, rounds and why traces
One rule set evaluated for the query: what it derived, how many rounds the fixpoint took, and each member’s why trace
object
Derived members with their traces, in the order concluded, at most 500
One member of a derived label or relationship type, with the firing chain that concluded it
object
The member node’s element id, the key to join query rows to traces (RETURN elementId(x)). For a derived relationship, the two endpoints’ element ids joined by a NUL character and ->
Derived property values as they settled at the fixpoint, by property name (the last write wins)
object
Fixpoint round, counting from 1, in which this member was first concluded
Position, counting from 1, of the rule that first concluded this member
Firings oldest first: each rule’s first conclusion of this member, and every later firing that changed its values
One firing in a derived member’s why trace: which rule concluded it, in which fixpoint round, with what property values
object
Derived property values this firing concluded, by property name; empty when the head declares none
object
Fixpoint round the rule fired in, counting from 1
Position of the rule that fired in the rule set’s rules, counting from 1
The label, or relationship type, the rule set derives
Number of members derived, counted in full even when derivations is truncated
Fixpoint rounds run, including the final round that changed nothing
Qualified name of the rule set evaluated
True when derivations was capped at 500; members and rounds still cover everything
The Cypher query’s result, run over the derived overlay
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.
Example
{ "result": { "answerBoundary": { "kind": "SUPPORTING_CONTEXT_ONLY" }, "dataContract": { "checks": [ { "verdict": "PASS" } ], "mode": "observe", "verdict": "PASS" } }}The rule set failed validation; error carries every violation
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"}