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

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

Les utilisateurs de BigQuery peuvent configurer un workflow RETL sur Bigtable qui combine les fonctionnalités d'analyse de BigQuery avec la faible latence et le haut débit de Bigtable. Ce workflow vous permet de diffuser des données aux utilisateurs de l'application sans épuiser les quotas et les limites sur BigQuery.

Caractéristiques des tables Bigtable

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

  • Les tables Bigtable et BigQuery sont composées de lignes, mais une ligne Bigtable est composée de clés de ligne et de familles de colonnes ayant 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, il n'est pas nécessaire de spécifier des colonnes qui lui appartiennent.
  • 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 pour 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

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 section Gérer les accès.

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

Limites

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.

Par 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.

Par 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 acceptés sont semblables à la lecture 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. L'exportation d'une valeur NULL pour une famille de colonnes et une colonne données dans Bigtable supprime les valeurs actuelles d'une ligne Bigtable.

  • Si une valeur Bigtable avec une clé de ligne, une famille de colonnes, un qualificatif de colonne et un horodatage donnés n'existent 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) AS column_family1 FROM T

  • Les lignes contenant NULL clés de ligne 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 :

Field name 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 pas de code non UTF-8. Les champs qualifierString et qualifierEncoding s'excluent mutuellement. Si vous ne spécifiez ni qualifierString, ni qualifierEncoded, fieldName est utilisé comme qualificatif de colonne.
columnFamilies.columns.qualifierEncoded Facultatif : Qualificatif de colonne encodé en base64. Semblable à qualifierString si le qualificatif de colonne doit comporter des codes non 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 d'ensemble de résultats doit correspondre à 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 page Configurer des exportations avec bigtable_options.

Si vous utilisez des valeurs exportées avec les 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 product amount order_time
1970-01-01T00:00:00Z Joystick 1970-01-01T00:00:00Z 2 1680000054000

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

Définir l'horodatage 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 d'horodatage indiquée dans le champ _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 l'horodatage 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 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 colonnes sur la même ligne. Dans cet exemple, la table orders de BigQuery contient les données suivantes :

id customer order_timestamp amount_spent
100 Robert 2023-01-01T10:10:54Z 10.99
101 Alice 2023-01-02T12:10:50Z 102.7
102 Robert 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
Robert 2023-01-01T10:10:54Z 10.99
2023-01-04T15:17:01Z 11.1

L'exportation vers Bigtable fusionne de 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, les nouvelles valeurs peuvent remplacer partiellement ou complètement les valeurs antérieures en fonction de la famille de colonnes, des noms de colonnes et des horodatages 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 en tant que Protobuf peut être utile en tenant compte de la gestion des différents types entre BigQuery et Bigtable. Vous pouvez utiliser des fonctions définies par l'utilisateur BigQuery pour exporter des données en tant que valeurs binaires Protobuf vers Bigtable. Pour en savoir plus, consultez la section Exporter des données sous forme de colonnes Protobuf.

Optimisation des exportations

Il existe plusieurs façons d'augmenter le débit auquel les enregistrements sont exportés de BigQuery vers Bigtable. Vous pouvez optimiser vos performances d'exportation de différentes manières:

Tarification

Pour en savoir plus sur la tarification de l'exportation de données, consultez la page Tarifs de BigQuery.

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