Importar dados do BigQuery para o AlloyDB

É possível importar dados para o AlloyDB para PostgreSQL de tabelas integradas, visualizações materializadas e visualizações do BigQuery, bem como tabelas externas do BigLake (como tabelas gerenciadas do Apache Iceberg) e tabelas externas padrão. O Iceberg é um formato de tabela aberta para gerenciar e trocar dados.

Ao importar dados, você elimina a necessidade de criar e manter pipelines de dados complexos e propensos a erros que movem dados manualmente do BigQuery de volta para o AlloyDB. Para mais informações, consulte Visão geral da sincronização de dados.

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

1. Configure a flag bigquery_fdw.enabled na instância do AlloyDB.
2. Analise os mapeamentos de tipo de dados para entender como os tipos do BigQuery são representados no PostgreSQL ao usar bigquery_fdw.
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 serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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 serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

3. Para criar e se conectar ao AlloyDB, ative as APIs do Cloud necessárias.

   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 Cloud Resource Manager
   • API Service Networking
   • API BigQuery Storage

   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 Cloud 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:

• 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.

Conceder acesso do AlloyDB ao conjunto de dados do BigQuery

Depois de configurar a extensão bigquery_fdw no cluster do AlloyDB, conceda acesso da conta de serviço do cluster do AlloyDB ao conjunto de dados do BigQuery.

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 Locais do AlloyDB.

   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 Detalhes 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

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 estrangeiro 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 estrangeiro. 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ário executando o comando CREATE USER MAPPING, que especifica as credenciais a serem usadas quando você se conecta ao servidor estrangeiro.

   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 estrangeira. Para um usuário do IAM, o nome precisa ser todo em letras minúsculas e usar aspas porque contém caracteres especiais, como @ e .).
   • BIGQUERY_SERVER_NAME: identificador exclusivo do servidor estrangeiro que você criou.

4. Defina tabelas estrangeiras 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 estrangeira 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 Mapeamentos de tipo de dados.

   CREATE FOREIGN TABLE TABLENAME (
     COLUMNX_NAME DATA_TYPE,
     COLUMNX_NAME DATA_TYPE,
     ...
   ) SERVER  BIGQUERY_SERVER_NAME
     OPTIONS (project 'BIGQUERY_PROJECT_ID',
              dataset  'BIGQUERY_DATASET_NAME',
              table  'BIGQUERY_TABLE_NAME');
   

   Substitua:

   • TABLENAME: nome da tabela estrangeira no banco de dados local.
   • 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 estrangeiro 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.

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

Importar dados

Para importar dados do BigQuery ou dados do BigLake Iceberg armazenados no BigQuery para o AlloyDB, siga estas etapas:

1. Identifique uma fonte de dados atual ou crie uma tabela integrada do BigQuery ou novas tabelas gerenciadas do Iceberg.

2. Use psql para criar local_table executando o seguinte comando:

   CREATE TABLE local_table AS (SELECT * from foreign_table);
   

   Esse comando cria uma cópia da tabela do BigQuery em uma tabela padrão do AlloyDB local. Dependendo do fluxo de trabalho do aplicativo, você pode configurar a extensão pg_cron do PostgreSQL para atualizar a tabela do AlloyDB em intervalos periódicos.

Configurar uma programação para importar dados periodicamente

Ao importar dados do BigQuery, bigquery_fdw se conecta à tabela remota como uma tabela estrangeira, permitindo que você copie os dados para o armazenamento local do AlloyDB usando CREATE TABLE ... AS (SELECT * FROM foreign_table).

Para manter a tabela importada atualizada, você pode usar a extensão pg_cron para executar novamente essa consulta periodicamente e atualizar os dados locais em uma programação.

Observação:essa abordagem recria periodicamente uma cópia local de uma tabela do BigQuery executando consultas SQL em bigquery_fdw. Se você precisar de sincronização de dados em segundo plano gerenciada e automatizada sem manter manualmente scripts SQL periódicos ou substituições de tabelas, use a extensão alloydb_sync. Para mais informações, consulte Sincronizar dados do BigQuery com o AlloyDB.

Para configurar uma programação para importar dados do BigQuery ou dados do BigLake Iceberg para o AlloyDB periodicamente, siga estas etapas:

1. Configure a extensão bigquery_fdw.
2. Ative a extensão pg_cron na instância do AlloyDB. Para mais informações, consulte Extensões de banco de dados compatíveis.
   1. Defina a flag alloydb.enable_pg_cron como on. Para mais informações, consulte alloydb.enable_pg_cron.
   2. Defina a flag cron.database_name como o nome do banco de dados em que você instalou a extensão bigquery_fdw e em que quer executar as consultas SQL para atualizar os dados. Para mais informações, consulte Flags de banco de dados compatíveis.

3. Para atualizar periodicamente uma cópia local da tabela estrangeira, execute os seguintes comandos no banco de dados em que você instalou a extensão bigquery_fdw:

   CREATE EXTENSION pg_cron;
   SELECT cron.schedule(JOB_NAME, SCHEDULE, 'CREATE TABLE IF NOT EXISTS local_table_copy AS (SELECT * FROM foreign_table); DROP TABLE IF EXISTS local_table; ALTER TABLE local_table_copy RENAME TO local_table;');
   

   Substitua:

   • JOB_NAME: o nome do job.
   • SCHEDULE: a programação do job.

   Para mais informações, consulte O que é pg_cron?.

Mapeamentos de tipo de dados

Ao definir uma tabela estrangeira usando bigquery_fdw, você mapeia os tipos de dados do BigQuery para os tipos de PostgreSQL apropriados.

A tabela a seguir lista os mapeamentos de tipo de dados entre o BigQuery e o AlloyDB.

Tipos de dados da tabela do BigQuery	Tipos de dados recomendados da tabela estrangeira do PostgreSQL data types
BOOLEAN	BOOLEAN
INTEGER (INT64)	BIGINT
FLOAT (FLOAT64)	DOUBLE PRECISION
STRING	VARCHAR
NUMERIC	NUMERIC(38, 9)
NUMERIC(P[, S])	NUMERIC(P, S)
BIGNUMERIC	NUMERIC(77, 38)
BIGNUMERIC(P[, S])	NUMERIC(P, S)
DATE	DATE
TIMESTAMP	TIMESTAMPTZ
TIME	TIME
JSON	JSONB
BYTES	BYTEA
GEOGRAPHY	GEOGRAPHY(POINT), ... Para mais informações, consulte PostGIS_Geography.
DATETIME	TIMESTAMP
ARRAY	VECTOR(N) N é a dimensão do vetor. Você precisa definir a bigquery_fdw.enable_vector_downcasting flag na sessão. Como o tipo VECTOR no AlloyDB usa float4 tipo, você pode ter perda de precisão nesta conversão. Para mais informações, consulte a extensão pgvector

A seguir

• Escolha como acessar os dados do BigQuery.
• Visão geral da sincronização de dados.
• Configurar o acesso a dados em tempo real.