Referência das tabelas do sistema de linhagem

Esta página inclui uma referência para as duas tabelas do sistema de linhagem. Essas tabelas do sistema se baseiam no recurso de linhagem de dados do Unity Catalog, permitindo que você consulte programaticamente dados de linhagem para alimentar a tomada de decisões e relatórios. Para acessar as tabelas, os esquemas devem ser habilitados em seu system catálogo. Para mais informações, consulte Ativar tabelas do sistema.

Tabela de linhagem

A tabela de sistema de linhagem de tabelas inclui um registo para cada evento de leitura ou escrita numa tabela ou caminho do Unity Catalog. Isso inclui, mas não está limitado a, execuções de trabalho, execuções de notebooks e painéis atualizados com eventos de leitura ou escrita.

Caminho da tabela: Esta tabela do sistema está localizada em system.access.table_lineage.

Esquema de linhagem da tabela

A tabela do sistema de linhagem usa o esquema a seguir.

Tabela de linhagem de colunas

A tabela de linhagem de colunas não inclui eventos que não tenham uma fonte. Por exemplo, se você inserir em uma coluna usando valores explícitos, ela não será capturada. Se você ler uma coluna, ela será capturada independentemente de você escrever ou não a saída.

Caminho da tabela: Esta tabela do sistema está localizada em system.access.column_lineage.

Esquema de linhagem de coluna

A tabela do sistema de linhagem de colunas usa o seguinte esquema:

Leitura de tabelas do sistema de linhagem

• Para determinar se o evento foi uma leitura ou uma gravação, você pode exibir o tipo de origem e o tipo de destino.
  • Somente leitura: o tipo de origem não é nulo, mas o tipo de destino é nulo.
  • Somente gravação: O tipo de destino não é nulo, mas o tipo de origem é nulo.
  • Leitura e gravação: O tipo de origem e o tipo de destino não são nulos.

Referência de metadados de entidade

O entity_metadata struct tem o seguinte esquema:

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"

O Azure Databricks regista eventos de linhagem a partir de Lakeflow Spark Declarative Pipelines, notebooks, trabalhos, consultas SQL do Databricks e painéis. Não há suporte para eventos de outras entidades.

Vários valores podem ser preenchidos dependendo do tipo de evento. Por exemplo, um trabalho que executa uma tarefa de bloco de anotas preenchia ambos job_info e notebook_id.

Se todos os valores em entity_metadata forem null, isso significa que nenhuma entidade do Azure Databricks esteve envolvida no evento. Por exemplo, pode ser o resultado de uma consulta JDBC ou de um utilizador a clicar no separador Dados de Exemplo na interface do utilizador do Azure Databricks.

Exemplo de tabela do sistema de linhagem

Como um exemplo de como a linhagem é registrada em tabelas do sistema, aqui está um exemplo de consulta seguido pelos registros de linhagem que a consulta cria:

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

O registro em system.access.table_lineage seria parecido com:

O registro em system.access.column_lineage seria parecido com:

Analisando a popularidade da tabela usando a tabela de linhagem de tabela

A tabela do sistema de linhagem de tabelas pode ser usada para estimar a popularidade das tabelas. Por exemplo, o trecho a seguir recupera as 100 principais tabelas consultadas com mais frequência nos últimos 7 dias:

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;

Você pode ingressar com a tabela do sistema de histórico de consultas para obter detalhes adicionais sobre consultas executadas em armazéns SQL ou computação sem servidor, incluindo aquelas servidas a partir de cache (observe que as tabelas do sistema de linhagem não emitem entradas para resultados de consulta em cache). Por exemplo, o trecho a seguir recupera tabelas com consultas que excedem uma hora de tempo de execução nos últimos 7 dias:

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;

Solução de problemas de consultas de tabelas externas

Quando você faz referência a uma tabela externa usando seu caminho de armazenamento em nuvem, o registro de linhagem associado inclui apenas o nome do caminho e não o nome da tabela. Por exemplo, o registro de linhagem para esta consulta incluiria o nome do caminho e não o nome da tabela:

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

Se você estiver tentando consultar registros de linhagem para uma tabela externa referenciada por caminho, deverá filtrar a consulta usando source_path ou target_path em vez de source_table_full_name ou target_table_full_name. Por exemplo, a consulta a seguir extrai todos os registros de linhagem para uma tabela 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";

Recuperar registros de linhagem com base no nome da tabela externa

Se você não quiser recuperar manualmente o caminho de armazenamento em nuvem para encontrar linhagem, você pode usar a seguinte função para obter dados de linhagem usando o nome da tabela. Você também pode substituir system.access.table_lineage por system.access.column_lineage na função se quiser consultar a linhagem da coluna.

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

Em seguida, use o seguinte comando para chamar a função e exibir registros de linhagem para a tabela externa:

display(getLineageForTable("table_name"))