Skip to content
Embabel Worlds

Bring one graph fact up to date for the signed-in user, under its recompute policy

POST
/api/v1/kg/graph-facts/refresh
curl --request POST \
  --url http://localhost:11044/api/v1/kg/graph-facts/refresh \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "fact": "example", "force": true }'

Recomputes only if the graph the fact reads changed (or force is set), writes the derived results into the caller’s own scope, and names only the communities that changed. Answers what was decided and why, what changed, and the top results.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

The fact to refresh, by the name its declaration gives, and whether to ignore the recompute policy

Media typeapplication/json

Which graph fact to bring up to date.

object
fact
required

The fact’s name as its declaration gives it, e.g. support/customer-groups.

string
force
required

Recompute even when the recompute policy says the graph has not changed enough. Defaults to false.

boolean

Example generated

{
  "fact": "example",
  "force": true
}

Responses

Section titled “Responses”

200

Section titled “200”

What the refresh decided and wrote

Media typeapplication/json

One refresh of one graph fact for the signed-in user: what was decided and why, what changed, and the top results.

object
algorithm
required

The algorithm the fact runs, e.g. components.

string
fact
required

The fact refreshed.

string
projected
required

How much of the graph the fact read.

object
edges
required

Edges between those nodes.

integer format: int32
nodes
required

Nodes the fact’s declaration selected.

integer format: int32
read
required

The Cypher that reads the whole result, to run through the ordinary query surfaces.

string
reason
required

Why the policy recomputed or skipped, in words.

string
recomputed
required

True when the algorithm ran; false when the policy found the graph unchanged and kept the stored result.

boolean
reports

Community names and summaries brought up to date; absent for a fact with no reports.

object
cached
required

Reports kept because their community had not changed.

integer format: int32
ceiling
required

The most model calls one refresh may make.

integer format: int32
deferred
required

Reports left for a later refresh because the cap was reached.

integer format: int32
modelCalls
required

Model calls this refresh made.

integer format: int32
written
required

Reports written this refresh.

integer format: int32
top
required

The top results as rows keyed by the fact’s read columns, at most ten.

Array<object>
object
key
additional properties
warnings
required

Anything the refresh left out or could not do, e.g. nodes with no key; empty when nothing was.

Array<string>
writes
required

What the refresh wrote into the caller’s scope.

object
created
required

Nodes, edges or properties newly written.

integer format: int32
removed
required

Ones the new result no longer holds, removed.

integer format: int32
updated
required

Ones that existed and changed.

integer format: int32

Example generated

{
  "algorithm": "example",
  "fact": "example",
  "projected": {
    "edges": 1,
    "nodes": 1
  },
  "read": "example",
  "reason": "example",
  "recomputed": true,
  "reports": {
    "cached": 1,
    "ceiling": 1,
    "deferred": 1,
    "modelCalls": 1,
    "written": 1
  },
  "top": [
    {
      "additionalProperty": "example"
    }
  ],
  "warnings": [
    "example"
  ],
  "writes": {
    "created": 1,
    "removed": 1,
    "updated": 1
  }
}

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

404

Section titled “404”

The caller’s world declares no such fact; error names the ones it does

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

409

Section titled “409”

The fact’s declaration cannot run as declared; error says why

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