Pular para o conteúdo principal
Última atualização em

execução de consultas federadas no Google BigQuery

Esta página descreve como configurar o lakehouse Federation para execução de consultas federadas em dados do BigQuery que não são gerenciados pelo Databricks. Para saber mais sobre a Federação Lakehouse, consulte Conecte-se a bancos de dados externos e catálogos

Para conectar-se ao seu banco de dados BigQuery usando o Lakehouse Federation, você deve criar o seguinte no seu metastore do Databricks Unity Catalog (os espaços de trabalho criados após 6 de março de 2024 já possuem um provisionamento automático de metastore Unity Catalog ):

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

Requisitos​

Para executar consultas federadas no BigQuery, crie uma conexão com BigQuery e um catálogo externo que espelhe seu banco de dados BigQuery . Em seguida, você pode consultar e gerenciar o uso de dados BigQuery Databricks e Unity Catalog. Requisitos adicionais de permissão são especificados em cada seção baseada em tarefas que se segue.

Requisitos do workspace:

  • Espaço de trabalho preparado para o Catálogo do Unity.

Requisitos de computação:

  • Network connectivity from your compute resource to the required Google endpoints. See Required endpoints and connectivity checks.
  • O compute do Databricks deve usar o Databricks Runtime 16.1 ou acima e o modo de acesso standard ou dedicated (anteriormente compartilhado e de usuário único).
  • SQL warehouses devem ser Pro ou Serverless.

Requisitos de autorização:

  • Para criar uma conexão, você deve ter o privilégio CREATE CONNECTION no metastore Unity Catalog anexado ao workspace.
  • Para criar um catálogo externo é preciso ter a permissão CREATE CATALOG no metastore e ser proprietário da conexão ou ter o privilégio CREATE FOREIGN CATALOG na conexão.

Endpoints necessários e verificações de conectividade​

Your Databricks compute connects directly to Google APIs over HTTPS. BigQuery authenticates with a Google serviço account key, so the connector obtains and refreshes access tokens from the compute plane rather than the Databricks control plane. Allowlisting compute egress to the endpoints abaixo is therefore sufficient. If your compute has outbound network restrictions, allow these endpoints and confirm that compute can reach them before you create a connection or catalog.

Required endpoints​

Permita a saída HTTPS (porta 443) do seu compute do Databricks para os seguintes endpoints do Google:

  • bigquery.googleapis.com: BigQuery REST API, used for metadata operações and the Test connection check.
  • bigquerystorage.googleapis.com: BigQuery Storage API. O conector lê dados de tabela por meio da Storage API no Databricks Runtime 16.1 e acima, portanto, este endpoint é necessário para que as queries federadas retornem dados. Consulte Materialization.
  • oauth2.googleapis.com and accounts.google.com: Google authentication endpoints used to authenticate the connection's service account. These are the hosts in the token_uri and auth_uri fields of the serviço account JSON. Your values might differ, so allow the hosts that appear in your downloaded file. See the authentication note in Create a connection.

If your compute uses a custom DNS server, make sure it can resolve each of these hostnames. On networks that route Google traffic through a restricted virtual IP, confirm that your *.googleapis.com configuration covers the googleapis.com Endpoint and that accounts.google.com also resolves.

nota

The Test connection check exercises the BigQuery REST API and the authentication endpoints, but it doesn't read data through the Storage API. A passing test doesn't confirm that bigquerystorage.googleapis.com is reachable, which federated queries require on Databricks Runtime 16.1 and above. Use the connectivity check abaixo to validate every endpoint.

Validate connectivity from compute​

Antes de criar uma conexão, confirme se o seu compute pode alcançar cada endpoint necessário. Execute a seguinte verificação a partir de um notebook anexado a um cluster todo-propósito que usa a mesma configuração de rede do compute do qual você planeja fazer a federação.

Um teste bem-sucedido confirma a acessibilidade apenas para o compute clássico que compartilha esse caminho de rede, como clusters todo-propósito, clusters de Jobs e SQL Warehouse pro. Os SQL warehouses serverless alcançam o Google por um caminho de saída serverless separado, portanto, um teste de cluster bem-sucedido não confirma a conectividade serverless. Para controlar e verificar a saída serverless, consulte O que é controle de saída serverless?.

  1. Anexe um notebook a um cluster que use a configuração de rede de destino.

  2. Execute o seguinte shell comando para testar a acessibilidade de cada endpoint:

    Bash
    %sh
    for host in bigquery.googleapis.com bigquerystorage.googleapis.com oauth2.googleapis.com accounts.google.com; do
      nc -zv "$host" 443
    done

  3. Confirm that each host reports a successful connection. A failure or timeout for any host means outbound traffic to that endpoint is blocked, or DNS resolution is failing on your compute.

Crie uma conexão​

A conexão especifica um caminho e as credenciais 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 do SQL em um Notebook do Databricks ou no editor de consultas SQL do Databricks.

nota

O senhor também pode usar a API REST da Databricks ou a CLI da Databricks para criar uma conexão. Veja POST /api/2.1/unity-catalog/connections e Unity Catalog comando.

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

  1. Em seu site Databricks workspace, clique em Ícone de dados. Catalog .

  2. Na parte superior do painel Catálogo , clique em Ícone de adicionar ou ícone de mais Adicione o ícone e selecione "Criar uma conexão" no menu.

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

  4. Selecione um tipo de conexão do Google BigQuery e clique em Next (Avançar ).

  5. Na página Authentication (Autenticação ), digite o serviço do Google account key JSONpara sua instância BigQuery.

    Esse é um objeto JSON bruto usado para especificar o projeto BigQuery e fornecer autenticação. O senhor pode gerar esse objeto JSON e download a partir da página de detalhes do serviço account no Google Cloud em "key". O serviço account deve ter as permissões adequadas concedidas em BigQuery, incluindo BigQuery User e BigQuery Data Viewer . Veja a seguir um exemplo.

    JSON
    {
      "type": "service_account",
      "project_id": "PROJECT_ID",
      "private_key_id": "KEY_ID",
      "private_key": "PRIVATE_KEY",
      "client_email": "SERVICE_ACCOUNT_EMAIL",
      "client_id": "CLIENT_ID",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "token_uri": "https://oauth2.googleapis.com/token",
      "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
      "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/SERVICE_ACCOUNT_EMAIL",
      "universe_domain": "googleapis.com"
    }
nota

O Google define os valores de URL no JSON da conta de serviço, e eles podem variar por account. Use-os exatamente como aparecem no seu arquivo JSON download. Se você configurar regras de proxy de rede para o Databricks alcançar as APIs do Google, permita tanto https://accounts.google.com quanto https://oauth2.googleapis.com. Para ver a lista completa de Endpoint do Google necessários e como validar a conectividade a partir do compute, consulte Endpoint necessários e verificações de conectividade.

  1. (Opcional) Insira o ID do projeto para sua instância do BigQuery:

    Esse é um nome para o projeto BigQuery usado para o faturamento de todas as consultas executadas sob essa conexão. padrão para o ID do projeto de seu serviço account. O serviço account deve ter as permissões adequadas concedidas para esse projeto em BigQuery, incluindo o usuárioBigQuery . dataset adicionais usados para armazenar tabelas temporárias por BigQuery podem ser criados neste projeto.

  2. (Opcional) Adicione um comentário.

  3. Clique em Criar conexão .

  4. Na página Noções básicas do catálogo , insira um nome para o catálogo estrangeiro. Um catálogo externo espelha um banco de dados em um sistema de dados externo para que o senhor possa consultar e gerenciar o acesso aos dados desse banco de dados usando o Databricks e o Unity Catalog.

  5. (Opcional) Clique em Testar conexão para confirmar se está funcionando.

  6. Clique em Criar catálogo .

  7. Na página Access (Acesso) , selecione o espaço de trabalho no qual os usuários podem acessar o catálogo que o senhor criou. O senhor pode selecionar All workspace have access (Todos os espaços de trabalho têm acesso ) ou clicar em Assign to workspace (Atribuir ao espaço de trabalho), selecionar o espaço de trabalho e clicar em Assign (Atribuir ).

  8. Altere o proprietário que poderá gerenciar o acesso a todos os objetos no catálogo. começar a digitar um diretor na caixa de texto e, em seguida, clicar no diretor nos resultados retornados.

  9. Conceda privilégios no catálogo. Clique em Conceder :

    1. Especifique os diretores que terão acesso aos objetos no catálogo. começar a digitar um diretor na caixa de texto e, em seguida, clicar no diretor nos resultados retornados.

    2. Selecione as predefinições de privilégios a serem concedidas a cada diretor. Todos os usuários de account recebem BROWSE por default.

      • 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 os privilégios read e modify aos objetos no catálogo.
      • Selecione manualmente os privilégios a serem concedidos.

    3. Clique em Conceder .

  10. Clique em Avançar .

  11. Na página Metadata (Metadados ), especifique as tags em key-value. Para obter mais informações, consulte Apply tags to Unity Catalog securable objects.

  12. (Opcional) Adicione um comentário.

  13. Clique em Salvar .

Crie um catálogo estrangeiro​

nota

Se o senhor usar a interface do usuário para criar uma conexão com a fonte de dados, a criação do catálogo externo estará incluída e o senhor poderá ignorar essa etapa.

Um catálogo externo espelha um banco de dados em um sistema de dados externo para que o senhor possa consultar e gerenciar o acesso aos dados desse banco de dados usando o Databricks e o Unity Catalog. Para criar um catálogo externo, use uma conexão com a fonte de dados que já foi definida.

Para criar um catálogo externo, o senhor pode usar o Catalog Explorer ou CREATE FOREIGN CATALOG em um Notebook Databricks ou o editor de consultas Databricks SQL. O senhor também pode usar a API REST da Databricks ou a CLI da Databricks para criar um catálogo. Veja POST /api/2.1/unity-catalog/catalogs ou Unity Catalog comando.

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.

  1. Em seu site Databricks workspace, clique em Ícone de dados. Catalog para abrir o Catalog Explorer.

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

    Como alternativa, na página de acesso rápido , clique no botão Catálogos e no botão Criar catálogo .

  3. (Opcional) Insira a seguinte propriedade do catálogo:

    ID do projeto de dados : Um nome para o projeto do BigQuery que contém dados que serão mapeados para esse catálogo. padrão para o ID do projeto de faturamento definido no nível da conexão.

  4. Siga as instruções para criar catálogos estrangeiros em Criar catálogos.

  5. (Opcional) Especifique as seguintes opções de catálogo:

    • Materialization Dataset: Um nome de conjunto de dados opcional do BigQuery a ser usado para materializar os resultados da consulta. Caso não seja especificado, um conjunto de dados de materialização é provisionado automaticamente quando necessário. Veja Materialização para mais informações.
    • Force materialization: Indica se os resultados de cada query ao catálogo devem ser exibidos. O default é false. Consulte a seção Materialização para obter mais informações.
    • BIGNUMERIC Default Scale: Um valor de escala opcional para mapear BigQuery BIGNUMERIC para Spark DecimalType. Consulte Mapeamentos de tipos de dados para obter mais informações.

Materialização​

Ao contrário de outros conectores de federação, o conector do BigQuery usa a API BigQuery Storage em vez de JDBC para desempenho aprimorado. O Databricks pode ler do BigQuery diretamente do armazenamento ou usando um dataset materializado. Leituras diretas oferecem melhor desempenho para grandes varreduras e suportam pushdowns de filtro e projeção. A materialização envia operações adicionais (limite, agregações, joins, classificação) para o compute do BigQuery antes de transmitir os resultados para o Databricks.

As visualizações e tabelas externas são sempre materializadas. Todas as outras leituras usam armazenamento direto sem materialização por default.

Considere habilitar a materialização se precisar de pushdowns avançados, estiver lendo conjuntos de resultados pequenos de conjuntos de dados grandes ou estiver lendo dados entre regiões diferentes. A materialização acarreta custos adicionais de compute do BigQuery.

Para forçar a materialização de cada query em um catálogo externo, selecione Force materialization no Explorador de Catálogos ou defina a opção de catálogo forceMaterialization como true. Você não precisa atualizar query individuais.

A opção de catálogo forceMaterialization é compatível com o compute necessário, exceto que os clusters devem executar o Databricks Runtime 16.4 LTS ou acima.

Para habilitar a materialização para uma única query, defina a opção materializationEnabled como true após o nome da tabela do BigQuery:

SQL
SELECT * FROM <catalog-name>.<schema-name>.<table-name>
WITH ('materializationEnabled' 'true');

Por default, um conjunto de dados de materialização é provisionado automaticamente quando necessário. Você pode especificar um conjunto de dados personalizado usando a opção de catálogo materializationDataset ao criar ou alterar o catálogo estrangeiro. Isso é útil se a account de serviço não tiver permissões para criar conjuntos de dados ou se você quiser controlar onde as tabelas de materialização temporárias são armazenadas. Por exemplo:

SQL
CREATE FOREIGN CATALOG my_catalog USING CONNECTION my_bq_connection
OPTIONS (materializationDataset 'my_materialization_dataset');

Para atualizar um catálogo existente, execute:

SQL
ALTER CATALOG my_catalog OPTIONS (materializationDataset 'my_materialization_dataset');

Ler tabelas externas do BigQuery​

Você pode consultar tabelas externas BigQuery , incluindo tabelas com suporte do BigLake e do armazenamento cloud , diretamente do seu fluxo de trabalho. Essas tabelas são materializadas automaticamente antes da execução da consulta, permitindo acesso total ao seu conteúdo sem configuração adicional.

Tabelas externas suportadas​

O BigLake e tabelas externas de armazenamento cloud são compatíveis.

  • As tabelas BigLake fazem referência a dados armazenados no armazenamento cloud e incluem gerenciamento de controle de acesso granular por meio BigQuery.
  • As tabelas externas do armazenamento em nuvem fazem referência a arquivos diretamente usando URIs.

Ao consultar essas tabelas, o sistema materializa os dados para que a execução da sua consulta seja feita no armazenamento integrado BigQuery , oferecendo suporte completo a recursos SQL e desempenho ideal.

Para obter mais informações, consulte a documentação BigQuery para tabelas BigLake e tabelas externas do Cloud Storage.

Pushdowns suportados​

O suporte ao pushdown depende de a materialização estar ativada ou não. Algumas operações são enviadas automaticamente para BigQuery compute , enquanto outras requerem materialização.

Os seguintes pushdowns são suportados sem materialização:

  • Filtros, aplicados como restrições de linha da API do BigQuery Storage (somente predicados simples — comparações coluna-para-literal, IN, IS NULL, LIKE e combinações AND ou OR desses). Filtros que fazem referência aos operadores ou funções listados abaixo exigem materialização.
  • Projeções

Os seguintes processamentos adicionais são suportados com a materialização ativada. Com a materialização, os filtros são compilados para SQL em vez de restrições de linha da API BigQuery Storage, para que possam conter adicionalmente os seguintes operadores e funções:

  • Limite
  • Offset, quando usado com limite
  • Agregados
  • Classificação, quando usada com limite
  • join (Databricks Runtime 16.1 ou acima)
  • Operadores de comparação, Boolean, bit a bit e aritméticos (operadores aritméticos só são processados quando o modo ANSI está ativado)
  • Funções matemáticas (ABS, FLOOR) — suporte parcial, somente expressões de filtro
  • Funções de strings (CONCAT, UPPER, LOWER, LENGTH, TRIM, LTRIM, RTRIM) — suporte parcial, apenas expressões de filtro
  • Contains, Startswith, Endswith
  • Funções de data, hora e timestamp (DATE_TRUNC e EXTRACT para ano, trimestre, mês, dia, hora e minuto) — suporte parcial, apenas expressões de filtro
  • Funções diversas (COALESCE, Cast, CASE WHEN, IF, e acesso a elementos de array) — suporte parcial, apenas expressões de filtro

Os seguintes pushdowns não são suportados:

  • Funções da janela

Mapeamentos de tipos de dados​

A tabela a seguir mostra o mapeamento do tipo de dados do BigQuery para o Spark.

Tipo de BigQuery

Spark tipo

BIGNUMERIC, NUMERIC

DecimalType*

INT64

LongType

FLOAT64

DoubleType

ARRAY, GEOGRAPHY, JSON, STRING, STRUCT

VarcharType

BYTES

BinaryType

BOOL

BooleanType

DATE

DateType

DATETIME

TimestampNTZType, exceto StringType no Databricks Runtime 16.4 a 17.x**

TIME, TIMESTAMP

TimestampType/TimestampNTZType

Qualquer tipo com modo REPEATED

ArrayType do tipo Spark correspondente

Tipo de BigQuery

Spark tipo

BIGNUMERIC, NUMERIC

DecimalType*

INT64

LongType

FLOAT64

DoubleType

ARRAY, GEOGRAPHY, JSON, STRING, STRUCT

VarcharType

BYTES

BinaryType

BOOL

BooleanType

DATE

DateType

DATETIME

TimestampNTZType, exceto StringType no Databricks Runtime 16.4 a 17.x**

TIME, TIMESTAMP

TimestampType/TimestampNTZType

Qualquer tipo com modo REPEATED

ArrayType do tipo Spark correspondente

* O BigQuery BIGNUMERIC tem uma precisão de até 76 dígitos, o que excede a precisão máxima do Spark DecimalType de 38. Por default, BIGNUMERIC corresponde a DecimalType(38, 38). Para configurar a escala, use a opção de catálogo bigNumericDefaultScale . Os valores permitidos são [0, 38]. Por exemplo, bigNumericDefaultScale = '10' mapeia BIGNUMERIC para DecimalType(38, 10). BigQuery NUMERIC mapeia para sua precisão e escala declaradas.

O conector começou a usar a API BigQuery Storage no Databricks Runtime 16.4. Do Databricks Runtime 16.4 a 17.x, a API Storage mapeava o BigQuery DATETIME para o Spark StringType em vez de TimestampNTZType. O Databricks Runtime 18.0 restaura o mapeamento TimestampNTZType.

No BigQuery, uma coluna com o modo REPEATED é mapeada para um ArrayType do Spark contendo o tipo Spark correspondente. Por exemplo, uma coluna REPEATED STRING do BigQuery é mapeada para ArrayType(VarcharType), e uma coluna REPEATED INT64 do BigQuery é mapeada para ArrayType(LongType).

Quando o senhor lê em BigQuery, BigQuery Timestamp é mapeado para Spark TimestampType se preferTimestampNTZ = false (default). BigQuery Timestamp é mapeado para TimestampNTZType se preferTimestampNTZ = true.

nota

Colunas INTERVAL do BigQuery não são suportadas no momento. Uma tabela estrangeira que contém uma coluna INTERVAL falha quando seu esquema é carregado, portanto, você não pode descrever, query ou ingerir a tabela. Tabelas sem uma coluna INTERVAL não são afetadas.

Solução de problemas​

A seção a seguir descreve um erro comum e sua solução ao usar o conector BigQuery.

Error creating destination table using the following query [<query>]​

Causa comum: a account de serviço usada pela conexão não tem a função de usuárioBigQuery .

Resolução:

  1. Conceda a função de usuárioBigQuery à account serviço usada pela conexão. Esta função é necessária para criar o dataset de materialização que armazena temporariamente os resultados da consulta.
  2. Reexecução da consulta.
Nesta página