Skip to main content
Compare the compiled project with ClickHouse and print a read-only warehouse plan. A successful command assembles the complete workflow that a build would execute against the same observed state, then atomically publishes its JSON and SQL visibility artifacts without mutating ClickHouse.
The effective project mode chooses the planner:
  • Direct mode: plan the requested destructive rebuild. No selector means every model; selectors include downstream closure. Matching objects are not pruned.
  • Virtual environments: plan changed deployment objects, replay roots, and policies against published and staged state.
Use --deployment-id in virtual-environment mode to inspect exact deployment-specific physical names. Its timestamp prefix also fixes the deployment creation timestamp, so unchanged warehouse state and the same explicit identity produce deterministic workflow bytes. If omitted, plan generates a disposable preview identity.

​
Selection

Repeat --select to union bare model names and pipeline:<name> selectors:
Graph + syntax, tags, paths, globs, and exclusions are not supported by plan.

​
Replay controls

Both require --select and are mutually exclusive. --full-refresh applies only to virtual environments. --start-time applies to both modes. In direct mode it shows the effective start time in plan text and the nullable top-level start_time field in plan JSON. The direct SQL template shows the capture, preflight, and replay structure; values captured from ClickHouse during execution remain placeholders. Direct replay inputs must already exist and expose timestamp or landed-at lineage through the selected closure.

​
Common options

Connecting commands accept --host, --port, --username, --password, --database, --target, --vars, and --project-dir. --json emits structured output and --verbose (-v) includes full schema diffs.

​
Workflow artifacts

After read-only connected inspection, StreamBuild atomically replaces the complete plan directory. Direct mode publishes a non-executable template because replay watermarks and other runtime captures do not exist yet:
Virtual-environment plans have all physical identities and SQL values available during planning, so they publish exact workflow.sql and steps/*.sql files instead. The bytes printed by stb plan --json are exactly the bytes stored in plan.json; text mode writes the same JSON through the same serializer. In either layout, the combined workflow joins the numbered statements in execution order. Plan and build use the same connected preparation and ordering rules. They remain independent invocations: stb build inspects current warehouse state again and never reads, compares, promotes, or executes target/run/plan/. Warehouse changes between commands can therefore produce a different build workflow; build preflight assertions protect the state observed during its own preparation. All target/run/ files are disposable visibility output, not local state. Failed compilation, connected inspection, workflow assembly, or publication leaves any previous complete plan artifact unchanged.