Capture e visualize linhagens de dados usando o Unity Catalog

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

Você pode usar o Unity Catalog para capturar 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 da coluna. 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 as tabelas do sistema de linhagem e a API REST do Databricks.

A linhagem é agregada em todos os espaços de trabalho anexados 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 compartilhe esse metastore. Os usuários devem ter as permissões corretas para exibir os dados de linhagem. Os dados de linhagem são retidos por 1 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.

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

Requisitos

São necessárias as seguintes condições para capturar a linhagem de dados com o Unity Catalog:

• O espaço de trabalho deve ter o Unity Catalog habilitado.

• As tabelas têm de estar registadas num metastore do 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 exibir a linhagem de uma tabela ou exibição, os usuários devem ter pelo menos o BROWSE privilégio no catálogo pai da tabela ou da exibição.

• 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 Catálogo Unity, você deve ter CAN_VIEW permissões no pipeline.

• O rastreamento de linhagem de streaming entre tabelas Delta requer o Databricks Runtime 11.3 LTS ou superior.

• O rastreamento de linhagem de colunas para cargas de trabalho do Delta Live Tables requer o 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 Hubs de Eventos no plano de controle 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 obter o ponto de extremidade Hubs de Eventos para sua região de espaço de trabalho, consulte Metastore, armazenamento de Blob de artefato, armazenamento de tabelas 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

Capture e explore a linhagem

Para capturar dados de linhagem:

1. Vá para a página inicial do Azure Databricks, clique em Novo na barra lateral e selecione Bloco de Anotações no menu.

2. Insira um nome para o bloco de anotações e selecione SQL no idioma padrão.

3. Em Cluster, selecione um cluster com acesso ao Unity Catalog.

4. Clique em Criar.

5. 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
   

6. Para executar as consultas, clique na célula e pressione shift+enter ou clique e selecione Executar célula.

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

1. Na caixa Pesquisar na barra superior do espaço de trabalho do Azure Databricks, procure a lineage_data.lineagedemo.dinner tabela e selecione-a.

2. Selecione a guia Linhagem . O painel de linhagem aparece e exibe tabelas relacionadas (para este exemplo, é a menu tabela).

3. 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 em um nó para revelar mais conexões, se estiverem disponíveis.

4. Clique em uma seta que conecta nós no gráfico de linhagem para abrir o painel de conexão Linhagem. O painel Conexão Linhagem mostra detalhes sobre a conexão, incluindo tabelas de origem e destino, blocos de anotações e trabalhos.

   

5. Para mostrar o bloco de anotações associado à dinner tabela, selecione-o no painel de conexão Linhagem ou feche o gráfico de linhagem e clique em Blocos de Anotações. Para abrir o bloco de notas num novo separador, clique no nome do bloco de notas.

6. Para exibir a linhagem em nível de coluna, clique em uma coluna no gráfico para mostrar links para colunas relacionadas. Por exemplo, clicar na coluna «full_menu» mostra as colunas a montante das quais a coluna foi derivada:

   

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

1. 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")
   

2. Execute a célula clicando na célula e pressionando shift+enter ou clicando e selecionando Executar célula.

3. Na caixa Pesquisar na barra superior do espaço de trabalho do Azure Databricks, procure a lineage_data.lineagedemo.price tabela e selecione-a.

4. 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.

   

5. Clique em uma seta que conecta nós no gráfico de linhagem para abrir o painel de conexão Linhagem. O painel Conexão Linhagem mostra detalhes sobre a conexão, incluindo tabelas de origem e destino, blocos de anotações e trabalhos.

Capturar e visualizar linhagem de fluxo de trabalho

O Lineage também é capturado para qualquer fluxo de trabalho que leia ou grave no Unity Catalog. Para exibir a linhagem de um fluxo de trabalho do Azure Databricks:

1. Clique em Novo na barra lateral e selecione Bloco de Anotações no menu.

2. Insira um nome para o bloco de anotações e selecione SQL no idioma padrão.

3. Clique em Criar.

4. Na primeira célula do bloco de notas, introduza a seguinte consulta:

   SELECT * FROM lineage_data.lineagedemo.menu
   

5. Clique em Agendar na barra superior. Na caixa de diálogo de agendamento, selecione Manual, selecione um cluster com acesso ao Unity Catalog e clique em Criar.

6. Clique em Executar agora.

7. Na caixa Pesquisar na barra superior do espaço de trabalho do Azure Databricks, procure a lineage_data.lineagedemo.menu tabela e selecione-a.

8. Na guia Linhagem, clique em Fluxos de Trabalho e selecione a guia Downstream. O nome do trabalho aparece em Nome do trabalho como um consumidor da menu tabela.

Capture e visualize a linhagem do painel

Para criar um painel e exibir sua linhagem de dados:

1. Vá para a página inicial do Azure Databricks e abra o Gerenciador de Catálogos clicando em Catálogo na barra lateral.

2. Clique no nome do catálogo, clique em lineagedemo e selecione a menu tabela. Você também pode usar a caixa Pesquisar na barra superior para pesquisar a menu tabela.

3. Clique em Abrir em um painel.

4. Selecione as colunas que deseja adicionar ao painel e clique em Criar.

5. Publique o painel.

   Somente os painéis publicados são rastreados na linhagem de dados.

6. Na caixa Pesquisar na barra superior, procure a lineage_data.lineagedemo.menu tabela e selecione-a.

7. Na guia Linhagem, clique em Painéis. O painel aparece em Nome do painel como um consumidor da tabela de menus.

Permissões de linhagem

Os gráficos de linhagem compartilham o mesmo modelo de permissão do Unity Catalog. Se um usuário não tiver o BROWSE privilégio ou SELECT em uma tabela, ele não poderá explorar a linhagem. Além disso, os usuários só podem ver blocos de anotações, trabalhos e painéis que eles têm permissão para exibir. Por exemplo, se você executar os seguintes comandos para um usuário userAnã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 visualiza o gráfico de linhagem da lineage_data.lineagedemo.menu tabela, eles verão a menu tabela. Eles não poderão ver informações sobre tabelas associadas, como a tabela a jusante lineage_data.lineagedemo.dinner . A dinner tabela é exibida como um masked nó na exibição para userA, e userA não pode expandir o gráfico para revelar tabelas downstream de tabelas que eles não têm permissão para acessar.

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

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

userB Agora pode visualizar o gráfico de linhagem de qualquer tabela no lineage_data esquema.

Para obter mais informações sobre como gerenciar o acesso a objetos protegíveis no Unity Catalog, consulte Manage privileges in 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

Para excluir dados de linhagem, você deve excluir o metastore que gerencia os objetos do 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 tabelas do sistema

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

Se seu espaço de trabalho estiver em uma região que não ofereça suporte a tabelas do sistema de linhagem, você poderá, 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 linhagens de tabelas e colunas. No entanto, se o espaço de trabalho estiver em uma região que ofereça suporte às tabelas do sistema de linhagem, você deverá usar consultas de tabela 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 suporta as tabelas do sistema de linhagem.

Recuperar linhagem de tabela

Este exemplo recupera dados de linhagem para a dinner tabela.

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

Este exemplo recupera dados de coluna para a dinner tabela.

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

• Como a linhagem é calculada em uma janela de rolagem de um ano, a linhagem coletada há mais de um ano não é exibida. Por exemplo, se um trabalho ou consulta ler 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 dentro da janela de um ano.
• 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 em nível de tabela e coluna ainda é capturada ao usar a runs submit solicitação, mas o link para a execução não é capturado.
• O Unity Catalog captura a linhagem ao nível da coluna tanto quanto possível. No entanto, existem alguns casos em que a linhagem ao nível da coluna não pode ser capturada.
• A linhagem de colunas é suportada 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 pode ser capturada se a origem ou o destino for abordado 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 usar o ponto de verificação do conjunto de dados Spark SQL, a linhagem não será capturada. Consulte pyspark.sql.DataFrame.checkpoint na documentação do Apache Spark.
• O Unity Catalog captura a linhagem de pipelines 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 pipelines usam as tabelas APPLY CHANGES API ou TEMPORARY .
• Lineage não captura funções de pilha.