Capture e visualize linhagens de dados usando o Unity Catalog

Artigo
01/10/2025

Este artigo descreve como capturar e visualizar a linhagem de dados usando o Catalog Explorer, o sistema de linhagem de dados tablese a API REST.

Você pode usar o Unity Catalog para capturar a linhagem de dados de tempo de execução em consultas executadas no Azure Databricks. A linhagem é suportada para todos os idiomas e é capturada até o nível column. Os dados de linhagem incluem blocos de anotações, trabalhos e painéis relacionados à consulta. A linhagem pode ser visualizada no Catalog Explorer quase em tempo real e recuperada programaticamente usando o sistema de linhagem tables e a API REST do Databricks.

O Lineage é agregado em todos os espaços de trabalho conectados a um metastore do Unity Catalog. Isso significa que a linhagem capturada em um espaço de trabalho é visível em qualquer outro espaço de trabalho que shares esse metastore. Especificamente, tables e outros objetos de dados registrados no metastore são visíveis para os usuários que têm pelo menos BROWSE permissões nesses objetos, em todos os espaços de trabalho anexados ao metastore. No entanto, informações detalhadas sobre objetos no nível do espaço de trabalho, como blocos de anotações e painéis em outros espaços de trabalho, são mascaradas (consulte Limitações e Permissões de linhagem).

Os dados de linhagem são retidos por um ano.

A imagem a seguir é um gráfico de linhagem de exemplo. Exemplos e funcionalidades específicas de linhagem de dados são abordados mais adiante neste artigo.

Visão geral da linhagem

Para obter informações sobre como controlar a linhagem de um modelo de aprendizado de máquina, consulte Controlar a linhagem de dados de um modelo no Unity Catalog.

Requisitos

O seguinte é necessário para capturar linhagem de dados usando Unity Catalog:

O espaço de trabalho deve ter Unity Catalog ativado.
Tables deve estar registado em um metastore Unity Catalog.
As consultas têm de utilizar o Spark DataFrame (por exemplo, funções do Spark SQL que devolvem um DataFrame) ou interfaces SQL do Databricks. Para obter exemplos de consultas Databricks SQL e PySpark, consulte Exemplos.
Para ver a linhagem de um table ou de uma vista, os utilizadores devem ter pelo menos o privilégio BROWSE no catalog pai do table ou da vista. O pai catalog também deve estar acessível a partir da área de trabalho. Veja Limitcatalog acesso a espaços de trabalho específicos.
Para exibir informações de linhagem para blocos de anotações, trabalhos ou painéis, os usuários devem ter permissões nesses objetos, conforme definido pelas configurações de controle de acesso no espaço de trabalho. Consulte Permissões de linhagem.
Para exibir a linhagem de um pipeline habilitado para Unity Catalog, é necessário ter permissões de CAN_VIEW no pipeline.
O rastreamento de linhagem de streaming entre Delta tables requer o Databricks Runtime 11.3 LTS ou superior.
Column O rastreamento de linhagem para as cargas de trabalho do Delta Live Tables requer o Databricks Runtime 13.3 LTS ou superior.
Talvez seja necessário update as suas regras de firewall de saída para permitir a conectividade com o endpoint do Event Hubs no plano de controlo do Azure Databricks. Normalmente, isso se aplica se seu espaço de trabalho do Azure Databricks for implantado em sua própria VNet (também conhecida como injeção de VNet). Para get o ponto de extremidade de Hubs de Eventos para sua região de espaço de trabalho, consulte Metastore, armazenamento de Blob de artefato, armazenamento de tables do sistema, armazenamento de Blob de log e endereços IP de ponto de extremidade de Hubs de Eventos. Para obter informações sobre como configurar rotas definidas pelo utilizador (UDR) para o Azure Databricks, veja Definições de rota definidas pelo utilizador para o Azure Databricks.

Exemplos

Nota

Os exemplos a seguir usam o nome cataloglineage_data e o nome schemalineagedemo. Para usar um catalog e schemadiferentes, altere os nomes usados nos exemplos.
Para concluir este exemplo, deve ter privilégios de CREATE e USE SCHEMA num(a) schema. Um administrador de metastore, catalog proprietário, schema proprietário ou usuário com o privilégio MANAGE no schema pode grant esses privilégios. Por exemplo, para dar permissão a todos os usuários do grupo 'data_engineers' para criar tables no lineagedemoschema no lineage_datacatalog, um usuário com um dos privilégios ou funções acima pode executar as seguintes consultas:
```
CREATE SCHEMA lineage_data.lineagedemo;
GRANT USE SCHEMA, CREATE on SCHEMA lineage_data.lineagedemo to `data_engineers`;
```

Capture e explore a linhagem

Para capturar dados de linhagem:

Vá para a sua página inicial do Azure Databricks, clique em Novo na barra lateral e selectBloco de Anotações no menu.
Insira um nome para o bloco de anotações e selectSQL em Idioma Padrão.
No Cluster, o select é um cluster com acesso ao Unity Catalog.
Clique em Criar.

Na primeira célula do bloco de notas, introduza as seguintes consultas:

CREATE TABLE IF NOT EXISTS
  lineage_data.lineagedemo.menu (
    recipe_id INT,
    app string,
    main string,
    dessert string
  );

INSERT INTO lineage_data.lineagedemo.menu
    (recipe_id, app, main, dessert)
VALUES
    (1,"Ceviche", "Tacos", "Flan"),
    (2,"Tomato Soup", "Souffle", "Creme Brulee"),
    (3,"Chips","Grilled Cheese","Cheesecake");

CREATE TABLE
  lineage_data.lineagedemo.dinner
AS SELECT
  recipe_id, concat(app," + ", main," + ",dessert)
AS
  full_menu
FROM
  lineage_data.lineagedemo.menu

Para executar as consultas, clique na célula e pressione shift+enter ou clique em de Menu e selectExecutar Célula.

Para usar o Catalog Explorer para exibir a linhagem gerada por essas consultas:

Na caixa de Pesquisa na barra superior do espaço de trabalho do Azure Databricks, procure pelo lineage_data.lineagedemo.dinnertable e realize a ação select sobre ele.
Select a guia Lineage. O painel de linhagem aparece e exibe tables relacionados; para este exemplo, é o menutable.
Para exibir um gráfico interativo da linhagem de dados, clique em Ver gráfico de linhagem. Por padrão, um nível é exibido no gráfico. Clique no ícone num nó para revelar mais connections se eles estiverem disponíveis.
Clique em uma seta que conecta nós no gráfico de linhagem para abrir o painel de conexão Linhagem. O painel de conexão do Lineage mostra detalhes sobre a conexão, incluindo de origem e de destino, blocos de anotações e trabalhos.
Para mostrar o bloco de anotações associado ao , o bloco de anotações no painel de conexão do Lineage ou feche o gráfico de linhagem e clique em Notebooks. Para abrir o bloco de notas num novo separador, clique no nome do bloco de notas.
Para exibir a linhagem de nível de column, clique num column no gráfico para mostrar os links relacionados a columns. Por exemplo, clicar no column «full_menu» mostra o columns a montante de onde o column foi derivado.

Para visualizar a linhagem usando uma linguagem diferente, por exemplo, Python:

Abra o bloco de notas que criou anteriormente, crie uma nova célula e introduza o seguinte código Python:

%python
from pyspark.sql.functions import rand, round
df = spark.range(3).withColumn("price", round(10*rand(seed=42),2)).withColumnRenamed("id","recipe_id")

df.write.mode("overwrite").saveAsTable("lineage_data.lineagedemo.price")

dinner = spark.read.table("lineage_data.lineagedemo.dinner")
price = spark.read.table("lineage_data.lineagedemo.price")

dinner_price = dinner.join(price, on="recipe_id")
dinner_price.write.mode("overwrite").saveAsTable("lineage_data.lineagedemo.dinner_price")

Execute a célula clicando na célula e pressionando shift+enter ou clicando e selecionando Executar célula.
Na caixa de Pesquisa na barra superior do espaço de trabalho do Azure Databricks, procure pelo lineage_data.lineagedemo.pricetable e realize a ação select sobre ele.
Vá para a guia Linhagem e clique em Ver gráfico de linhagem. Clique nos ícones para explorar a linhagem de dados gerada pelas consultas.
Clique em uma seta que conecta nós no gráfico de linhagem para abrir o painel de conexão Linhagem. O painel de conexão do Lineage mostra detalhes sobre a conexão, incluindo de origem e de destino, blocos de anotações e trabalhos.

Capturar e visualizar linhagem de fluxo de trabalho

A linhagem é capturada sempre que um fluxo de trabalho lê ou grava no Unity Catalog. Para exibir a linhagem de um fluxo de trabalho do Azure Databricks:

Clique Novo na barra lateral e selectBloco de Notas no menu.
Insira um nome para o bloco de anotações e selectSQL em Idioma Padrão.
Clique em Criar.
Na primeira célula do bloco de notas, introduza a seguinte consulta:
```
SELECT * FROM lineage_data.lineagedemo.menu
```
Clique em Agendar na barra superior. Na caixa de diálogo de agendamento, selectManual, select um cluster com acesso ao Unity Catalog, e clique em Criar.
Clique em Executar agora.
Na caixa de Pesquisa na barra superior do espaço de trabalho do Azure Databricks, procure pelo lineage_data.lineagedemo.menutable e realize a ação select sobre ele.
Na guia Linhagem, clique em Fluxos de Trabalho e a guia Downstream. O nome do trabalho aparece sob Nome do Trabalho como um consumidor do .

Capture e visualize a linhagem do painel

Para criar um painel e exibir sua linhagem de dados:

Vá para a página inicial do Azure Databricks e abra o Catalog Explorer clicando em Catalog na barra lateral.
Clique no nome catalog, clique no lineagedemoe select o menutable. Também pode utilizar a caixa de Pesquisa na barra superior para procurar o menutable.
Clique em Abrir em um painel.
Select o columns que pretendes adicionar ao painel e clica em Criar.
Publique o painel.

Somente os painéis publicados são rastreados na linhagem de dados.
Na caixa de Pesquisa na barra superior, procure o lineage_data.lineagedemo.menutable e depois select-o.
Na guia Linhagem, clique em Painéis. O painel aparece sob o nome de Painel como um consumidor do menu table.

Permissões de linhagem

Os gráficos de linhagem partilham o mesmo modelo de permissão que o Unity Catalog. Tables e outros objetos de dados registrados no metastore Unity Catalog são visíveis apenas para usuários que tenham pelo menos BROWSE permissões nesses objetos. Se um usuário não tiver o privilégio de BROWSE ou SELECT em um table, ele não poderá explorar sua linhagem. Os gráficos de linhagem exibem objetos Unity Catalog em todos os espaços de trabalho anexados ao metastore, desde que o usuário tenha permissões de objeto adequadas.

Por exemplo, execute os seguintes comandos para userA:

GRANT USE SCHEMA on lineage_data.lineagedemo to `userA@company.com`;
GRANT SELECT on lineage_data.lineagedemo.menu to `userA@company.com`;

Quando userAviews o gráfico de linhagem para o lineage_data.lineagedemo.menutable, eles verão o menutable. Eles não poderão ver informações sobre os tablesassociados, como os lineage_data.lineagedemo.dinnertablea jusante. O dinnertable é apresentado como um nó masked na exibição para userA, e userA não pode expandir o gráfico para revelar tables a jusante de tables, pois eles não têm permissão para acessar.

Se você executar o seguinte comando para grant a permissão de BROWSE para userB, esse usuário poderá exibir o gráfico de linhagem para qualquer table no lineage_dataschema.:

GRANT BROWSE on lineage_data to `userB@company.com`;

Da mesma forma, os usuários de linhagem devem ter permissões específicas para exibir objetos de espaço de trabalho, como blocos de anotações, trabalhos e painéis. Além disso, eles só podem ver informações detalhadas sobre objetos de espaço de trabalho quando estiverem conectados ao espaço de trabalho no qual esses objetos foram criados. Informações detalhadas sobre objetos no nível do espaço de trabalho em outros espaços de trabalho são mascaradas no gráfico de linhagem.

Para obter mais informações sobre como gerenciar o acesso a objetos protegíveis no Unity Catalog, consulte Gerenciar privilégios no Unity Catalog. Para obter mais informações sobre como gerenciar o acesso a objetos de espaço de trabalho, como blocos de anotações, trabalhos e painéis, consulte Listas de controle de acesso.

Excluir dados de linhagem

Aviso

As instruções a seguir excluem todos os objetos armazenados no Unity Catalog. Utilize estas instruções apenas se necessário. Por exemplo, para atender aos requisitos de conformidade.

Para excluir dados de linhagem, você deve excluir o metastore que gerencia os objetos Unity Catalog. Para obter mais informações sobre como excluir o metastore, consulte Excluir um metastore. Os dados serão eliminados no prazo de 90 dias.

Consultar dados de linhagem usando tables do sistema

Você pode usar o sistema de linhagem tables para consultar programaticamente dados de linhagem. Para obter instruções detalhadas, consulte a atividade da conta Monitorizar com o sistema tables e o sistema Lineage, referência tables.

Se o seu espaço de trabalho estiver em uma região que não ofereça suporte ao sistema de linhagem tables, você pode, alternativamente, usar a API REST de linhagem de dados para recuperar dados de linhagem programaticamente.

Recuperar linhagem usando a API REST de linhagem de dados

A API de linhagem de dados permite recuperar a linhagem table e column. No entanto, se o espaço de trabalho estiver numa região que ofereça suporte ao sistema de linhagem tables, deverá usar consultas do sistema table em vez de usar a API REST. O System tables é uma opção melhor para a obtenção programática de dados de linhagem. A maioria das regiões suporta o sistema de linhagem tables.

Importante

Para aceder às APIs REST do Databricks, tem de se autenticar.

Recuperar linhagem table

Este exemplo recupera dados de linhagem para o dinnertable.

Pedir

curl --netrc -X GET \
-H 'Content-Type: application/json' \
https://<workspace-instance>/api/2.0/lineage-tracking/table-lineage \
-d '{"table_name": "lineage_data.lineagedemo.dinner", "include_entity_lineage": true}'

Substitua <workspace-instance>.

Este exemplo usa um arquivo .netrc .

Response

{
  "upstreams": [
    {
      "tableInfo": {
        "name": "menu",
        "catalog_name": "lineage_data",
        "schema_name": "lineagedemo",
        "table_type": "TABLE"
      },
      "notebookInfos": [
        {
          "workspace_id": 4169371664718798,
          "notebook_id": 1111169262439324
        }
      ]
    }
  ],
  "downstreams": [
    {
      "notebookInfos": [
        {
          "workspace_id": 4169371664718798,
          "notebook_id": 1111169262439324
        }
      ]
    },
    {
      "tableInfo": {
        "name": "dinner_price",
        "catalog_name": "lineage_data",
        "schema_name": "lineagedemo",
        "table_type": "TABLE"
      },
      "notebookInfos": [
        {
          "workspace_id": 4169371664718798,
          "notebook_id": 1111169262439324
        }
      ]
    }
  ]
}

Recuperar linhagem column

Este exemplo recupera dados column para o dinnertable.

Pedir

curl --netrc -X GET \
-H 'Content-Type: application/json' \
https://<workspace-instance>/api/2.0/lineage-tracking/column-lineage \
-d '{"table_name": "lineage_data.lineagedemo.dinner", "column_name": "dessert"}'

Substitua <workspace-instance>.

Este exemplo usa um arquivo .netrc .

Response

{
  "upstream_cols": [
    {
      "name": "dessert",
      "catalog_name": "lineage_data",
      "schema_name": "lineagedemo",
      "table_name": "menu",
      "table_type": "TABLE"
    },
    {
      "name": "main",
      "catalog_name": "lineage_data",
      "schema_name": "lineagedemo",
      "table_name": "menu",
      "table_type": "TABLE"
    },
    {
      "name": "app",
      "catalog_name": "lineage_data",
      "schema_name": "lineagedemo",
      "table_name": "menu",
      "table_type": "TABLE"
    }
  ],
  "downstream_cols": [
    {
      "name": "full_menu",
      "catalog_name": "lineage_data",
      "schema_name": "lineagedemo",
      "table_name": "dinner_price",
      "table_type": "TABLE"
    }
  ]
}

Limitações

Embora a linhagem seja agregada para todos os espaços de trabalho anexados ao mesmo metastore do Unity Catalog, os detalhes dos objetos do espaço de trabalho, como blocos de anotações e painéis, são visíveis apenas no espaço de trabalho no qual foram criados.
Como a linhagem é calculada em um windowmóvel de um ano, a linhagem coletada há mais de um ano não é exibida. Por exemplo, se um trabalho ou consulta ler dados do table A e gravar no table B, o link entre o table A e o table B será exibido por apenas um ano. Você pode filtrar dados de linhagem por período de tempo no período de um ano window.
Os trabalhos que usam a solicitação da API runs submit de Trabalhos não estão disponíveis ao exibir a linhagem. A linhagem dos níveis Table e column ainda é capturada ao usar o pedido runs submit, mas o link para a execução não é capturado.
Unity Catalog captura a linhagem para o nível column tanto quanto possível. No entanto, existem alguns casos em que a linhagem de nível wherecolumnnão pode ser capturada.
Column linhagem é suportada somente quando a origem e o destino são referenciados por table nome (Exemplo: select * from <catalog>.<schema>.<table>). Column linhagem não pode ser capturada se a origem ou o destino for endereçado por caminho (Exemplo: select * from delta."s3://<bucket>/<path>").
Se uma table ou exibição for renomeada, a linhagem não será capturada para a table ou exibição renomeada.
Se um schema ou catalog for renomeado, a linhagem não será capturada para tables e views sob o catalog ou schemarenomeado.
Se usar o ponto de verificação do conjunto de dados Spark SQL, a linhagem não será capturada.
O Unity Catalog captura linhagem de oleodutos Delta Live Tables na maioria dos casos. No entanto, em alguns casos, a cobertura completa de linhagem não pode ser garantida, como quando os dutos usam o APLICAR ALTERAÇÕES API ou tablesTEMPORÁRIA.
Lineage não captura funções de pilha.
Os temp globais views não são capturados na linhagem de dados.
Tables sob system.information_schema não são registados na linhagem.
A linhagem completa de nível columnnão é capturada por padrão para operações MERGE.

Você pode ativar a captura de linhagem para MERGE operações definindo a propriedade spark.databricks.dataLineage.mergeIntoV2Enabled Spark como true. Habilitar esse sinalizador pode diminuir o desempenho da consulta, especialmente em cargas de trabalho que envolvem tablesmuito ampla.

Partilhar via

Capture e visualize linhagens de dados usando o Unity Catalog

Requisitos

Exemplos

Capture e explore a linhagem

Capturar e visualizar linhagem de fluxo de trabalho

Capture e visualize a linhagem do painel

Permissões de linhagem

Excluir dados de linhagem

Consultar dados de linhagem usando tables do sistema

Recuperar linhagem usando a API REST de linhagem de dados

Recuperar linhagem table

Pedir

Response

Recuperar linhagem column

Pedir

Response

Limitações

Comentários

Recursos adicionais