Exporte dados para o Spanner (ETL inverso)

Este documento descreve como pode configurar um fluxo de trabalho de extração, transformação e carregamento (ETL inverso) do BigQuery para o Spanner. Pode fazê-lo através da declaração EXPORT DATA para exportar dados de origens de dados do BigQuery, incluindo tabelas Iceberg, para uma tabela Spanner.

Este fluxo de trabalho de ETL inverso combina capacidades analíticas no BigQuery com baixa latência e elevado débito no Spanner. Este fluxo de trabalho permite-lhe publicar dados para utilizadores da aplicação sem esgotar as quotas e os limites no BigQuery.

Antes de começar

Funções necessárias

Para obter as autorizações de que precisa para exportar dados do BigQuery para o Spanner, peça ao seu administrador que lhe conceda as seguintes funções do IAM no seu projeto:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Limitações

  • Esta funcionalidade não é suportada no Assured Workloads.

  • Os seguintes tipos de dados do BigQuery não têm equivalentes no Spanner e não são suportados:

Dialeto da base de dados do Spanner Tipos do BigQuery não suportados
Todos os dialetos
  • STRUCT
  • GEOGRAPHY
  • DATETIME
  • RANGE
  • TIME
GoogleSQL
  • BIGNUMERIC: o tipo NUMERIC suportado não é suficientemente largo. Considere adicionar conversões explícitas ao tipo 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 subordinada de outra tabela (INTERLEAVE IN PARENT) ou se a tabela de destino tiver restrições de chaves externas, as chaves externas e a chave principal são validadas durante a exportação. Se uma linha exportada for escrita numa tabela com INTERLEAVE IN PARENT e a linha principal não existir, a exportação falha com a mensagem "Parent row is missing. Erro "Não é possível escrever na linha". Se a linha exportada for escrita numa tabela com restrições de chaves externas e estiver a referenciar uma chave que não existe, a exportação falha com o erro "Restrição de chave externa violada". Quando exporta para várias tabelas, recomendamos que sequencie a exportação para garantir que a integridade referencial é mantida durante a exportação. Normalmente, isto significa exportar tabelas principais e tabelas referenciadas por chaves externas antes das tabelas que as referenciam.

    Se a tabela que é o destino da exportação tiver restrições de chaves estrangeiras, ou for um elemento secundário de outra tabela (INTERLEAVE IN PARENT), a tabela principal tem de ser preenchida antes de uma exportação de tabela secundária e deve conter todas as chaves correspondentes. Uma tentativa de exportar uma tabela secundária quando uma tabela principal não tem o conjunto completo de chaves relevantes falha.

  • Uma tarefa do BigQuery, como uma tarefa de extração para o Spanner, tem uma duração máxima de 6 horas. Para obter informações sobre a otimização de tarefas de extração grandes, consulte a secção Otimização da exportação. Em alternativa, considere dividir a entrada em blocos de dados individuais, que podem ser exportados como tarefas de extração individuais.

  • As exportações para o Spanner só são suportadas para as edições BigQuery Enterprise ou Enterprise Plus. A edição padrão do BigQuery e a computação a pedido não são suportadas.

  • Não pode usar consultas contínuas para exportar para tabelas do Spanner com chaves primárias geradas automaticamente.

  • Não pode usar consultas contínuas para exportar para tabelas do Spanner numa base de dados com dialeto PostgreSQL.

  • Quando usar consultas contínuas para exportar para uma tabela do Spanner, certifique-se de que escolhe uma chave primária que não corresponda a um número inteiro monotonamente crescente na sua tabela do BigQuery. Caso contrário, pode causar problemas de desempenho na exportação. Para obter informações sobre as chaves primárias no Spanner e formas de mitigar estes problemas de desempenho, consulte o artigo Escolha uma chave primária.

Configure exportações com a opção spanner_options

Pode usar a opção spanner_options para especificar uma base de dados e uma tabela do Spanner de destino. A configuração é expressa sob a forma de uma string JSON, como mostra o exemplo seguinte:

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 o seguinte:

  • PROJECT_ID: o nome do seu projeto Google Cloud .
  • INSTANCE_ID: o nome da instância da base de dados.
  • DATABASE_ID: o nome da sua base de dados.
  • TABLE_NAME: o nome de uma tabela de destino existente.
  • CHANGE_TIMESTAMP: o nome da coluna de tipo TIMESTAMP na tabela do Spanner de destino. Esta opção é usada durante a exportação para acompanhar a data/hora da atualização da linha mais recente. Quando esta opção é especificada, a exportação executa primeiro uma leitura da linha na tabela do Spanner para garantir que apenas a atualização da linha mais recente é escrita. Recomendamos que especifique uma coluna de TIMESTAMPtipo quando executa uma exportação contínua, em que a ordem das alterações às linhas com a mesma chave principal é importante.
  • PRIORITY (opcional): prioridade dos pedidos de gravação. Valores permitidos: LOW, MEDIUM, HIGH. Valor predefinido: MEDIUM.
  • TAG (opcional): etiqueta de pedido para ajudar a identificar o tráfego do exportador na monitorização do Spanner. Valor predefinido: bq_export.

Requisitos de consulta de exportação

Para exportar os resultados da consulta para o Spanner, os resultados têm de cumprir os seguintes requisitos:

  • Todas as colunas no conjunto de resultados têm de existir na tabela de destino e os respetivos tipos têm de corresponder ou ser convertíveis.
  • O conjunto de resultados tem de conter todas as colunas NOT NULL da tabela de destino.
  • Os valores das colunas não podem exceder os limites de tamanho dos dados do Spanner nas tabelas.
  • Todos os tipos de colunas não suportados têm de ser convertidos num dos tipos suportados antes da exportação para o Spanner.

Conversões de tipo

Para facilitar a utilização, o exportador do Spanner aplica automaticamente as seguintes conversões de tipos:

Tipo do BigQuery Tipo de chave inglesa
BIGNUMERIC NUMERIC (apenas no dialeto PostgreSQL)
FLOAT64 FLOAT32
BYTES PROTO
INT64 ENUM

Exportar dados

Pode usar a declaração EXPORT DATA para exportar dados de uma tabela do BigQuery para uma tabela do Spanner.

O exemplo seguinte exporta campos selecionados de uma tabela denominada 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 o seguinte:

  • PROJECT_ID: o nome do seu Google Cloud projeto
  • INSTANCE_ID: o nome da sua instância de base de dados
  • DATABASE_ID: o nome da sua base de dados
  • TABLE_NAME: o nome de uma tabela de destino existente

Exporte vários resultados com o mesmo valor de rowkey

Quando exporta um resultado que contém várias linhas com o mesmo valor rowkey, os valores escritos no Spanner acabam na mesma linha do Spanner. Apenas a linha do BigQuery com uma única correspondência (não existe garantia de qual) estará presente no conjunto de linhas do Spanner produzido pela exportação.

Exporte continuamente

Para processar continuamente uma consulta de exportação, consulte as instruções em Crie consultas contínuas e o código de exemplo.

Otimização de exportação

Para otimizar a exportação de registos do BigQuery para o Spanner, pode experimentar o seguinte:

  • Aumente o número de nós na instância de destino do Spanner. Durante as fases iniciais da exportação, o aumento do número de nós na instância pode não aumentar imediatamente a taxa de transferência de exportação. Pode ocorrer um ligeiro atraso enquanto o Spanner realiza a divisão baseada na carga. Com a divisão baseada na carga, o débito de exportação aumenta e estabiliza. Usar dados de lotes de declarações para otimizar as gravações no Spanner.EXPORT DATA Para mais informações, consulte o artigo Vista geral do desempenho.

  • Especifique a prioridade HIGH em spanner_options. Se a instância do Spanner tiver a escalabilidade automática ativada, a definição da prioridade HIGH ajuda a garantir que a utilização da CPU atinge o limite necessário para acionar a escalabilidade. Isto permite que o dimensionamento automático adicione recursos de computação em resposta à carga de exportação, o que pode melhorar o débito geral de exportação.

    O exemplo seguinte mostra um comando de exportação do Spanner definido com a 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 contiver todas as colunas de chave principal, o exportador ordena automaticamente as chaves principais 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 das colunas geradas à consulta para garantir que os dados exportados são ordenados e processados em lote corretamente.

    Por exemplo, no esquema do Spanner seguinte, SaleYear e SaleMonth são colunas geradas que constituem 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);

    Quando exporta dados do BigQuery para uma tabela do Spanner com colunas geradas usadas na chave primária, é recomendado, mas não obrigatório, incluir as expressões para estas colunas geradas na sua consulta EXPORT DATA. Isto permite que o BigQuery pré-ordene os dados corretamente, o que é fundamental para o processamento em lote e a escrita eficientes no Spanner. Os valores das colunas geradas na declaraçã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 seguinte exporta dados para uma tabela do Spanner Sales cuja chave principal usa colunas geradas. Para otimizar o desempenho de escrita, a consulta inclui expressões EXTRACT que correspondem às colunas SaleYear e SaleMonth geradas, o que permite ao BigQuery pré-ordenar 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 tarefas de longa duração, exporte os dados por partição. Divida os dados do BigQuery em partições usando uma chave de partição, como uma 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';

    Isto permite que a consulta seja concluída no tempo de execução da tarefa de 6 horas. Para mais informações sobre estes limites, consulte os limites de tarefas de consulta.

  • Para melhorar o desempenho do carregamento de dados, elimine o índice na tabela do Spanner onde os dados são importados. Em seguida, volte a criá-lo após a conclusão da importação.

  • Recomendamos que comece com um nó do Spanner (1000 unidades de processamento) e uma reserva de slots do BigQuery mínima. Por exemplo, 100 espaços ou 0 espaços de base com o dimensionamento automático. Para exportações inferiores a 100 GB, esta configuração é normalmente concluída dentro do limite de 6 horas da tarefa. Para exportações superiores a 100 GB, aumente a taxa de transferência dimensionando os nós do Spanner e as reservas de slots do BigQuery, conforme necessário. A taxa de transferência é dimensionada a aproximadamente 5 MiB/s por nó.

Preços

Quando exporta dados para o Spanner através da declaração EXPORT DATA, a faturação é feita com base nos preços de computação de capacidade do BigQuery.

Para exportar continuamente para o Spanner através de uma consulta contínua, tem de ter uma reserva de slots da edição Enterprise ou Enterprise Plus do BigQuery e uma atribuição de reserva que use o tipo de tarefa CONTINUOUS.

As exportações do BigQuery para o Spanner que atravessam limites regionais são cobradas com base nas taxas de extração de dados. Para mais informações, consulte os preços do BigQuery. Para evitar custos de transferência de dados, certifique-se de que a exportação do BigQuery é executada na mesma região que o líder predefinido do Spanner. As exportações de consultas contínuas não suportam exportações que ultrapassam os limites regionais.

Após a exportação dos dados, é-lhe cobrado o armazenamento dos dados no Spanner. Para mais informações, consulte os preços do Spanner.