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 essa versão, consulte a página de solicitação de acesso.

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

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, é possível criar sistemas operacionais que se beneficiam do acesso transacional de baixa latência ao data lake. Ao contrário de um encapsulamento de dados externos (FDW), que consulta dados no local, a tabela de sincronização move os dados para o armazenamento do AlloyDB para maximizar o desempenho.

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

• Sincronização única:cria uma cópia independente e gravável da sua 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 desempenho 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 dos horários de pico para evitar afetar a 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 veem 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. Saiba como o bigquery_fdw processa tipos de dados e mapeamentos de colunas do BigQuery, porque a extensão alloydb_sync usa o bigquery_fdw para se conectar ao BigQuery.
Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de 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 a conectividade de rede com o AlloyDB usando uma rede VPC que reside no mesmo projeto Google Cloud 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 Google Cloud diferente.

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 ao conjunto de dados do BigQuery acesso à conta de serviço do cluster do AlloyDB, você precisa das seguintes permissões:

• Leitor de dados do BigQuery (roles/bigquery.dataViewer) ou qualquer papel personalizado com permissões bigquery.tables.get e bigquery.tables.getData. Quando concedido a uma conta de serviço, esse papel 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 papel personalizado 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 papel personalizado 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. Se você usa o console Google Cloud , o AlloyDB executa essas etapas automaticamente.

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: você precisa criar essas extensões em todos os bancos de dados em que quer sincronizar dados do BigQuery.

2. Para permitir que o AlloyDB se autentique com o BigQuery, crie o mapeamento de usuários.

   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. É possível 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 consoleGoogle Cloud ou o psql.

Usar o console do Google Cloud

Para sincronizar uma tabela do BigQuery com o AlloyDB usando o consoleGoogle Cloud , faça o seguinte:

1. Abra a página do BigQuery no console do Google Cloud .

   Acessar a página do BigQuery

2. No painel à esquerda, clique em Explorer:

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

3. No painel Explorer, expanda o projeto, clique em Conjuntos de dados e clique no conjunto de dados.

4. Clique em Visão geral > Tabelas e selecione uma tabela.

5. No painel de detalhes, clique em Fazer upload Exportar / sincronizar > AlloyDB (exportar uma vez ou sincronizar).

6. Em Escolher um cluster de destino, selecione uma das seguintes opções:

   • Selecione Usar um cluster atual para exportar a tabela do BigQuery para um cluster do AlloyDB. Em seguida, faça o seguinte:

     1. Selecione o cluster principal do AlloyDB.

     2. Selecione o banco de dados de destino do AlloyDB.

     3. Selecione o esquema da tabela de destino do AlloyDB.

     4. Especifique um nome para a tabela de destino do AlloyDB.

     5. Em Frequência de sincronização, selecione Apenas uma vez para criar uma cópia da tabela do BigQuery.

     6. Clique em Configurar exportação.

     Quando a configuração da sincronização for concluída, use as instruções SQL fornecidas para acompanhar o job de importação e consultar as tabelas importadas. Clique em Consulta para acessar a tabela importada no AlloyDB Studio.

   • Selecione Criar um novo cluster para exportar a tabela do BigQuery para um novo cluster do AlloyDB. Em seguida, faça o seguinte:

     1. Clique em Configurar exportação.

     2. Na caixa de diálogo Redirecionar para o AlloyDB, selecione Redirecionar.

     3. Selecione um tipo de cluster, Cluster de teste sem custo financeiro ou Cluster provisionado.

     4. Clique em Continuar.

     5. Em Configuração de sincronização, selecione o banco de dados postgres padrão do AlloyDB de destino, o esquema public padrão para a tabela de destino do AlloyDB e especifique um nome para ela.

        Em Frequência de sincronização, selecione Apenas uma vez para criar uma cópia da tabela do BigQuery.

     6. Clique em Continuar.

     7. Configure seu cluster. Para mais informações sobre cada campo, consulte Criar um cluster e uma instância principal.

     8. Clique em Criar cluster.

     Quando a configuração da sincronização for concluída, navegue até o AlloyDB Studio para consultar as tabelas importadas.

Sincronizar uma tabela do BigQuery uma única vez usando 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 função alloydb_sync.import_bq_table.

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 está localizado.
• DATASET_ID: o nome do conjunto de dados do BigQuery para a tabela. Para tabelas 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 em que os dados serão criados e importados. 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 para usar 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.

Compatibilidade com 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 a 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 console Google Cloud ou o psql.

Usar o console do Google Cloud

Para sincronizar uma tabela do BigQuery com o AlloyDB usando o consoleGoogle Cloud , faça o seguinte:

1. Abra a página do BigQuery no console do Google Cloud .

   Acessar a página do BigQuery

2. No painel à esquerda, clique em Explorer:

   

   Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.

3. No painel Explorer, expanda o projeto, clique em Conjuntos de dados e clique no conjunto de dados.

4. Clique em Visão geral > Tabelas e selecione uma tabela.

5. No painel de detalhes, clique em Fazer upload Exportar / sincronizar > AlloyDB (exportar uma vez ou sincronizar).

6. Em Escolher um cluster de destino, selecione uma das seguintes opções:

   • Selecione Usar um cluster atual para exportar a tabela do BigQuery para um cluster do AlloyDB. Em seguida, faça o seguinte:

     1. Selecione o cluster principal do AlloyDB.

     2. Selecione o banco de dados de destino do AlloyDB.

     3. Selecione o esquema da tabela de destino do AlloyDB.

     4. Especifique um nome para a tabela de destino do AlloyDB.

     5. Em Frequência de sincronização, selecione um período para criar uma sincronização periódica da tabela do BigQuery. Por exemplo, A cada hora ou A cada seis horas.

     6. Clique em Configurar exportação.

     Quando a configuração da sincronização for concluída, use as instruções SQL fornecidas para acompanhar o job de importação e consultar a tabela importada. Clique em Consulta para acessar a tabela importada no AlloyDB Studio.

   • Selecione Criar um novo cluster para exportar a tabela do BigQuery para um novo cluster do AlloyDB. Em seguida, faça o seguinte:

     1. Clique em Configurar exportação.

     2. Na caixa de diálogo Redirecionar para o AlloyDB, selecione Redirecionar.

     3. Selecione um tipo de cluster, Cluster de teste sem custo financeiro ou Cluster provisionado.

     4. Clique em Continuar.

     5. Em Configuração de sincronização, selecione o banco de dados postgres padrão do AlloyDB de destino, o esquema public padrão para a tabela de destino do AlloyDB e especifique um nome para ela.

        Em Frequência de sincronização, selecione Apenas uma vez para criar uma cópia da tabela do BigQuery.

     6. Clique em Continuar.

     7. Configure seu cluster. Para mais informações sobre cada campo, consulte Criar um cluster e uma instância principal.

     8. Clique em Criar cluster.

     Quando a configuração da sincronização for concluída, navegue até o AlloyDB Studio para consultar as tabelas importadas.

Criar uma sincronização periódica

Para manter uma tabela somente leitura 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 do BigQuery ou visualização, 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 em que os dados serão criados e sincronizados.
• 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 usadas como chave primária.

Exemplo

O exemplo a seguir mostra como criar um espelho do 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, é possível monitorar o progresso dela e gerenciar os jobs.

Verificar o status do job

Sincronizações grandes podem levar tempo. Para monitorar o progresso, incluindo registros processados e tempo estimado de conclusão, consulte 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');

Parar 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: use essa função em vez dos comandos DROP TABLE padrão do PostgreSQL para excluir tabelas replicadas. A exclusão manual de uma tabela de sincronização 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.

Mapeamentos de tipo de dados

Ao sincronizar ou importar dados do BigQuery para o AlloyDB usando a extensão alloydb_sync, o AlloyDB mapeia os tipos de dados do BigQuery para os tipos de dados correspondentes do PostgreSQL na tabela de destino.

Verifique se as colunas da tabela do BigQuery de origem usam os seguintes tipos de dados compatíveis.

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

Tipos de dados da tabela do BigQuery	Tipos de dados recomendados para tabelas externas do PostgreSQL
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. Defina a flag bigquery_fdw.enable_vector_downcasting na sessão. Como o tipo VECTOR no AlloyDB usa o tipo float4, pode haver perda de precisão nessa conversão. Para mais informações, consulte a extensão pgvector.

Limitações

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

• Esse recurso é compatível apenas com a versão 18 do PostgreSQL.
• Se você DROP a extensão alloydb_sync, reinicie 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, elas poderão se substituir.
• Se ocorrer uma interrupção durante a importação inicial em segundo plano de uma tabela de sincronização recém-registrada, ela vai 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 os tipos de dados e mapeamentos de colunas do BigQuery compatíveis.
• Não exclua 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, use DROP DATABASE ... WITH (FORCE).
• Se o banco de dados do Postgres falhar durante uma importação, os metadados poderão ficar presos no estado RUNNING, bloqueando importações futuras. Você precisa executar manualmente UPDATE alloydb_sync.import_job_status SET status = 'FAILED' WHERE status = 'RUNNING'; para desbloquear.

Preços

Ao sincronizar dados do BigQuery com o AlloyDB, você recebe uma cobrança usando os preços de leituras de streaming do BigQuery (API Storage Read).

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 Exportar dados para o AlloyDB (ETL reverso).
• Saiba mais sobre como consultar dados do BigQuery no local usando FDW.