Exportar dados para o Spanner (ETL reverso)
Este documento descreve como configurar um fluxo de trabalho de extração, transformação e
carregamento reverso (ETL reverso) do BigQuery para o Spanner. É possível fazer isso usando a instrução EXPORT DATA para exportar dados de fontes de dados do BigQuery, incluindo tabelas do Iceberg, para uma tabela do Spanner.
Esse fluxo de trabalho ETL reverso combina recursos analíticos no BigQuery com baixa latência e alta capacidade no Spanner. Esse fluxo de trabalho permite disponibilizar dados para usuários de aplicativos sem esgotar cotas e limites no BigQuery.
Antes de começar
Crie um banco de dados do Spanner, incluindo uma tabela para receber os dados exportados.
Atribua papéis do Identity and Access Management (IAM) que concedam aos usuários as permissões necessárias para realizar cada tarefa deste documento.
Crie uma reserva do Enterprise ou de um nível superior. É possível reduzir os custos de computação do BigQuery ao executar exportações únicas para o Spanner definindo uma capacidade de slot de linha de base de zero e ativando o escalonamento automático.
Funções exigidas
Para conseguir as permissões necessárias para exportar dados do BigQuery para o Spanner, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto:
-
Exporte dados de uma tabela do BigQuery:
Leitor de dados do BigQuery (
roles/bigquery.dataViewer) -
Execute um job de extração:
Usuário do BigQuery (
roles/bigquery.user) -
Verifique os parâmetros da instância do Spanner:
Visualizador do Cloud Spanner (
roles/spanner.viewer) -
Grave dados em uma tabela do Spanner:
Usuário do banco de dados do Cloud Spanner (
roles/spanner.databaseUser)
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.
Limitações
Esse recurso não é compatível com o Assured Workloads.
Os seguintes tipos de dados do BigQuery não têm equivalentes no Spanner e não são compatíveis:
| Dialeto do banco de dados do Spanner | Tipos do BigQuery sem suporte |
|---|---|
| Todos os dialetos |
|
| GoogleSQL |
|
O tamanho máximo de uma linha exportada não pode exceder 1 MiB.
O Spanner aplica a integridade referencial durante a exportação. Se a tabela de destino for filha de outra (INTERLEAVE IN PARENT) ou tiver restrições de chave externa, as chaves externas e a chave mãe serão validadas durante a exportação. Se uma linha exportada for gravada em uma tabela com INTERLEAVE IN PARENT e a linha principal não existir, a exportação vai falhar com a mensagem "Parent row is missing. Erro "Não é possível gravar a linha". Se a linha exportada for gravada em uma tabela com restrições de chave externa e estiver referenciando uma chave que não existe, a exportação vai falhar com o erro "A restrição de chave externa foi violada". Ao exportar para várias tabelas, recomendamos sequenciar a exportação para garantir que a integridade referencial seja mantida durante o processo. Isso geralmente significa exportar tabelas principais e tabelas referenciadas por chaves estrangeiras antes das tabelas que as referenciam.
Se a tabela de destino da exportação tiver restrições de chave externa ou for filha de outra tabela (INTERLEAVE IN PARENT), a tabela mãe precisará ser preenchida antes da exportação de uma tabela filha e conter todas as chaves correspondentes. Uma tentativa de exportar uma tabela filha enquanto uma tabela mãe não tem o conjunto completo de chaves relevantes vai falhar.
Um job do BigQuery, como um job de extração para o Spanner, tem duração máxima de 6 horas. Para informações sobre como otimizar jobs de extração grandes, consulte Otimização de exportação. Como alternativa, divida a entrada em blocos individuais de dados, que podem ser exportados como jobs de extração individuais.
As exportações para o Spanner só são compatíveis com as edições BigQuery Enterprise ou Enterprise Plus. A edição Standard do BigQuery e a computação sob demanda não são compatíveis.
Não é possível usar consultas contínuas para exportar para tabelas do Spanner com chaves primárias geradas automaticamente.
Não é possível usar consultas contínuas para exportar para tabelas do Spanner em um banco de dados com dialeto PostgreSQL.
Ao usar consultas contínuas para exportar para uma tabela do Spanner, escolha uma chave primária que não corresponda a um número inteiro monotonicamente crescente na tabela do BigQuery. Isso pode causar problemas de performance na exportação. Para informações sobre chaves primárias no Spanner e maneiras de reduzir esses problemas de desempenho, consulte Escolher uma chave primária.
Configurar exportações com a opção spanner_options
Você pode usar a opção spanner_options para especificar um banco de dados e uma tabela de destino do Spanner. A configuração é expressa na forma de uma string JSON, conforme mostrado neste exemplo:
EXPORT DATA OPTIONS( uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID", format='CLOUD_SPANNER', spanner_options = """{ "table": "TABLE_NAME", "change_timestamp_column": "CHANGE_TIMESTAMP", "priority": "PRIORITY", "tag": "TAG", }""" )
Substitua:
PROJECT_ID: o nome do projeto Google Cloud .INSTANCE_ID: o nome da instância do banco de dados.DATABASE_ID: o nome do banco de dados.TABLE_NAME: o nome de uma tabela de destino atual.CHANGE_TIMESTAMP: o nome da coluna do tipoTIMESTAMPna tabela de destino do Spanner. Essa opção é usada durante a exportação para rastrear o carimbo de data/hora da atualização de linha mais recente. Quando essa opção é especificada, a exportação primeiro realiza uma leitura da linha na tabela do Spanner para garantir que apenas a atualização mais recente da linha seja gravada. Recomendamos especificar uma coluna de tipoTIMESTAMPao executar uma exportação contínua, em que a ordenação das mudanças em linhas com a mesma chave primária é importante.PRIORITY(opcional): prioridade das solicitações de gravação. Valores permitidos:LOW,MEDIUM,HIGH. Valor padrão:MEDIUM.TAG(opcional): tag de solicitação para ajudar a identificar o tráfego do exportador no monitoramento do Spanner. Valor padrão:bq_export.
Requisitos de consulta de exportação
Para exportar resultados de consulta para o Spanner, eles precisam atender aos seguintes requisitos:
- Todas as colunas do conjunto de resultados precisam existir na tabela de destino, e os tipos delas precisam corresponder ou ser conversíveis.
- O conjunto de resultados precisa conter todas as colunas
NOT NULLda tabela de destino. - Os valores das colunas não podem exceder os limites de tamanho de dados em tabelas do Spanner.
- Os tipos de coluna incompatíveis precisam ser convertidos em um dos tipos compatíveis antes de exportar para o Spanner.
Conversões de tipos
Para facilitar o uso, o exportador do Spanner aplica automaticamente as seguintes conversões de tipo:
| Tipo do BigQuery | Tipo de Spanner |
|---|---|
| BIGNUMERIC | NUMERIC (somente dialeto PostgreSQL) |
| FLOAT64 | FLOAT32 |
| BYTES | PROTO |
| INT64 | ENUM |
Exportar dados
É possível usar a
instrução EXPORT DATA
para exportar dados de uma tabela do BigQuery para uma
tabela do Spanner.
O exemplo a seguir exporta campos selecionados de uma tabela chamada
mydataset.table1:
EXPORT DATA OPTIONS ( uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID", format='CLOUD_SPANNER', spanner_options="""{ "table": "TABLE_NAME" }""" ) AS SELECT * FROM mydataset.table1;
Substitua:
PROJECT_ID: o nome do projeto Google CloudINSTANCE_ID: o nome da sua instância de banco de dados.DATABASE_ID: o nome do banco de dados.TABLE_NAME: o nome de uma tabela de destino atual.
Exportar vários resultados com o mesmo valor rowkey
Quando você exporta um resultado que contém várias linhas com o mesmo valor rowkey, os valores gravados no Spanner acabam na mesma linha do Spanner. Apenas uma linha correspondente do BigQuery (não há garantia de qual) estará presente no conjunto de linhas do Spanner produzido pela exportação.
Exportar usando uma conexão CLOUD_RESOURCE
É possível delegar permissões de gravação a uma conexão CLOUD_RESOURCE do BigQuery para executar exportações sem dar acesso direto a um usuário no banco de dados do Spanner.
Antes de exportar para o Spanner com uma conexão CLOUD_RESOURCE, faça o seguinte:
Crie uma conexão
Você pode criar ou usar uma conexão CLOUD_RESOURCE para se conectar ao Spanner.
Console
Acessar a página do BigQuery.
No painel à esquerda, clique em Explorer:

Se o painel esquerdo não aparecer, clique em Expandir painel esquerdo para abrir.
No painel Explorer, expanda o nome do projeto e clique em Conexões.
Na página Conexões, clique em Criar conexão.
Em Tipo de conexão, escolha Modelos remotos da Vertex AI, funções remotas, BigLake e Spanner (recurso do Cloud).
No campo ID da conexão, insira um nome para a conexão.
Em Tipo de local, selecione um local para sua conexão. A conexão precisa estar no mesmo local que seus outros recursos, como conjuntos de dados.
Clique em Criar conexão.
Clique em Ir para conexão.
No painel Informações da conexão, copie o ID da conta de serviço para usar em uma etapa posterior.
bq
Em um ambiente de linha de comando, crie uma conexão:
bq mk --connection --location=REGION --project_id=PROJECT_ID \ --connection_type=CLOUD_RESOURCE CONNECTION_ID
O parâmetro
--project_idsubstitui o projeto padrão.Substitua:
REGION: sua região de conexãoPROJECT_ID: o ID do projeto do Google CloudCONNECTION_ID: um ID para sua conexão
Quando você cria um recurso de conexão, o BigQuery cria uma conta de serviço do sistema exclusiva e a associa à conexão.
Solução de problemas: se você receber o seguinte erro de conexão, atualize o SDK Google Cloud:
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
Recupere e copie o ID da conta de serviço para uso em uma etapa posterior:
bq show --connection PROJECT_ID.REGION.CONNECTION_ID
O resultado será o seguinte:
name properties 1234.REGION.CONNECTION_ID {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}
Python
Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Node.js
Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Node.js.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
Terraform
Use o
recurso
google_bigquery_connection.
Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.
O exemplo a seguir cria uma conexão a recursos do Cloud chamada
my_cloud_resource_connection na região US:
Para aplicar a configuração do Terraform em um projeto Google Cloud , siga as etapas nas seções a seguir.
Preparar o Cloud Shell
- Inicie o Cloud Shell.
-
Defina o projeto Google Cloud padrão em que você quer aplicar as configurações do Terraform.
Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.
Preparar o diretório
Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.
-
No Cloud Shell, crie um diretório e um novo
arquivo dentro dele. O nome do arquivo precisa ter a extensão
.tf, por exemplo,main.tf. Neste tutorial, o arquivo é chamado demain.tf.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.
Copie o exemplo de código no
main.tfrecém-criado.Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.
- Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
- Salve as alterações.
-
Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.
terraform init
Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção
-upgrade:terraform init -upgrade
Aplique as alterações
-
Revise a configuração e verifique se os recursos que o Terraform vai criar ou
atualizar correspondem às suas expectativas:
terraform plan
Faça as correções necessárias na configuração.
-
Para aplicar a configuração do Terraform, execute o comando a seguir e digite
yesno prompt:terraform apply
Aguarde até que o Terraform exiba a mensagem "Apply complete!".
- Abra seu Google Cloud projeto para conferir os resultados. No console do Google Cloud , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.
Depois de criar a conexão, abra-a. No painel Informações da conexão, copie o ID da conta de serviço. Você vai precisar desse ID ao configurar as permissões da conexão. Quando você cria um recurso de conexão, o BigQuery cria uma conta de serviço do sistema exclusiva e a associa à conexão.
Configurar o acesso
Conceda à conta de serviço associada à nova conexão acesso de gravação à sua instância ou banco de dados do Spanner. Recomendamos que você use o papel predefinido do IAM Usuário do banco de dados do Cloud Spanner (roles/spanner.databaseUser).
Essas etapas exigem o ID da conta de serviço que você copiou ao criar a conexão.
Para conceder acesso a papéis no nível do banco de dados para a conta de serviço, faça o seguinte:
Acesse a página "Instâncias do Spanner".
Clique no nome da instância que contém o banco de dados.
Na guia Visão geral, marque a caixa de seleção do banco de dados.
A caixa de diálogo Painel de informações aparece. Clique em Adicionar principal.
Em Novos principais, insira o ID da conta de serviço que você copiou anteriormente.
No campo Selecionar um papel, escolha um papel com permissões
spanner.databases.write. Recomendamos que você use o papel Usuário do banco de dados do Cloud Spanner.Clique em Salvar.
Execute a exportação usando a conexão CLOUD_RESOURCE.
Com a conexão criada e o acesso adequado concedido a ela, é possível executar a exportação usando a conexão CLOUD_RESOURCE. O exemplo a seguir mostra um comando EXPORT que exporta com uma conexão CLOUD_RESOURCE.
EXPORT DATA WITH CONNECTION `PROJECT_ID.LOCATION.CONNECTION_NAME` OPTIONS ( uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID", format='CLOUD_SPANNER', spanner_options="""{ "table": "SPANNER_TABLE_NAME" }""" ) AS SELECT * FROM my_bq_dataset.table1;
Substitua:
PROJECT_ID: o nome do projeto Google Cloud .LOCATION: o local em que você criou a conexão, por exemplo,us.CONNECTION_NAME: o nome da conexão usada para executar a exportação. Por exemplo,myconnection.INSTANCE_ID: o nome da instância do banco de dados do Spanner.DATABASE_ID: o nome do banco de dados do Spanner.SPANNER_TABLE_NAME: o nome da tabela de destino do Spanner.
Exportar continuamente
Para processar continuamente uma consulta de exportação, consulte Criar consultas contínuas para instruções e exemplo de código.
Otimização da exportação
Para otimizar a exportação de registros do BigQuery para o Spanner, tente o seguinte:
Aumente o número de nós na instância de destino do Spanner. Durante os estágios iniciais da exportação, aumentar o número de nós na instância pode não aumentar imediatamente a taxa de transferência de exportação. Pode ocorrer um pequeno atraso enquanto o Spanner realiza a divisão baseada em carga. Com a divisão baseada em carga, a taxa de transferência de exportação aumenta e se estabiliza. Usar a instrução
EXPORT DATAem lotes de dados para otimizar as gravações no Spanner. Para mais informações, consulte Visão geral da performance.Especifique a prioridade
HIGHemspanner_options. Se a instância do Spanner tiver o escalonamento automático ativado, definir a prioridadeHIGHajudará a garantir que a utilização da CPU atinja o limite necessário para acionar o escalonamento. Isso permite que o escalonador automático adicione recursos de computação em resposta à carga de exportação, o que pode melhorar a capacidade de processamento geral da exportação.O exemplo a seguir mostra um comando de exportação do Spanner definido como prioridade
HIGH:EXPORT DATA OPTIONS ( uri="https://spanner.googleapis.com/projects/
PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID", format='CLOUD_SPANNER', spanner_options="""{ "table": "TABLE_NAME", "priority": "HIGH" }""" )Evite ordenar os resultados da consulta. Se o conjunto de resultados tiver todas as colunas chave primária, o exportador classificará automaticamente as chaves primárias da tabela de destino para simplificar as gravações e minimizar a contenção.
Se a chave primária da tabela de destino incluir colunas geradas, adicione as expressões dessas colunas à consulta para garantir que os dados exportados sejam classificados e agrupados corretamente.
Por exemplo, no esquema do Spanner a seguir,
SaleYeareSaleMonthsão colunas geradas que compõem o início da chave primária do Spanner:CREATE TABLE Sales ( SaleId STRING(36) NOT NULL, ProductId INT64 NOT NULL, SaleTimestamp TIMESTAMP NOT NULL, Amount FLOAT64, -- Generated columns SaleYear INT64 AS (EXTRACT(YEAR FROM SaleTimestamp)) STORED, SaleMonth INT64 AS (EXTRACT(MONTH FROM SaleTimestamp)) STORED, ) PRIMARY KEY (SaleYear, SaleMonth, SaleId);
Ao exportar dados do BigQuery para uma tabela do Spanner com colunas geradas usadas na chave primária, é recomendável, mas não obrigatório, incluir as expressões dessas colunas geradas na consulta
EXPORT DATA. Isso permite que o BigQuery pré-ordene os dados corretamente, o que é fundamental para o agrupamento e a gravação eficientes no Spanner. Os valores das colunas geradas na instruçãoEXPORT DATAnão são confirmados no Spanner porque são gerados automaticamente pelo Spanner, mas são usados para otimizar a exportação.O exemplo a seguir exporta dados para uma tabela
Salesdo Spanner cuja chave primária usa colunas geradas. Para otimizar a performance de gravação, a consulta inclui expressõesEXTRACTque correspondem às colunasSaleYeareSaleMonthgeradas, permitindo que o BigQuery pré-classifique os dados antes da exportação:EXPORT DATA OPTIONS ( uri="https://spanner.googleapis.com/projects/
PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID", format='CLOUD_SPANNER', spanner_options="""{ "table": "Sales" }""" ) AS SELECT s.SaleId, s.ProductId, s.SaleTimestamp, s.Amount, -- Add expressions that match the generated columns in the Spanner PK EXTRACT(YEAR FROM s.SaleTimestamp) AS SaleYear, EXTRACT(MONTH FROM s.SaleTimestamp) AS SaleMonth FROM my_dataset.sales_export AS s;Para evitar jobs de longa duração, exporte os dados por partição. Fragmentar seus dados do BigQuery usando uma chave de partição, como um carimbo de data/hora na consulta:
EXPORT DATA OPTIONS ( uri="https://spanner.googleapis.com/projects/
PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID", format='CLOUD_SPANNER', spanner_options="""{ "table": "TABLE_NAME", "priority": "MEDIUM" }""" ) AS SELECT * FROM 'mydataset.table1' d WHERE d.timestamp >= TIMESTAMP '2025-08-28T00:00:00Z' AND d.timestamp < TIMESTAMP '2025-08-29T00:00:00Z';Isso permite que a consulta seja concluída dentro do tempo de execução do job de 6 horas. Para mais informações sobre esses limites, consulte limites de jobs de consulta.
Para melhorar o desempenho do carregamento de dados, descarte o índice na tabela do Spanner em que os dados são importados. Em seguida, recrie-o após a conclusão da importação.
Recomendamos começar com um nó do Spanner (1.000 unidades de processador) e uma reserva mínima de Slot do BigQuery. Por exemplo, 100 slots ou 0 slots de valor de referência com escalonamento automático. Para exportações com menos de 100 GB, essa configuração normalmente é concluída dentro do limite de 6 horas do job. Para exportações maiores que 100 GB, aumente a capacidade de processamento escalonando verticalmente os nós do Spanner e as reservas de Slot do BigQuery, conforme necessário. A capacidade de processamento aumenta em aproximadamente 5 MiB/s por nó.
Preços
Quando você exporta dados para o Spanner usando a instrução EXPORT DATA,
a cobrança é feita usando os
preços de computação da capacidade do BigQuery.
Para exportar continuamente para o Spanner usando uma consulta contínua, você precisa ter uma reserva de slot da edição Enterprise ou Enterprise Plus do BigQuery e uma atribuição de reserva que use o tipo de serviço CONTINUOUS.
As exportações do BigQuery para o Spanner que cruzam limites regionais são cobradas usando taxas de extração de dados. Para mais informações, consulte preços do BigQuery. Para evitar cobranças de transferência de dados, verifique se a exportação do BigQuery é executada na mesma região do líder padrão do Spanner.
Depois que os dados são exportados, você é cobrado pelo armazenamento dos dados no Spanner. Para mais informações, consulte os preços do Spanner.