Skip to content

Add airflowctl dags clear command - #68706

Merged
henry3260 merged 6 commits into
apache:mainfrom
henry3260:add-airflowctl-dags-clear
Jul 30, 2026
Merged

Add airflowctl dags clear command#68706
henry3260 merged 6 commits into
apache:mainfrom
henry3260:add-airflowctl-dags-clear

Conversation

@henry3260

@henry3260 henry3260 commented Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Why

This adds airflowctl dags clear so those Dag runs can be selected declaratively and cleared in one command, with a confirmation prompt before anything is modified.

What

New command — airflow-ctl/src/airflowctl/ctl/cli_config.py,
airflow-ctl/src/airflowctl/ctl/commands/dag_command.py,
airflow-ctl/src/airflowctl/ctl/help_texts.yaml:

  • airflowctl dags clear DAG_ID selects Dag runs by exactly one of --run-id,
    --partition-key, or the --partition-date-start / --partition-date-end
    window, and clears each selected run's task instances via the existing
    tasks.clear operation (reset_dag_runs=True).
  • --only-failed / --only-running narrow which task instances are cleared;
    --yes skips the confirmation prompt. Without --yes the command prints the
    matching Dag runs and asks before clearing.
  • All selector validation lives in one place: exactly one selector must be given,
    the partition-date bounds must be supplied together and in order,
    --only-failed and --only-running are mutually exclusive, and unparsable
    dates are rejected up front — before any API call is made.
  • Partition-date bounds accept YYYY-MM-DD or a full ISO 8601 datetime; only the
    calendar day is used, matching how the API interprets partition_date in the
    Dag's timetable timezone.
  • --partition-key matches exactly. The API filter is a pattern filter, so the
    returned page is additionally filtered client-side to drop prefix matches such
    as customer-a-suffix.
  • Dag-run listing is paginated to completion rather than stopping at the default
    page limit, so a large selection is not silently truncated.

API client — airflow-ctl/src/airflowctl/api/operations.py:

  • DagRunOperations.list gained offset, partition_date_gte,
    partition_date_lte, and partition_key_pattern, matching the query
    parameters the GET /dags/{dag_id}/dagRuns endpoint actually declares. FastAPI
    silently drops query params it does not declare, so a mismatched name would
    return an unfiltered list — and the command would clear every run of the Dag.
  • _serialize_query_param now serializes datetime.date as well as
    datetime.datetime.
  • cli_config.CommandFactory learned to map the datetime.date annotation to
    the corresponding argparse type.

Docs — airflow-ctl/docs/images/output_dags.svg and command_hashes.txt
regenerated for the new subcommand.

related: #68402

Was generative AI tooling used to co-author this PR?
  • Yes — Claude Code (Opus 5)

@henry3260 henry3260 mentioned this pull request Jun 18, 2026
Merged
1 task
henry3260 and others added 2 commits July 29, 2026 15:33
@henry3260
Add airflowctl dags clear command
2280cf8
@henry3260
Fix airflowctl dags clear ignoring the partition date window
5500c51 
The Dag run list endpoint declares the partition window as
partition_date_gte / partition_date_lte. The names the command sent
belong to the request body of a different route, and FastAPI drops
query params it does not declare, so the window was silently discarded
and every run of the Dag came back — and was cleared.

partition_date_gt / partition_date_lt are not query params on that
endpoint either, so they could never have filtered anything.
@henry3260
henry3260 force-pushed the add-airflowctl-dags-clear branch from 4cac9a5 to 5500c51 Compare July 29, 2026 09:36
henry3260 added 4 commits July 29, 2026 18:58
@henry3260
Drop unused Dag run logical date filters from airflowctl
f80baa7 
Nothing ever passed logical_date_gt or logical_date_lt, and documenting
them broke the docs build: the spelling wordlist carries gte and lte but
not gt and lt, so the generated API docs failed spell-checking.
@henry3260
Reuse the tasks clear operation for airflowctl dags clear
2a9c66a 
DagRunOperations gained a private clear helper that duplicated the
existing TasksOperations.clear. Because the CLI is generated from the
operation classes, that helper also surfaced as a subcommand named
"-clear-task-instances" with no help text.

The Dag run list filters for run ID and partition key prefix had no
callers either.
@henry3260
Group airflowctl dags clear arguments with the other Dag arguments
e2441d2 
The new arguments landed under the "# Task Commands Args" heading, so anyone
looking for what "dags clear" accepts would not find them in the Dag section
where they belong.
@henry3260
Consolidate airflowctl dags clear argument validation in one place
65fa9f4 
The partition date ordering check sat in the function that fetches Dag runs
while every other check lived in the validator, so a reader had to look in two
places to learn what the command rejects. Parsing the window up front also
removes a branch that could never be taken.
@henry3260
henry3260 marked this pull request as ready for review July 29, 2026 17:31
bugraoz93
bugraoz93 approved these changes Jul 29, 2026
View reviewed changes

@bugraoz93 bugraoz93 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Henry!

@henry3260

henry3260 commented Jul 30, 2026

Copy link
Copy Markdown
Contributor Author

Thanks Henry!

Thanks for review!

@henry3260
henry3260 merged commit 07f5458 into apache:main Jul 30, 2026
188 checks passed
@github-actions

github-actions Bot commented Jul 30, 2026

Copy link
Copy Markdown
Contributor

Backport failed to create: airflow-ctl/v0-1-test. View the failure log Run details

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status Branch Result
❌ airflow-ctl/v0-1-test Commit Link

You can attempt to backport this manually by running:

cherry_picker 07f5458 airflow-ctl/v0-1-test

This should apply the commit to the airflow-ctl/v0-1-test branch and leave the commit in conflict state marking
the files that need manual conflict resolution.

After you have resolved the conflicts, you can continue the backport process by running:

cherry_picker --continue

If you don't have cherry-picker installed, see the installation guide.

dabla pushed a commit to dabla/airflow that referenced this pull request Aug 14, 2026
@henry3260 @dabla
Add airflowctl dags clear command (apache#68706)
c6b285f 
* Add airflowctl dags clear command

* Fix airflowctl dags clear ignoring the partition date window

The Dag run list endpoint declares the partition window as
partition_date_gte / partition_date_lte. The names the command sent
belong to the request body of a different route, and FastAPI drops
query params it does not declare, so the window was silently discarded
and every run of the Dag came back — and was cleared.

partition_date_gt / partition_date_lt are not query params on that
endpoint either, so they could never have filtered anything.

* Drop unused Dag run logical date filters from airflowctl

Nothing ever passed logical_date_gt or logical_date_lt, and documenting
them broke the docs build: the spelling wordlist carries gte and lte but
not gt and lt, so the generated API docs failed spell-checking.

* Reuse the tasks clear operation for airflowctl dags clear

DagRunOperations gained a private clear helper that duplicated the
existing TasksOperations.clear. Because the CLI is generated from the
operation classes, that helper also surfaced as a subcommand named
"-clear-task-instances" with no help text.

The Dag run list filters for run ID and partition key prefix had no
callers either.

* Group airflowctl dags clear arguments with the other Dag arguments

The new arguments landed under the "# Task Commands Args" heading, so anyone
looking for what "dags clear" accepts would not find them in the Dag section
where they belong.

* Consolidate airflowctl dags clear argument validation in one place

The partition date ordering check sat in the function that fetches Dag runs
while every other check lived in the validator, so a reader had to look in two
places to learn what the command rejects. Parsing the window up front also
removes a branch that could never be taken.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@bugraoz93 bugraoz93 bugraoz93 approved these changes
@potiuk potiuk Awaiting requested review from potiuk potiuk is a code owner
@dheerajturaga dheerajturaga Awaiting requested review from dheerajturaga dheerajturaga is a code owner

Assignees

No one assigned

Labels

area:airflow-ctl backport-to-airflow-ctl/v0-1-test kind:documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@henry3260 @bugraoz93