Skip to content
Embabel Worlds

Save a user-authored view (optionally parameterized) into the caller's world

POST
/api/v1/kg/studio/views
curl --request POST \
  --url http://localhost:11044/api/v1/kg/studio/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”

Request Bodyrequired

Section titled “Request Bodyrequired”

The view to store in the caller’s world: name, cypher 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 same-named view the caller saved is replaced, and a name a shipped view owns is a 400

Media typeapplication/json

A user-authored view to save into the acting user’s world: the body of POST /views.

object
cypher

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.

string
description

One line on what the view answers, shown to the query generator beside the schema. Defaults to empty.

string
goal

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.

string
materialized

Cache the result and serve reads from the cache until ttl lapses. Defaults false: a regular view re-runs on every read.

boolean
name
required

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.

string
outputLabel

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.

string
params

Bind variables the body references as $name, by name. A materialized view may declare none.

object
key
additional properties

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
choices

The fixed set of values this param accepts — rendered as a select, enforced at invocation. Absent = any value of the declared type.

Array
default

Used when an invocation omits this param. Absent = required on invocation, unless required: false.

description

What the argument means — rendered verbatim as the field’s hint.

string
required

False lets an invocation omit a param that has no default; it is then bound to null.

boolean
type

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.

string
default: string
Allowed values: string int number float double boolean date
ttl

Cache lifetime for a materialized view, e.g. 30m, 2h, 1d. Absent means 1h; ignored for a regular view.

string

Responses

Section titled “Responses”

200

Section titled “200”

View saved

Media typeapplication/json

A view was saved.

object
name
required

The name the view was saved under — the requested name, trimmed.

string
note

Why the stored query differs from the one sent

string
ok
required

Always true; a refusal answers 400 with a different body.

boolean
savedCypher

The stored query, when promotion inlined captured scopes into it

string

Example generated

{
  "name": "example",
  "note": "example",
  "ok": true,
  "savedCypher": "example"
}

400

Section titled “400”

Invalid view — bad name, unrunnable body, or the name is taken

Media typeapplication/json

A view was refused: a bad name, an unrunnable body, or a name already taken.

object
error

Why the view was refused. Always present.

string
name

The requested name, trimmed. Absent when the declaration itself was malformed — a reserved or uncoercible param, say — and refused before a save was attempted.

string
ok
required

Always false.

boolean
violations

Preflight defects when the body names shapes the schema contradicts.

Array<string>

Example generated

{
  "error": "example",
  "name": "example",
  "ok": true,
  "violations": [
    "example"
  ]
}

401

Section titled “401”

Not authenticated

Media typeapplication/json

A refusal carrying only a human-readable reason.

object
error
required

What went wrong, in the terms the caller can act on.

string

Example generated

{
  "error": "example"
}