Acessar o BigQuery no AlloyDB

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Nesta página, descrevemos como usar a federação do Lakehouse para acessar dados armazenados ou acessíveis usando o BigQuery em uma Interface PostgreSQL do AlloyDB.

O wrapper de dados externos oferece suporte a uma ampla variedade de recursos do BigQuery, o que permite consultar o seguinte:

• Tabelas nativas e visualizações materializadas
• Visualizações do BigQuery(visualizações lógicas)
• Tabelas externas do BigLake, incluindo aquelas para tabelas gerenciadas do Apache Iceberg
• Tabelas externas padrão

Ao usar essa integração, você pode tratar os conjuntos de dados do BigQuery como tabelas locais no ambiente do PostgreSQL para realizar análises entre mecanismos. Para mais informações, consulte a visão geral da federação do Lakehouse no AlloyDB.

Esta página pressupõe que você tenha um cluster e uma instância principal do AlloyDB, além de um conjunto de dados e tabelas do BigQuery. Para mais informações, consulte Criar conjuntos de dados e Criar e usar tabelas.

Antes de começar

Observação: se você usar o Google Cloud console para conectar tabelas do BigQuery, o console vai ativar automaticamente as APIs necessárias e conceder as permissões necessárias à conta de serviço do cluster.

1. Verifique se o bigquery_fdw.enabled flag está configurado na instância do AlloyDB para PostgreSQL.
2. Familiarize-se com os tipos de dados e mapeamentos de colunas do BigQuery compatíveis.
Faça login na sua Google Cloud conta do. Se você não conhece o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the AlloyDB, Compute Engine, Resource Manager, and BigQuery APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

3. Ative as APIs do Cloud necessárias para criar e se conectar ao AlloyDB para PostgreSQL.

   Ativar as APIs

4. Na etapa Confirmar projeto, clique em Avançar para confirmar o nome do projeto no qual você vai fazer alterações.

5. Na etapa Ativar APIs, clique em Ativar para ativar o seguinte:

   • API AlloyDB
   • API Compute Engine
   • API Resource Manager
   • API Service Networking
   • API BigQuery Storage
   • API BigQuery

   A API Service Networking é necessária se você planeja configurar conectividade de rede com o AlloyDB usando uma rede VPC que reside no mesmo Google Cloud projeto do AlloyDB.

   As APIs Compute Engine e API Resource Manager são necessárias se você planeja configurar a conectividade de rede com o AlloyDB usando uma rede VPC que reside em um projeto diferente Google Cloud

Funções exigidas

Para conceder acesso de leitura ao conjunto de dados do BigQuery à conta de serviço do cluster do AlloyDB, você precisa das seguintes permissões. Para mais informações, consulte Conceder acesso do AlloyDB ao conjunto de dados do BigQuery.

• Leitor de dados do BigQuery (roles/bigquery.dataViewer) ou qualquer função personalizada com permissões bigquery.tables.get e bigquery.tables.getData. Quando concedida em uma tabela ou visualização, essa função fornece permissões para ler dados e metadados da tabela ou visualização.
• Usuário de sessão de leitura do BigQuery (roles/bigquery.readSessionUser) ou qualquer função personalizada com permissões bigquery.readsessions.create e bigquery.readsessions.getData. Permite criar e usar sessões de leitura.
• Usuário de jobs do BigQuery (roles/bigquery.jobUser) ou qualquer função personalizada com permissões bigquery.jobs.create. Concede permissões para executar jobs, incluindo consultas, no projeto usando a API BigQuery. Essa função só pode ser concedida em recursos do Resource Manager (projetos, pastas e organizações).
• Leitor de objetos do Storage (roles/storage.objectViewer) ou qualquer função personalizada com permissões storage.objects.get. Concede permissões para acessar tabelas externas do BigQuery. Precisa ser concedido no nível do projeto ou do bucket.

Conceder acesso do AlloyDB ao conjunto de dados do BigQuery

Depois que o recurso de federação do Lakehouse for ativado no cluster do AlloyDB, você precisará conceder acesso da conta de serviço do cluster do AlloyDB ao conjunto de dados do BigQuery.

O Google Cloud console concede automaticamente as permissões necessárias à conta de serviço do cluster quando você conecta uma tabela do BigQuery usando o AlloyDB Studio.

Para conceder acesso usando a CLI gcloud, siga estas etapas:

gcloud

Para usar a CLI gcloud, você pode instalar e inicializar a Google Cloud CLI ou usar o Cloud Shell.

1. Abra a CLI gcloud. Se você não tiver a CLI gcloud instalada, instale e inicialize a CLI gcloud ou use o Cloud Shell.

2. Execute o gcloud beta alloydb clusters describe comando:

   gcloud beta alloydb clusters describe CLUSTER --region=REGION

   Substitua:

   • CLUSTER: o ID do cluster do AlloyDB.
   • REGION: o local do cluster do AlloyDB, por exemplo, asia-east1, us-east1. Consulte a lista completa de regiões em Gerenciar locais de instâncias.

   A saída contém um campo serviceAccountEmail, que é a conta de serviço desse cluster. Você também pode encontrar a conta de serviço na página Visão geral do cluster.

3. Conceder as permissões necessárias. Para mais informações, consulte Controlar o acesso a recursos com o IAM.

   Se a conta de serviço do cluster não tiver as permissões necessárias, os seguintes erros vão aparecer quando uma consulta for executada na tabela do BigQuery:

   • The user does not have bigquery.readsessions.create permissions
   • Permission bigquery.tables.get denied on table
   • Permission bigquery.tables.getData denied on table
   Observação: Se bigquery.readsessions.getData não for fornecido, resultados vazios serão retornados sem um erro.

Configurar a extensão

Para configurar a extensão, siga estas etapas:

Console

1. Acesse a página Clusters.

   Acessar Clusters

2. Clique no ID do cluster que você quer usar.

3. No menu de navegação, clique em AlloyDB Studio.

4. Faça login no banco de dados.

5. No painel Explorer, expanda o esquema relevante.

6. Clique no menu Ações ao lado de Tabelas do BigQuery e clique em Conectar tabela do BigQuery.

7. No painel Conectar tabela do BigQuery , escolha um projeto de origem, um conjunto de dados de origem e uma tabela.

8. A tabela Revisar e selecionar colunas mostra as colunas da tabela selecionada. Selecione as colunas que você quer mapear.

9. No campo Nome da tabela, insira um nome para a tabela externa.

10. Opcional: clique em Visualizar comando SQL para conferir o comando gerado.

11. Clique em Conectar tabela. Uma caixa de diálogo mostra o progresso. Depois que o processo for concluído, você poderá consultar a tabela como qualquer outra no AlloyDB.

psql

1. Crie a extensão.

   1. Conecte-se à instância do AlloyDB usando o cliente psql seguindo as instruções em Conectar um cliente psql a uma instância. Ou você pode usar o AlloyDB Studio. Para mais informações, consulte Gerenciar seus dados usando o Google Cloud console.

   2. Execute este comando:

      CREATE EXTENSION bigquery_fdw;
      

      Observação: é necessário criar essa extensão em todos os bancos de dados em que os conjuntos de dados do BigQuery precisam ser acessados.

2. Crie um servidor externo para definir os parâmetros de conexão do conjunto de dados remoto do BigQuery.

   CREATE SERVER BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw;
   

   Substitua:

   • BIGQUERY_SERVER_NAME: identificador exclusivo do servidor externo. Defina isso uma vez em um determinado banco de dados. Você pode substituir BIGQUERY_SERVER_NAME pelo nome do servidor.

3. Crie o mapeamento de usuários executando o CREATE USER MAPPING comando, que mapeia um usuário local do PostgreSQL que você quer conectar ao servidor externo.

   CREATE USER MAPPING FOR USERNAME SERVER BIGQUERY_SERVER_NAME ;
   

   Substitua:

   • USERNAME: um nome de usuário do banco de dados ou um usuário do IAM que acessa a tabela externa.
   • BIGQUERY_SERVER_NAME: identificador exclusivo do servidor externo que você criou.

4. Defina tabelas externas que correspondam às tabelas que você quer acessar no BigQuery usando o comando CREATE FOREIGN TABLE. Esse comando permite definir a estrutura de uma tabela remota. A tabela externa pode ter todas ou um subconjunto das colunas na tabela de origem no BigQuery.

   Observação: verifique se o tipo de dados que você está usando é mapeado para os tipos de dados compatíveis. Para mais informações, consulte Tipos de dados e mapeamentos de colunas do BigQuery compatíveis.

   CREATE FOREIGN TABLE TABLENAME (
   COLUMN1_NAME DATA_TYPE,
   COLUMN2_NAME DATA_TYPE,
   ... ) SERVER BIGQUERY_SERVER_NAME OPTIONS (project BIGQUERY_PROJECT_ID,
   dataset BIGQUERY_DATASET_NAME,
   table BIGQUERY_TABLE_NAME
   [, mode EXECUTION_MODE]);
   

   Substitua:

   • TABLENAME: o nome da tabela externa no banco de dados local do AlloyDB.
   • COLUMNX_NAME: o nome da coluna do AlloyDB. O nome da coluna precisa corresponder exatamente ao nome da coluna correspondente na tabela de origem do BigQuery. X indica que a tabela pode ser criada com várias colunas. O nome também precisa corresponder ao caso exato da coluna do BigQuery. Se o nome da coluna do BigQuery contiver letras maiúsculas (por exemplo, employeeID), o identificador do AlloyDB precisará estar entre aspas duplas (por exemplo, "employeeID") para preservar letras mistas ou maiúsculas.
   • DATA_TYPE: o tipo de dados da coluna.
   • BIGQUERY_SERVER_NAME: identificador exclusivo do servidor externo que você criou.
   • BIGQUERY_PROJECT_ID: ID do projeto em que o conjunto de dados do BigQuery reside.
   • BIGQUERY_DATASET_NAME: nome do conjunto de dados do BigQuery para a tabela.
   • BIGQUERY_TABLE_NAME: nome da tabela do BigQuery.
   • EXECUTION_MODE: opcional. A opção mode pode ser query para usar a API BigQuery para consultas complexas, storage para usar a API BigQuery Storage para leituras em massa mais rápidas ou auto para escolher automaticamente entre os modos. auto é o padrão. Para mais informações, consulte Modos de execução do wrapper de dados externos do BigQuery.

   Depois que a tabela externa for criada, você poderá consultar essa tabela da mesma forma que consulta qualquer tabela no AlloyDB.

Modos de execução do wrapper de dados externos do BigQuery

O modo de execução determina como o AlloyDB para PostgreSQL interage com o BigQuery para recuperar dados. O wrapper de dados externos do BigQuery oferece suporte a dois modos de execução: query e storage. A escolha do modo certo é fundamental, já que cada modo tem características de desempenho e preços separados. Consulte Preços do BigQuery para mais informações.

Modo Query

Esse modo usa API BigQuery para recuperar dados do BigQuery. Ele usa o mecanismo de computação do BigQuery para executar consultas complexas enviando filtros e agregações. Ou seja, as cláusulas WHERE, GROUP BY e as agregações são executadas no BigQuery antes de enviar dados de volta ao PostgreSQL. Esse modo também oferece suporte à consulta de visualizações e tabelas externas do BigQuery.

Como essa API fornece respostas de linha estruturadas e paginadas adequadas para pequenos conjuntos de resultados, a leitura de grandes conjuntos de dados tem limitações de capacidade de processamento e latências mais altas em comparação com a alternativa transmitida da API BigQuery Storage.

Modo Storage

Esse modo usa a API BigQuery Storage para recuperar dados do BigQuery. Ele permite leituras de alta capacidade enviando dados estruturados por fio em um formato de serialização binária. Esse é o modo preferencial para verificar tabelas grandes no BigQuery.

No entanto, esse modo tem algumas limitações. Nem todas as operações SQL complexas podem ser enviadas para a API BigQuery Storage. Por exemplo, as agregações não podem ser enviadas para o BigQuery e precisam ser executadas no AlloyDB. Esse modo também não oferece suporte à consulta de visualizações e tabelas externas do BigQuery.

Modo Auto

O modo padrão é definido como auto se você não definir o modo no comando CREATE FOREIGN TABLE. Ao usar o modo auto, o AlloyDB seleciona a API subjacente para equilibrar o desempenho e maximizar as operações SQL enviadas ao BigQuery.

A seguir

• Sincronizar dados do BigQuery e do Iceberg com o AlloyDB.
• Saiba mais sobre os tipos de dados e mapeamentos de colunas do BigQuery compatíveis.