Exporter des données vers Spanner (ETL inversé)

Ce document explique comment configurer un workflow d'extraction, de transformation et de chargement inversé (ETL inversé) de BigQuery vers Spanner. Pour ce faire, utilisez l'instruction EXPORT DATA pour exporter les données de sources de données BigQuery, y compris les tables Iceberg, vers une table Spanner.

Ce workflow ETL inversé combine des fonctionnalités analytiques dans BigQuery avec une faible latence et un débit élevé dans Spanner. Ce workflow vous permet de diffuser des données aux utilisateurs de l'application sans épuiser les quotas et limites de BigQuery.

Avant de commencer

Rôles requis

Pour obtenir les autorisations nécessaires à l'exportation des données BigQuery vers Spanner, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Limites

  • Cette fonctionnalité n'est pas disponible dans Assured Workloads.

  • Les types de données BigQuery suivants n'ont pas d'équivalent dans Spanner et ne sont pas compatibles :

Dialecte de la base de données Spanner Types BigQuery non compatibles
Tous les dialectes
  • STRUCT
  • GEOGRAPHY
  • DATETIME
  • RANGE
  • TIME
GoogleSQL
  • BIGNUMERIC : le type NUMERIC compatible n'est pas assez large. Envisagez d'ajouter des diffusions explicites au type NUMERIC dans la requête.

  • La taille maximale d'une ligne exportée ne peut pas dépasser 1 Mio.

  • Spanner applique l'intégrité référentielle lors de l'exportation. Si la table cible est un enfant d'une autre table (INTERLEAVE IN PARENT) ou si la table cible comporte des contraintes de clé étrangère, les clés étrangères et la clé parent seront validées lors de l'exportation. Si une ligne exportée est écrite dans une table avec INTERLEAVE IN PARENT et que la ligne parent n'existe pas, l'exportation échoue et affiche le message d'erreur "Ligne parent manquante. Impossible d'écrire la ligne". Si la ligne exportée est écrite dans une table avec des contraintes de clé étrangère et qu'elle fait référence à une clé qui n'existe pas, l'exportation échoue et l'erreur "La contrainte de clé étrangère est en conflit" s'affiche. Lorsque vous exportez vers plusieurs tables, nous vous recommandons de séquencer l'exportation pour vous assurer que l'intégrité référentielle est maintenue. Cela implique généralement d'exporter les tables parentes et les tables référencées par des clés étrangères avant les tables qui les référencent.

    Si la table cible de l'exportation présente des contraintes de clé étrangère ou est l'enfant d'une autre table (INTERLEAVE IN PARENT), la table parent doit être renseignée avant l'exportation d'une table enfant et doit contenir toutes les clés correspondantes. Toute tentative d'exportation d'une table enfant alors qu'une table parente ne dispose pas de l'ensemble complet des clés pertinentes échoue.

  • La durée maximale d'une tâche BigQuery, telle qu'une tâche d'extraction vers Spanner, est de six heures. Pour en savoir plus sur l'optimisation des tâches d'extraction volumineuses, consultez Optimisation de l'exportation. Vous pouvez également diviser l'entrée en blocs de données individuels, qui peuvent être exportés en tant que tâches d'extraction individuelles.

  • Les exportations vers Spanner ne sont compatibles qu'avec les éditions BigQuery Enterprise ou Enterprise Plus. L'édition Standard de BigQuery et le calcul à la demande ne sont pas compatibles.

  • Vous ne pouvez pas utiliser de requêtes continues pour exporter des données vers des tables Spanner avec des clés primaires générées automatiquement.

  • Vous ne pouvez pas utiliser de requêtes continues pour exporter des données vers des tables Spanner dans une base de données utilisant le dialecte PostgreSQL.

  • Lorsque vous utilisez des requêtes continues pour exporter des données vers une table Spanner, assurez-vous de choisir une clé primaire qui ne correspond pas à un entier croissant de manière monotone dans votre table BigQuery. Cela pourrait entraîner des problèmes de performances dans votre exportation. Pour en savoir plus sur les clés primaires dans Spanner et sur les moyens d'atténuer ces problèmes de performances, consultez Choisir une clé primaire.

Configurer des exportations avec l'option spanner_options

Vous pouvez utiliser l'option spanner_options pour spécifier une base de données et une table Spanner de destination. La configuration est exprimée sous la forme d'une chaîne JSON, comme le montre l'exemple suivant :

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",
   }"""
)

Remplacez les éléments suivants :

  • PROJECT_ID : nom de votre projet Google Cloud .
  • INSTANCE_ID : nom de votre instance de base de données.
  • DATABASE_ID : nom de votre base de données.
  • TABLE_NAME : nom d'une table de destination existante.
  • CHANGE_TIMESTAMP : nom de la colonne de type TIMESTAMP dans la table Spanner de destination. Cette option est utilisée lors de l'exportation pour suivre l'horodatage de la dernière mise à jour de ligne. Lorsque cette option est spécifiée, l'exportation effectue d'abord une lecture de la ligne dans la table Spanner, pour s'assurer que seule la dernière mise à jour de la ligne est écrite. Nous vous recommandons de spécifier une colonne de type TIMESTAMP lorsque vous exécutez une exportation continue, où l'ordre des modifications apportées aux lignes ayant la même clé primaire est important.
  • PRIORITY (facultatif) : priorité des requêtes d'écriture. Valeurs autorisées : LOW, MEDIUM, HIGH. Valeur par défaut : MEDIUM.
  • TAG (facultatif) : tag de requête permettant d'identifier le trafic de l'exportateur dans la surveillance Spanner. Valeur par défaut : bq_export.

Exigences de requêtes d'exportation

Pour exporter des résultats de requête vers Spanner, les résultats doivent répondre aux exigences suivantes :

  • Toutes les colonnes de l'ensemble de résultats doivent exister dans la table de destination, et leurs types doivent correspondre ou être convertibles.
  • L'ensemble de résultats doit contenir toutes les colonnes NOT NULL pour la table de destination.
  • Les valeurs de colonne ne doivent pas dépasser les limites de taille des données dans les tables de Spanner.
  • Tous les types de colonne non compatibles doivent être convertis en l'un des types compatibles avant l'exportation vers Spanner.

Conversions de types

Pour faciliter l'utilisation, l'exportateur Spanner applique automatiquement les conversions de type suivantes :

Type BigQuery Type Spanner
BIGNUMERIC NUMERIC (dialecte PostgreSQL uniquement)
FLOAT64 FLOAT32
BYTES PROTO
INT64 ENUM

Exporter les données

Vous pouvez utiliser l'instruction EXPORT DATA pour exporter les données d'une table BigQuery vers une table Spanner.

L'exemple suivant exporte les champs sélectionnés à partir d'une table nommée 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;

Remplacez les éléments suivants :

  • PROJECT_ID : nom de votre projet Google Cloud
  • INSTANCE_ID : nom de votre instance de base de données
  • DATABASE_ID : nom de votre base de données
  • TABLE_NAME : nom d'une table de destination existante.

Exporter plusieurs résultats avec la même valeur rowkey

Lorsque vous exportez un résultat contenant plusieurs lignes avec la même valeur rowkey, les valeurs écrites dans Spanner se retrouvent dans la même ligne Spanner. Une seule ligne BigQuery correspondante (dont on ne peut pas garantir l'identité) sera présente dans l'ensemble de lignes Spanner produit par l'exportation.

Exporter en continu

Pour traiter en continu une requête d'exportation, consultez Créer des requêtes continues pour obtenir des instructions et un exemple de code.

Optimisation des exportations

Pour optimiser l'exportation d'enregistrements de BigQuery vers Spanner, essayez ces solutions :

  • Augmentez le nombre de nœuds dans l'instance de destination Spanner. Au début de l'exportation, l'augmentation du nombre de nœuds de l'instance peut ne pas entraîner immédiatement une augmentation du débit d'exportation. Un léger délai peut survenir lorsque Spanner effectue une division basée sur la charge. Avec la répartition basée sur la charge, le débit d'exportation augmente et se stabilise. L'instruction EXPORT DATA permet de regrouper les données par lot pour optimiser les écritures dans Spanner. Pour en savoir plus, consultez la présentation des performances.

  • Spécifiez la priorité HIGH dans spanner_options. Si l'autoscaling est activé pour votre instance Spanner, la définition de la priorité HIGH permet de s'assurer que l'utilisation du processeur atteint le seuil nécessaire pour déclencher le scaling. Cela permet au scaler automatique d'ajouter des ressources de calcul en réponse à la charge d'exportation, ce qui peut améliorer le débit global des exportations.

    L'exemple suivant montre une commande d'exportation Spanner définie sur la priorité 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" }"""
)

  • Évitez de trier les résultats de la requête. Si l'ensemble de résultats contient toutes les colonnes de clé primaire, l'exportateur trie automatiquement les clés primaires de la table de destination pour simplifier les écritures et minimiser les conflits.

    Si la clé primaire de la table de destination inclut des colonnes générées, ajoutez les expressions de ces colonnes à la requête pour vous assurer que les données exportées sont correctement triées et regroupées par lots.

    Par exemple, dans le schéma Spanner suivant, SaleYear et SaleMonth sont des colonnes générées qui constituent le début de la clé primaire 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);

    Lorsque vous exportez des données de BigQuery vers une table Spanner avec des colonnes générées utilisées dans la clé primaire, il est recommandé, mais pas obligatoire, d'inclure les expressions de ces colonnes générées dans votre requête EXPORT DATA. Cela permet à BigQuery de pré-trier correctement les données, ce qui est essentiel pour un traitement par lots et une écriture efficaces dans Spanner. Les valeurs des colonnes générées dans l'instruction EXPORT DATA ne sont pas validées dans Spanner, car elles sont générées automatiquement par Spanner, mais elles sont utilisées pour optimiser l'exportation.

    L'exemple suivant exporte des données vers une table Sales Spanner dont la clé primaire utilise des colonnes générées. Pour optimiser les performances d'écriture, la requête inclut des expressions EXTRACT qui correspondent aux colonnes SaleYear et SaleMonth générées, ce qui permet à BigQuery de pré-trier les données avant l'exportation :

    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;

  • Pour éviter les tâches de longue durée, exportez les données par partition. Partitionnez vos données BigQuery à l'aide d'une clé de partitionnement, telle qu'un code temporel dans votre requête :

    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';

    Cela permet à la requête de s'exécuter dans le délai de six heures. Pour en savoir plus sur ces limites, consultez la section Limites des jobs de requête.

  • Pour améliorer les performances de chargement des données, supprimez l'index dans la table Spanner dans laquelle les données sont importées. Ensuite, recréez-le une fois l'importation terminée.

  • Nous vous recommandons de commencer par un nœud Spanner (1 000 unités de processeur) et une réservation de emplacement BigQuery minimale. Par exemple, 100 emplacements ou 0 emplacements de référence avec autoscaling. Pour les exportations de moins de 100 Go, cette configuration se termine généralement dans la limite de six heures. Pour les exportations de plus de 100 Go, augmentez le débit en augmentant le nombre de nœuds Spanner et de réservations d'emplacement BigQuery, si nécessaire. Le débit est d'environ 5 Mio/s par nœud.

Tarifs

Lorsque vous exportez des données vers Spanner à l'aide de l'instruction EXPORT DATA, la tarification des calculs de capacité BigQuery s'applique.

Pour exporter en continu vers Spanner à l'aide d'une requête continue, vous devez disposer d'une réservation d'emplacements BigQuery Enterprise ou Enterprise Plus et d'une attribution de réservation qui utilise le type de job CONTINUOUS.

Les exportations BigQuery vers Spanner qui franchissent les limites régionales sont facturées selon les tarifs d'extraction de données. Pour en savoir plus, consultez la page relative aux tarifs de BigQuery. Pour éviter les frais de transfert de données, assurez-vous que votre exportation BigQuery s'exécute dans la même région que le leader par défaut Spanner. Les exportations de requêtes continues ne sont pas compatibles avec les exportations qui franchissent les limites régionales.

Une fois les données exportées, leur stockage dans Spanner vous est facturé. Pour en savoir plus, consultez la page Tarifs de Spanner.