(airflow) branch main updated: docs: Clarify HLL in extraction precedence (#63723)

[mo...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

mobuchowski 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 df77f37266b docs: Clarify HLL in extraction precedence (#63723)
df77f37266b is described below

commit df77f37266b25c9a8cb44f4672296558dbf830ce
Author: Kacper Muda <mu...@gmail.com>
AuthorDate: Mon Mar 16 14:23:05 2026 +0100

    docs: Clarify HLL in extraction precedence (#63723)
---
 devel-common/src/sphinx_exts/templates/openlineage.rst.jinja2 |  3 +++
 providers/openlineage/docs/guides/developer.rst               | 10 +++++++++-
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/devel-common/src/sphinx_exts/templates/openlineage.rst.jinja2 b/devel-common/src/sphinx_exts/templates/openlineage.rst.jinja2
index 52c6a6df8c4..5f5e32516ad 100644
--- a/devel-common/src/sphinx_exts/templates/openlineage.rst.jinja2
+++ b/devel-common/src/sphinx_exts/templates/openlineage.rst.jinja2
@@ -69,6 +69,9 @@ the integration can go further. Besides recording which assets were read or writ
 it may also extract the executed SQL text, external query/job IDs. For each query a separate pair of child OpenLineage
 events is emitted.
 
+For details on when hook-level lineage is attached to the OpenLineage event and how it interacts with
+extractors and inlets/outlets, see :ref:`extraction_precedence:openlineage`.
+
 .. important::
   The level of detail captured varies between hooks and methods. Some may only report dataset information, while others
   expose SQL text, query IDs and more. Review the hook implementation to confirm what lineage data is available.
diff --git a/providers/openlineage/docs/guides/developer.rst b/providers/openlineage/docs/guides/developer.rst
index c37bd8c366a..ed2651bc8f2 100644
--- a/providers/openlineage/docs/guides/developer.rst
+++ b/providers/openlineage/docs/guides/developer.rst
@@ -41,7 +41,15 @@ it's important to keep in mind the order in which OpenLineage looks for lineage
 
 1. **Extractor** - check if there is a custom Extractor specified for Operator class name. Any custom Extractor registered by the user will take precedence over default Extractors defined in Airflow Provider source code (f.e. BashExtractor).
 2. **OpenLineage methods** - if there is no Extractor explicitly specified for Operator class name, DefaultExtractor is used, that looks for OpenLineage methods in Operator.
-3. **Inlets and Outlets** - if there are no OpenLineage methods defined in the Operator, inlets and outlets are checked.
+3. **Hook Level Lineage** - when extractor or Openlineage methods return no inputs and no outputs, hook lineage is merged
+   with any other metadata produced (e.g. run facets, job facets). When neither extractor nor Openlineage methods
+   are present, hook lineage is used directly as the full lineage result. In both cases it takes precedence over inlets
+   and outlets.
+4. **Inlets and Outlets** - only consulted as a last resort when all of the above yield no datasets. This step
+   attempts to convert inlets and outlets into OpenLineage input/output datasets, which has limited support.
+   Note that inlets and outlets defined as Airflow Assets are always included in the ``airflow`` run facet
+   (under ``task.inlets`` / ``task.outlets``) regardless of whether this conversion succeeds —
+   so the ``airflow`` run facet is the most reliable place to look for inlet/outlet information.
 
 If all the above options are missing, no lineage data is extracted from the Operator. You will still receive OpenLineage events
 enriched with things like general Airflow facets, proper event time and type, but the inputs/outputs will be empty