What you will be able to do
- Explain what the Run when another job finishes trigger does and which job type it applies to
- Configure a downstream deploy job with the right project, upstream job and Completes on statuses
- Design fan-out and cross-project chains, and trace a triggered run back to its upstream job
- Tell job chaining apart from the chaining of run steps inside a single job
Key concept
Trigger on job completion (job chaining) — A deploy job trigger that enqueues the job when a chosen upstream deploy job finishes with one of the run statuses you selected. The upstream job's completion starts the downstream job, so you do not need a clock time or an external orchestrator to line the two up.
1.Why start a job from another job's completion
Two jobs that depend on each other are hard to line up on a clock. Say a daily ingestion-and-staging job usually takes forty minutes and a marts job is scheduled an hour after it starts. That works until the first job runs slow one morning. The marts job then builds on yesterday's staging tables, and nothing errors. Job chaining fixes this by tying the downstream job to the upstream job's completion rather than to a time of day.
In dbt the feature is a trigger on a deploy job, the job type that builds production data assets. A deploy job can start in three ways: on a schedule, through the API, or when another job completes. Neither of the other two job types has the third option. CI jobs start from a commit to a pull request or from the API. Merge jobs start from a merge into the environment's branch or from the API.
| Job type | What can trigger it |
|---|---|
| Deploy jobs | A schedule, the API, or the successful completion of another job |
| CI jobs | A commit to a PR, or the API |
| Merge jobs | A successful merge into the environment's branch, or the API |
The job scheduler treats a completion trigger as event-driven execution. That puts it in a different category from cron-based runs, which are covered under [scheduling a job](lesson:4.3). Merge jobs, API calls and a user clicking Run now are the scheduler's other event-driven triggers. The scheduler queues the job and runs it, the same as any other run.
Checkpoint 1 of 8· Check yourself
A team wants a job to start automatically whenever their nightly production build finishes. Which job type can be set up with that trigger?
Only deploy jobs list the completion of another job as a trigger type. CI jobs start from PR commits or the API, and merge jobs start from merges or the API.
“Deploy jobs — Build production data assets. Runs on a schedule, by API, or after another job completes.”Source: docs.getdbt.com
2.Configuring Run when another job finishes
You configure the chain on the downstream job, not on the upstream one. In the downstream deploy job's Triggers section, next to Run on schedule, there is a second option called Run when another job finishes. Turning it on shows three fields, and together they say exactly which upstream run should start this job.
| Field | What you set |
|---|---|
| Project | The parent project that contains the upstream deploy job |
| Job | The upstream deploy job whose completion starts this one |
| Completes on | The job run status(es) that will enqueue this deploy job |
Completes on is the field that needs a decision. The downstream job is enqueued only when the upstream run ends in a status you selected. If you select only success, a failed upstream run leaves the downstream job idle, which is usually what you want when it reads the upstream job's tables. Select more statuses only when the downstream job is worth running whatever the upstream outcome, for example because it does not rely on what the upstream job built.
Checkpoint 2 of 8· Put it in order
Put the steps for chaining a deploy job to an upstream job in order.
- 1.Select the project that has the upstream deploy job
- 2.In Completes on, select the run status(es) that will enqueue the job
- 3.Specify the upstream (parent) job whose completion triggers this job
- 4.In the Triggers section, enable the Run when another job finishes option
First you enable the trigger. Then you narrow it down to a project, then to a job in that project, and finally you choose which outcomes of that job start this one.
“In the Triggers section, enable the Run when another job finishes option.”Source: docs.getdbt.com
The UI isn't the only way to set this up. The same trigger can be set when a job is created through the Create Job API, which suits teams that manage job definitions in code. You also need two things before you start. The account must be on the Starter or an Enterprise-tier plan, because the trigger is not offered below that. And you need permissions on both the project and the job you are chaining from.
Checkpoint 3 of 8· Check yourself
An engineer can create and run deploy jobs but cannot find Run when another job finishes in the Triggers section. What should they check first?
The Trigger on job completion feature requires a Starter or Enterprise-tier plan. Docs, version and deferral settings have nothing to do with whether the trigger is available.
“For the Trigger on job completion feature, your dbt account must be on the Starter or an Enterprise-tier plan.”Source: docs.getdbt.com
Checkpoint 4 of 8· Exam question
A data platform engineer on the dbt Cloud Team plan opens a downstream deploy job's settings and looks for a way to make it run after an upstream job finishes, but the option is missing from the Triggers section. What is the most likely reason?
Correct answer: A — Job chaining is available only on Starter, Enterprise, and Enterprise+ plans, so the Team plan does not expose the "Run when another job finishes" toggle.
- A. Job chaining is gated to the Starter, Enterprise, and Enterprise+ plan tiers, so an account on a lower tier simply never renders the "Run when another job finishes" toggle. This matches the scenario exactly, since the setting is missing rather than merely disabled.
- B. Missing Job Admin permission would typically prevent editing the job at all rather than selectively hiding only the chaining toggle while leaving other trigger controls visible. Plan tier is the documented gate for this specific feature, not a permission scope.
- C. The upstream job's run history has no bearing on whether the chaining toggle appears in the downstream job's settings. The toggle's visibility depends on account plan tier, not on prior run outcomes of the job being referenced.
- D. Cross-project job chaining is supported directly from the downstream job's Triggers section by selecting the upstream project and job, with no separate account-level enablement step. There is no additional cross-project switch that must be turned on first.
Sources3
3.Fan-out and chains across projects
A single upstream job can start more than one job. Several downstream (child) jobs can all point at the same parent, and so can jobs in other projects. This works because the trigger lives on each child: every child names the parent and chooses its own Completes on statuses. One child might run only after a successful parent run, while another runs after any outcome.
Cross-project chaining is what makes multi-project setups practical without other tooling. In the dbt Mesh quickstart, a Finance team wants its customer payment journey job to run as soon as the Data Analytics team's daily job has refreshed. They create a deploy job in the Finance project and set it to Run when another job finishes. Then they pick the Daily job from the Data Analytics project. When Daily is run and completes successfully, the Finance job starts on its own. Without the trigger, coordinating the two projects would mean an external orchestrator. For how separate projects are set up in the first place, see [setting up additional dbt projects](lesson:7.1).
Checkpoint 5 of 8· Check yourself
A Finance project's model reads from tables built by a daily job in a separate Data Analytics project. What is the simplest way to make the Finance job run right after those tables refresh?
Completion triggers work across projects, so the Finance job can name the Data Analytics job as its parent. That keeps the two in sync without a fixed time offset or an external orchestrator.
“This simplifies the process of staying in sync with the upstream tables and removes the need for more sophisticated orchestration skills”Source: docs.getdbt.com
You can trace a chained run back to its parent. A run started by another job shows a link to the upstream job in its run details, and every run records its job trigger type in the run overview. When a downstream run looks wrong, follow that link to the upstream run that started it. Your configuration only names a job, and the link tells you which of its runs fired the trigger.
Open the run's details. The run overview shows the job trigger type. If another job started it, the run details also link to the upstream job, so you can open the parent run that fired the trigger.
Checkpoint 6 of 8· Exam question
A team wants a downstream cleanup job to run whenever an upstream deploy job finishes, whether that run succeeds or fails, so failure logs can be archived regardless of outcome. Which "Completes on" setting on the downstream job's trigger satisfies this requirement?
Correct answer: C — Success or failure
- A. This condition enqueues the downstream job only when the upstream run succeeds, so a failed upstream run would never trigger the cleanup job and the archiving requirement would be missed.
- B. This condition enqueues the downstream job only when the upstream run fails, so successful upstream runs would never trigger the cleanup job, again missing half of the required outcomes.
- C. This condition enqueues the downstream job regardless of whether the upstream run ends in success or failure, matching the requirement to archive logs no matter the outcome.
- D. This refers to a deferral setting, not a job-completion status condition, and has no effect on which upstream run outcomes are allowed to trigger the downstream job.
4.Chained run steps versus chained jobs
"Chained" means two different things in dbt, and exam questions use that. Inside a job, the commands in Execution settings are chained run steps. They run in order, and if one fails the whole job fails with an Error status. [Steps within a dbt job](lesson:4.2) covers this in detail. Between jobs, chaining is the completion trigger described above: separate jobs, each with its own commands, settings and run history.
Each kind of chaining handles failure in its own way. With run steps, failure handling is fixed: a failed step stops the job, with one exception. The Run source freshness option runs before the job and can fail while the job still succeeds if later steps pass. With chained jobs, you choose what happens. The downstream job's Completes on statuses decide whether an upstream Error starts it. That makes splitting work into chained jobs useful when you want different settings per stage, a separate run record per stage, or a later stage that still runs after an earlier one fails.
| Aspect | Run steps in one job | Chained deploy jobs |
|---|---|---|
| Where configured | Commands in Execution settings | Run when another job finishes in Triggers |
| When a step or job fails | The entire job fails with an Error status | The downstream job is enqueued only if that status is selected in Completes on |
| Scope | One job, one environment | Across jobs, including jobs in other projects |
Checkpoint 7 of 8· Match them up
Match each setting to what it controls.
Tap a term, then the definition that fits it.
Commands and Run source freshness belong to Execution settings inside one job. Project and Completes on belong to the Run when another job finishes trigger, which links two jobs.
“In the Completes on option, select the job run status(es) that will enqueue the deploy job.”Source: docs.getdbt.com
Checkpoint 8 of 8· Exam question
A platform architect wants a single "core marts" deploy job to trigger three downstream jobs immediately after it completes successfully: one in the same project and two in separate dbt Cloud projects owned by other teams. What is the correct way to set this up?
Correct answer: A — Configure each of the three downstream jobs individually, enabling "Run when another job finishes" on each and pointing it at the core marts job as the upstream job.
- A. Job chaining is configured from the downstream side, so each of the three jobs must independently enable "Run when another job finishes" and point at the core marts job, which is exactly how one upstream job can fan out to many downstream jobs across projects.
- B. Run steps execute commands within a single job's own environment and cannot invoke jobs in other projects, so this approach cannot fan out to jobs owned by other teams.
- C. There is no upstream-side rule that lists multiple downstream jobs; chaining is always configured on each downstream job by selecting its own upstream project and job, not centrally on the upstream job.
- D. The Triggers section on a job configures how that job itself gets triggered, such as webhooks for CI, and does not broadcast completion events to other projects' schedulers.
Sources3
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Job chaining is configured on the upstream job by listing the jobs it should start next.Why is that wrong?
The trigger lives on the downstream job. In its Triggers section, you enable Run when another job finishes and specify the upstream (parent) job.
Covered in Configuring Run when another job finishes
2.A completion trigger can only point at a job in the same project, and a parent job can start only one child.Why is that wrong?
One upstream job can trigger multiple downstream jobs, including jobs in other projects, as long as you have permissions on that project and job.
Covered in Fan-out and chains across projects
3.CI and merge jobs can also be set to run after another job completes.Why is that wrong?
Completion of another job is a trigger type only for deploy jobs. CI jobs start from PR commits or the API, and merge jobs start from merges or the API.
4.If one run step in a job fails, the remaining steps still run, much like a chained job that is set to complete on Error.Why is that wrong?
Run steps inside one job are chained so that a failing step makes the entire job fail with an Error status. Only job-to-job triggers have a Completes on choice.
Covered in Chained run steps versus chained jobs
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://docs.getdbt.com/docs/deploy/jobsOfficial docs
“Triggered by a schedule, API, or the successful completion of another job.”
↩︎ Why start a job from another job's completion“Triggered by a schedule, API, or the successful completion of another job.”
↩︎ Exam trap 3“Deploy jobs — Build production data assets. Runs on a schedule, by API, or after another job completes.”
↩︎ Checkpoint - 2.https://docs.getdbt.com/docs/deploy/job-schedulerOfficial docs
“Event-driven execution of dbt jobs that run based on the completion of another job (trigger on job completion)”
↩︎ Why start a job from another job's completion - 3.https://docs.getdbt.com/docs/deploy/deploy-jobsOfficial docs
“Project — Specify the parent project that has that upstream deploy job.”
↩︎ Configuring Run when another job finishes“In the Completes on option, select the job run status(es) that will enqueue the deploy job.”
↩︎ Configuring Run when another job finishes“You must have proper permissions to the project and job to configure the trigger.”
↩︎ Configuring Run when another job finishes“If another job triggers your job to run, you can find a link to the upstream job in the run details section.”
↩︎ Fan-out and chains across projects“If the step fails, the job can succeed if subsequent steps pass.”
↩︎ Chained run steps versus chained jobs“Run when another job finishes — Run the deploy job when another upstream deploy job completes.”
↩︎ Key concept“Specify the upstream (parent) job that, when completed, will trigger your job. You can also use the Create Job API to do this.”
↩︎ Exam trap 1“You can set up a configuration where an upstream job triggers multiple downstream (child) jobs and jobs in other projects.”
↩︎ Exam trap 2“During a job run, built-in commands are "chained" together and if one run step fails, the entire job fails with an "Error" status.”
↩︎ Exam trap 4“In the Triggers section, enable the Run when another job finishes option.”
↩︎ Checkpoint“For the Trigger on job completion feature, your dbt account must be on the Starter or an Enterprise-tier plan.”
↩︎ Checkpoint“During a job run, built-in commands are "chained" together and if one run step fails, the entire job fails with an "Error" status.”
↩︎ Prediction“In the Completes on option, select the job run status(es) that will enqueue the deploy job.”
↩︎ Checkpoint - 4.https://docs.getdbt.com/guides/mesh-qsOfficial docs
“In the Triggers section, configure the job to Run when another job finishes and select the upstream job”
↩︎ Fan-out and chains across projects“This simplifies the process of staying in sync with the upstream tables and removes the need for more sophisticated orchestration skills”
↩︎ Checkpoint