Sincronizar dados do BigQuery com o 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.

Para informações sobre o acesso a esta versão, consulte a página de solicitação de acesso.

Observação: o recurso de dados de sincronização é compatível apenas com o PostgreSQL versão 18.

Nesta página, mostramos como sincronizar tabelas do BigQuery com sua instância do AlloyDB para PostgreSQL.

Ao sincronizar dados analíticos do BigQuery com o AlloyDB, você pode criar sistemas operacionais que se beneficiam do acesso transacional de baixa latência ao seu data lake. Ao contrário de um wrapper de dados externos (FDW) que consulta dados no local, a tabela de sincronização move os dados para o armazenamento do AlloyDB para maximizar a performance.

O AlloyDB oferece as seguintes maneiras de mover dados do BigQuery para sua instância:

• Sincronização única:cria uma cópia gravável e independente da tabela do BigQuery.

• Sincronização periódica (espelhamento) : cria uma tabela local somente leitura que é atualizada automaticamente em uma programação. Por exemplo, a cada 6 horas ou diariamente.

Considerações sobre performance e operação

Ao usar tabelas de sincronização do BigQuery, considere o seguinte:

• Uso de recursos: a movimentação de dados consome CPU e memória. Para tabelas muito grandes, considere programar sincronizações fora do horário de pico para evitar afetar sua carga de trabalho transacional principal.
• Visibilidade dos dados: durante uma operação de substituição, a tabela de destino atual é descartada e recriada antecipadamente. As consultas durante a importação mostram uma tabela vazia inicialmente, seguida por dados recém-importados que aparecem de forma incremental à medida que as transações em lote são confirmadas.

Antes de começar

1. Familiarize-se com a forma como o bigquery_fdw processa os tipos de dados e os mapeamentos de colunas do BigQuery, porque a extensão alloydb_sync usa bigquery_fdw para se conectar ao BigQuery.
Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em situações 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.

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.

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

   Ativar as APIs

3. Para confirmar o nome do projeto em que você vai fazer mudanças, na etapa Confirmar projeto, clique em Próxima.

4. 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 que o 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

5. Verifique se você tem uma tabela do BigQuery para sincronizar os dados. Para mais informações, consulte Criar e usar tabelas do BigQuery.

Funções exigidas

Para conceder acesso 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 a uma conta de serviç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. Permite criar e executar jobs, incluindo jobs de consulta.

Configurar a extensão

Antes de sincronizar tabelas do BigQuery, ative a extensão necessária e configure a conexão com o BigQuery.

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.

   2. Execute este comando:

      CREATE EXTENSION IF NOT EXISTS alloydb_sync;
      

      Observação: é necessário criar essas extensões em todos os bancos de dados em que você quer sincronizar dados do BigQuery.

2. Para permitir que o AlloyDB faça a autenticação com o BigQuery, crie o mapeamento de usuário.

   CREATE EXTENSION IF NOT EXISTS bigquery_fdw;
   CREATE SERVER IF NOT EXISTS BIGQUERY_SERVER_NAME FOREIGN DATA WRAPPER bigquery_fdw;
   CREATE USER MAPPING IF NOT EXISTS FOR USER SERVER BIGQUERY_SERVER_NAME;
   

   Substitua:

   • USER: um nome de usuário do banco de dados ou um usuário do IAM que acessa a tabela do BigQuery.
   • BIGQUERY_SERVER_NAME: identificador exclusivo do servidor do BigQuery. Defina isso uma vez em um determinado banco de dados. Você pode substituir BIGQUERY_SERVER_NAME pelo nome do servidor.

Sincronizar uma tabela do BigQuery para exportação única

É possível sincronizar uma tabela do BigQuery para exportação única usando o psql.

Sincronizar uma tabela do BigQuery uma vez usando o psql

Observação: A função alloydb_sync.import_bq_table() cria uma tabela gravável do AlloyDB que não atualiza os dados do BigQuery automaticamente.

Para criar uma cópia editável dos dados do BigQuery, use psql para executar a alloydb_sync.import_bq_table função.

SELECT alloydb_sync.import_bq_table(
  'PROJECT_ID.DATASET_ID.TABLE_ID',
  'ALLOYDB_DESTINATION_TABLE_NAME',
  'ON_EXISTS',
  ARRAY['PRIMARY_KEY_COLUMN']
);

Substitua:

• PROJECT_ID: o ID do projeto em que o conjunto de dados do BigQuery reside.
• DATASET_ID: o nome do conjunto de dados do BigQuery para a tabela. Para tabelas do Iceberg com um nome de quatro partes, esse é o Catalog.Namespace.
• TABLE_ID: o nome da tabela ou visualização do BigQuery.
• ALLOYDB_DESTINATION_TABLE_NAME: o nome da tabela local no banco de dados do AlloyDB para criar e importar dados. Você pode incluir o nome do esquema, por exemplo, public.local_sales.
• ON_EXISTS: a estratégia a ser usada se a tabela de destino já existir.
• PRIMARY_KEY_COLUMN: uma lista opcional de nomes de colunas a serem usados como chave primária.

Exemplo

O exemplo a seguir mostra como sincronizar uma tabela chamada transactions de um conjunto de dados do BigQuery em uma nova tabela do AlloyDB chamada public.local_sales:

SELECT alloydb_sync.import_bq_table(
    'my-gcp-project.sales_data.transactions',
    'public.local_sales',
    'replace'
);

Parâmetro on_exists

O parâmetro on_exists determina como a função processa a sincronização se a tabela de destino já existir no AlloyDB:

• error: a opção padrão. Interrompe a sincronização se a tabela de destino já existir.
• skip: ignora a sincronização se a tabela de destino já existir.
• replace: substitui a tabela local atual por dados atualizados do BigQuery.

Suporte à chave primária

Se você fornecer o parâmetro opcional primary_key como uma matriz de texto, o AlloyDB criará a tabela com as colunas especificadas como chave primária.

SELECT alloydb_sync.import_bq_table(
    'my-gcp-project.sales_data.transactions',
    'public.local_sales',
    ARRAY['transaction_id']
);

Sincronizar uma tabela do BigQuery para exportação periódica

É possível sincronizar uma tabela do BigQuery para exportação periódica usando o psql.

Criar uma sincronização periódica

Para manter uma tabela somente leitura que permaneça sincronizada com os dados do BigQuery, use o psql para executar a função alloydb_sync.create_bq_sync_table.

SELECT alloydb_sync.create_bq_sync_table(
    'PROJECT_ID.DATASET_ID.TABLE_ID',
    'ALLOYDB_DESTINATION_TABLE_NAME',
    'REFRESH_INTERVAL',
    'ON_EXISTS',
    ARRAY['PRIMARY_KEY_COLUMN']
);

Substitua:

• PROJECT_ID.DATASET_ID.TABLE_ID: O nome totalmente qualificado da tabela ou visualização do BigQuery, incluindo o ID do projeto, o ID do conjunto de dados e o ID da tabela, separados por pontos. Para tabelas do Iceberg com um nome de quatro partes, o DATASET_ID é representado como Catalog.Namespace. Por exemplo, my-gcp-project.sales_data.transactions.
• ALLOYDB_DESTINATION_TABLE_NAME: o nome da tabela local no banco de dados do AlloyDB para criar e sincronizar dados.
• REFRESH_INTERVAL: o intervalo em que o AlloyDB atualiza periodicamente os dados do BigQuery. Por exemplo, 12 hours.
• ON_EXISTS: a estratégia a ser usada se a tabela de destino já existir.
• PRIMARY_KEY_COLUMN: uma lista opcional de nomes de colunas a serem usados como chave primária.

Exemplo

O exemplo a seguir mostra como criar um espelho de perfil do cliente que é atualizado a cada 12 horas:

SELECT alloydb_sync.create_bq_sync_table(
    'my-gcp-project.crm_data.profiles',
    'public.customer_mirror',
    '12 hours',
    'replace'
);

Monitorar e gerenciar jobs

Depois de iniciar uma sincronização, você pode monitorar o progresso e gerenciar os jobs.

Verificar o status do job

Sincronizações grandes podem levar tempo. É possível monitorar o progresso, incluindo os registros processados e o tempo estimado de conclusão, consultando a visualização job_status:

Observação: A função alloydb_sync.import_bq_table() retorna um UUID de job que você pode corresponder ao import_id na visualização alloydb_sync.job_status.

SELECT
    import_id,
    status,
    records_processed,
    total_records,
    error
FROM alloydb_sync.job_status;

Por exemplo, para cancelar o job, execute o seguinte comando:

SELECT alloydb_sync.cancel_import_job('85bb5dfa-dfb9-4017-9153-738f55abe4b1');

Interromper e excluir um job de sincronização

Para interromper o espelhamento de uma tabela do BigQuery e excluir a tabela local, use a função alloydb_sync.delete_bq_sync_table:

SELECT alloydb_sync.delete_bq_sync_table('public.customer_mirror');

Importante: é necessário usar essa função em vez dos comandos DROP TABLE padrão do PostgreSQL para excluir tabelas replicadas. Descartar uma tabela de sincronização manualmente sem essa função não remove os hooks do programador em segundo plano, o que pode fazer com que o programador encontre erros continuamente e esgote os slots de worker em segundo plano.

Limitações

As seguintes limitações se aplicam ao sincronizar tabelas do BigQuery:

• Esse recurso é compatível apenas com o PostgreSQL versão 18.
• Se você DROP a extensão alloydb_sync, será necessário reiniciar a instância antes de criar a extensão novamente.
• As sincronizações são executadas em uma transação. Se o job de importação for interrompido ou falhar, o sistema vai reverter os dados importados.
• Se dois usuários iniciarem jobs de sincronização ao mesmo tempo com as mesmas tabelas de destino, as tabelas poderão se substituir.
• Se ocorrer alguma interrupção durante a importação inicial em segundo plano de uma tabela de sincronização recém-registrada, a tabela permanecerá incompleta até o próximo intervalo de atualização programado. Para resolver isso, exclua a tabela de sincronização usando a função alloydb_sync.delete_bq_sync_table() e recrie-a.
• Tipos complexos do BigQuery, como ARRAY, BYTES, VECTOR e GEOGRAPHY, não são compatíveis com a sincronização. Para uma lista completa, consulte Tipos de dados e mapeamentos de colunas do BigQuery compatíveis.
• Não descarte manualmente uma tabela replicada. Use a função de API alloydb_sync.delete_bq_sync_table() para descartar a tabela e as atualizações com segurança.
• Para descartar um banco de dados que usa a extensão alloydb_sync, é necessário usar DROP DATABASE ... WITH (FORCE).
• Se o banco de dados do Postgres falhar enquanto uma importação estiver em execução, os metadados poderão ficar presos no estado RUNNING, bloqueando importações futuras. É necessário executar manualmente UPDATE alloydb_sync.import_job_status SET status = 'FAILED' WHERE status = 'RUNNING'; para desbloqueá-lo.

Preços

Ao sincronizar dados do BigQuery com o AlloyDB, você é cobrado usando os preços de computação da capacidade do BigQuery.

Depois que os dados são exportados, você é cobrado pelo armazenamento deles no AlloyDB. Para mais informações, consulte Preços do AlloyDB para PostgreSQL.

A seguir

• Saiba mais sobre como exportar dados para o AlloyDB (ETL reverso).
• Saiba mais sobre como consultar dados do BigQuery no local usando o FDW.