Capture e visualize linhagens de dados usando o Catálogo do Unity

Artigo
12/13/2024

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

Você pode usar o Catálogo do Unity para capturar a linhagem de dados de runtime em consultas executadas no Azure Databricks. A linhagem tem suporte para todos os idiomas e é capturada até o nível da coluna. Os dados da linhagem incluem notebooks, trabalhos e painéis de controle relacionados à consulta. A linhagem de dados pode ser visualizada no Catalog Explorer em quase tempo real e recuperada programaticamente usando as tabelas do sistema de linhagem de dados e a API REST do Databricks.

A linhagem é agregada em todos os workspaces anexados a um metastore do Catálogo do Unity. Isso significa que a linhagem capturada em um workspace é visível em qualquer outro workspace que compartilhe esse metastore. Os usuários devem ter as permissões corretas para exibir os dados de linhagem. Os dados da linhagem são mantidos por um ano.

A imagem a seguir é um grafo de linhagem de exemplo. A funcionalidade e os exemplos de linhagem de dados específicos são abordados posteriormente neste artigo.

Visão geral da linhagem

Para obter informações sobre como acompanhar a linhagem de um modelo de machine learning, consulte Acompanhar a linhagem de dados de um modelo no Catálogo do Unity.

Requisitos

As seguintes condições são necessárias para capturar a linhagem de dados usando o Catálogo do Unity:

O espaço de trabalho deve ter o Catálogo do Unity habilitado.
As tabelas precisam ser registradas em um metastore do Catálogo do Unity.
As consultas devem usar o DataFrame do Spark (por exemplo, funções SQL do Spark que retornam um DataFrame) ou interfaces do Databricks SQL. Para obter exemplos de consultas do Databricks SQL e do PySpark, veja Exemplos.
Para visualizar a linhagem de uma tabela ou visualização, os usuários devem ter pelo menos o privilégio BROWSE no catálogo pai da tabela ou visualização. O catálogo pai também deve ser acessível a partir do espaço de trabalho. Consulte Limitar acesso do catálogo a espaços de trabalho específicos.
Para exibir informações de linhagem para notebooks, trabalhos ou painéis, os usuários devem ter permissões nesses objetos, conforme definido pelas configurações de controle de acesso no workspace. Veja Permissões de linhagem.
Para exibir a linhagem de um pipeline habilitado para o Catálogo do Unity, você deve ter permissões CAN_VIEW no pipeline.
O acompanhamento de linhagem do streaming entre tabelas Delta requer Databricks Runtime 11.3 LTS ou superior.
O acompanhamento de linhagem de coluna para cargas de trabalho delta live tables requer Databricks Runtime 13.3 LTS ou superior.
Talvez seja necessário atualizar suas regras de firewall de saída para permitir a conectividade com o ponto de extremidade dos Hubs de Eventos no painel de controle do Azure Databricks. Normalmente, isso é aplicável se o workspace do Azure Databricks está implantado na sua VNet (o que também é conhecido como injeção de VNet). Para obter o ponto de extremidade dos Hub de Eventos para a sua região de workspace, confira Metastore, armazenamento de blobs de artefatos, armazenamento de tabelas do sistema, armazenamento de blobs de log e endereços IP de ponto de extremidade dos Hubs de Eventos. Para obter informações sobre como configurar UDR (rotas definidas pelo usuário) para o Azure Databricks, consulte configurações de rota definidas pelo usuário para o Azure Databricks.

Exemplos

Observação

Os exemplos a seguir usam o nome do catálogo lineage_data e o nome do esquema lineagedemo. Para usar um catálogo e um esquema diferentes, altere os nomes usados nos exemplos.
Para concluir este exemplo, você deve ter os privilégios CREATE e USE SCHEMA em um esquema. Um administrador de metastore, proprietário do catálogo, proprietário do esquema ou usuário com o privilégio MANAGE no esquema pode conceder esses privilégios. Por exemplo, para dar a todos os usuários do grupo ‘data_engineers’ permissão para criar tabelas no esquema lineagedemo do catálogo lineage_data, um usuário com um dos privilégios ou uma das 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`;
```

Capturar e explorar linhagem

Para capturar dados de linhagem:

Vá para a página inicial do Azure Databricks, clique em Novo na barra lateral e selecione Notebook no menu.
Insira um nome para o notebook e selecione SQL em Idioma Padrão.
Em Cluster, selecione um cluster com acesso ao Catálogo do Unity.
Clique em Criar.

Na primeira célula do notebook, insira 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 e selecione Executar célula.

Para usar o Gerenciador de Catálogos para exibir a linhagem gerada por essas consultas:

Na caixa Pesquisar na barra superior do workspace do Azure Databricks, pesquise a tabela lineage_data.lineagedemo.dinner e selecione-a.
Selecione a guia Linhagem. O painel de linhagem aparece e exibe tabelas relacionadas (neste exemplo, é a tabela menu).
Para exibir um grafo interativo da linhagem de dados, clique em Ver grafo de linhagem. Por padrão, um nível é exibido no grafo. Clique no ícone em um nó para revelar mais conexões se elas estiverem disponíveis.
Clique em uma seta que conecta nós no grafo de linhagem para abrir o painel Conexão de linhagem. O painel Conexão de linhagem mostra detalhes sobre a conexão, incluindo tabelas de origem e de destino, notebooks e trabalhos.
Para mostrar o notebook associado à tabela dinner, selecione-o no painel Conexão de linhagem ou feche o grafo de linhagem e clique em Notebooks. Para abrir o bloco de anotações em uma nova guia, clique no nome do bloco de anotações.
Para exibir a linhagem no nível da coluna, clique em uma coluna no grafo para mostrar links para colunas relacionadas. Por exemplo, clicar na coluna ''full_menu'' mostra as colunas upstream das quais a coluna foi derivada:

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

Abra o notebook que você criou anteriormente, crie uma célula e insira 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 nela e pressionando shift+enter ou clicando em e selecionando Executar célula.
Na caixa Pesquisar na barra superior do workspace do Azure Databricks, pesquise a tabela lineage_data.lineagedemo.price e selecione-a.
Selecione a guia Linhagem e clique em Ver Grafo de Linhagem. Clique nos ícones para explorar a linhagem de dados gerada pelas consultas.
Clique em uma seta que conecta nós no grafo de linhagem para abrir o painel Conexão de linhagem. O painel Conexão de linhagem mostra detalhes sobre a conexão, incluindo tabelas de origem e de destino, notebooks e trabalhos.

Capturar e exibir linhagem de fluxo de trabalho

A linhagem também é capturada para qualquer fluxo de trabalho que lê ou grava no Catálogo do Unity. Para exibir a linhagem de um fluxo de trabalho do Azure Databricks:

Clique em Novo na barra lateral e selecione Notebook no menu.
Insira um nome para o notebook e selecione SQL em Idioma Padrão.
Clique em Criar.
Na primeira célula do notebook, insira a seguinte consulta:
```
SELECT * FROM lineage_data.lineagedemo.menu
```
Clique em Agendar na barra superior. No diálogo de agendamento, selecione Manual, selecione um cluster com acesso ao Catálogo do Unity e clique em Criar.
Clique em Executar agora.
Na caixa Pesquisar na barra superior do workspace do Azure Databricks, pesquise a tabela lineage_data.lineagedemo.menu e selecione-a.
Na guia Linhagem, clique em fluxos de trabalhoe selecione a guia Downstream. O nome do trabalho aparece em Nome do Trabalho como um consumidor da tabela menu.

Capturar e exibir a linhagem do painel

Para criar um painel e exibir sua linhagem de dados:

Vá para a página de aterrissagem do Azure Databricks e abra o Explorador de Catálogos clicando em Catálogo na barra lateral.
Clique no nome do catálogo, clique em lineagedemo e selecione a tabela menu. Você também pode usar a caixa Pesquisar na barra superior para pesquisar a tabela menu.
Clique em Abrir em um painel.
Selecione colunas para adicionar ao painel e clique em Criar.
Publique o painel.

Somente os painéis publicados são acompanhados na linhagem de dados.
Na caixa Pesquisar na barra superior, pesquise a tabela lineage_data.lineagedemo.menu e selecione-a.
Na guia Linhagem, clique Dashboards. O nome do painel aparece em Nome do Painel como um consumidor da tabela de menus.

Permissões de linhagem

Os grafos de linhagem compartilham o mesmo modelo de permissão que o Catálogo do Unity. Se um usuário não tiver o privilégio BROWSE ou SELECT em uma tabela, ele não poderá explorar a linhagem. Além disso, os usuários só podem ver notebooks, trabalhos e painéis que têm permissão para exibir. Por exemplo, se você executar os seguintes comandos para um usuário userA não administrador:

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

Quando userA exibir o grafo de linhagem da tabela lineage_data.lineagedemo.menu, eles verão a tabela menu. Eles não poderão ver informações sobre tabelas associadas, como a tabela downstream lineage_data.lineagedemo.dinner. A tabela dinner é exibida como um nó masked na exibição para userA e userA não pode expandir o grafo para revelar tabelas de downstream de tabelas que não têm permissão para acessar.

Se você executar o seguinte comando para conceder a permissão BROWSE a um usuário userBnão administrador:

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

userB agora pode exibir o grafo de linhagem para qualquer tabela no esquema lineage_data.

Para mais informações sobre como gerenciar o acesso a objetos protegíveis no Unity Catalog, veja como Gerenciar privilégios no Unity Catalog. Para obter mais informações sobre como gerenciar o acesso a objetos de workspace, como notebooks, trabalhos e painéis, confira Lista de controle de acesso.

Excluir dados de linhagem

Aviso

As instruções a seguir excluem todos os objetos armazenados no Catálogo do Unity. Use estas instruções somente se necessário. Por exemplo, para atender aos requisitos de conformidade.

Para excluir dados de linhagem, exclua o metastore que gerencia os objetos do Catálogo do Unity. Para obter mais informações sobre como excluir o metastore, veja Excluir um metastore. Os dados serão excluídos em 90 dias.

Consultar os dados de linhagem usando as tabelas de sistema

Você pode usar as tabelas do sistema de linhagem para consultar dados de linhagem programaticamente. Para obter instruções detalhadas, consulte Monitorar a atividade da conta com tabelas do sistema e Referência de tabelas do sistema de linhagem.

Se seu espaço de trabalho estiver em uma região que não dá suporte para tabelas do sistema de linhagem, você pode alternativamente usar a API REST de Linhagem de Dados para recuperar os dados de linhagem programaticamente.

Recuperar a linhagem usando a API REST de Linhagem de Dados

A API de linhagem de dados permite que você recupere a linhagem de tabela e coluna. No entanto, se seu espaço de trabalho estiver em uma região com suporte para tabelas do sistema de linhagem, você deverá usar as consultas das tabelas do sistema em vez da API REST. As tabelas do sistema são uma opção melhor para a recuperação programática de dados de linhagem. A maioria das regiões dá suporte para tabelas do sistema de linhagem.

Importante

Para acessar as APIs REST do Databricks, é necessário autenticar-se.

Recuperar linhagem de tabela

Este exemplo recupera dados de linhagem para a tabela dinner.

Solicitação

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}'

Substituir <workspace-instance>.

Este exemplo usa um arquivo .netrc.

Resposta

{
  "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 de coluna

Este exemplo recupera dados de coluna para a tabela dinner.

Solicitação

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"}'

Substituir <workspace-instance>.

Este exemplo usa um arquivo .netrc.

Resposta

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

Como a linhagem é computada em uma janela sem interrupção de um ano, a linhagem coletada há mais de um ano não é exibida. Por exemplo, se um trabalho ou consulta fizer a leitura dos dados da tabela A e gravar na tabela B, o link entre a tabela A e a tabela B será exibido por apenas um ano. Você pode filtrar dados de linhagem por período dentro da janela de um ano.
Os trabalhos que usam a solicitação runs submit de API de Trabalhos não estarão disponíveis ao exibir a linhagem. A linhagem de nível de tabela e coluna ainda será capturada ao usar a solicitação runs submit, mas o link para a execução não será capturado.
O Catálogo do Unity captura a linhagem para o nível de coluna ao máximo. No entanto, há alguns casos em que a linhagem no nível da coluna não pode ser capturada.
Há suporte para a linhagem da coluna somente quando a origem e o destino são referenciados pelo nome da tabela (Exemplo: select * from <catalog>.<schema>.<table>). A linhagem de coluna não poderá ser capturada se a origem ou o destino for endereçado por caminho (exemplo: select * from delta."s3://<bucket>/<path>").
Se uma tabela ou exibição for renomeada, a linhagem não será capturada para a tabela ou exibição renomeada.
Se um esquema ou catálogo for renomeado, a linhagem não será capturada para tabelas e exibições no catálogo ou esquema renomeado.
Se você usar o ponto de verificação do conjunto de dados do Spark SQL, a linhagem não será capturada.
O Catálogo do Unity captura a linhagem de pipelines das Tabelas Dinâmicas Delta na maioria dos casos. No entanto, em alguns casos não é possível garantir a cobertura completa da linhagem, como quando os pipelines usam a API APLICAR ALTERAÇÕES ou tabelas TEMPORÁRIAS.
A linhagem não captura funções Stack.
As exibições temporárias globais não são capturadas na linhagem.
As tabelas sob system.information_schema não são capturadas na linhagem.
A linhagem completa em nível de coluna não é capturada por padrão para MERGE operações.

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 tabelas muito amplas.

Compartilhar via

Capture e visualize linhagens de dados usando o Catálogo do Unity

Requisitos

Exemplos

Capturar e explorar linhagem

Capturar e exibir linhagem de fluxo de trabalho

Capturar e exibir a linhagem do painel

Permissões de linhagem

Excluir dados de linhagem

Consultar os dados de linhagem usando as tabelas de sistema

Recuperar a linhagem usando a API REST de Linhagem de Dados

Recuperar linhagem de tabela

Solicitação

Resposta

Recuperar linhagem de coluna

Solicitação

Resposta

Limitações

Comentários

Recursos adicionais