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

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:

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
  • STRUCT
  • GEOGRAPHY
  • DATETIME
  • RANGE
  • TIME
GoogleSQL
  • BIGNUMERIC: o tipo de NUMERIC compatível não é grande o suficiente. Considere adicionar transmissões explícitas ao NUMERIC na consulta.

  • 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 principal 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 "A linha principal está faltando. 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 uma 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 tipo TIMESTAMP na 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 lê a linha na tabela do Spanner para garantir que apenas a atualização mais recente da linha seja gravada. Recomendamos especificar uma coluna de tipo TIMESTAMP ao 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 NULL da 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 Cloud
  • INSTANCE_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 continuamente

Para processar continuamente uma consulta de exportação, consulte Criar consultas contínuas para instruções e exemplos 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 DATA para agrupar dados e otimizar as gravações no Spanner. Para mais informações, consulte Visão geral da performance.

  • Especifique a prioridade HIGH em spanner_options. Se a instância do Spanner tiver o escalonamento automático ativado, definir a prioridade HIGH ajudará 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 taxa de transferência 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, SaleYear e SaleMonth sã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é-classifique os dados corretamente, o que é fundamental para o agrupamento e a gravação eficientes no Spanner. Os valores das colunas geradas na instrução EXPORT DATA nã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 Sales do Spanner cuja chave primária usa colunas geradas. Para otimizar a performance de gravação, a consulta inclui expressões EXTRACT que correspondem às colunas SaleYear e SaleMonth geradas, 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 seis horas. Para mais informações sobre esses limites, consulte limites de jobs de consulta.

  • Para melhorar a performance 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 transferência escalonando os nós do Spanner e as reservas 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 job 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. As exportações de consultas contínuas não aceitam exportações que cruzam limites regionais.

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.