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

Ce document explique comment configurer le processus ETL inversé (RETL) depuis BigQuery vers Bigtable. Pour ce faire, utilisez l'instruction EXPORT DATA pour exporter les données d'une table BigQuery vers une table Bigtable.

Vous pouvez utiliser un workflow RETL vers Bigtable afin de combiner les fonctionnalités d'analyse de BigQuery avec la faible latence et le débit élevé de Bigtable. Ce workflow vous permet de diffuser des données aux utilisateurs de l'application sans épuiser les quotas et limites de BigQuery.

Caractéristiques des tables Bigtable

Les tables Bigtable présentent plusieurs différences avec les tables BigQuery :

  • Les tables Bigtable et BigQuery sont toutes deux composées de lignes, mais une ligne Bigtable est composée de clés de ligne et de familles de colonnes comportant un nombre arbitraire de colonnes appartenant à la même famille de colonnes.
  • Les familles de colonnes d'une table donnée sont créées en même temps que la table, mais elles peuvent également être ajoutées ou supprimées ultérieurement. Lorsqu'une famille de colonnes est créée, les colonnes qui lui appartiennent n'ont pas besoin d'être spécifiées.
  • Les colonnes Bigtable n'ont pas besoin d'être définies à l'avance et peuvent être utilisées pour stocker des données dans leur nom (également appelé qualificatif) au sein des limites de taille des données dans les tables.
  • Les colonnes Bigtable peuvent avoir n'importe quelle valeur binaire au sein des limites de taille des données dans les tables.
  • Les colonnes Bigtable ont toujours une dimension temporelle (également appelée version). Un nombre quelconque de valeurs peut être stocké dans n'importe quelle ligne pour la même colonne, à condition que l'horodatage ne soit pas identique.
  • L'horodatage Bigtable est mesuré en microsecondes depuis l'époque Unix. Par exemple, 0 représente 1970-01-01T00:00:00 UTC. Les horodatages doivent être un nombre non négatif de microsecondes avec une précision à la milliseconde (seuls les multiples de 1 000 us sont acceptés). Par défaut, l'horodatage Bigtable est 0.
  • Dans Bigtable, les données sont lues par clé de ligne, plusieurs clés de ligne, plage de clés de ligne ou à l'aide d'un filtre. Au moins une clé de ligne ou une plage de clés de ligne est requise dans tous les types de requêtes de lecture, à l'exception de l'analyse complète de la table.

Pour en savoir plus sur la préparation des résultats BigQuery à exporter vers Bigtable, consultez la page Préparer les résultats des requêtes pour l'exportation.

Avant de commencer

Vous devez créer une instance Bigtable et une table Bigtable pour recevoir les données exportées.

Attribuez aux utilisateurs des rôles IAM (Identity and Access Management) incluant les autorisations nécessaires pour effectuer l'ensemble des tâches du présent document.

Rôles requis

Pour obtenir les autorisations nécessaires à l'exportation des données BigQuery vers Bigtable, 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 la page 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

Considérations relatives aux emplacements

  • Si votre ensemble de données BigQuery se trouve dans une zone multirégionale, votre profil d'application Bigtable doit être configuré pour acheminer les données vers un cluster Bigtable dans cette zone multirégionale. Par exemple, si votre ensemble de données BigQuery se trouve dans la zone multirégionale US, le cluster Bigtable peut être situé dans la région us-west1 (Oregon), qui se trouve aux États-Unis.
  • Si votre ensemble de données BigQuery se trouve dans une seule région, votre profil d'application Bigtable doit être configuré pour acheminer les données vers un cluster Bigtable de la même région. Par exemple, si votre ensemble de données BigQuery se trouve dans la région asia-northeast1 (Tokyo), votre cluster Bigtable doit également se trouver dans la région asia-northeast1 (Tokyo).

Pour en savoir plus, consultez la page Zones Bigtable.

Types BigQuery compatibles

Les types de données suivants sont acceptés lorsqu'ils sont écrits dans Bigtable :

Type BigQuery Valeur Bigtable écrite
BYTES Exportée telle quelle.
STRING Convertie en BYTES
INTEGER Si bigtable_options.column_families.encoding est défini sur BINARY, la valeur est écrite dans un format big-endian de 8 octets (l'octet le plus important en premier). Si bigtable_options.column_families.encoding est défini sur TEXT, la valeur est écrite sous la forme d'une chaîne lisible par l'humain représentant un nombre.
FLOAT Écrit une valeur au format de sortie IEEE 754 de 8 octets.
BOOLEAN Si bigtable_options.column_families.encoding est défini sur BINARY, la valeur est écrite sous la forme d'une valeur de 1 octet (false = 0x00 ou true = 0x01). Si bigtable_options.column_families.encoding est défini sur TEXT, la valeur est écrite sous forme de texte ("true" ou "false").
JSON
Une colonne exportée de type JSON est interprétée comme un groupe de colonnes appartenant à une famille de colonnes Bigtable spécifique. Les membres de l'objet JSON sont interprétés comme des colonnes et leurs valeurs doivent être écrites dans Bigtable. Le nom de la colonne à écrire peut être ajusté à l'aide de la configuration bigtable_options.

Exemple :
    JSON '{"FIELD1": "VALUE1", "FIELD2": "VALUE2"}' as MY_COLUMN_FAMILY
Où les valeurs VALUE1 et VALUE2 sont écrites dans Bigtable en tant que colonnes FIELD1 et FIELD2 dans la famille de colonnes MY_COLUMN_FAMILY.
STRUCT
Une colonne exportée de type STRUCT est interprétée comme un groupe de colonnes appartenant à une famille de colonnes Bigtable spécifique. Les membres de la structure sont interprétés comme des colonnes et leurs valeurs à écrire dans Bigtable. Le nom de la colonne à écrire peut être ajusté à l'aide de la configuration bigtable_options.

Exemple :
    STRUCT<FIELD1  STRING, FIELD2 INTEGER> as MY_COLUMN_FAMILY
Où les valeurs FIELD1 et FIELD2 sont écrites dans Bigtable en tant que colonnes FIELD1 et FIELD2 dans la famille de colonnes MY_COLUMN_FAMILY.

Ces types de données compatibles sont semblables à la lecture à partir de tables Bigtable externes pour BigQuery.

Valeurs NULL dans Bigtable

Les valeurs NULL dans Bigtable présentent les contraintes suivantes :

  • Bigtable n'a pas d'équivalent pour les valeurs NULL. Exporter une valeur NULL pour une famille de colonnes et une colonne données dans Bigtable supprime les valeurs actuelles à partir d'une ligne Bigtable.

  • Si une valeur Bigtable dotée d'une clé de ligne, d'une famille de colonnes, d'un qualificatif de colonne et d'un code temporel donnés n'existe pas avant l'exportation, les valeurs NULL exportées n'ont aucun effet sur la ligne Bigtable.

  • Lors de l'exportation d'une valeur NULL de type STRUCT ou JSON, toutes les valeurs de colonne appartenant à la famille de colonnes correspondante de la ligne concernée sont supprimées. Vous devez convertir la valeur NULL en fonction du type STRUCT ou JSON pour que le moteur SQL lui associe un type approprié. La requête suivante supprime toutes les données de la famille de colonnes column_family1 avec un ensemble de clés de ligne données :

    EXPORT DATA OPTIONS (...) AS
SELECT
  rowkey,
CAST(NULL as STRUCT<INT64>) AS column_family1 FROM T

  • Les lignes ayant des clés de ligne NULL sont ignorées lors de l'exportation. Le nombre de lignes ignorées est renvoyé à l'appelant dans les statistiques d'exportation.

Configurer des exportations avec bigtable_options

Vous pouvez utiliser la configuration bigtable_options lors d'une exportation pour combler les différences entre les modèles de stockage BigQuery et Bigtable. La configuration est exprimée sous la forme d'une chaîne JSON, comme illustré dans l'exemple suivant :

EXPORT DATA OPTIONS(
   uri="https://bigtable.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/appProfiles/APP_PROFILE_ID/tables/TABLE",
   bigtable_options = """{
     "columnFamilies": [{
       "familyId": "COLUMN_FAMILY_NAME",
       "encoding": "ENCODING_VALUE",
       "columns": [
         {
           "qualifierString": "BIGTABLE_COLUMN_QUALIFIER",
           ["qualifierEncoded": "BASE_64_ENCODED_VALUE",]
           "fieldName": "BIGQUERY_RESULT_FIELD_NAME"
         }
       ]
    }]
   }"""
)

Le tableau suivant décrit les champs possibles utilisés dans une configuration bigtable_options :

Nom du champ Description
columnFamilies Tableau de descripteurs de famille de colonnes.
columnFamilies.familyId Identifiant de famille de colonnes Bigtable.
columnFamilies.encoding La valeur peut être définie sur BINARY ou TEXT. Pour en savoir plus sur l'encodage des types, consultez la section Types BigQuery compatibles.
columnFamilies.columns Tableau de mappages de colonnes Bigtable.
columnFamilies.columns.qualifierString Facultatif : qualificatif de colonne Bigtable. Spécifiez cette valeur si le qualificatif de colonne ne comporte aucun code non UTF-8. Les champs qualifierString et qualifierEncoding sont mutuellement exclusifs. Si ni qualifierString, ni qualifierEncoded ne sont spécifiés, fieldName est utilisé comme qualificatif de colonne.
columnFamilies.columns.qualifierEncoded Facultatif : Qualificatif de colonne encodé en base64. Semblable à qualifierString dans le cas où le qualificatif de colonne doit avoir des codes autres que UTF-8.
columnFamilies.columns.fieldName Obligatoire : Nom du champ de l'ensemble de résultats BigQuery. Dans certains cas, peut être une chaîne vide. Pour obtenir un exemple d'utilisation d'une valeur fieldName vide avec des champs de types simples, consultez la section Préparer les résultats des requêtes pour l'exportation.

Préparer les résultats des requêtes pour l'exportation

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

  • L'ensemble de résultats doit contenir une colonne rowkey de type STRING ou BYTES.
  • Les clés de ligne, les qualificatifs de colonnes, les valeurs et les horodatages ne doivent pas dépasser les limites de taille des données dans les tables.
  • Au moins une colonne autre que rowkey doit être présente dans l'ensemble de résultats.
  • Chaque colonne de l'ensemble de résultats doit appartenir à l'un des types BigQuery compatibles. Tous les types de colonne non compatibles doivent être convertis en l'un des types compatibles avant l'exportation vers Bigtable.

Bigtable ne nécessite pas que les qualificatifs de colonne soient des noms de colonnes BigQuery valides, et Bigtable accepte l'utilisation d'octets. Pour en savoir plus sur le remplacement des qualificatifs de colonnes cibles pour une exportation, consultez la section Configurer des exportations avec bigtable_options.

Si vous utilisez des valeurs exportées avec des API Bigtable, telles que ReadModifyWriteRow, toutes les valeurs numériques doivent utiliser l'encodage binaire approprié.

Par défaut, les colonnes de résultats autonomes de type autre que STRUCT ou JSON sont interprétées comme des valeurs pour les familles de colonnes de destination égales au nom de la colonne de résultat, et le qualificatif de colonne est égal à une chaîne vide.

Pour illustrer la façon dont ces types de données sont écrits, considérons l'exemple SQL suivant, dans lequel column et column2 sont des colonnes de résultats autonomes :

SELECT
  x as column1, y as column2
FROM table

Dans cet exemple de requête, SELECT x as column1 écrit des valeurs dans Bigtable sous la famille de colonnes column1 et '' (chaîne vide) dans le qualificatif de colonne lors du traitement de types autres que JSON ou STRUCT.

Vous pouvez modifier la façon dont ces types sont écrits dans une exportation à l'aide de la configuration bigtable_options, comme le montre l'exemple suivant :

EXPORT DATA OPTIONS (
  …
  bigtable_options="""{
   "columnFamilies" : [
      {
        "familyId": "ordered_at",
        "columns": [
           {"qualifierString": "order_time", "fieldName": ""}
        ]
      }
   ]
}"""
) AS
SELECT
  order_id as rowkey,
  STRUCT(product, amount) AS sales_info,
  EXTRACT (MILLISECOND FROM order_timestamp AT TIME ZONE "UTC") AS ordered_at
FROM T

Dans cet exemple, la table BigQuery T contient la ligne suivante :

order_id order_timestamp product amount
101 2023-03-28T10:40:54Z Joystick 2

Si vous utilisez la configuration bigtable_options précédente avec la table T, les données suivantes sont écrites dans Bigtable :

rowkey sales_info (famille de colonnes) ordered_at (famille de colonnes)
101 produit amount order_time
1970-01-01T00:00:00Z Joystick 1970-01-01T00:00:00Z 2 1680000054000

1680000054000 représente 2023-03-28T10:40:54Z en millisecondes depuis l'epoch Unix dans le fuseau horaire UTC.

Définir le code temporel pour toutes les cellules d'une ligne à l'aide de _CHANGE_TIMESTAMP

Vous pouvez ajouter une colonne _CHANGE_TIMESTAMP de type TIMESTAMP au résultat d'exportation. Chaque cellule écrite dans Bigtable utilise la valeur du code temporel de _CHANGE_TIMESTAMP de la ligne de résultat exportée.

Bigtable n'accepte pas les horodatages antérieurs à l'époque Unix (1970-01-01T00:00:00Z). Si la valeur _CHANGE_TIMESTAMP est définie sur NULL, l'epoch Unix de 0 est utilisé comme valeur d'horodatage par défaut.

La requête suivante écrit des cellules pour les colonnes product et amount avec le code temporel spécifié dans la colonne order_timestamp de la table T.

EXPORT DATA OPTIONS (...) AS
SELECT
  rowkey,
  STRUCT(product, amount) AS sales_info,
  order_timestamp as _CHANGE_TIMESTAMP
FROM T

Exporter en continu

Si vous souhaitez traiter en continu une requête d'exportation, vous pouvez la configurer en tant que requête continue.

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 Bigtable se retrouvent dans la même ligne Bigtable.

Vous pouvez utiliser cette méthode pour générer plusieurs versions de valeurs de colonne dans la même ligne. Dans cet exemple, la table orders de BigQuery contient les données suivantes :

id customer order_timestamp amount_spent
100 Bob 2023-01-01T10:10:54Z 10.99
101 Alice 2023-01-02T12:10:50Z 102.7
102 Bob 2023-01-04T15:17:01Z 11.1

L'utilisateur exécute ensuite l'instruction EXPORT DATA suivante :

EXPORT DATA OPTIONS (
uri="https://bigtable.googleapis.com/projects/PROJECT-ID/instances/INSTANCE-ID/appProfiles/APP_PROFILE_ID/tables/TABLE",
format="CLOUD_BIGTABLE"
) AS
SELECT customer as rowkey, STRUCT(amount_spent) as orders_column_family, order_timestamp as _CHANGE_TIMESTAMP
FROM orders

L'utilisation de cette instruction avec la table BigQuery orders entraîne l'écriture des données suivantes dans Bigtable :

orders_column_family
Clé de ligne amount_spent
Alice 2023-01-02T12:10:50Z 102.7
Bob 2023-01-01T10:10:54Z 10.99
2023-01-04T15:17:01Z 11.1

L'exportation vers Bigtable fusionne les nouvelles valeurs dans la table au lieu de remplacer des lignes entières. Si des valeurs sont déjà présentes dans Bigtable pour une clé de ligne, de nouvelles valeurs peuvent remplacer partiellement ou entièrement les valeurs précédentes en fonction de la famille de colonnes, des noms de colonnes et des codes temporels des cellules en cours d'écriture.

Exporter plusieurs colonnes en tant que valeurs du tampon de protocole (Protobuf)

Les tampons de protocole représentent un mécanisme flexible et efficace pour sérialiser des données structurées. L'exportation au format Protobuf peut être utile compte tenu de la manière dont les différents types sont gérés entre BigQuery et Bigtable. Vous pouvez utiliser des fonctions définies par l'utilisateur (UDF) BigQuery pour exporter des données sous forme de valeurs binaires Protobuf vers Bigtable. Pour en savoir plus, consultez la section Exporter des données sous forme de colonnes Protobuf.

Optimisation des exportations

Vous pouvez modifier le débit auquel les enregistrements sont exportés de BigQuery vers Bigtable en modifiant le nombre de nœuds dans le cluster de destination Bigtable. Le débit (en lignes écrites par seconde) évolue de manière linéaire avec le nombre de nœuds du cluster de destination. Par exemple, si vous doublez le nombre de nœuds dans votre cluster de destination, votre débit d'exportation double à peu près.

Tarifs

Lorsque vous exportez des données dans une requête standard, vous êtes facturé selon la tarification de l'extraction de données. Lorsque vous exportez des données dans une requête continue, la tarification des calculs de capacité BigQuery s'applique. Pour exécuter des requêtes continues, vous devez disposer d'une réservation qui utilise l'édition Enterprise ou Enterprise Plus et d'une attribution de réservation qui utilise le type de job CONTINUOUS.

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