This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch v3-1-test
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/v3-1-test by this push:
new 6f955514350 [v3-1-test] docs(asset): enhance asset extra documentation
(#58769) (#58830)
6f955514350 is described below
commit 6f955514350515c03afbda07adf99dc4de567e2d
Author: github-actions[bot]
<41898282+github-actions[bot]@users.noreply.github.com>
AuthorDate: Fri Nov 28 21:42:12 2025 +0100
[v3-1-test] docs(asset): enhance asset extra documentation (#58769) (#58830)
(cherry picked from commit 2a84037dbad9a8681e6fd22efa503bc48032b024)
Co-authored-by: Wei Lee <[email protected]>
---
.../docs/authoring-and-scheduling/assets.rst | 50 +++++++++++++++++++---
1 file changed, 45 insertions(+), 5 deletions(-)
diff --git a/airflow-core/docs/authoring-and-scheduling/assets.rst
b/airflow-core/docs/authoring-and-scheduling/assets.rst
index 7e06d0344a5..dcdf15e4e3b 100644
--- a/airflow-core/docs/authoring-and-scheduling/assets.rst
+++ b/airflow-core/docs/authoring-and-scheduling/assets.rst
@@ -90,10 +90,10 @@ The identifier does not have to be absolute; it can be a
scheme-less, relative U
Non-absolute identifiers are considered plain strings that do not carry any
semantic meanings to Airflow.
-Extra information on asset
+Extra information on assets
----------------------------
-If needed, you can include an extra dictionary in an asset:
+If needed, you can include an additional dictionary in an asset using the
``extra`` parameter:
.. code-block:: python
@@ -102,9 +102,49 @@ If needed, you can include an extra dictionary in an asset:
extra={"team": "trainees"},
)
-This can be used to supply custom description to the asset, such as who has
ownership to the target file, or what the file is for. The extra information
does not affect an asset's identity.
+This allows you to provide custom metadata about the asset, such as ownership
information or the purpose of the file. The ``extra`` field does **NOT** affect
the identity of an asset.
+Thus, maintaining the uniqueness of the ``extra`` value is the user
responsibility. It suggested to have only one single set of ``extra`` value per
asset.
+
+For example, in the following snippet, only one of the ``extra`` dictionaries
will ultimately be stored, but it does guaranteed which one will be stored.
+
+.. code-block:: python
+
+ Asset("s3://asset/example.csv", extra={"d": "e"})
+ Asset("s3://asset/example.csv", extra={"f": "g"})
+
+This behavior also applies to dynamically generated assets created through
``AssetAlias``.
+In the example below, the final stored ``extra`` value is not guaranteed and
it might vary based on Dag processor settings.
+
+.. code-block:: python
+
+ from airflow.sdk import AssetAlias
+
+
+ @dag(schedule=None)
+ def my_dag_1():
+
+ @task(outlets=[AssetAlias("my-task-outputs")])
+ def my_task_with_outlet_events(*, outlet_events):
+ outlet_events[AssetAlias("my-task-outputs")].add(
+ # Asset extra set as {"from": "asset alias"}
+ Asset("s3://bucket/my-task", extra={"from": "asset alias"})
+ )
+
+ my_task_with_outlet_events()
+
+
+ # Asset extra set as {"key": "value"}
+ @dag(schedule=Asset("s3://bucket/my-task", extra={"key": "value"}))
+ def my_dag_2(): ...
+
+
+ my_dag_1()
+ my_dag_2()
+
+ # It's not guaranteed which extra will be the one stored
+
+.. note:: **Security Note:** Asset URIs and values in the ``extra`` field are
stored in cleartext in Airflow's metadata database. These fields are **not
encrypted**. **DO NOT** store sensitive information, especially credentials, in
either the asset URI or the ``extra`` dictionary.
-.. note:: **Security Note:** Asset URI and extra fields are not encrypted,
they are stored in cleartext in Airflow's metadata database. Do NOT store any
sensitive values, especially credentials, in either asset URIs or extra key
values!
Creating a task to emit asset events
------------------------------------
@@ -149,7 +189,7 @@ Attaching extra information to an emitting asset event
.. versionadded:: 2.10.0
A task with an asset outlet can optionally attach extra information before it
emits an asset event. This is different
-from `Extra information on asset`_. Extra information on an asset statically
describes the entity pointed to by the asset URI; extra information on the
*asset event* instead should be used to annotate the triggering data change,
such as how many rows in the database are changed by the update, or the date
range covered by it.
+from `Extra information on assets`_. Extra information on an asset statically
describes the entity pointed to by the asset URI; extra information on the
*asset event* instead should be used to annotate the triggering data change,
such as how many rows in the database are changed by the update, or the date
range covered by it.
The easiest way to attach extra information to the asset event is by
``yield``-ing a ``Metadata`` object from a task:
