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 a Federação Lakehouse, veja o que é a Federação Lakehouse?

Para se conectar ao seu banco de dados Snowflake usando Federation Lakehouse, você deve criar o seguinte no metastore do Unity Catalog do Azure Databricks:

• 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 a ID do Microsoft Entra
• 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 Snowflake.

Federação de consulta

Antes de começar

Requisitos de área de trabalho:

• Espaço de trabalho habilitado para o Unity Catalog.

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

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 Adicionar uma conexão no menu.

   Como alternativa, na página Acesso rápido, clique no botão Dados externos >, vá até a guia Conexões e clique em Criar conexão.

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. Selecione o botão 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.

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
• 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, dados, tempo e carimbo de data/hora e outras funções diversas, como Alias, Cast, SortOrder)
• Funções do Windows (DenseRank, Rank, RowNumber)
• Sorting

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 IPs de saída do plano de gerenciamento 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.

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)