This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new e7369d04c45 Clarify backfill reprocessing options (#72590)
e7369d04c45 is described below
commit e7369d04c459853bf26a9a7bca21f033fd4ae87d
Author: Sasali <[email protected]>
AuthorDate: Mon Oct 19 04:36:08 2026 +0800
Clarify backfill reprocessing options (#72590)
Users currently have to infer how the CLI and REST API values correspond to
the clearer labels shown in the UI. Making that relationship explicit prevents
the same behavior from appearing to be three different settings.
---
airflow-core/docs/core-concepts/backfill.rst | 10 ++++++----
airflow-core/src/airflow/cli/cli_config.py | 6 +++---
airflow-core/tests/unit/cli/test_cli_parser.py | 13 +++++++++++++
3 files changed, 22 insertions(+), 7 deletions(-)
diff --git a/airflow-core/docs/core-concepts/backfill.rst
b/airflow-core/docs/core-concepts/backfill.rst
index 3db1903a1ad..e0202f85711 100644
--- a/airflow-core/docs/core-concepts/backfill.rst
+++ b/airflow-core/docs/core-concepts/backfill.rst
@@ -27,11 +27,13 @@ Backfill does not make sense for Dags that don't have a
time-based schedule.
Control over data reprocessing
------------------------------
-There are three options for reprocessing behavior:
+There are three options for reprocessing behavior. The user-facing names and
their corresponding
+CLI and REST API values are:
-* **none** - if there's already a run for this logical date, do not create
another, no matter the state
-* **failed** - if a run exists, if the state is failed, create a new run for
this date
-* **completed** - if a run exists, if the state is completed or failed, create
a new run for this date
+* **Missing Runs** (``none``) - if there's already a run for this logical
date, do not create another,
+ no matter the state
+* **Missing and Errored Runs** (``failed``) - if a run exists and is failed,
create a new run for this date
+* **All Runs** (``completed``) - if a run exists and is completed or failed,
create a new run for this date
If the latest run is still running or is queued, we do not create another run,
no matter the chosen reprocessing behavior.
diff --git a/airflow-core/src/airflow/cli/cli_config.py
b/airflow-core/src/airflow/cli/cli_config.py
index aec3ec81dfa..76e35eca7bb 100644
--- a/airflow-core/src/airflow/cli/cli_config.py
+++ b/airflow-core/src/airflow/cli/cli_config.py
@@ -423,10 +423,10 @@ ARG_BACKFILL_DRY_RUN = Arg(
ARG_BACKFILL_REPROCESS_BEHAVIOR = Arg(
("--reprocess-behavior",),
help=(
- "When a run exists for the logical date, controls whether new runs
will be "
- "created for the date. Default is none."
+ "Select which Dag runs to create: 'none' (Missing Runs), 'failed'
(Missing and Errored Runs), "
+ "or 'completed' (All Runs). Default is 'none'."
),
- choices=("none", "completed", "failed"),
+ choices=("none", "failed", "completed"),
)
ARG_BACKFILL_RUN_ON_LATEST_VERSION = Arg(
("--run-on-latest-version",),
diff --git a/airflow-core/tests/unit/cli/test_cli_parser.py
b/airflow-core/tests/unit/cli/test_cli_parser.py
index e136be55c5d..f12b4da158d 100644
--- a/airflow-core/tests/unit/cli/test_cli_parser.py
+++ b/airflow-core/tests/unit/cli/test_cli_parser.py
@@ -480,6 +480,19 @@ class TestCli:
with pytest.raises(SystemExit):
parser.parse_args([*cmd_args, "--help"])
+ def test_backfill_reprocess_behavior_help_uses_user_facing_names(self):
+ parser = cli_parser.get_parser()
+
+ with contextlib.redirect_stdout(StringIO()) as stdout,
pytest.raises(SystemExit):
+ parser.parse_args(["backfill", "create", "--help"])
+
+ normalized_help = " ".join(stdout.getvalue().split())
+ assert "--reprocess-behavior {none,failed,completed}" in
normalized_help
+ assert (
+ "'none' (Missing Runs), 'failed' (Missing and Errored Runs), or
'completed' (All Runs)"
+ in normalized_help
+ )
+
def test_dag_cli_should_display_help(self):
parser = cli_parser.get_parser(dag_parser=True)
