Skip to content
Embabel Worlds

List the acting user's saved views with their cache state

GET
/api/v1/admin/kg/views
curl --request GET \
  --url http://localhost:11044/api/v1/admin/kg/views \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
username
string

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.

Responses

Section titled “Responses”

200

Section titled “200”

Saved views across the world and realm tiers

Media typeapplication/json
Array<object>

A saved view visible to the acting user — world or realm tier — with its definition and, for a materialised view, its cache state. The items of GET /views.

object
cachedMembers

Nodes — or, for a row snapshot, rows — the cache holds. Null for a regular view, or a materialised one with nothing cached.

integer format: int64
cypher
required

The view’s Cypher body, trimmed, with any $name parameter references as declared.

string
dataContract

The ODCS contract the view is pinned to, and in which mode. Absent when it is not contracted.

object
id
required

Id of the ODCS contract; must not be blank

string
mode
required

observe (the default): rows are returned and the verdict reported beside them. enforce: rows are withheld when the verdict is FAIL or UNKNOWN, and the contract must be active or deprecated to run at all

string
Allowed values: observe enforce
object
required

The schema object in the contract the view’s rows are checked against, by name or else physical name; must not be blank

string
version
required

The contract version pinned; must not be blank. Only the contract with exactly this id and version governs the view

string
description
required

One line on what the view answers. Empty when it declares none.

string
expiresAt

Epoch milliseconds at which the cache expires; may already be past. Null for a regular view, or a materialised one with nothing cached.

integer format: int64
goal
required

A goal view’s goal: the final query its plan answers. cypher is then the statement the goal compiled to, which is what runs. Null for a view declared by its Cypher; always serialized, so its presence says this server supports goal views.

string
goalStatus

Whether a goal view’s pinned plan stands: pinned, not compiled, or stale: <what moved>. A view that is not pinned refuses to run until it is replanned. Absent for a view declared by its Cypher.

string
materialized
required

True when reads are served from a cache that is recomputed once ttl lapses.

boolean
name
required

The view’s name, which a query uses as a label and /views/{name} paths take.

string
outputLabel

The node label the view’s rows are. Null for a tabular view, and for a materialised view that keeps its rows as a snapshot.

string
params
required

Declared bind variables by name. Empty for an unparameterized view, and always for a materialised one.

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
source

The realm that shipped the view. Null for a view of the world’s own.

string
ttl

Cache lifetime, e.g. 30m, 2h, 1d. Null for a regular view.

string

Example 

[
  {
    "dataContract": {
      "mode": "observe"
    },
    "params": {
      "additionalProperty": {
        "type": "string"
      }
    }
  }
]

401

Section titled “401”

No authenticated principal

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"
}

403

Section titled “403”

username names someone other than the signed-in principal

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"
}