Executar consultas federadas no Snowflake (token de acesso OAuth)

Esta página descreve como configurar a Lakehouse Federation para executar consultas federadas em dados do Snowflake que não são gerenciados pelo Azure Databricks. Para saber mais sobre o Lakehouse Federation, consulte Conectar-se a bancos de dados e catálogos externos

Para se conectar ao banco de dados Snowflake usando a Federação de Lakehouse, você deve criar o seguinte no metastore do Catálogo do Unity do Azure Databricks (workspaces criados após 9 de novembro de 2023 já têm um metastore do Catálogo do Unity provisionado automaticamente):

• Uma conexão com seu banco de dados do Snowflake.
• Um catálogo estrangeiro que espelha seu banco de dados do Snowflake no Catálogo do Unity para que você possa usar a sintaxe de consulta do Catálogo do Unity e as ferramentas de governança de dados para gerenciar o acesso do usuário do Azure Databricks ao banco de dados.

Esta página aborda como executar consultas federadas em dados snowflake usando um token de acesso OAuth. Para outros métodos de autenticação, consulte as seguintes páginas:

• OAuth interno do Snowflake
• OAuth com o Microsoft Entra ID
• OAuth com Okta
• Chave privada PEM
• Autenticação básica (nome de usuário/senha)

Você pode executar consultas federadas no Snowflake usando federação de consulta ou federação de catálogo.

Na federação de consultas, o JDBC transfere a consulta do Unity Catalog para o banco de dados externo. Isso é ideal para relatórios sob demanda ou trabalho de prova de conceito em seus pipelines de ETL.

Na federação de catálogo, a consulta do Catálogo Unity é executada diretamente no armazenamento de arquivos. Essa abordagem é útil para a migração incremental sem adaptação de código ou como um modelo híbrido de longo prazo para organizações que devem manter alguns dados no Snowflake junto com seus dados registrados no Catálogo do Unity. Consulte Habilitar federação do catálogo do Snowflake.

Antes de começar

Requisitos de área de trabalho:

• Espaço de trabalho habilitado para o Unity Catalog. Os workspaces criados após 9 de novembro de 2023 são automaticamente habilitados para o Unity Catalog, incluindo o provisionamento automático de metastore. Você não precisa criar um metastore manualmente, a menos que seu workspace tenha sido criado antes da habilitação automática e não tenha sido ativado para o Unity Catalog. Consulte Introdução ao Catálogo do Unity.

Requisitos de computação:

• Conectividade de rede do recurso de computação para os sistemas de banco de dados de destino. Confira Recomendações de rede para a Federação de Lakehouse.
• A computação do Azure Databricks deve usar o Databricks Runtime 13.3 LTS ou superior e modo de acesso Standard ou Dedicado.
• Os sql warehouses devem ser profissionais ou sem servidor e devem usar 2023.40 ou superior.

Permissões necessárias:

• Para criar uma conexão, você deve ser um administrador de metastore ou um usuário com o privilégio de CREATE CONNECTION no metastore do Unity Catalog anexado ao espaço de trabalho. Em workspaces que foram habilitados automaticamente para o Unity Catalog, os administradores de workspace têm o privilégio CREATE CONNECTION por padrão.
• Para criar um catálogo estrangeiro, você deve ter a permissão CREATE CATALOG no metastore e ser o proprietário da conexão ou ter o privilégio CREATE FOREIGN CATALOG na conexão. Em workspaces que foram habilitados automaticamente para o Unity Catalog, os administradores de workspace têm o privilégio CREATE CATALOG por padrão.

Requisitos de permissão adicionais são especificados em cada seção baseada em tarefas a seguir.

Solicitar um token de acesso OAuth

Siga Como: Gerar e usar um token OAuth usando o Snowflake OAuth para os clientes personalizados na Base de Conhecimento do Snowflake.

Criar uma conexão

Uma conexão especifica um caminho e credenciais para acessar um sistema de banco de dados externo. Para criar uma conexão, você pode usar o Gerenciador de Catálogos ou o comando SQL CREATE CONNECTION em um notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

Permissões necessárias: administrador do metastore ou usuário que possua o privilégio CREATE CONNECTION.

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Clique Conecte-se e clique em Conexões.

3. Clique no botão Criar conexão .

4. Na página Noções básicas sobre a conexão do assistente Configurar conexão, insira um Nome da conexão amigável.

5. Para o tipo de conexão, selecione Snowflake.

6. Para tipo de autenticação, selecione OAuth Access Token no menu suspenso.

7. (Opcional) Adicione um comentário.

8. Clique em Próximo.

9. Insira os seguintes detalhes de autenticação e conexão na página Autenticação .

   • Host: Por exemplo, snowflake-demo.east-us-2.azure.snowflakecomputing.com.
   • Porta: o valor padrão é 443.
   • Usuário: Use seu nome de usuário do Snowflake pessoal.
   • Token de acesso: token de acesso em Solicitar um token de acesso OAuth.
   • (Opcional) Expira em segundos: o tempo de expiração (em segundos) para o token de acesso de Solicitar um token de acesso OAuth (expires_in).

10. Clique em Próximo.

11. Na página Detalhes da conexão , insira o nome do seu armazém Snowflake.

12. Se você quiser usar o proxy para se conectar ao Snowflake, marque a caixa Usar proxy e preencha os detalhes necessários.

13. Clique em Criar conexão.

14. Na página Noções básicas sobre o catálogo, insira um nome para o catálogo estrangeiro.

15. Para o Banco de Dados, insira um nome de banco de dados no Snowflake. Um catálogo estrangeiro espelha um banco de dados em um sistema de dados externo para que você possa consultar e gerenciar o acesso aos dados nesse banco de dados usando o Azure Databricks e o Catálogo do Unity.

16. (Opcional) Clique em Testar conectividade para confirmar se está funcionando.

17. Clique em Criar catálogo.

18. Na página Access, selecione os workspaces nos quais os usuários podem acessar o catálogo que você criou. Você pode selecionar Todos os workspaces têm acesso ou clicar em Atribuir a workspaces, selecionar os workspaces e clicar em Atribuir.

19. Altere o Proprietário que poderá gerenciar o acesso a todos os objetos do catálogo. Comece a digitar uma entidade de segurança na caixa de texto e clique na entidade de segurança nos resultados retornados.

20. Conceda Privilégios no catálogo. Clique em Conceder:

    1. Especifique as Entidades de segurança que terão acesso aos objetos no catálogo. Comece a digitar uma entidade de segurança na caixa de texto e clique na entidade de segurança nos resultados retornados.
    2. Selecione as Predefinições de privilégio a conceder a cada usuário. Todos os usuários da conta recebem BROWSE como padrão.
       • Selecione Leitor de Dados no menu suspenso para conceder privilégios read em objetos no catálogo.
       • Selecione Editor de Dados no menu suspenso para conceder privilégios read e modify em objetos no catálogo.
       • Selecione manualmente os privilégios a serem concedidos.
    3. Selecione Conceder.

21. Clique em Próximo.

22. Na página Metadados, especifique os pares chave-valor das marcações. Para obter mais informações, consulte Aplicar etiquetas a objetos securitizáveis do Catálogo Unity.

23. (Opcional) Adicione um comentário.

24. Clique em Salvar.

SQL

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks.

CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  host '<hostname>',
  port '<port>',
  sfWarehouse '<warehouse-name>',
  user '<user>',
  access_token '<access-token>',
  expires_in_secs '<expiration-time-in-seconds>'
);

O Databricks recomenda usar segredos em vez de cadeias de caracteres de texto sem formatação para valores confidenciais, como credenciais. Por exemplo:

CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  host '<hostname>',
  port '<port>',
  sfWarehouse '<warehouse-name>',
  user secret ('<secret-scope>','<secret-key-user>'),
  access_token secret ('<secret-scope>','<secret-key-access-token>'),
  expires_in_secs '<expiration-time-in-seconds>'
)

Para obter informações sobre como configurar segredos, consulte a seção Gerenciamento de segredos.

Opções avançadas de conexão

As conexões snowflake dão suporte à seguinte opção avançada para ambientes de saída restrita ou de conectividade privada:

• disableOCSPChecks: defina como true para desabilitar as verificações de revogação de certificados via OCSP (Protocolo de Status de Certificado Online) no driver JDBC do Snowflake. Desabilitar as verificações de OCSP ignora as verificações de revogação de certificados.

Essa opção não é mostrada no Gerenciador de Catálogos. Você pode defini-la ao criar a conexão com o SQL:

CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  <connection-options>,
  disableOCSPChecks 'true'
);

Para uma conexão existente, use ALTER CONNECTION.

Identificadores do banco de dados que diferenciam maiúsculas de minúsculas

O campo database do catálogo estrangeiro é mapeado para um identificador de banco de dados Snowflake. Se o identificador do banco de dados Snowflake não diferencia maiúsculas de minúsculas, a maiúscula que você usa no catálogo estrangeiro <database-name> será preservada. Porém, se o identificador do banco de dados do Snowflake diferencia maiúsculas de minúsculas, você precisa encapsular o catálogo estrangeiro <database-name> entre aspas duplas para preservar as maiúsculas e minúsculas.

Por exemplo:

• database é convertido em DATABASE

• "database" é convertido em database

• "database""" é convertido em database"

  Para escapar uma aspa dupla, use outra aspa dupla.

• "database"" resulta em um erro porque a aspa dupla não foi escapada corretamente.

Para obter mais informações, confira Requisitos do identificador na documentação do Snowflake.

Pushdowns com suporte

Há suporte para os seguintes pushdowns:

• Filtros
• Projeções
• Limite
• Offset
• Junções
• Agregações (Average, Corr, CovPopulation, CovSample, Count, Max, Min, StddevPop, StddevSamp, Sum, VariancePop, VarianceSamp)
• Funções (Funções de cadeia de caracteres, funções matemáticas, funções Date, Time e Timestamp e outras funções diversas, como Alias, Cast, SortOrder)
• Funções de janela (DenseRank, Rank, RowNumber)
• Classificação
• Top-N (combinando classificação e limite em uma única operação), com suporte no Databricks Runtime 17.3 e superior

Mapeamentos de tipo de dados

Quando você lê do Snowflake para o Spark, os tipos de dados são mapeados da seguinte maneira:

Limitações

• O endpoint Snowflake OAuth deve estar acessível a partir dos IPs da camada de controle do Databricks. Consulte Painel de controle IPs de saída do Azure Databricks. Snowflake oferece suporte à configuração de políticas de rede no nível de integração de segurança, permitindo uma política de rede separada que viabiliza a conectividade direta do plano de controle do Databricks ao endpoint OAuth para fins de autorização.
• As opções de configuração Use Proxy, Proxy host, Proxy port e Snowflake role não são suportadas. Especifique a função Snowflake como parte do escopo OAuth.

Recursos adicionais

Confira os seguintes artigos na documentação do Snowflake:

• Configurar o Snowflake OAuth para os clientes personalizados
• Referência do SQL: CREATE SECURITY INTEGRATION (Snowflake OAuth)