Skip to content

Answer a background view run's question

POST
/api/v1/views/runs/{runId}/answer
curl --request POST \
--url http://localhost:11044/api/v1/views/runs/example/answer \
--header 'Content-Type: application/json' \
--header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
--data '{ "choice": "example" }'

The owner’s answer to the quote a WAITING_INPUT run carries. proceed or background runs it, allowed to spend what was quoted; narrow or cancel settles it CANCELLED with nothing fetched. Answers with the run’s envelope after the answer.

runId
required
string

The run id: the executionId of the WAITING_INPUT envelope

The chosen option’s value under choice

Media typeapplication/json

The answer to a background view run’s question: one of the values its choice.options lists

object
choice
required

The chosen option’s value, e.g. background, proceed, narrow or cancel

string

Example generated

{
"choice": "example"
}

The run’s envelope after the answer

Media typeapplication/json

The result of invoking a named lens or view: its status and outcome, the data, and stable warning and error codes, never the query or script behind it

object
choice

Only on a WAITING_INPUT envelope from a background run: the quote its owner must answer before it runs

object
answer
required

Where the answer goes: POST {“choice”: “<an option’s value>”}; only the run’s owner may answer

string
expiresAt

Epoch milliseconds after which the question lapses unanswered and nothing runs

integer format: int64
options
required

The answers the question takes

Array<object>

One answer a background run’s question takes

object
label
required

What to show for this answer

string
value
required

The value to post as the answer

string
question
required

What the run would cost and the question put to its owner, e.g. the calls it would make to a named source

string
columnSources

Each result column and the plain expression that computed it, where that can be stated without exposing the query

object
key
additional properties
string
contractVersion
required

This envelope’s contract version, so a consumer can pin the shape

string
data

The result as nested JSON; null when there is no data (see outcome)

object
array
boolean
bigDecimal
boolean
bigInteger
boolean
binary
boolean
boolean
boolean
container
boolean
double
boolean
embeddedValue
boolean
empty
boolean
float
boolean
floatingPointNumber
boolean
int
boolean
integralNumber
boolean
long
boolean
missingNode
boolean
nodeType
string
Allowed values: ARRAY BINARY BOOLEAN MISSING NULL NUMBER OBJECT POJO STRING
null
boolean
number
boolean
object
boolean
pojo
boolean
short
boolean
string
boolean
textual
boolean
valueNode
boolean
dataContract

For a view bound to an ODCS data contract, the verdict its result was checked to

object
apiVersion
required

The ODCS apiVersion the contract declares, such as v3.1.0; v3.1.0 when the view was refused before it ran

string
available
required

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

boolean
blocksRows
required
boolean
checkedAt
required

ISO-8601 instant the result was checked

string
checks
required

Each check made, in the order it was made

Array<object>

One check made when a view’s result was evaluated against its data contract

object
kind
required

schema, quality, freshness, status, binding or execution

string
message

What it found, in words, naming rows and fields but never their values; null when there is nothing to say

string
ruleId
required

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

string
scope

invocation for the schema check, which covers this one result; null for every other check

string
verdict
required

PASS, WARN, FAIL, or UNKNOWN when the check could not be made

string
Allowed values: PASS WARN FAIL UNKNOWN
id
required

Id of the governing contract, as the view’s binding pins it

string
mode
required

observe or enforce, from the view’s binding

string
Allowed values: observe enforce
object
required

The contract object the rows were checked against, as the binding names it

string
status
required

The contract’s ODCS status, such as active, deprecated or retired; unavailable when the pinned contract is not in the world

string
verdict
required

The worst of the checks: FAIL if any failed, else UNKNOWN if any could not be made, else WARN if any warned, else PASS

string
Allowed values: PASS WARN FAIL UNKNOWN
version
required

The pinned contract version

string
error

Present only on a failed or refused outcome: a stable code and a message written to be shown

object
code
required

A stable, machine-readable code, e.g. FAN_OUT_OVER_BUDGET, FETCH_CAPPED, VIEW_QUERY_INVALID, CANCELLED

string
message
required

What happened and what would change it, safe to show; names no query, index or internal label

string
reason

Why a lookup that read records answered none, where a caller may act on it (FETCHED_NOT_MATCHED or UNPUSHED_FILTER); on a TOO_BROAD stopped at a fixed budget, which budget (MATCH_WORK, HELD_ROWS, STATEMENT_TIME, EXPRESSION_COST, STATEMENT_SHAPE, FETCHED_RECORDS, DERIVED_PAIRS, DERIVATION_ROUNDS, GRAPH_HEAP), or UNBOUNDED when nothing bounded a source it reads; null otherwise

string
executionId
required

Server-minted id of this execution; for a background run, the run id to poll, answer or stop it by

string
metrics
required

Coarse execution metrics: duration and call counts, never the calls themselves

object
cacheHit

Whether the answer was served from cache, when known

boolean
derivationMs

Milliseconds spent pricing and evaluating those rule sets, when any ran

integer format: int64
derivedFacts

Facts DERIVE rule sets concluded for this answer, when any ran

integer format: int64
durationMs
required

Wall-clock milliseconds the execution took

integer format: int64
externalCalls
required

Calls made to external data sources, as a count

integer format: int32
semanticCalls
required

Relevance searches made for a semantic anchor, as a count

integer format: int32
operationId
required

The lens id or view name that was invoked

string
outcome
required

Why the result is what it is: OK, EMPTY, PARTIAL, SOURCE_UNAVAILABLE, TOO_BROAD, TOO_EXPENSIVE, NOT_PERMITTED, UNTRUSTED_DATA, FAILED, or PENDING while a run has not settled

string
Allowed values: OK EMPTY PARTIAL SOURCE_UNAVAILABLE TOO_BROAD TOO_EXPENSIVE NOT_PERMITTED UNTRUSTED_DATA FAILED PENDING
outputType

The declared output type of data (rows, or a lens’s kind); null when there is no data

string
status
required

Lifecycle status: SUCCEEDED or FAILED for a synchronous call; RUNNING, WAITING_INPUT or CANCELLED only on the background surface

string
Allowed values: SUCCEEDED FAILED RUNNING WAITING_INPUT CANCELLED
warnings
required

Machine-readable warnings with stable codes; non-empty means the rows are not the whole story

Array<object>

A warning about a result: a stable code and a message that names no producer, index, label or query

object
code
required

A stable, machine-readable warning code, e.g. PARTIAL

string
message
required

What the warning means for these rows, safe to show

string

Example

{
"data": {
"nodeType": "ARRAY"
},
"dataContract": {
"checks": [
{
"verdict": "PASS"
}
],
"mode": "observe",
"verdict": "PASS"
},
"outcome": "OK",
"status": "SUCCEEDED"
}

The choice is not one the question takes; the refusal names those it does. A body that will not parse answers an ApiError

One of:

A request-level refusal from the headless surface. Carries only the reason; an execution that ran and failed answers 200 with the outcome in its envelope instead

object
error
required

Why the request was refused, written to be shown: the unknown lens, view or run, the argument at fault, or the field the body should not have

string

Example generated

{
"error": "example"
}

Not authenticated. The filter chain answers an ApiError; a principal that resolves to no user answers the refusal

One of:

A request-level refusal from the headless surface. Carries only the reason; an execution that ran and failed answers 200 with the outcome in its envelope instead

object
error
required

Why the request was refused, written to be shown: the unknown lens, view or run, the argument at fault, or the field the body should not have

string

Example generated

{
"error": "example"
}

No background view run of this id belongs to the caller; another user’s run answers the same

Media typeapplication/json

A request-level refusal from the headless surface. Carries only the reason; an execution that ran and failed answers 200 with the outcome in its envelope instead

object
error
required

Why the request was refused, written to be shown: the unknown lens, view or run, the argument at fault, or the field the body should not have

string

Example generated

{
"error": "example"
}

The run is not waiting for an answer: it already ran, was answered, or its question lapsed. The body is its envelope

Media typeapplication/json

The result of invoking a named lens or view: its status and outcome, the data, and stable warning and error codes, never the query or script behind it

object
choice

Only on a WAITING_INPUT envelope from a background run: the quote its owner must answer before it runs

object
answer
required

Where the answer goes: POST {“choice”: “<an option’s value>”}; only the run’s owner may answer

string
expiresAt

Epoch milliseconds after which the question lapses unanswered and nothing runs

integer format: int64
options
required

The answers the question takes

Array<object>

One answer a background run’s question takes

object
label
required

What to show for this answer

string
value
required

The value to post as the answer

string
question
required

What the run would cost and the question put to its owner, e.g. the calls it would make to a named source

string
columnSources

Each result column and the plain expression that computed it, where that can be stated without exposing the query

object
key
additional properties
string
contractVersion
required

This envelope’s contract version, so a consumer can pin the shape

string
data

The result as nested JSON; null when there is no data (see outcome)

object
array
boolean
bigDecimal
boolean
bigInteger
boolean
binary
boolean
boolean
boolean
container
boolean
double
boolean
embeddedValue
boolean
empty
boolean
float
boolean
floatingPointNumber
boolean
int
boolean
integralNumber
boolean
long
boolean
missingNode
boolean
nodeType
string
Allowed values: ARRAY BINARY BOOLEAN MISSING NULL NUMBER OBJECT POJO STRING
null
boolean
number
boolean
object
boolean
pojo
boolean
short
boolean
string
boolean
textual
boolean
valueNode
boolean
dataContract

For a view bound to an ODCS data contract, the verdict its result was checked to

object
apiVersion
required

The ODCS apiVersion the contract declares, such as v3.1.0; v3.1.0 when the view was refused before it ran

string
available
required

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

boolean
blocksRows
required
boolean
checkedAt
required

ISO-8601 instant the result was checked

string
checks
required

Each check made, in the order it was made

Array<object>

One check made when a view’s result was evaluated against its data contract

object
kind
required

schema, quality, freshness, status, binding or execution

string
message

What it found, in words, naming rows and fields but never their values; null when there is nothing to say

string
ruleId
required

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

string
scope

invocation for the schema check, which covers this one result; null for every other check

string
verdict
required

PASS, WARN, FAIL, or UNKNOWN when the check could not be made

string
Allowed values: PASS WARN FAIL UNKNOWN
id
required

Id of the governing contract, as the view’s binding pins it

string
mode
required

observe or enforce, from the view’s binding

string
Allowed values: observe enforce
object
required

The contract object the rows were checked against, as the binding names it

string
status
required

The contract’s ODCS status, such as active, deprecated or retired; unavailable when the pinned contract is not in the world

string
verdict
required

The worst of the checks: FAIL if any failed, else UNKNOWN if any could not be made, else WARN if any warned, else PASS

string
Allowed values: PASS WARN FAIL UNKNOWN
version
required

The pinned contract version

string
error

Present only on a failed or refused outcome: a stable code and a message written to be shown

object
code
required

A stable, machine-readable code, e.g. FAN_OUT_OVER_BUDGET, FETCH_CAPPED, VIEW_QUERY_INVALID, CANCELLED

string
message
required

What happened and what would change it, safe to show; names no query, index or internal label

string
reason

Why a lookup that read records answered none, where a caller may act on it (FETCHED_NOT_MATCHED or UNPUSHED_FILTER); on a TOO_BROAD stopped at a fixed budget, which budget (MATCH_WORK, HELD_ROWS, STATEMENT_TIME, EXPRESSION_COST, STATEMENT_SHAPE, FETCHED_RECORDS, DERIVED_PAIRS, DERIVATION_ROUNDS, GRAPH_HEAP), or UNBOUNDED when nothing bounded a source it reads; null otherwise

string
executionId
required

Server-minted id of this execution; for a background run, the run id to poll, answer or stop it by

string
metrics
required

Coarse execution metrics: duration and call counts, never the calls themselves

object
cacheHit

Whether the answer was served from cache, when known

boolean
derivationMs

Milliseconds spent pricing and evaluating those rule sets, when any ran

integer format: int64
derivedFacts

Facts DERIVE rule sets concluded for this answer, when any ran

integer format: int64
durationMs
required

Wall-clock milliseconds the execution took

integer format: int64
externalCalls
required

Calls made to external data sources, as a count

integer format: int32
semanticCalls
required

Relevance searches made for a semantic anchor, as a count

integer format: int32
operationId
required

The lens id or view name that was invoked

string
outcome
required

Why the result is what it is: OK, EMPTY, PARTIAL, SOURCE_UNAVAILABLE, TOO_BROAD, TOO_EXPENSIVE, NOT_PERMITTED, UNTRUSTED_DATA, FAILED, or PENDING while a run has not settled

string
Allowed values: OK EMPTY PARTIAL SOURCE_UNAVAILABLE TOO_BROAD TOO_EXPENSIVE NOT_PERMITTED UNTRUSTED_DATA FAILED PENDING
outputType

The declared output type of data (rows, or a lens’s kind); null when there is no data

string
status
required

Lifecycle status: SUCCEEDED or FAILED for a synchronous call; RUNNING, WAITING_INPUT or CANCELLED only on the background surface

string
Allowed values: SUCCEEDED FAILED RUNNING WAITING_INPUT CANCELLED
warnings
required

Machine-readable warnings with stable codes; non-empty means the rows are not the whole story

Array<object>

A warning about a result: a stable code and a message that names no producer, index, label or query

object
code
required

A stable, machine-readable warning code, e.g. PARTIAL

string
message
required

What the warning means for these rows, safe to show

string

Example

{
"data": {
"nodeType": "ARRAY"
},
"dataContract": {
"checks": [
{
"verdict": "PASS"
}
],
"mode": "observe",
"verdict": "PASS"
},
"outcome": "OK",
"status": "SUCCEEDED"
}