Executar consultas federadas no Snowflake

Artigo
01/14/2025

Este artigo descreve como set 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 Lakehouse Federation, consulte O que é Lakehouse Federation?.

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

Uma conexão com seu banco de dados Snowflake.
Uma catalog estrangeira que espelha o seu banco de dados Snowflake no Unity Catalog, para que possa usar a sintaxe de consulta Unity Catalog e as ferramentas de governança de dados para gerir o acesso de utilizadores do Azure Databricks ao banco de dados.

Antes de começar

Requisitos do espaço de trabalho:

Espaço de trabalho habilitado para Unity Catalog.

Requisitos de computação:

Conectividade de rede do seu recurso de computação para os sistemas de banco de dados de destino. Consulte Recomendações de rede para a Lakehouse Federation.
A computação do Azure Databricks deve usar o Databricks Runtime 13.3 LTS ou superior e modo de acesso Compartilhado ou modo de acesso de usuário único .
Os armazéns SQL 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 Unity Catalog anexado ao espaço de trabalho.
Para criar um catalogestrangeiro, você deve ter a permissão CREATE CATALOG no metastore e ser o proprietário da conexão ou ter o privilégio de CREATE FOREIGN CATALOG na conexão.

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

Se você planeja autenticar usando OAuth, crie uma integração de segurança no console do Snowflake.
Se você planeja autenticar usando um token de acesso OAuth, também deve solicitar um token de acesso.

(Opcional) Criar uma integração de segurança no console do Snowflake

Se você quiser autenticar usando OAuth, siga esta etapa antes de criar uma conexão Snowflake. Para autenticar usando um nome de usuário e senha, ignore esta seção.

Nota

Apenas a integração OAuth integrada do Snowflake é suportada. Integrações OAuth externas como Okta ou Microsoft Entra ID não são suportadas.

No console Snowflake, execute CREATE SECURITY INTEGRATION. Substitua o seguinte values:

<integration-name>: Um nome exclusivo para sua integração OAuth.
<workspace-url>: Uma URL do espaço de trabalho do Azure Databricks. Você deve setOAUTH_REDIRECT_URI para https://<workspace-url>/login/oauth/snowflake.html, e where<workspace-url> é a URL exclusiva do espaço de trabalho do Azure Databricks where onde você criará a conexão com o Snowflake.
<duration-in-seconds>: Um período de tempo para refresh tokens.

Importante

OAUTH_REFRESH_TOKEN_VALIDITY é um campo personalizado que é set a 90 dias por padrão. Depois que o token de refresh expirar, você deverá autenticar novamente a conexão. Set definir o campo para uma duração de tempo razoável.

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;

(Opcional) Solicitar um token de acesso OAuth

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

Criar uma conexão

Uma conexão especifica um caminho e credentials para acessar um sistema de banco de dados externo. Para criar uma conexão, você pode usar o Catalog Explorer ou o comando CREATE CONNECTION SQL em um bloco de anotações do Azure Databricks ou no editor de consultas Databricks SQL.

Nota

Você também pode usar a API REST do Databricks ou a CLI do Databricks para criar uma conexão. Consulte os comandos POST /api/2.1/unity-catalog/connections e Unity Catalog.

Permissões necessárias: administrador do Metastore ou usuário com o CREATE CONNECTION privilégio.

Catalog Explorer

No seu espaço de trabalho do Azure Databricks, clique Catalog.
Na parte superior do painel Catalog, clique no ícone ícone Adicionar e selectAdicionar uma conexão no menu.

Como alternativa, na página Acesso rápido, clique no botão dados externos , vá para a guia e clique em Criar conexão.
Na página Noções básicas de conexão do assistente de de conexão -up, insira um nome de conexão amigável.
Select um tipo de conexão do Snowflake.
Para Auth, digite, selectUsername and password (autenticação básica), OAuth access token, PEM Private Keyou OAuth no menu suspenso.
(Opcional) Adicione um comentário.
Clique Avançar.
Insira os seguintes detalhes de autenticação e conexão para seu armazém Snowflake. As propriedades específicas do método de autenticação selecionado são precedidas pelo Auth type entre parênteses.
- Anfitrião: Por exemplo, snowflake-demo.east-us-2.azure.snowflakecomputing.com
- Porto: Por exemplo, 443
- Usuário: Por exemplo, snowflake-user
- (Autenticação básica) Palavra-passe: Por exemplo, password123
- (Token de acesso OAuth) Token de acesso: Token de acesso proveniente de (Opcional) Solicite um token de acesso OAuth.
- (Token de acesso OAuth) Expira em segundos: O tempo de expiração (em segundos) para o token de acesso de (Opcional) Solicitar um token de acesso OAuth (expires_in).
- (OAuth) 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.
- (OAuth) segredo do cliente: No console do Snowflake, execute SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('<security-integration-name>') para recuperar o segredo do cliente para a integração de segurança.
- (OAuth) âmbito OAuth: refresh_token session:role:<role-name>. Especifique a função Floco de Neve a ser usada no <role-name>.
- (OAuth) Inicie sessão com o Snowflake: Clique e inicie sessão no Snowflake usando o seu OAuth credentials.
- (Chave privada PEM) chave privada PEM: Chave privada do par de chaves RSA no formato HEX64.
- (PEM Private Key) Expira em segundos: O tempo de expiração (em segundos) para a conexão feita com uma chave privada.
  
  Após o login bem-sucedido, será direcionado de volta para o assistente de conexão Set-up.
Clique em Criar conexão.
(Autenticação básica) Na página Detalhes da Conexão, especifique o seguinte:
- Armazém de flocos de neve: Por exemplo, my-snowflake-warehouse
- (Opcional) Host de proxy: Host do proxy usado para se conectar ao Snowflake. Você deve também selectusar proxy e especificar a porta de proxy .
- (Opcional) Usar proxy: Se deseja se conectar ao Snowflake usando um servidor proxy.
- (Opcional) Porta de proxy: Porta do proxy usado para se conectar ao Snowflake. Você também deve selectusar proxy e especificar host de proxy.
- (Opcional) função Snowflake: A função de segurança padrão a ser usada para a sessão após a conexão.
Clique Avançar.
Na página de noções básicas Catalog, insira um nome para o estrangeiro catalog. Um catalog externo espelha uma base de dados num sistema de dados externo para que possa consultar e gerir o acesso aos dados nessa base de dados utilizando o Azure Databricks e o Unity Catalog.
(Opcional) Clique em Testar conexão para confirmar se ela funciona.
Clique Criar catalog.
Na página do Access, os espaços de trabalho nos quais os usuários podem acessar o que você criou. Você pode selectTodos os espaços de trabalho têm acessoou clicar em Atribuir a espaços de trabalho, select os espaços de trabalho e, em seguida, clique em Atribuir.
Altere o Proprietário que poderá gerir o acesso a todos os objetos no catalog. Comece a digitar um principal na caixa de texto e clique no principal nos resultados.
Grant Privilégios no catalog. Clique Grant:
1. Especifique as Entidades que terão acesso aos objetos no catalog. Comece a digitar um principal na caixa de texto e clique no principal nos resultados.
2. Select as predefinições de privilégio para grant cada principal. Todos os usuários da conta recebem BROWSE por padrão.
  - Select Leitor de Dados no menu suspenso para definir grantread privilégios em objetos no catalog.
  - Select Editor de Dados a partir do menu suspenso para grantread e modify privilégios em objetos no catalog.
  - Manualmente select os privilégios para grant.
3. Clique em Grant.
Clique Avançar.
Na página de Metadados , especifique os pares de chave-valor de tags. Para obter mais informações, consulte Aplicar tags em objetos protegíveis do Unity Catalog.
(Opcional) Adicione um comentário.
Clique Salvar.

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL.

CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  host '<hostname>',
  port '<port>',
  sfWarehouse '<warehouse-name>',
  user '<user>',
  password '<password>'
);

Recomendamos que você use o Azure Databricks segredos em vez de cadeias de caracteres de texto sem formatação para values confidenciais como credentials. Por exemplo:

CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  host '<hostname>',
  port '<port>',
  sfWarehouse '<warehouse-name>',
  user secret ('<secret-scope>','<secret-key-user>'),
  password secret ('<secret-scope>','<secret-key-password>')
)

Para obter informações sobre como configurar segredos, consulte Gerenciamento de segredos.

Criar uma catalog estrangeira

Nota

Se você usar a interface do usuário para criar uma conexão com a fonte de dados, a criação de catalog estrangeira será incluída e você poderá ignorar esta etapa.

Um catalog externo espelha uma base de dados num sistema de dados externo para que possa consultar e gerir o acesso aos dados nessa base de dados utilizando o Azure Databricks e o Unity Catalog. Para criar um catalogexterno, utilize uma conexão com a fonte de dados que já foi definida.

Para criar um catalogexterno, você pode usar o Catalog Explorer ou o comando CREATE FOREIGN CATALOG SQL em um bloco de anotações do Azure Databricks ou no editor de consultas SQL.

Você também pode usar a API REST do Databricks ou a CLI do Databricks para criar um catalog. Consulte os comandos POST /api/2.1/unity-catalog/catalogs e Unity Catalog.

Permissões necessárias:CREATE CATALOG permissão no metastore e propriedade da conexão ou o CREATE FOREIGN CATALOG privilégio na conexão.

Catalog Explorer

No seu espaço de trabalho do Azure Databricks, clique Catalog para abrir o Catalog Explorer.
Na parte superior do painel Catalog, clique no ícone Adicionar ícone Adicionar e selectAdicionar um catalog no menu.

Como alternativa, na página Acesso rápido, clique no botão Catalogs e, em seguida, clique no botão Criar catalog.
Siga as instruções para criar catalogs estrangeiros no Criar catalogs.

SQL

Execute o seguinte comando SQL em um bloco de anotações ou editor de consultas SQL. Os itens entre parênteses são opcionais. Substitua o marcador de posição values:

<catalog-name>: Nome do catalog no Azure Databricks.
<connection-name>: O objeto de conexão que especifica a fonte de dados, o caminho e o acesso credentials.
<database-name>: Nome do banco de dados que você deseja espelhar como um catalog no Azure Databricks.

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
OPTIONS (database '<database-name>');

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

O campo database do catalog estrangeiro é mapeado para um banco de dados Snowflake identifier. Se a identifier do banco de dados Snowflake não diferenciar maiúsculas de minúsculas, o invólucro usado no catalog<database-name> estrangeiro será preservado. No entanto, se a identifier do banco de dados Snowflake diferenciar maiúsculas de minúsculas, você deverá envolver o catalog<database-name> estrangeiro entre aspas duplas para preservar o caso.

Por exemplo:

database é convertido em DATABASE
"database" é convertido em database
"database""" é convertido em database"

Para escapar de uma aspa dupla, use outra aspa dupla.
"database"" resulta em um erro porque a aspa dupla não é escapada corretamente.

Para obter mais informações, consulte os requisitos Identifier na documentação do Snowflake.

Pushdowns suportados

As seguintes flexões são suportadas:

Filtros
Projeções
Limit
Associações
Agregados (Average, Corr, CovPopulation, CovSample, Count, Max, Min, StddevPop, StddevSamp, Sum, VariancePop, VarianceSamp)
Funções (funções String, funções matemáticas, dados, funções de carimbo de data/hora e carimbo de data/hora e outras funções diversas, como Alias, Cast, SortOrder)
Funções do Windows (DenseRank, Rank, RowNumber)
Ordenar

Mapeamentos de tipo de dados

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

Tipo de floco de neve	Tipo de faísca
decimal, número, numérico	Tipo decimal
bigint, byteint, int, inteiro, smallint, tinyint	Tipo inteiro
flutuar, flutuar4, flutuar8	Tipo de flutuação
duplo, precisão dupla, real	Tipo Duplo
char, caractere, string, texto, tempo, varchar	StringType
binário	BinaryType
boolean	BooleanType
data	Tipo de Data
datetime, timestamp, timestamp_ltz, timestamp_ntz timestamp_tz	Tipo de carimbo de data/hora

Limitações do OAuth

A seguir estão as limitações de suporte do OAuth:

O ponto de extremidade OAuth do Snowflake deve ser acessível a partir de IPs do plano de controle Databricks. Consulte Saída do plano de controle do Azure Databricks. O Snowflake suporta a configuração de políticas de rede no nível de integração de segurança, o que permite uma diretiva de rede separada que permite a conectividade direta do plano de controle Databricks para o ponto de extremidade OAuth para autorização.
Não há suporte para as opções de configuração de configuração de função Proxy, host Proxy, porta proxy e Snowflake. Especifique a função Snowflake como parte do escopo OAuth.

Limitações da chave privada PEM

A seguir estão as limitações de suporte de chave privada do PEM:

O driver JDBC Snowflake não suporta autenticação com chaves privadas criptografadas. Para evitar erros, generate uma chave com -nocrypt opção adicionada, da seguinte forma:
```
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
```

Recursos adicionais

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

Partilhar via

Executar consultas federadas no Snowflake

Antes de começar

(Opcional) Criar uma integração de segurança no console do Snowflake

(Opcional) Solicitar um token de acesso OAuth

Criar uma conexão

Catalog Explorer

SQL

Criar uma catalog estrangeira

Catalog Explorer

SQL

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

Pushdowns suportados

Mapeamentos de tipo de dados

Limitações do OAuth

Limitações da chave privada PEM

Recursos adicionais

Comentários

Recursos adicionais