Linhagem externa¶

Fluxo de trabalho da linhagem externa¶

A implementação da linhagem externa para uma ferramenta de dados consiste nas seguintes tarefas:

1. Conceder os privilégios necessários ao usuário que está se autenticando no ponto de extremidade da linhagem externa.

2. Configurar sua ferramenta de dados para enviar eventos de OpenLineage ao ponto de extremidade REST do Snowflake.

3. Escolher um método de autenticação que funcione com as APIs REST do Snowflake e, em seguida, configurar sua ferramenta de dados para usá-lo na autenticação de suas solicitações para o ponto de extremidade da linhagem externa.

4. Use sua ferramenta de dados como de costume. Os eventos de OpenLineage são enviados ao Snowflake automaticamente e aparecem no gráfico da linhagem nativa no Snowsight.

Se quiser testar o ponto de extremidade da linhagem externa antes de configurar uma ferramenta de dados para emitir eventos de OpenLineage, consulte Enviar solicitações manuais para estabelecer a linhagem.

Visualizar sua linhagem de dados¶

Para visualizar a linhagem de dados no Snowsight, conclua as seguintes etapas:

1. Faça login no Snowsight com o privilégios necessários.

2. No menu de navegação, selecione Catalog » Database Explorer e, em seguida, selecione um objeto com suporte como uma tabela ou exibição.

3. Selecione a guia Lineage.

Quando uma ferramenta de dados envia informações de linhagem ao Snowflake, os objetos externos aparecem no gráfico de linhagem do Snowsight e são rotulados como um nó externo. Por exemplo:

Você pode selecionar um objeto externo ou a linha que conecta os objetos para obter informações adicionais, da mesma forma que na linhagem nativa.

Conceder privilégios do Snowflake¶

Depois que uma solicitação REST é autenticada, o Snowflake verifica se o usuário associado à solicitação tem autorização para usar a linhagem externa. O usuário associado à solicitação deve ter uma função que tenha recebido o privilégio INGEST LINEAGE na conta.

Por exemplo, suponha que você queira que as solicitações enviadas pelo usuário do serviço dbt_integration_user apareçam na linhagem do Snowsight. Como administrador, execute os seguintes comandos para criar uma função dedicada, conceder a ela o privilégio necessário e, em seguida, conceder a função ao usuário:

CREATE ROLE dbt_lineage_role;
GRANT INGEST LINEAGE ON ACCOUNT TO ROLE dbt_lineage_role;
GRANT ROLE dbt_lineage_role TO USER dbt_integration_user;

Configurar sua ferramenta de dados¶

As seções a seguir apresentam instruções básicas para usar a linhagem externa com o dbt e o Apache AirFlow.

• Configurar o dbt para enviar dados de linhagem ao Snowflake

• Configurar o Airflow para enviar dados de linhagem ao Snowflake

Escolher um método de autenticação¶

O Snowflake oferece vários métodos para autenticar solicitações para um ponto de extremidade REST do Snowflake, como aquele usado pela linhagem externa. Para obter uma lista completa dos métodos de autenticação, consulte Autenticando o Snowflake REST APIs com Snowflake.

Depois de selecionar seu método de autenticação preferido, você deverá gerar um token de segurança para um usuário específico. O token é usado para associar um usuário à solicitação REST para que o Snowflake possa autenticar o usuário e verificar se ele tem autorização para usar a linhagem externa.

Depois de associar com sucesso um usuário a um token de segurança no Snowflake, você precisará configurar sua ferramenta de dados para autenticar suas solicitações com esse token. Por exemplo, se você usa um arquivo de configuração YAML para definir as variáveis de transporte para OpenLineage, use o código a seguir para especificar o token de segurança que é enviado no cabeçalho da solicitação:

transport:
   auth:
      type: api_key
      apiKey: eyJ0eXAiOiJKV1QiLsecuritytoken...

Para outros métodos de especificação de token de segurança, consulte a documentação sobre OpenLineage da sua ferramenta de dados.

Enviar solicitações manuais para estabelecer a linhagem¶

A linhagem externa funciona aceitando cargas úteis JSON em conformidade com a especificação de OpenLineage para eventos COMPLETE. Quando integrada a uma ferramenta de dados, a ferramenta emite os eventos COMPLETE. No entanto, você também pode construir um evento COMPLETE e, em seguida, enviá-lo ao ponto de extremidade usando qualquer ferramenta ou linguagem que possa enviar solicitações POST a um ponto de extremidade.

Uma solicitação válida consiste no método, URL base e ponto de extremidade a seguir:

POST https://<account_identifier>.snowflakecomputing.com/api/v2/lineage/external-lineage

Em que account_identifier é o identificador da sua conta Snowflake.

O seguinte exemplo mostra como usar o curl para enviar informações de linhagem à linhagem externa:

curl -i -X POST \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLsecuritytoken..." \
 -H "Accept: application/json" \
 -H "User-Agent: myApplicationName/1.0" \
 -H "X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT" \
 -d "@request_body.json" \
 "https://MYORG-DEV_ACCOUNT.snowflakecomputing.com/api/v2/lineage/external-lineage"

Em que request_body.json está em conformidade com a especificação de OpenLineage para eventos COMPLETE. Para obter mais informações sobre a carga útil JSON, consulte Requisitos de carga útil.

{
   "eventType": "COMPLETE",
   "eventTime": "2025-03-12T06:51:12.000Z",
   "job": {"namespace": "exampleNamespace", "name": "exampleJob"},
   "run": {"runId": "123e4567-e89b-12d3-a456-426614174000"},
   "producer": "https://github.com/OpenLineage/OpenLineage/blob/v1-0-0/client",
   "schemaURL": "https://openlineage.io/spec/0-0-1/OpenLineage.json",
   "inputs": [{"namespace": "snowflake://AXORG-AX_TEST_PP8", "name": "OL_TEST.OL_TEST_SCH.TEST_DEMO"}],
   "outputs": [{"namespace": "postgres://localhost:5432", "name": "PDB.SCH.OUTPUT"}]
}

"outputs": [
    {
        "namespace": "postgres://db.company.com:5432",
        "name": "db.schema.view",
        "facets": {"datasetType": {"datasetType": "VIEW"}},
    },
],

Enviar solicitações para remover a linhagem¶

Você pode enviar uma solicitação DELETE ao ponto de extremidade da linhagem externa para remover a linhagem estabelecida entre um objeto Snowflake e um objeto externo.

• Para separar a linhagem entre o objeto de origem e o objeto de destino, use parâmetros de consulta URL para especificar os detalhes sobre os dois objetos.

• Para separar a linhagem entre um objeto e todos os respectivos objetos downstream, especifique o objeto de origem sem especificar um objeto de destino.

• Para remover um objeto de destino do gráfico de linhagem, independentemente de quantos objetos estejam acima dele, especifique o objeto de destino sem especificar um objeto de origem.

Uma solicitação válida para remover a linhagem consiste no método, no URL base e no ponto de extremidade a seguir:

DELETE https://<account_identifier>.snowflakecomputing.com/api/v2/lineage/external-lineage

Limitações e considerações¶

• Um objeto Snowflake deve ser INPUT ou OUTPUT de um evento COMPLETE. Ou seja, a linhagem externa não ingere eventos de linhagem quando nem os dados de entrada nem os dados de saída são um objeto Snowflake.

• O Snowflake não oferece suporte a OpenLineage versão 2.

• O período de retenção para eventos de linhagem externa é de um ano.

• O Snowflake reconhece apenas eventos de linhagem COMPLETE. Todos os outros eventos emitidos por uma ferramenta de dados são ignorados.

• A linhagem de fontes externas não aparece na saída da função GET_LINEAGE.

• A linhagem externa não oferece suporte à linhagem de colunas.

• O nome totalmente qualificado de um conjunto de dados, ou seja, a entrada ou a saída, não pode exceder 1.000 caracteres.

• Não é possível armazenar mais de 10.000 eventos na mesma conta. Se atingir esse limite, você terá que excluir eventos antes de adicionar novos.