configure-dbt-build-after

name

configure-dbt-build-after

description

Configure dbt model build_after for Orchestra state-aware orchestration — author the config.freshness.build_after block (count, period, updates_on) on dbt models so Orchestra rebuilds a model only after a minimum SLA window AND when its upstream data is fresh, then ensure use_state_orchestration is enabled on the Orchestra dbt task. Use when asked to set up build_after, configure per-model rebuild SLAs, gate model rebuilds on upstream freshness, stop unnecessary dbt rebuilds, or set up state-aware orchestration in Orchestra. Trigger on phrases like "configure build_after", "add build_after", "only rebuild when upstream is fresh", "per-model SLA", "updates_on any/all", or "stop rebuilding models that haven't changed" in a dbt or Orchestra context. build_after is warehouse-agnostic (same config for Snowflake, BigQuery, Databricks, MotherDuck) but depends on source freshness being configured — the source/freshness-signal half is the separate configure-dbt-source-freshness skill.

Configure dbt build_after

Author the per-model build_after config so Orchestra rebuilds a model only when both its SLA window has elapsed and its upstream data is fresh. This is the model-side half of state-aware orchestration (SAO); the source-side half is source freshness (see the configure-dbt-source-freshness skill). This skill writes config only — it does not run dbt or trigger pipelines.

Unlike freshness, build_after is warehouse-agnostic — the same config works on Snowflake, BigQuery, Databricks, and MotherDuck. The only warehouse nuance lives upstream in the freshness signal it consumes.

When to use

• User wants per-model rebuild SLAs, or to stop rebuilding models when nothing upstream changed.
• User is setting up Orchestra SAO and needs the model-side gating.
• Files like a model's YAML config: block or dbt_project.yml models: are in play.

What "done" looks like

1. config.freshness.build_after (count, period, optional updates_on) is set on the target models, in the model YAML or dbt_project.yml, matching project conventions.
2. use_state_orchestration: true is set on the Orchestra dbt Core task.
3. Source freshness is confirmed present upstream (or flagged as a required companion step).
4. A handoff explains the SLA values chosen, the updates_on choice, and how to verify.

Read first

• ../../references/orchestra/dbt-sao/build-after.md — build_after schema and how to pick count/period/updates_on.
• ../../references/orchestra/dbt-sao/orchestra-task.md — enabling SAO on the task.
• ../../references/orchestra/dbt-sao/source-freshness.md — only if you also need to add the upstream freshness build_after depends on.

Workflow

1. Confirm upstream freshness exists. build_after gates on "is upstream fresh?", which is meaningless without source freshness configured. Check the project's sources: YAML. If freshness is missing, say so and pair this with configure-dbt-source-freshness — don't author build_after against a signal that doesn't exist.

2. Identify the target models. Which models get an SLA? Usually marts / exposed models the user cares about refreshing on a cadence. Read a neighbouring model's config to match how the project configures models (inline config: vs dbt_project.yml).

3. Settle the SLA (count/period) — ask first, don't guess. The SLA is a business decision, and the user often already knows it. Prompt the user before doing anything else: do they have a target SLA per model (or a marts-wide default) in mind, or would they like you to derive one from warehouse usage? Two paths (see build-after.md for queries and detail):

   • B — user-defined (expect this first): take the SLA the user gives you.
   • A — derive from warehouse usage: only if the user asks for it and your client can run read-only warehouse queries — estimate how often each model is consumed (or how often its upstreams refresh) from query/access history, then show the user the number + the evidence to confirm or override. Read-only only — never mutate the warehouse, and don't run the query without the user opting in. Never invent a number; if the user has no SLA and doesn't want the usage path, leave a clearly-marked placeholder and explain the trade-off.

4. Author build_after. Set count + period to the agreed SLA (e.g. hourly → count: 1, period: hour). Choose updates_on from the model's DAG:

   • all — wait until every upstream is fresh (joins where a partial refresh would mislead).
   • any (default) — rebuild as soon as any upstream has new data.

5. Ensure SAO is enabled on the Orchestra task. use_state_orchestration: true is the SAO master switch — it makes Orchestra consume all SAO config (freshness and build_after), not a build_after-specific setting. Find the dbt Core task (integration: DBT_CORE, integration_job: DBT_CORE_EXECUTE) and make sure it's on, following orchestra-task.md for the Git-backed vs Orchestra-backed path. If it's already enabled (e.g. source freshness was set up first), just confirm it — don't re-toggle.

6. Hand off. Report: models changed, SLA values + how they were chosen (usage-derived vs user-defined) and updates_on rationale, whether upstream freshness was present or still needed, whether SAO was newly enabled, and how to verify.

Verifying (don't run it for them)

Explain rather than execute: on the next Orchestra run with SAO enabled, a model with build_after is skipped until its window elapses and upstream is fresh; otherwise it builds. The user can inspect SAO decisions by setting ORCHESTRA_DBT_DEBUG=true on the task.

Guardrails

• Write config only for the pipeline/repo — never run dbt, never start_pipeline, never mutate the warehouse. You may run read-only usage/metadata queries to estimate SLAs only if the user opts in and your client can query the warehouse; otherwise ask the user for the SLAs.
• Don't author build_after without upstream source freshness — flag it as a dependency.
• count/period are required; updates_on defaults to any — only set it when all is meant.
• Match the project's config location (model YAML vs dbt_project.yml); don't reformat unrelated YAML.
• use_state_orchestration is SAO — not Slim CI. Don't conflate them.