This is an automated email from the ASF dual-hosted git repository.
eladkal 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 8930bc3db2d Document supported `databricks_retry_args` usage for
deferrable Databricks operators (#68017)
8930bc3db2d is described below
commit 8930bc3db2d32d9122001c89b35498a4c0d536ca
Author: kosiew <[email protected]>
AuthorDate: Sun Nov 8 02:36:28 2026 +0800
Document supported `databricks_retry_args` usage for deferrable Databricks
operators (#68017)
* docs(databricks): document retry_args serialization constraint for
deferrable operators
Add "Retry args in deferrable mode" subsection under
DatabricksSubmitRunDeferrableOperator and DatabricksRunNowDeferrableOperator
explaining:
- Serialization requirement: only plain Python primitives allowed across
the trigger boundary
- Supported shapes (int/float primitives, nested plain-dict)
- Unsupported shapes (Tenacity objects, callables) with note that a
ValueError is raised at task submission
- Recommended workaround: use non-deferrable mode for custom retry
strategies
Also update changelog for 7.16.0.
* Fix Databricks deferrable retry docs and validation
* chore(databricks): update operator documentation with full module paths
and clean up xrefs
- Fixed all Databricks operator cross-references to use full module
paths
- Verified removal of stale short xrefs, reraise, "plain primitives,"
and "task submission" wording
- Updated changelog and ensured generated checksum remains consistent
with main branch
* docs: improve retry hook documentation
- Remove misleading retry callable guidance
- Document hook overwrites retry/after
- Clarify non-deferrable escape hatch (stop/wait only)
- Warn that non‑empty args replace defaults; require both stop and wait
- Rename new anchors to match current operator names
---
providers/databricks/docs/operators/run_now.rst | 43 +++++++++++++++++++++-
providers/databricks/docs/operators/submit_run.rst | 43 +++++++++++++++++++++-
2 files changed, 82 insertions(+), 4 deletions(-)
diff --git a/providers/databricks/docs/operators/run_now.rst
b/providers/databricks/docs/operators/run_now.rst
index 908ea35b5ad..cbc2da28c82 100644
--- a/providers/databricks/docs/operators/run_now.rst
+++ b/providers/databricks/docs/operators/run_now.rst
@@ -20,7 +20,7 @@
DatabricksRunNowOperator
========================
-Use the
:class:`~airflow.providers.databricks.operators.DatabricksRunNowOperator` to
trigger a run of an existing Databricks job
+Use the
:class:`~airflow.providers.databricks.operators.databricks.DatabricksRunNowOperator`
to trigger a run of an existing Databricks job
via `api/2.2/jobs/run-now
<https://docs.databricks.com/dev-tools/api/latest/jobs.html#operation/JobsRunNow>`_
API endpoint.
@@ -175,6 +175,45 @@ operator always triggers a fresh run on retry, exactly as
before this feature ex
DatabricksRunNowDeferrableOperator
==================================
-Deferrable version of the
:class:`~airflow.providers.databricks.operators.DatabricksRunNowOperator`
operator.
+Deferrable version of the
:class:`~airflow.providers.databricks.operators.databricks.DatabricksRunNowOperator`
operator.
It allows to utilize Airflow workers more effectively using `new functionality
introduced in Airflow 2.2.0
<https://airflow.apache.org/docs/apache-airflow/2.2.0/concepts/deferring.html#triggering-deferral>`_
+
+.. _howto/operator:DatabricksRunNowOperator:retry-args:
+
+Retry args in deferrable mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When ``deferrable=True``, the ``databricks_retry_args`` dictionary is
serialized across the
+trigger boundary and must contain only values that Airflow serde can
serialize. Primitive
+values such as ``int``, ``float``, ``str``, ``bool``, ``None``, ``dict``, and
``list`` are
+the common safe choices.
+
+For controlling attempt count and delay in deferrable mode, leave
+``databricks_retry_args`` unset and use the dedicated operator parameters
+``retry_limit`` and ``retry_delay``. When ``databricks_retry_args`` is set,
+these dedicated parameters are ignored for the hook retry policy.
+
+Serialization validation only verifies that values can cross the trigger
boundary; it does
+not verify that the supplied keys and values are valid or meaningful
``tenacity.Retrying``
+keyword arguments. Custom tenacity strategy objects (``stop``, ``wait``,
``before``, etc.)
+require callable objects, which are not serialization-safe in deferrable mode.
The hook always
+replaces supplied ``retry`` and ``after`` values, so setting them has no
effect in either mode.
+
+**Not supported** in deferrable mode (will raise ``ValueError`` when the task
defers; the
+Databricks run has already been submitted at that point):
+
+.. code-block:: python
+
+ from tenacity import stop_after_attempt, wait_incrementing
+
+ # Tenacity strategy objects — NOT serializable
+ databricks_retry_args = {"stop": stop_after_attempt(3)}
+ databricks_retry_args = {"wait": wait_incrementing(start=30, increment=30)}
+
+If you need custom ``stop`` or ``wait`` strategies, use the non-deferrable
+:class:`~airflow.providers.databricks.operators.databricks.DatabricksRunNowOperator`
(``deferrable=False``).
+Setting non-empty ``databricks_retry_args`` replaces the hook's default retry
policy rather
+than merging with it, so supply both ``stop`` and ``wait``. Otherwise,
Tenacity defaults to
+``stop_never`` and ``wait_none()``, which retries persistently retryable API
errors forever
+without backoff.
diff --git a/providers/databricks/docs/operators/submit_run.rst
b/providers/databricks/docs/operators/submit_run.rst
index 87e3c869a8b..8124b928095 100644
--- a/providers/databricks/docs/operators/submit_run.rst
+++ b/providers/databricks/docs/operators/submit_run.rst
@@ -23,7 +23,7 @@
DatabricksSubmitRunOperator
===========================
-Use the
:class:`~airflow.providers.databricks.operators.DatabricksSubmitRunOperator` to
submit
+Use the
:class:`~airflow.providers.databricks.operators.databricks.DatabricksSubmitRunOperator`
to submit
a new Databricks job via Databricks `api/2.2/jobs/runs/submit
<https://docs.databricks.com/dev-tools/api/latest/jobs.html#operation/JobsRunsSubmit>`_
API endpoint.
@@ -244,6 +244,45 @@ operator always submits a fresh run on retry, exactly as
before this feature exi
DatabricksSubmitRunDeferrableOperator
=====================================
-Deferrable version of the
:class:`~airflow.providers.databricks.operators.DatabricksSubmitRunOperator`
operator.
+Deferrable version of the
:class:`~airflow.providers.databricks.operators.databricks.DatabricksSubmitRunOperator`
operator.
It allows to utilize Airflow workers more effectively using `new functionality
introduced in Airflow 2.2.0
<https://airflow.apache.org/docs/apache-airflow/2.2.0/concepts/deferring.html#triggering-deferral>`_
+
+.. _howto/operator:DatabricksSubmitRunOperator:retry-args:
+
+Retry args in deferrable mode
+-----------------------------
+
+When ``deferrable=True``, the ``databricks_retry_args`` dictionary is
serialized across the
+trigger boundary and must contain only values that Airflow serde can
serialize. Primitive
+values such as ``int``, ``float``, ``str``, ``bool``, ``None``, ``dict``, and
``list`` are
+the common safe choices.
+
+For controlling attempt count and delay in deferrable mode, leave
+``databricks_retry_args`` unset and use the dedicated operator parameters
+``retry_limit`` and ``retry_delay``. When ``databricks_retry_args`` is set,
+these dedicated parameters are ignored for the hook retry policy.
+
+Serialization validation only verifies that values can cross the trigger
boundary; it does
+not verify that the supplied keys and values are valid or meaningful
``tenacity.Retrying``
+keyword arguments. Custom tenacity strategy objects (``stop``, ``wait``,
``before``, etc.)
+require callable objects, which are not serialization-safe in deferrable mode.
The hook always
+replaces supplied ``retry`` and ``after`` values, so setting them has no
effect in either mode.
+
+**Not supported** in deferrable mode (will raise ``ValueError`` when the task
defers; the
+Databricks run has already been submitted at that point):
+
+.. code-block:: python
+
+ from tenacity import stop_after_attempt, wait_incrementing
+
+ # Tenacity strategy objects — NOT serializable
+ databricks_retry_args = {"stop": stop_after_attempt(3)}
+ databricks_retry_args = {"wait": wait_incrementing(start=30, increment=30)}
+
+If you need custom ``stop`` or ``wait`` strategies, use the non-deferrable
+:class:`~airflow.providers.databricks.operators.databricks.DatabricksSubmitRunOperator`
(``deferrable=False``).
+Setting non-empty ``databricks_retry_args`` replaces the hook's default retry
policy rather
+than merging with it, so supply both ``stop`` and ``wait``. Otherwise,
Tenacity defaults to
+``stop_never`` and ``wait_none()``, which retries persistently retryable API
errors forever
+without backoff.
