Skip to main content
Direct mode is StreamBuild’s default operational model. It rebuilds selected model tables and materialized views at their ordinary names, then replays retained source history into them.
No mode setting is required. An explicit value is equivalent:

​
Plan behavior

Direct plans are intentionally conservative:
  • no selector rebuilds every model
  • a selector includes the selected model or pipeline and all downstream models
  • upstream prerequisites outside the execution closure are preserved
  • matching warehouse state does not prune a requested rebuild
  • plans show destructive drop and create actions but make no modifications
--start-time requires at least one selector. It plans the ordinary selected downstream closure but bounds replay from the effective source frontier. --full-refresh remains unavailable because an ordinary direct build already replays all retained source history.

​
Build behavior

One build:
  1. validates adopted sources and preserves managed Kafka landing resources
  2. rejects incompatible managed-source drift
  3. verifies retained history can satisfy the rebuild
  4. drops selected materialized views and model tables in reverse dependency order
  5. recreates model tables and views in dependency order
  6. captures inclusive replay watermarks and replays retained history
  7. runs applicable SQL audits against the rebuilt direct tables
Only the selected derived closure is torn down and recreated. Source objects and source rows stay in place, replay repopulates the new live tables with inclusive at-least-once boundaries, and audits run after those rebuilt resources are already live. A later failure does not restore the previous graph. With --start-time, the lifecycle stays destructive and unseeded: StreamBuild drops and recreates the same selected closure, then replays only the lower-and-upper-bounded source window. Managed and adopted source definitions and rows are not replaced, truncated, or deleted. Derived rows before the effective lower frontier are intentionally absent after success. --start-time is interpreted as UTC and remains an explicit UTC instant through planning and execution. A non-UTC ClickHouse server does not shift the boundary, including across daylight-saving transitions where local wall-clock hours may be skipped or repeated. Every replay input in the selected closure must already exist and expose its configured timestamp or landed-at lineage. Run an ordinary direct build first to create a managed source. If an intermediate model becomes a replay input, project time lineage through that model before requesting --start-time. Direct model names are unsuffixed:
There are no deployment-specific model branches, stable logical views, or deployment promotion.

​
Delivery guarantee

Replay is at least once around the inclusive cutoff. Rows arriving near boundary capture may be delivered by both the live materialized view and replay. Duplicate delivery is preferred over a missing interval. Use deduplicating engines, stable keys, or aggregate-idempotent model design when duplicate contribution would be incorrect.

​
Failure and rerun

Direct builds are destructive and do not roll back. If a build fails after teardown, rerun stb build after correcting the cause. Recovery is always a new invocation, never a resumed workflow. Each invocation inspects the live catalog and retained input again. A repeated --start-time request keeps the requested lower boundary but captures a fresh upper boundary; its preflight fails if the source no longer retains the requested window. An error-severity audit makes the command fail after the new resources are live; it does not revert the rebuild.

​
Authority and SQL baselines

Project declarations, the live ClickHouse catalog, and live source and target data are authoritative in direct mode. Replay boundaries are captured in process memory for the current build; StreamBuild does not use a direct-mode checkpoint or ownership table. _streambuild_direct_fingerprints is optional, best-effort history of successfully applied model SQL. It enables query diffs in later plans but never decides what exists, what should execute, or which replay range is safe. Missing or inaccessible fingerprint metadata does not block a build.

​
Mode ownership

Automatic conversion between direct and virtual-environment layouts is not supported. Use separate target databases for different modes and do not switch an existing managed target between modes.