Principle:Astronomer Astronomer cosmos Operator Arguments Configuration

Overview

A configuration pattern for passing runtime arguments to every dbt operator generated within an orchestration DAG. The operator_args dictionary provides a single point of control for broadcasting shared settings across all dbt tasks produced during graph rendering.

Description

When rendering a dbt project as orchestration tasks, each generated operator (run, test, seed, snapshot, etc.) may need shared configuration. These settings span several categories:

Environment variables -- key-value pairs injected into the operator execution environment via the env or append_env keys.
dbt flags -- boolean or string flags such as install_deps, full_refresh, or vars that control dbt CLI behavior.
Execution-mode-specific settings -- parameters required by a particular execution backend, for example Docker image names, Kubernetes secrets, pod resource requests, or virtual-environment Python packages.
Watcher / deferrable settings -- keys like deferrable, execution_timeout, poke_interval, and timeout that control Airflow sensor behavior when running in watcher mode.

The operator_args dict is the mechanism for broadcasting all of these settings uniformly. It is accepted by both DbtDag and DbtTaskGroup at instantiation time, and its contents are merged into every operator that the Cosmos graph builder creates.

Usage

Use operator_args when you need to uniformly configure all generated dbt tasks. Common scenarios include:

Passing install_deps=True so that every operator installs dbt packages before execution.
Providing full_refresh=True to force a full reload across all models.
Setting vars to inject dbt variables into every invocation.
Supplying Kubernetes-specific arguments like image, secrets, get_logs, and is_delete_operator_pod when using the Kubernetes execution mode.
Configuring watcher-mode behavior with deferrable=True and execution_timeout.

The pattern is especially valuable when the same configuration must be applied consistently across dozens or hundreds of generated tasks, eliminating the need to configure each operator individually.

Theoretical Basis

This is a broadcast pattern -- a single dictionary of keyword arguments is merged into every operator instantiation during graph building. The mechanism works as follows:

The user provides an operator_args dict to DbtDag or DbtTaskGroup.
During graph construction, the build_airflow_graph() function receives this dict as task_args.
For each dbt node being mapped to an Airflow operator, the builder unpacks task_args as keyword arguments into the operator constructor.

This broadcast approach ensures:

Consistency -- every operator receives the same base configuration.
Single point of change -- modifying one dict updates all tasks.
Composability -- the dict can be assembled programmatically, allowing environment-specific overrides.

For watcher mode, additional keys like deferrable and execution_timeout control sensor behavior, enabling asynchronous polling of long-running dbt commands.

Knowledge Sources

Domains

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment