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

Artigo
03/20/2024

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, fluxos de trabalho e painéis relacionados à consulta. A linhagem pode ser visualizada no Catalog Explorer em tempo quase real e recuperada com a API REST do Databricks.

Observação

Você também pode exibir e consultar os dados de linhagem usando as tabelas do sistema de linhagem (Visualização Pública). Para obter mais informações, consulte Referência das tabelas do sistema de linhagem.

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.

Este artigo descreve a visualização da linhagem usando o Catalog Explorer e a API REST. 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.
Para exibir informações de linhagem para notebooks, fluxos de trabalho 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.
Talvez seja necessário atualizar suas regras de firewall de saída para permitir a conectividade com o ponto de extremidade do Hub 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 do 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 do hub 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.

Limitações

Há suporte para o streaming entre tabelas Delta apenas no Databricks Runtime 11.3 LTS ou superior.
Como a linhagem é computada em uma janela móvel 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 de tempo. Quando "Toda a linhagem" é selecionado, os dados de linhagem coletados a partir de junho de 2023 são exibidos.
Os fluxos de trabalho 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.
A linhagem da coluna só é suportada quando a origem e o destino são referenciados pelo nome da tabela (Exemplo: select * from <catalog>.<schema>.<table>). A linhagem da coluna não pode ser capturada se a origem ou o destino forem endereçados por caminho (Exemplo: select * from delta."s3://<bucket>/<path>").
A linhagem de dados não captura leituras em tabelas com máscaras de coluna. Consulte Filtrar dados confidenciais da tabela usando filtros de linha e máscaras de coluna.
Se uma tabela for renomeada, a linhagem não será capturada para a tabela renomeada.
Se você usar o ponto de verificação do conjunto de dados do Spark SQL, a linhagem não será capturada. Confira pyspark.sql.DataFrame.checkpoint na documentação do Apache Spark.
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.

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 de catálogo ou proprietário de 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, use as seguintes etapas:

Vá para a página de aterrissagem do Azure Databricks, clique no 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 Catalog Explorer para exibir a linhagem gerada por essas consultas, use as seguintes etapas:

Na caixa Pesquisar na barra superior do workspace do Azure Databricks, insira lineage_data.lineagedemo.dinner e clique em Pesquisar lineage_data.lineagedemo.dinner no Databricks.
Em Tabelas, clique na tabela dinner.
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. Você pode clicar no em um nó para revelar mais conexões se estiverem disponíveis.
Clique em uma seta conectando 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 fluxos de trabalho.
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 notebook em uma nova guia, clique no nome dele.
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 demonstrar a criação e exibição de linhagem com uma linguagem diferente, por exemplo, Python, use as seguintes etapas:

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, insira lineage_data.lineagedemo.price e clique em Pesquisar lineage_data.lineagedemo.price no Databricks.
Em Tabelas, clique na tabela price.
Selecione a guia Linhagem e clique em Ver Grafo de Linhagem. Clique nos ícones para explorar a linhagem de dados gerada pelas consultas SQL e Python.
Clique em uma seta conectando 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 fluxos de trabalho.

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 demonstrar a exibição de linhagem para um fluxo de trabalho do Azure Databricks, use as seguintes etapas:

Clique no 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, insira lineage_data.lineagedemo.menu e clique em Pesquisar lineage_data.lineagedemo.menu no Databricks.
Em Tabelas Exibir todas as tabelas, clique na tabela menu.
Selecione a guia Linhagem, clique em Fluxos de Trabalho e selecione a guia Downstream. O nome do trabalho aparecerá em Nome do Trabalho como um consumidor da tabela menu.

Capturar e exibir a linhagem do painel

Para demonstrar a exibição da linhagem de um painel do SQL, use as seguintes etapas:

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 de texto Pesquisar tabelas na barra superior para pesquisar a tabela menu.
Clique em Ações > Criar um painel rápido.
Selecione colunas para adicionar ao painel e clique em Criar.
Na caixa Pesquisar na barra superior do workspace do Azure Databricks, insira lineage_data.lineagedemo.menu e clique em Pesquisar lineage_data.lineagedemo.menu no Databricks.
Em Tabelas Exibir todas as tabelas, clique na tabela menu.
Selecione a guia Linhagem e clique em Painéis. 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, fluxos de trabalho 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, fluxos de trabalho 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.

API de linhagem de dados

A API de linhagem de dados permite que você recupere a linhagem de tabela e coluna.

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://<databricks-instance/api/2.0/lineage-tracking/table-lineage \
-d '{"table_name": "lineage_data.lineagedemo.dinner", "include_entity_lineage": true}}'

Substituir <get-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://<databricks-instance/api/2.0/lineage-tracking/column-lineage \
-d '{"table_name": "lineage_data.lineagedemo.dinner", "column_name": "dessert"}}'

Substituir <get-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"
    }
  ]
}

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

Requisitos

Limitações

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

API de linhagem de dados

Recuperar linhagem de tabela

Solicitação

Resposta

Recuperar linhagem de coluna

Solicitação

Resposta

Recursos adicionais