Create a run (rebuild a version, or a single scoped unit)
Starts a run for this package’s version identified by versionId. By
default (no scope selectors) it is a full run that re-materializes every
persist source in the version and rebuilds every indexed dimension it
defines — one run driving both unit families through the same two-phase
build (tables first, then indexes). It is the on-demand equivalent of the
run a publish triggers.
The optional sourceName / dimension / modelFilePath selectors (see
CreateRunRequest) narrow the run to a single unit (Phase C per-unit
dispatch); a null selector widens back to the whole version, so the
whole-version full run stays the default. A version that predates the
content-addressed index model is discovered and migrated into it as part
of the run. The produced
units are surfaced in the run’s build plan (buildPlan.nodes/edges on
getRun), each advancing its own serving pointer independently (a failed
unit does not block the others). Returns the started run.
Scheduled packages reject scoped runs. When the version’s package
declares a materialization.schedule (legal only in scope: version), it
refreshes the whole version atomically on its cron, so the only on-demand
rebuild it supports is the whole-version full run. A request that carries
any scope selector (sourceName / dimension / modelFilePath) against a
scheduled version is rejected with 400 rather than silently widened — omit
the selectors to refresh the whole version instead.
Authorization: Requires update access to the package.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
The unique identifier of the organization Standard identifier pattern for resource names
^[a-zA-Z0-9_ -]+$The unique identifier of the environment Standard identifier pattern for resource names
^[a-zA-Z0-9_ -]+$The unique identifier of the package Standard identifier pattern for resource names
^[a-zA-Z0-9_ -]+$Body
Request a run for a version. By default (no scope selectors) this is a full run: re-materialize every persist source in the version and rebuild every indexed dimension it defines, in one run. The optional sourceName / dimension / modelFilePath selectors narrow the run to a single unit (Phase C per-unit dispatch); a null selector widens to the whole version, so the whole-version full run stays the default.
The version to (re)build. With no scope selectors the run re-materializes all of the version's persist sources and rebuilds all of the dimensions they define. A version that predates the content-addressed index model is discovered and migrated into it as part of the same run.
Optional. Restrict the run to a single persist source's table (Phase C per-source dispatch). The named source is force-rebuilt (a fresh generation at the same content address); its persist upstreams are referenced from their existing materialized tables, not rebuilt (unless includeUpstream is set). Null widens to every persist source in the version.
Optional. Only meaningful when the target resolves to a source (sourceName set — for a source rerun, or an index rerun that also names its source). When true, the run also force-rebuilds the target's transitive upstream persisted sources (its full derivation closure), so the whole lineage feeding the target is refreshed rather than referenced from existing tables:
- source target: rebuild the source and every persisted source it derives from.
- index target (dimension set): rebuild the source table the index reads from and its upstream closure, then re-index. When false (default): a source target rebuilds only that source (its upstreams reused); an index target reuses the source table and only re-indexes. Ignored for a full run or a dimension target that names no source.
Optional. Restrict the run to a single indexed dimension's index. Combined with sourceName it targets that dimension on that source; alone it targets the dimension across the sources that define it (disambiguated by modelFilePath when set). Null widens to every indexed dimension in scope.
Optional. Disambiguates a dimension defined in more than one model file. Null widens to every model file defining the matched dimension.
Response
Run created (build started)
A package-level build/refresh event (version-independent) — the single,
unified run resource. It records the requested scope and correlates the
dispatch; its concrete units are the typed artifacts it produced —
materialized sources (source nodes) and built indexes (index nodes) —
surfaced in the run's build plan (buildPlan.nodes/edges, populated on
getRun). A run defaults to a full run spanning both families — a
publish, an on-demand rebuild, and a scheduled re-materialization all
refresh a version's tables and its indexes — but may also be scoped to a
single unit (Phase C per-unit dispatch). Each produced unit advances its
own serving pointer independently, so a partial failure leaves the run
READY while the failed unit carries its own error.
Stable, 1-based build ordinal within the package — the "Build gNNN" the UI shows (zero-padded for display). Monotonic per package, assigned at run creation. This is the run build number, NOT the per-source physical table generation (the g in a materialized table name), which counts per-source rebuilds and diverges under reuse. Null only for legacy runs created before the number existed.
PUBLISH, ON_DEMAND, SCHEDULER Run lifecycle status, rolled up from the units it produced.
Non-terminal: BUILDING. Terminal: READY, FAILED, CANCELLED. A run is
READY once every produced unit is terminal; individual unit failures
are carried per node in the run's build plan (buildPlan.nodes, on getRun).
BUILDING, READY, FAILED, CANCELLED Requested target source (Phase C per-unit dispatch). Null on a whole-version run (the createRun default); set when createRun scoped the run to a single source via the sourceName selector. A null component widens to the whole package.
Requested target dimension (Phase C per-unit dispatch). Null on a whole-version run; set when createRun scoped the run to a single indexed dimension via the dimension selector.
Requested target model file (Phase C per-unit dispatch). Null on a whole-version run; disambiguates a dimension defined in more than one model file when the modelFilePath selector is set.
The scoped rerun's upstream choice (Phase C). Only meaningful with
targetSourceName/targetDimension: when true, the rerun also
force-rebuilt the target's transitive upstream persisted closure
(rather than reusing those upstream tables); false / absent = the
target alone (a source references its upstreams, an index reuses its
source table). Always false on a whole-version run.
The version this run was started for — the version whose publish drove a PUBLISH run, the version an on-demand full run rebuilds, or the version a scheduled re-materialization refreshes. Provenance only: the run itself is package-scoped and may impact other versions that bind the same dimension. Null only for a future package-level scoped refresh with no single initiating version.
A run's build plan across both unit families. Two layers:
- A diagnostic summary (counters + name lists): how many persist
sources (table units) and indexed dimensions (index units) it planned,
and their outcomes. Always populated (on both
listRunsandgetRun). - A stateful dependency graph (
nodes+edges): one node per source (materialized table) and per indexed dimension, each carrying that unit's live state, wired source -> index. Populated ongetRunonly; null onlistRunsto keep the list payload small (mirrors howVersion.buildPlanisgetVersion-only). This graph is the single source of truth for a run's units — the internal content address (entity_id) is never exposed.
Run-level failure reason (planning/orchestration failure); per-unit failures live on the produced units.