Habilitar a federação de catálogo do Lakehouse no Google Cloud

info

Beta

Este recurso está em Beta. Os administradores do Workspace podem controlar o acesso a este recurso na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

A federação de catálogo do Google Cloud Lakehouse permite que o Unity Catalog leia tabelas Iceberg do Google Cloud Lakehouse diretamente do armazenamento em cloud, o que pode proporcionar melhor desempenho e menor custo do que a federação de query.

Com a federação de catálogos, o Unity Catalog acessa diretamente a tabela Iceberg do Google Cloud lakehouse no Google Cloud Storage (GCS), e a query entra em execução inteiramente no compute do Databricks. Tabelas externas em um catálogo do Google Cloud Lakehouse são somente leitura.

A federação da Lakehouse no Google Cloud usa um tipo de conexão GOOGLE_CLOUD_LAKEHOUSE dedicado. Este é um tipo de conexão separado da federação de query do BigQuery.

Ao criar um foreign catalog, você especifica o caminho do warehouse do Google Cloud Lakehouse. O Unity Catalog descobre os namespaces e tabelas sob esse warehouse e os mapeia para o namespace de três níveis padrão do Unity Catalog:

Objeto Lakehouse do Google Cloud	Nome do Unity Catalog
warehouse	<foreign-catalog>
Namespace	<foreign-catalog>.<schema>
Tabela	<foreign-catalog>.<schema>.<table>

Objeto Lakehouse do Google Cloud	Nome do Unity Catalog
warehouse	<foreign-catalog>
Namespace	<foreign-catalog>.<schema>
Tabela	<foreign-catalog>.<schema>.<table>

Por exemplo, se você federar um warehouse com o namespace analytics contendo a tabela orders, a tabela aparecerá no Unity Catalog como <foreign-catalog>.analytics.orders.

Antes de começar

Revise os seguintes requisitos antes de configurar a federação de catálogo do Lakehouse no Google Cloud.

Requisitos do workspace:

• A federação do Lakehouse no Google Cloud é suportada apenas em Workspace do Databricks no Google Cloud.
• O Workspace deve estar habilitado para o Unity Catalog. Consulte Introdução ao Unity Catalog.
• Como este recurso está em versão Beta, um administrador do workspace deve ativá-lo na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

Requisitos de computação:

• O compute do Databricks deve usar o Databricks Runtime 19 ou acima.

  O Databricks Runtime 19 é um runtime unificado que recebe recursos como atualizações datadas em vez de novas versões secundárias. Consulte Databricks Runtime 19.

• SQL warehouses devem ser Pro ou Serverless.

• Clusters dedicados (anteriormente clusters de usuário único) não são suportados. Consulte Limitações.

Requisitos de rede:

• Se você aplicar controles de serviço de Virtual Private Cloud (VPC) Service Controls ou regras de firewall no Google Cloud, você deve incluir na lista de permissões os intervalos de IP de saída do Databricks para o plano de controle e o plano de dados. Consulte Recomendações de rede para a Lakehouse Federation.

Permissões necessárias:

• Para criar uma conexão, é preciso ser administrador de metastore ou usuário com o privilégio CREATE CONNECTION no metastore do Unity Catalog anexado ao espaço de trabalho.
• Para criar um foreign catalog, você deve ter a permissão CREATE CATALOG no metastore. Você também deve ser proprietário da conexão ou ter o privilégio CREATE FOREIGN CATALOG nela.
• Para inserir caminhos autorizados para o catálogo externo, você deve ter o privilégio CREATE FOREIGN SECURABLE em um local externo que cubra esses caminhos. O proprietário do local externo tem esse privilégio por default.

Cada seção baseada em tarefa que segue especifica requisitos de permissão adicionais.

O passo 1: configurar recursos do Google Cloud

Execute os seguintes passos no Google Cloud. Nenhuma ação no Databricks é necessária neste passo.

1. Crie um warehouse Google Cloud Lakehouse.

   Crie o warehouse e selecione ou crie um bucket GCS para dar suporte a ele. Por exemplo, um warehouse com suporte do bucket my-warehouse tem o caminho de warehouse gs://my-warehouse.

2. Crie tabelas Iceberg no warehouse.

   Use qualquer mecanismo compatível com Iceberg, como Spark, Flink ou BigQuery SQL. Verifique se as tabelas podem ser lidas a partir do BigQuery. Por exemplo:

   SQL

   SELECT * FROM `PROJECT_ID.NAMESPACE.TABLE`;

3. Crie duas account de serviço com privilégio mínimo.

   As IAM roles do Google Cloud Lakehouse usam o namespace biglake, portanto, as funções na tabela a seguir aparecem em BigLake no console do Google Cloud.

account de serviço	Propósito	IAM roles necessárias
account de serviço de conexão	Lê metadados do catálogo.	roles/biglake.viewer no projeto.
account de serviço de armazenamento	Lê dados de tabela no GCS.	roles/storage.objectViewer no bucket do GCS. Adicione roles/bigquery.dataViewer se as tabelas forem gerenciadas pelo BigQuery.

account de serviço	Propósito	IAM roles necessárias
account de serviço de conexão	Lê metadados do catálogo.	roles/biglake.viewer no projeto.
account de serviço de armazenamento	Lê dados de tabela no GCS.	roles/storage.objectViewer no bucket do GCS. Adicione roles/bigquery.dataViewer se as tabelas forem gerenciadas pelo BigQuery.

4. Gere uma key JSON para a account de serviço da conexão.

   No console do Google Cloud, gere e faça download de uma key JSON para a account de serviço de conexão. Você fornece esta key ao criar a conexão do Unity Catalog no o passo 2: Criar uma conexão. Armazene a key com segurança.

   Para obter instruções sobre como criar contas de serviço, atribuir IAM roles e gerar keys, consulte a documentação do Google Cloud IAM.

O passo 2: Criar uma conexão

A conexão especifica um caminho e as credenciais para acessar um sistema externo. Crie uma conexão usando o Catalog Explorer ou o comando CREATE CONNECTION do SQL em um Notebook do Databricks ou no editor de query do Databricks SQL.

nota

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

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

Catalog Explorer

1. No seu workspace do Databricks, clique em 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 de conexão do assistente Configurar conexão , insira um nome de conexão fácil de lembrar.
4. Selecione um Tipo de conexão de Google Cloud Lakehouse e, em seguida, clique em Próximo .
5. Na página Autenticação , insira o ID do projeto do Google Cloud e o JSON da key da account de serviço para a account de serviço de conexão que você criou no o passo 1: configurar recursos do Google Cloud.
6. (Opcional) Adicione um comentário.
7. Clique em Criar conexão .

SQL

Execute o seguinte comando em um notebook ou no editor de consultas SQL do Databricks. Substitua os valores temporários:

• <connection-name>: Nome para a conexão no Databricks.
• <gcp-project-id>: O ID do projeto do Google Cloud que contém o catálogo do Google Cloud Lakehouse.
• <secret-scope> e <secret-key>: O Secret Scope e a key que armazenam a JSON key da account de serviço de conexão.

SQL

CREATE CONNECTION <connection-name> TYPE GOOGLE_CLOUD_LAKEHOUSE
OPTIONS (
  gcp_project_id '<gcp-project-id>',
  service_account_json secret('<secret-scope>','<secret-key>')
);

O Databricks recomenda que você use segredos em vez de strings de texto simples para valores confidenciais, como a key da account de serviço. Para obter informações sobre como configurar segredos, consulte Gerenciamento de segredos.

O passo 3: Criar uma credencial de armazenamento e um local externo

Configure uma credencial de armazenamento e um local externo no Unity Catalog para reger o acesso aos buckets do GCS que contêm suas tabelas do Lakehouse no Google Cloud. Locais externos são objetos protegíveis do Unity Catalog que associam credenciais de armazenamento a caminhos de contêiner de armazenamento em cloud.

Você deve criar pelo menos o seguinte:

• Uma credencial e um local externo cobrindo a raiz de armazenamento de metadados do catálogo. Este local armazena metadados para as tabelas Iceberg no catálogo, portanto, a account de serviço gerenciada pelo Databricks deve ter acesso de leitura e gravação. Este pode ser qualquer bucket do GCS. Não precisa estar relacionado aos buckets de tabela. Você especifica essa localização como a opção storage_root ao criar o foreign catalog.
• Uma ou mais credenciais e locais externos que cobrem os locais de armazenamento da tabela. Estes podem ser somente leitura.

Para criar uma credencial de armazenamento e um local externo, use o Catalog Explorer ou SQL. Por exemplo, para criar um local externo usando SQL:

SQL

CREATE EXTERNAL LOCATION <name>
URL 'gs://<bucket-path>'
WITH (STORAGE CREDENTIAL <gcp-storage-credential>);

Para instruções detalhadas, consulte Conectar a uma external location do Google Cloud Storage (GCS).

O passo 4: Criar um catálogo externo

Um foreign catalog espelha seu catálogo do lakehouse no Google Cloud para que você possa query e gerenciar o acesso às suas tabelas usando Databricks e Unity Catalog. Para criar um foreign catalog, use a conexão que você criou no O passo 2: Criar uma conexão.

Crie um catálogo externo usando o Catalog Explorer ou o comando SQL CREATE FOREIGN CATALOG em um Notebook do Databricks ou no editor de query Databricks SQL.

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

Catalog Explorer

1. No seu workspace do Databricks, clique em Catálogo para abrir o Catalog Explorer.

2. Na parte superior do painel Catálogo , clique no ícone Adicionar e selecione Adicionar um catálogo no menu.

3. Insira um Nome do catálogo e selecione um Tipo de catálogo externo .

4. Selecione a Connection que você criou na Etapa 2: Criar uma conexão no menu suspenso.

5. Para Warehouse , insira o caminho do warehouse do Google Cloud Lakehouse a ser federado. Use um caminho gs:// para um warehouse do Cloud Storage ou um caminho bq:// para um warehouse do BigQuery.

6. Para Caminhos autorizados , insira os caminhos de armazenamento em cloud que podem ser acessados através do catálogo. Apenas as tabelas sob estes caminhos podem ser consultadas através do catálogo externo. Os caminhos devem ser cobertos por locais externos. Consulte O que são caminhos autorizados?.

   É possível editar caminhos autorizados após a criação do catálogo.

7. No campo Storage location , especifique o local GCS gravável que armazena metadados para as tabelas Iceberg neste catálogo.

8. Clique em Criar catálogo .

9. Atribua acesso ao workspace, um proprietário e privilégios conforme solicitado.

SQL

Execute o seguinte comando em um notebook ou no editor de consultas SQL do Databricks. Os itens entre colchetes são opcionais. Substitua os valores temporários:

• <catalog-name>: Nome para o catálogo no Databricks.
• <connection-name>: O nome da conexão que você criou na o passo 2: Criar uma conexão.
• <warehouse-path>: O caminho do warehouse do Lakehouse no Google Cloud. Use um caminho gs:// para um warehouse de Cloud Storage ou um caminho bq:// para um warehouse do BigQuery.
• <path1>,<path2>: Caminhos de armazenamento em cloud que podem ser acessados através do catálogo. Os caminhos devem ser cobertos por locais externos. Consulte O que são caminhos autorizados?.
• <storage-location>: um local gravável no GCS onde os metadados do catálogo são armazenados.

SQL

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name>
USING CONNECTION <connection-name>
OPTIONS (
  warehouse '<warehouse-path>',
  authorized_paths '<path1>,<path2>',
  storage_root '<storage-location>'
);

O Unity Catalog descobre todos os namespaces e tabelas sob o catálogo:

• Os namespaces do Google Cloud Lakehouse tornam-se esquemas do Unity Catalog.
• As tabelas Iceberg da Lakehouse no Google Cloud tornam-se tabelas estrangeiras do Unity Catalog.

Conceder permissões e query o catálogo

Após configurar a federação de catálogo, os usuários devem ter as permissões apropriadas do Unity Catalog para acessar tabelas federadas:

• Todos os usuários precisam das permissões USE CATALOG e USE SCHEMA no catálogo e no esquema, respectivamente.
• Para ler de uma tabela federada, os usuários precisam da permissão SELECT.

Para mais informações sobre privilégios do Unity Catalog e como concedê-los, consulte Gerenciar privilégios no Unity Catalog.

Após conceder as permissões, os usuários podem fazer query nas tabelas externas a partir do Databricks:

SQL

SELECT * FROM <catalog-name>.<schema>.<table>;

Controle de acesso baseado em atributos e refinado

Tabelas externas oferecem suporte ao controle de acesso baseado em atributos (ABAC) e ao controle de acesso refinado (FGAC). Adicione tags usando o Explorador de Catálogos ou o comando ALTER TABLE ... SET TAGS. Consulte Aplicar tags a objetos protegidos do Unity Catalog.

Limitações

A federação de catálogo do Google Cloud Lakehouse tem as seguintes limitações:

• Os nomes de esquemas e tabelas seguem as limitações de nomenclatura padrão do Unity Catalog. O Databricks não oferece suporte a nomes que contenham ponto (.), espaço () ou barra (/).
• Tabelas externas em um catálogo do Google Cloud Lakehouse são somente leitura.
• Tabelas que contêm uma coluna com o tipo TIME não são suportadas.
• Os buckets do GCS devem ser de região única. Buckets multirregião e de região dupla não são suportados.
• Clusters dedicados (anteriormente clusters de usuário único) não são suportados.

Consulte Limitações para limitações relacionadas ao Iceberg.

Solução de problemas

A seção a seguir descreve erros comuns e suas resoluções.

Catalog not found ou Failed to load catalog

Causas comuns:

• A opção warehouse não corresponde a um caminho de warehouse do Lakehouse do Google Cloud no projeto do Google Cloud.
• A account de serviço da conexão não possui a função roles/biglake.viewer no projeto.

403 Forbidden ao ler dados da tabela

Causas comuns:

• A account de serviço de armazenamento não possui a função roles/storage.objectViewer no bucket do GCS.
• Se as tabelas forem gerenciadas pelo BigQuery, a account de serviço de armazenamento também não possui a função roles/bigquery.dataViewer.

DBR version not supported

O compute está em uma versão do Databricks Runtime abaixo do mínimo suportado. Use o Databricks Runtime 19 ou acima. Consulte Antes de começar.

Os esquemas aparecem, mas as tabelas não

Verifique se um local externo cobre o caminho de armazenamento onde as tabelas residem e se a opção authorized_paths cobre todos os caminhos de bucket que as tabelas realmente usam. Consulte O passo 3: Criar uma credencial de armazenamento e um local externo.

Authentication failed ao criar a conexão

O JSON da key da account de serviço não é válido ou expirou, ou a account de serviço não possui a função roles/biglake.viewer. Regenere a key no console do Google Cloud e confirme as funções da account de serviço. Consulte o passo 1: configurar recursos do Google Cloud.