Executar consultas federadas em Snowflake (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 do Snowflake usando a integração OAuth integrada do Snowflake. Para outros métodos de autenticação, consulte as seguintes páginas:

• OAuth com o Microsoft Entra ID
• OAuth com Okta
• Token de acesso OAuth
• 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.

Federação de consultas

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ê precisa ter a permissão de CREATE CATALOG no metastore e ser o proprietário da conexão ou ter o privilégio de 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 tarefa a seguir.

Criar uma integração de segurança

No console do Snowflake, execute CREATE SECURITY INTEGRATION. Substitua os seguintes valores:

• <integration-name>: um nome exclusivo para a integração OAuth.

• <workspace-url>: uma URL do workspace do Azure Databricks. Você deve definir OAUTH_REDIRECT_URI como https://<workspace-url>/login/oauth/snowflake.html, em que <workspace-url> é a URL exclusiva do workspace do Azure Databricks em que você criará a conexão Snowflake.

• <duration-in-seconds>: um período de tempo dos tokens de atualização.

  Important

  OAUTH_REFRESH_TOKEN_VALIDITY é um campo personalizado definido como 90 dias por padrão. Depois que o token de atualização expirar, você deverá autenticar novamente a conexão. Defina o campo como um período de tempo razoável.

Por exemplo:

CREATE SECURITY INTEGRATION <integration-name>
TYPE = oauth
ENABLED = true
OAUTH_CLIENT = custom
OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
OAUTH_REDIRECT_URI = 'https://<workspace-url>/login/oauth/snowflake.html'
OAUTH_ISSUE_REFRESH_TOKENS = TRUE
OAUTH_REFRESH_TOKEN_VALIDITY = <duration-in-seconds>
OAUTH_ENFORCE_PKCE = TRUE;

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 Explorador do Catálogo ou o comando SQL CREATE CONNECTION em um notebook do Azure Databricks, ou o editor de consulta do Databricks SQL.

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

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

2. Na parte superior do painel Catálogo , clique no ícone Adicionar e selecione Criar uma conexão no menu.

3. Na página Noções básicas da conexão do assistente Configurar conexão, insira um Nome de conexão fácil de usar.

4. Selecione um Tipo de Conexão do Snowflake.

5. Para tipo de autenticação, selecione OAuth no menu suspenso.

6. (Opcional) Adicione um comentário.

7. Clique em Próximo.

8. Insira os seguintes detalhes de autenticação e conexão para seu armazém Snowflake.

   • Host: por exemplo, snowflake-demo.east-us-2.azure.snowflakecomputing.com

   • Porta: por exemplo, 443

   • Usuário: por exemplo, snowflake-user

   • ID do cliente: no console do Snowflake, execute SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('<security-integration-name>') para recuperar a ID do cliente para a integração de segurança.

   • Segredo do cliente: No console Snowflake, execute SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('<security-integration-name>') para recuperar o segredo do cliente para a integração de segurança.

   • Escopo do OAuth: refresh_token session:role:<role-name>. Especifique a função Snowflake a ser usada em <role-name>.

   • Entre com Snowflake: clique e entre no Snowflake usando suas credenciais do OAuth.

     Após entrar com sucesso, você será redirecionado de volta ao assistente Configurar conexão.

9. Clique em Criar conexão.

10. Na página Noções básicas do catálogo, insira um nome para o catálogo estrangeiro. 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.

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

12. Clique em Criar catálogo.

13. Na página Access, selecione os workspaces nos quais os usuários podem acessar o catálogo que você criou. Você pode selecionar Todas as áreas de trabalho têm acesso ou clicar em Atribuir aos workspaces, selecionar as áreas de trabalho e então clicar em Atribuir.

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

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

    1. Especifique as Entidades de segurança que terão acesso a 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 nos objetos no catálogo.
       • Selecione Editor de Dados no menu suspenso para conceder os privilégios read e modify nos objetos no catálogo.
       • Selecione manualmente os privilégios a serem concedidos.
    3. Selecione Conceder.

16. Clique em Próximo.

17. Na página de Metadados, especifique os pares chave-valor dos rótulos. Para obter mais informações, consulte Aplicar etiquetas a objetos securitizáveis do Catálogo Unity.

18. (Opcional) Adicione um comentário.

19. Clique em Salvar.

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:

• Filters
• Projections
• Limit
• Offset
• Joins
• 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)
• Sorting
• 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 de federação de consulta

• O endpoint Snowflake OAuth deve ser acessível a partir dos IPs do plano de controle do Azure Databricks. Consulte Painel de controle IPs de saída do Azure Databricks. O Snowflake dá suporte à configuração de políticas de rede no nível de integração de segurança, o que permite uma política de rede separada que permite a conectividade direta do plano de controle do Azure Databricks para o ponto de extremidade OAuth para 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.
• Tabelas e views externas que contêm colunas com tipos de dados específicos do Snowflake não compatíveis com o Unity Catalog, como VECTOR, não podem ser consultadas pela Lakehouse Federation. O Catálogo do Unity deve armazenar metadados para todas as colunas na tabela estrangeira, portanto, tipos de coluna sem suporte causam um erro de "tipo sem suporte", mesmo que a consulta não faça referência a essas colunas. Para contornar isso, crie uma exibição do Snowflake que exclua as colunas sem suporte e consulte a exibição em vez disso.

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)