Referencia de tablas del sistema de linaje

Esta página incluye una referencia para las dos tablas del sistema de linaje. Estas tablas del sistema se basan en la característica de linaje de datos de Unity Catalog, lo que le permite consultar mediante programación los datos de linaje para impulsar la toma de decisiones e informes. Para acceder a las tablas, los esquemas deben estar habilitados dentro del catálogo system. Para obtener más información, consulte Habilitación de tablas del sistema.

Note

Ambas tablas de linaje representan un subconjunto de todos los eventos de lectura y escritura, ya que no siempre es posible capturar linaje. Los registros solo se emiten cuando se puede deducir el linaje. Las limitaciones de linaje de datos descritas en Limitaciones de linaje también se aplican a las tablas del sistema de linaje.

Tabla de linaje de tabla

La tabla del sistema de linaje de tabla incluye un registro para cada evento de lectura o escritura en una tabla o ruta de acceso de Unity Catalog. Esto incluye, entre otras cosas, ejecuciones de trabajos, ejecuciones de cuadernos y paneles actualizados con el evento de lectura o escritura.

Ruta de acceso de tabla: esta tabla del sistema se encuentra en system.access.table_lineage.

Esquema de linaje de tabla

La tabla del sistema de linaje utiliza el esquema siguiente.

Nombre de la columna	Tipo de dato	Description	Example
account_id	string	Identificador de la cuenta de Azure Databricks.	7af234db-66d7-4db3-bbf0-956098224879
metastore_id	string	Id. del metastore de Unity Catalog.	5a31ba44-bbf4-4174-bf33-e1fa078e6765
workspace_id	string	Id. del área de trabajo	123456789012345
entity_type	string	Tipo de entidad asociada al registro de linaje, si existe. El valor es NOTEBOOK, JOB, PIPELINE, , DASHBOARD_V3DBSQL_DASHBOARD(panel heredado), DBSQL_QUERYo NULL. Nota: consulte la entity_metadata columna para obtener información sobre todas las entidades implicadas en el registro de linaje.	JOB
entity_id	string	Identificador de la entidad asociada al registro de linaje o NULL. Nota: consulte la entity_metadata columna para obtener información sobre todas las entidades implicadas en el registro de linaje.	417306252667357
entity_run_id	string	Identificador de ejecución único de la entidad asociada al registro de linaje o NULL. Nota: consulte la entity_metadata columna para obtener información sobre todas las entidades implicadas en el registro de linaje.	688612062233399
source_table_full_name	string	Nombre de tres partes para identificar la tabla de origen.	catalog.schema.table
source_table_catalog	string	Catálogo de la tabla de origen.	catalog
source_table_schema	string	Esquema de la tabla de origen.	schema
source_table_name	string	El nombre de la tabla de origen.	table
source_path	string	Ubicación en el almacenamiento en la nube de la tabla de origen o la ruta de acceso si se lee directamente desde el almacenamiento en la nube.	abfss://my-container-name@storage-account-name.dfs.core.windows.net/table1
source_type	string	Tipo del origen. El valor es TABLE, PATH, VIEW, MATERIALIZED_VIEW, METRIC_VIEWo STREAMING_TABLE.	TABLE
target_table_full_name	string	Nombre de tres partes para identificar la tabla de destino.	catalog.schema.table
target_table_catalog	string	Catálogo de la tabla de destino.	catalog
target_table_schema	string	Esquema de la tabla de destino.	schema
target_table_name	string	Nombre de la tabla de destino.	table
target_path	string	Ubicación en el almacenamiento en la nube de la tabla de destino.	abfss://my-container-name@storage-account-name.dfs.core.windows.net/table1
target_type	string	Tipo del destino. El valor es TABLE, PATH, VIEW, MATERIALIZED_VIEW, METRIC_VIEWo STREAMING_TABLE.	TABLE
created_by	string	El usuario que generó este linaje. Puede ser un nombre de usuario de Azure Databricks, un id. de entidad de servicio de Azure Databricks, "Usuario del sistema" o NULL si no se puede capturar la información del usuario.	crampton.rods@email.com
event_time	timestamp	Marca de tiempo cuando se generó el linaje. La información de zona horaria se registra al final del valor con +00:00, que representa la hora UTC.	2025-04-20T19:47:21.194+00:00
event_date	date	Fecha en la que se generó el linaje. Se trata de una columna con particiones.	2025-04-20
record_id	string	Identificador único del registro de linaje. Este valor se genera automáticamente y no se puede combinar con ninguna tabla.	3c5c8eed-87bb-3aa6-8a86-80d00d48299e
event_id	string	Identificador único de un único evento de linaje. Varias filas pueden compartir lo mismo event_id si se generaron mediante el mismo evento. Este valor se genera automáticamente y no se puede combinar con ninguna tabla.	ca123ff3-f3f8-332b-a832-0154a6327353
statement_id	string	Identificador único de una instrucción de consulta que generó el evento de linaje. Se trata de una clave externa que se va a combinar con la tabla del sistema del historial de consultas. Este valor solo se establece cuando la consulta se ejecuta desde una instancia de SQL Warehouse.	1234526f-a6ac-475c-8601-e8637f8ee039
entity_metadata	struct	Metadatos sobre la entidad responsable del evento de linaje.	Consulte Metadatos de entidad.

Tabla de linaje de columnas

La tabla de linaje de columnas no incluye eventos que no tienen un origen. Por ejemplo, si inserta en una columna usando valores explícitos, no se capturará. Si lee una columna, se captura si escribe o no la salida.

Ruta de acceso de tabla: esta tabla del sistema se encuentra en system.access.column_lineage.

Esquema de linaje de columna

La tabla del sistema de linaje de columnas usa el esquema siguiente:

Nombre de la columna	Tipo de dato	Description	Example
account_id	string	Identificador de la cuenta de Azure Databricks.	7af234db-66d7-4db3-bbf0-956098224879
metastore_id	string	Id. del metastore de Unity Catalog.	5a31ba44-bbf4-4174-bf33-e1fa078e6765
workspace_id	string	Id. del área de trabajo	123456789012345
entity_type	string	Tipo de entidad asociada al registro de linaje, si existe. El valor es NOTEBOOK, JOB, PIPELINE, , DASHBOARD_V3DBSQL_DASHBOARD(panel heredado), DBSQL_QUERYo NULL. Nota: consulte la entity_metadata columna para obtener información sobre todas las entidades implicadas en el registro de linaje.	JOB
entity_id	string	Identificador de la entidad asociada al registro de linaje o NULL. Nota: consulte la entity_metadata columna para obtener información sobre todas las entidades implicadas en el registro de linaje.	417306252667357
entity_run_id	string	Identificador de ejecución único de la entidad asociada al registro de linaje o NULL. Nota: consulte la entity_metadata columna para obtener información sobre todas las entidades implicadas en el registro de linaje.	688612062233399
source_table_full_name	string	Nombre de tres partes para identificar la tabla de origen.	catalog.schema.table
source_table_catalog	string	Catálogo de la tabla de origen.	catalog
source_table_schema	string	Esquema de la tabla de origen.	schema
source_table_name	string	El nombre de la tabla de origen.	table
source_path	string	Ubicación en el almacenamiento en la nube de la tabla de origen o la ruta de acceso si se lee directamente desde el almacenamiento en la nube.	abfss://my-container-name@storage-account-name.dfs.core.windows.net/table1
source_type	string	Tipo del origen. El valor es TABLE, PATH, VIEW, MATERIALIZED_VIEW, METRIC_VIEWo STREAMING_TABLE.	TABLE
source_column_name	string	El nombre de la columna de origen.	date
target_table_full_name	string	Nombre de tres partes para identificar la tabla de destino.	catalog.schema.table
target_table_catalog	string	Catálogo de la tabla de destino.	catalog
target_table_schema	string	Esquema de la tabla de destino.	schema
target_table_name	string	Nombre de la tabla de destino.	table
target_path	string	Ubicación en el almacenamiento en la nube de la tabla de destino.	abfss://my-container-name@storage-account-name.dfs.core.windows.net/table1
target_type	string	Tipo del destino. El valor es TABLE, PATH, VIEW, MATERIALIZED_VIEW, METRIC_VIEWo STREAMING_TABLE.	TABLE
target_column_name	string	El nombre de la columna de destino.	date
created_by	string	El usuario que generó este linaje. Puede ser un nombre de usuario de Azure Databricks, un id. de entidad de servicio de Azure Databricks, "Usuario del sistema" o NULL si no se puede capturar la información del usuario.	crampton.rods@email.com
event_time	timestamp	Marca de tiempo cuando se generó el linaje. La información de zona horaria se registra al final del valor con +00:00, que representa la hora UTC.	2025-04-20T19:47:21.194+00:00
event_date	date	Fecha en la que se generó el linaje. Se trata de una columna con particiones.	2025-04-20
record_id	string	Identificador único del registro de linaje. Este valor se genera automáticamente y no se puede combinar con ninguna tabla.	3c5c8eed-87bb-3aa6-8a86-80d00d48299e
event_id	string	Identificador único de un único evento de linaje. Varias filas pueden compartir lo mismo event_id si se generaron mediante el mismo evento. Este valor se genera automáticamente y no se puede combinar con ninguna tabla.	ca123ff3-f3f8-332b-a832-0154a6327353
statement_id	string	Identificador único de una instrucción de consulta que generó el evento de linaje. Se trata de una clave externa que se va a combinar con la tabla del sistema del historial de consultas. Este valor solo se establece cuando la consulta se ejecuta desde una instancia de SQL Warehouse.	1234526f-a6ac-475c-8601-e8637f8ee039
entity_metadata	struct	Metadatos sobre la entidad responsable del evento de linaje.	Consulte Metadatos de entidad.

Leer las tablas del sistema de linaje

• Para determinar si el evento era de lectura o escritura, puede ver el tipo de origen y el tipo de destino.
  • Solo lectura: el tipo de origen no es null, pero el tipo de destino es null.
  • Solo escritura: el tipo de destino no es null, pero el tipo de origen es null.
  • Lectura y escritura: el tipo de origen y el tipo de destino no son null.

Referencia de metadatos de entidad

La entity_metadata estructura tiene el esquema siguiente:

job_info:
  job_id: "string"
  job_run_id: "string"
dashboard_id: "string"
legacy_dashboard_id: "string"
notebook_id: "string"
sql_query_id: "string"
dlt_pipeline_info:
  dlt_pipeline_id: "string"
  dlt_update_id: "string"

Azure Databricks registra eventos de linaje de canalizaciones declarativas de Spark de Lakeflow, cuadernos, trabajos, consultas SQL de Databricks y paneles. No se admiten eventos de otras entidades.

Se pueden rellenar varios valores en función del tipo de evento. Por ejemplo, un trabajo que ejecuta una tarea de cuaderno rellenaría tanto job_info como notebook_id.

Si todos los valores de entity_metadata son null, significa que ninguna entidad de Azure Databricks estaba implicada en el evento . Por ejemplo, podría ser el resultado de una consulta JDBC o de un usuario haciendo clic en la pestaña Datos de ejemplo de la interfaz de usuario de Azure Databricks.

Ejemplo de tabla del sistema de linaje

Como ejemplo de cómo se registra el linaje en las tablas del sistema, a continuación se muestra una consulta de ejemplo seguida de los registros de linaje que crea la consulta:

CREATE OR REPLACE TABLE car_features
AS SELECT *,  in1+in2 as premium_feature_set
FROM car_features_exterior
JOIN car_features_interior
USING(id, model);

El registro en system.access.table_lineage tendría el siguiente aspecto:

entity_type	entity_id	source_table_name	target_table_name	created_by	event_time
NOTEBOOK	27080565267	car_features_exterior	car_features	crampton@email.com	2023-01-25T16:19:58.908+0000
NOTEBOOK	27080565267	car_features_interior	car_features	crampton@email.com	2023-01-25T16:19:58.908+0000

El registro en system.access.column_lineage tendría el siguiente aspecto:

entity_type	entity_id	source_table_name	target_table_name	source_column_name	target_column_name	event_time
NOTEBOOK	27080565267	car_features_interior	car_features	in1	premium_feature_set	2023-01-25T16:19:58.908+0000
NOTEBOOK	27080565267	car_features_interior	car_features	in2	premium_feature_set	2023-01-25T16:19:58.908+0000

Note

No todas las columnas de linaje se muestran en el ejemplo anterior. Para obtener el esquema completo, consulte el esquema de linaje anterior.

Análisis de la popularidad de las tablas mediante la tabla de linaje de tablas

La tabla del sistema de linaje de tablas se puede usar para calcular la popularidad de las tablas. Por ejemplo, el fragmento de código siguiente recupera las 100 tablas consultadas con más frecuencia en los últimos 7 días:

SELECT
  source_table_full_name,
  COUNT(distinct event_id) AS num_of_queries
FROM
  system.access.table_lineage t
WHERE
  t.event_date > CURRENT_DATE() - INTERVAL 7 DAYS
  AND t.source_table_full_name IS NOT NULL
GROUP BY source_table_full_name
ORDER BY num_of_queries DESC
LIMIT 100;

Puede unirse a la tabla del sistema del historial de consultas para obtener detalles adicionales sobre las consultas que se ejecutan en almacenes de SQL o en proceso sin servidor, incluidas las que se sirven desde la memoria caché (tenga en cuenta que las tablas del sistema de linaje no emiten entradas para los resultados de las consultas almacenadas en caché). Por ejemplo, el fragmento de código siguiente recupera tablas con consultas que superan una hora de tiempo de ejecución en los últimos 7 días:

SELECT
  t.source_table_full_name,
  COUNT(distinct event_id) AS num_of_queries_over_hour
FROM
  system.query.history h
INNER JOIN system.access.table_lineage t
  ON t.statement_id = h.cache_origin_statement_id
WHERE
  h.total_duration_ms > 3600000
  AND t.event_date > CURRENT_DATE() - INTERVAL 7 DAYS
  AND t.source_table_full_name IS NOT NULL
GROUP BY t.source_table_full_name
ORDER BY num_of_queries_over_hour DESC;

Resolución de problemas de consultas a tablas externas

Cuando se hace referencia a una tabla externa utilizando su ruta de almacenamiento en la nube, el registro de linaje asociado solo incluye el nombre de la ruta y no el nombre de la tabla. Por ejemplo, el registro de linaje de esta consulta incluiría el nombre de la ruta y no el nombre de la tabla:

SELECT * FROM delta.`abfss://my-container-name@storage-account-name.dfs.core.windows.net/table1`;

Si está intentando consultar los registros de linaje de una tabla externa a la que hace referencia la ruta de acceso, debe filtrar la consulta mediante source_path o target_path en lugar de source_table_full_name o target_table_full_name. Por ejemplo, la siguiente consulta extrae todos los registros de linaje de una tabla externa:

SELECT *
FROM system.access.table_lineage
WHERE
  source_path = "abfss://my-container-name@storage-account-name.dfs.core.windows.net/table1" OR
  target_path = "abfss://my-container-name@storage-account-name.dfs.core.windows.net/table1";

Recuperación de registros de linaje basados en el nombre de la tabla externa

Si no desea recuperar manualmente la ruta de acceso de almacenamiento en la nube para buscar linaje, puede usar la siguiente función para obtener datos de linaje mediante el nombre de la tabla. También puede sustituir system.access.table_lineage con system.access.column_lineage en la función si desea consultar el linaje de las columnas.

def getLineageForTable(table_name):
  table_path = spark.sql(f"describe detail {table_name}").select("location").head()[0]

  df = spark.read.table("system.access.table_lineage")
  return df.where(
    (df.source_table_full_name == table_name)
    | (df.target_table_full_name == table_name)
    | (df.source_path == table_path)
    | (df.target_path == table_path)
  )

A continuación, utilice el siguiente comando para llamar a la función y mostrar los registros de linaje de la tabla externa:

display(getLineageForTable("table_name"))