This is an automated email from the ASF dual-hosted git repository.
amoghrajesh 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 1481de61c4c Document effect of clearing a task instance on task state
store (#71356)
1481de61c4c is described below
commit 1481de61c4c85dd984c33ecd6fe7ff173d4010ad
Author: Amogh Desai <[email protected]>
AuthorDate: Wed Aug 12 09:46:34 2026 +0530
Document effect of clearing a task instance on task state store (#71356)
---
airflow-core/docs/core-concepts/resumable-tasks.rst | 21 +++++++++++++++++++++
docs/spelling_wordlist.txt | 1 +
2 files changed, 22 insertions(+)
diff --git a/airflow-core/docs/core-concepts/resumable-tasks.rst
b/airflow-core/docs/core-concepts/resumable-tasks.rst
index 703bf445362..98df3d45e60 100644
--- a/airflow-core/docs/core-concepts/resumable-tasks.rst
+++ b/airflow-core/docs/core-concepts/resumable-tasks.rst
@@ -126,6 +126,27 @@ existing job on retry instead of submitting a new one.
For more details and a working example, see
:class:`~airflow.sdk.ResumableJobMixin`.
+**Clearing a task is treated the same as a retry**
+
+Clearing a task instance does not delete its ``task_state_store`` rows -- they
are only removed
+when the ``dag_run`` itself is deleted, or by :ref:`airflow state-store clean
+<task-and-asset-state-store-cleanup>`. For a checkpointed task this is usually
what you want:
+clearing resumes from the last checkpoint rather than starting over.
+
+For an operator with durable execution, it means clearing a task whose
external job already
+succeeded reads that stored result back and returns immediately, without
resubmitting the job. If
+you want clearing to always resubmit regardless of a prior success, set
+``[state_store] clear_on_success = True``, which deletes a task's state store
rows automatically
+when it moves to ``SUCCESS`` (see
:doc:`/administration-and-deployment/task-and-asset-state-store`).
+
+This does not guarantee the external job is still there to reconnect to,
though. Clearing a task
+that is actively running (``deferrable=False``) stops the worker process,
which runs the
+operator's ``on_kill``. Most operators with durable execution cancel the
external job there by
+default, so the next attempt finds it already stopped instead of still running
-- an operator that
+leaves the job running by default on kill is the exception, check its own
docs. Deferred tasks
+(``deferrable=True``) don't have this problem: there is no actively polling
worker process for the
+clear to interrupt.
+
.. _concepts-resumable-tasks-async:
Asynchronous Tasks
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index 73212e3d679..004b6a50629 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -237,6 +237,7 @@ charset
chatbot
chatbots
CheckOperator
+checkpointed
checksums
childs
chmod
