Référence de tables système de traçabilité

Cette page inclut une référence pour les deux tables système de lignage. Ces tables système s’appuient sur la fonctionnalité de traçabilité des données du catalogue Unity, ce qui vous permet d’interroger par programmation les données de traçabilité pour alimenter la prise de décision et les rapports. Pour accéder aux tables, les schémas doivent être activés dans votre system catalogue. Pour plus d’informations, consultez Activer les tables système.

Table de traçabilité de la table

La table système de traçabilité de la table inclut un enregistrement pour chaque événement de lecture ou d’écriture sur une table ou un chemin d’accès Unity Catalog. Cela inclut, sans y être limité, les exécutions de travaux, les exécutions de notebooks et les tableaux de bord mis à jour à la suite d’un événement de lecture ou d'écriture.

Chemin d’accès à la table : cette table système se trouve à l’emplacement system.access.table_lineage.

Schéma de traçabilité de la table

La table système de traçabilité de la table utilise le schéma suivant.

Table de traçabilité de colonne

La table de traçabilité de colonne n’inclut pas d’événements dépourvus de source. Par exemple, si vous effectuez une insertion dans une colonne en utilisant des valeurs explicites, la capture n’a pas lieu. Si vous lisez une colonne, elle est capturée, que vous écriviez ou non la sortie.

Chemin d’accès à la table : cette table système se trouve à l’emplacement system.access.column_lineage.

Schéma de lignée des colonnes

La table système de lignage des colonnes utilise le schéma suivant :

Lecture de tables système de traçabilité

• Pour déterminer si l’événement était une lecture ou une écriture, vous pouvez afficher le type source et le type cible.
  • Lecture seule : le type source n’est pas nul, mais le type cible est nul.
  • Lecture seule : le type cible n’est pas nul, mais le type source est nul.
  • Lecture et écriture : le type source et le type cible ne sont pas nuls.

Informations de référence sur les métadonnées d’entité

Le entity_metadata struct a le schéma suivant :

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 enregistre les événements de traçabilité à partir des pipelines déclaratifs de Lakehouse Spark, des notebooks, des tâches, des requêtes Databricks SQL et des tableaux de bord. Les événements d’autres entités ne sont pas pris en charge.

Plusieurs valeurs peuvent être remplies en fonction du type d’événement. Par exemple, un travail exécutant une tâche de notebook remplirait à la fois job_info et notebook_id.

Si toutes les valeurs entity_metadata sont null, cela signifie qu’aucune entité Azure Databricks n’a été impliquée dans l’événement. Par exemple, cela peut être le résultat d’une requête JDBC ou d’un utilisateur qui clique sur l’onglet Exemples de données dans l’interface utilisateur Azure Databricks.

Exemple de table système de traçabilité

Comme exemple d’enregistrement de la traçabilité dans des tables système, voici un exemple de requête suivi des enregistrements de traçabilité créés par la requête :

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);

L’enregistrement dans system.access.table_lineage se présente comme suit :

L’enregistrement dans system.access.column_lineage se présente comme suit :

Analyse de la popularité des tables à l’aide de la table de traçabilité de table

La table système de traçabilité des tables peut être utilisée pour estimer la popularité des tables. Par exemple, l’extrait de code suivant récupère les 100 tables les plus fréquemment interrogées au cours des 7 derniers jours :

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;

Vous pouvez vous joindre à la table système de l’historique des requêtes pour obtenir des détails supplémentaires sur les requêtes exécutées sur les entrepôts SQL ou le calcul serverless, y compris ceux servis à partir du cache (notez que les tables système de traçabilité n’émettent pas d’entrées pour les résultats de requête mis en cache). Par exemple, l’extrait de code suivant récupère les tables dont les requêtes dépassent une heure d’exécution au cours des 7 derniers jours :

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;

Résolution des problèmes liés aux requêtes de table externe

Lorsque vous référencez une table externe à l’aide de son chemin d’accès de stockage cloud, l’enregistrement de traçabilité associé comporte uniquement le nom du chemin d’accès, pas le nom de la table. Par exemple, l’enregistrement de traçabilité de cette requête inclurait le nom du chemin d’accès et non le nom de la table :

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

Si vous essayez d’interroger des enregistrements de traçabilité pour une table externe référencée par chemin d’accès, vous devez filtrer la requête à l’aide source_path ou target_path au lieu de source_table_full_name ou target_table_full_name. Par exemple, la requête suivante extrait tous les enregistrements de traçabilité d’une table externe :

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";

Récupérer des enregistrements de traçabilité en fonction du nom de la table externe

Si vous ne souhaitez pas récupérer manuellement le chemin de stockage cloud pour rechercher la traçabilité, vous pouvez utiliser la fonction suivante pour obtenir des données de traçabilité à l’aide du nom de la table. Vous pouvez également remplacer system.access.table_lineage par system.access.column_lineage dans la fonction si vous souhaitez interroger la traçabilité des colonnes.

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)
  )

Utilisez ensuite la commande suivante pour appeler la fonction et afficher les enregistrements de traçabilité pour la table externe :

display(getLineageForTable("table_name"))