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.

Antes de começar​

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:

  • Conectividade de rede do seu recurso de compute para os sistemas de banco de dados de destino. Consulte Recomendações de rede para a Lakehouse Federation.
  • 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.

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 da URL no JSON da conta de serviço, e eles podem variar por account. Use-os exatamente como aparecem em seu arquivo JSON baixado. 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.

  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, INTERVAL, 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, INTERVAL, 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.

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