Save a user-authored view (optionally parameterized) into the acting user's world
const url = 'http://localhost:11044/api/v1/admin/kg/views';const options = { method: 'POST', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>', 'Content-Type': 'application/json'}, body: '{"cypher":"example","description":"example","goal":"example","materialized":true,"name":"example","outputLabel":"example","params":{"additionalProperty":{"choices":["example"],"default":"example","description":"example","required":true,"type":"string"}},"ttl":"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/views \ --header 'Content-Type: application/json' \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \ --data '{ "cypher": "example", "description": "example", "goal": "example", "materialized": true, "name": "example", "outputLabel": "example", "params": { "additionalProperty": { "choices": [ "example" ], "default": "example", "description": "example", "required": true, "type": "string" } }, "ttl": "example" }'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 view to store in the acting user’s world: name, cypher (or goal, for a goal view) and an optional description. params declares the $name bind variables the body uses (an absent default makes the argument required on invocation); materialized caches the result for ttl (default 1h) under outputLabel, or as a row snapshot when that is omitted, and cannot be combined with params. The body is preflighted with defaults substituted before it is stored; a body written against captured scopes is stored with them inlined, which savedCypher then shows. A same-named view the user saved is replaced; a name a shipped view owns is a 400
A user-authored view to save into the acting user’s world: the body of POST /views.
object
The view’s body. RETURN one node variable for a view that composes as a label, or a projection for a tabular view run directly. Must pass the schema preflight with declared defaults substituted. Omitted for a goal view, which declares goal instead.
One line on what the view answers, shown to the query generator beside the schema. Defaults to empty.
A GOAL view, in place of cypher: the final read query, written over the facts it needs as if they existed. The server plans it over the world’s views and rules, compiles it and pins the result, which is what the view runs (savedCypher); params are the plan’s inputs, typed by how the steps read them. A goal that does not plan — unreachable, a tie between two plans, refused — is a 400 naming why.
Cache the result and serve reads from the cache until ttl lapses. Defaults false: a regular view re-runs on every read.
A plain identifier — letters, digits and underscore, not starting with a digit — because a query uses it as a label. Trimmed before it is checked; a name a shipped view owns is refused.
The node label the view’s rows are, e.g. Person. A materialized view with one caches its member nodes; without one it keeps its rows as a snapshot. A regular view does not need it.
Bind variables the body references as $name, by name. A materialized view may declare none.
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.
Cache lifetime for a materialized view, e.g. 30m, 2h, 1d. Absent means 1h; ignored for a regular view.
Responses
Section titled “Responses”View saved
A view was saved.
object
The name the view was saved under — the requested name, trimmed.
Why the stored query differs from the one sent
Always true; a refusal answers 400 with a different body.
The stored query, when promotion inlined captured scopes into it
Example generated
{ "name": "example", "note": "example", "ok": true, "savedCypher": "example"}Invalid view — bad name, unrunnable body, or the name is taken
A view was refused: a bad name, an unrunnable body, or a name already taken.
object
Why the view was refused. Always present.
The requested name, trimmed. Absent when the declaration itself was malformed — a reserved or uncoercible param, say — and refused before a save was attempted.
Always false.
Preflight defects when the body names shapes the schema contradicts.
Example generated
{ "error": "example", "name": "example", "ok": true, "violations": [ "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"}