Utiliser le connecteur Bigtable Spark

Le connecteur Bigtable Spark vous permet de lire et d'écrire des données vers et depuis Bigtable. Vous pouvez lire les données de votre application Spark à l'aide de Spark SQL et des DataFrames. Les opérations Bigtable suivantes sont compatibles avec le connecteur Spark Bigtable :

• Écrire des données
• Lire des données
• Créer une table

Ce document vous explique comment convertir une table Spark SQL DataFrames en table Bigtable, puis comment compiler et créer un fichier JAR pour envoyer un job Spark.

État de la compatibilité avec Spark et Scala

Le connecteur Bigtable Spark est compatible avec les versions Scala suivantes :

• 2.12
• 2.13

Le connecteur Bigtable Spark est compatible avec les versions Spark suivantes :

• 2.4.8
• 3.2.x
• 3.3.x
• 3.4.x
• 3.5.x

Le connecteur Bigtable Spark est compatible avec les versions Dataproc suivantes :

• Cluster de version d'image 1.5
• Cluster de version d'image 2.0
• 2.1 cluster image-version
• 2.2 Cluster image-version
• Version 1.0 du runtime Dataproc sans serveur

Calculer les coûts

Si vous décidez d'utiliser l'un des composants facturables suivants de Google Cloud, les ressources que vous utilisez vous seront facturées :

• Bigtable (l'utilisation de l'émulateur Bigtable n'entraîne pas de frais)
• Dataproc
• Cloud Storage

La tarification Dataproc s'applique à l'utilisation des clusters Dataproc sur Compute Engine. La tarification de Dataproc sans serveur s'applique aux charges de travail et aux sessions exécutées sur Dataproc sans serveur pour Spark.

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût.

Avant de commencer

Avant d'utiliser le connecteur Bigtable Spark, remplissez les conditions préalables suivantes.

Rôles requis

Pour obtenir les autorisations nécessaires à l'utilisation du connecteur Bigtable Spark, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

• Administrateur Bigtable (roles/bigtable.admin)(facultatif) : vous permet de lire ou d'écrire des données et de créer une table.
• Utilisateur Bigtable (roles/bigtable.user) : vous permet de lire ou d'écrire des données, mais pas de créer une table.

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 avec des rôles personnalisés ou d'autres rôles prédéfinis.

Si vous utilisez Dataproc ou Cloud Storage, des autorisations supplémentaires peuvent être requises. Pour en savoir plus, consultez les sections Autorisations Dataproc et Autorisations Cloud Storage.

Configurer Spark

En plus de créer une instance Bigtable, vous devez également configurer votre instance Spark. Vous pouvez le faire localement ou sélectionner l'une de ces options pour utiliser Spark avec Dataproc :

• Cluster Dataproc
• Dataproc sans serveur

Pour en savoir plus sur le choix entre un cluster Dataproc et une option sans serveur, consultez la documentation Comparaison entre Dataproc sans serveur pour Spark et Dataproc sur Compute Engine .

Télécharger le fichier JAR du connecteur

Vous trouverez le code source du connecteur Spark Bigtable avec des exemples dans le dépôt GitHub du connecteur Spark Bigtable.

En fonction de votre configuration Spark, vous pouvez accéder au fichier JAR comme suit :

• Si vous exécutez PySpark localement, vous devez télécharger le fichier JAR du connecteur à partir de l'emplacement Cloud Storage gs://spark-lib/bigtable/spark-bigtable_SCALA_VERSION-CONNECTOR_VERSION.jar.

  Remplacez SCALA_VERSION par 2.12 ou 2.13, qui sont les seules versions Scala compatibles, et remplacez CONNECTOR_VERSION par la version du connecteur que vous souhaitez utiliser.

• Pour l'option de cluster ou sans serveur Dataproc, utilisez le dernier fichier JAR comme artefact pouvant être ajouté à vos applications Spark Scala ou Java. Pour en savoir plus sur l'utilisation du fichier JAR en tant qu'artefact, consultez Gérer les dépendances.

• Si vous envoyez votre tâche PySpark à Dataproc, utilisez l'indicateur gcloud dataproc jobs submit pyspark --jars pour définir l'URI sur l'emplacement du fichier JAR dans Cloud Storage (par exemple, gs://spark-lib/bigtable/spark-bigtable_SCALA_VERSION-CONNECTOR_VERSION.jar).

Déterminer le type de calcul

Pour les jobs en lecture seule, vous pouvez utiliser le calcul sans serveur Data Boost, qui vous permet d'éviter d'affecter vos clusters de diffusion d'applications. Votre application Spark doit utiliser la version 1.1.0 ou ultérieure du connecteur Spark pour utiliser Data Boost.

Pour utiliser Data Boost, vous devez créer un profil d'application Data Boost, puis fournir l'ID du profil d'application pour l'option Spark spark.bigtable.app_profile.id lorsque vous ajoutez votre configuration Bigtable à votre application Spark. Si vous avez déjà créé un profil d'application pour vos jobs de lecture Spark et que vous souhaitez continuer à l'utiliser sans modifier le code de votre application, vous pouvez le convertir en profil d'application Data Boost. Pour en savoir plus, consultez Convertir un profil d'application.

Pour en savoir plus, consultez la présentation de Bigtable Data Boost.

Pour les tâches impliquant des lectures et des écritures, vous pouvez utiliser les nœuds de cluster de votre instance pour le calcul en spécifiant un profil d'application standard avec votre requête.

Identifier ou créer un profil d'application à utiliser

Si vous ne spécifiez pas d'ID de profil d'application, le connecteur utilise le profil d'application par défaut.

Nous vous recommandons d'utiliser un profil d'application unique pour chaque application que vous exécutez, y compris votre application Spark. Pour en savoir plus sur les types et les paramètres de profils d'application, consultez Présentation des profils d'application. Pour obtenir des instructions, consultez Créer et configurer des profils d'application.

Ajouter la configuration Bigtable à votre application Spark

Dans votre application Spark, ajoutez les options Spark qui vous permettent d'interagir avec Bigtable.

Options Spark acceptées

Utilisez les options Spark disponibles dans le package com.google.cloud.spark.bigtable.

Créer des métadonnées de table au format JSON

Le format de table Spark SQL DataFrames doit être converti en table Bigtable à l'aide d'une chaîne au format JSON. Ce format JSON de chaîne rend le format de données compatible avec Bigtable. Vous pouvez transmettre le format JSON dans le code de votre application à l'aide de l'option .option("catalog", catalog_json_string).

Prenons comme exemple le tableau DataFrame suivant et le tableau Bigtable correspondant.

Dans cet exemple, les colonnes name et birthYear du DataFrame sont regroupées sous la famille de colonnes info et renommées respectivement name et birth_year. De même, la colonne address est stockée sous la famille de colonnes location avec le même nom de colonne. La colonne id du DataFrame est convertie en clé de ligne Bigtable.

Les clés de ligne n'ont pas de nom de colonne dédié dans Bigtable. Dans cet exemple, id_rowkey est utilisé uniquement pour indiquer au connecteur qu'il s'agit de la colonne de clé de ligne. Vous pouvez utiliser n'importe quel nom pour la colonne de clé de ligne. Assurez-vous d'utiliser le même nom lorsque vous déclarez le champ "rowkey":"column_name" au format JSON.

Le format JSON du catalogue est le suivant :

    """
    {
      "table": {"name": "t1"},
      "rowkey": "id_rowkey",
      "columns": {
        "id": {"cf": "rowkey", "col": "id_rowkey", "type": "string"},
        "name": {"cf": "info", "col": "name", "type": "string"},
        "birthYear": {"cf": "info", "col": "birth_year", "type": "long"},
        "address": {"cf": "location", "col": "address", "type": "string"}
      }
    }
    """

Voici les clés et les valeurs utilisées dans le format JSON :

Types de données acceptés

Le connecteur permet d'utiliser les types string, long et binary (tableau d'octets) dans le catalogue. En attendant que la compatibilité avec d'autres types tels que int et float soit ajoutée, vous pouvez convertir manuellement ces types de données en tableaux d'octets (BinaryType de Spark SQL) avant d'utiliser le connecteur pour les écrire dans Bigtable.

Vous pouvez également utiliser Avro pour sérialiser des types complexes, tels que ArrayType. Pour en savoir plus, consultez Sérialiser des types de données complexes à l'aide d'Apache Avro.

Écrire dans Bigtable

Utilisez la fonction .write() et les options compatibles pour écrire vos données dans Bigtable.

  String catalog = "{" +
        "\"table\":{\"name\":\"" + tableName + "\"," +
        "\"tableCoder\":\"PrimitiveType\"}," +
        "\"rowkey\":\"wordCol\"," +
        "\"columns\":{" +
        "\"word\":{\"cf\":\"rowkey\", \"col\":\"wordCol\", \"type\":\"string\"}," +
        "\"count\":{\"cf\":\"example_family\", \"col\":\"countCol\", \"type\":\"long\"}" +
        "}}".replaceAll("\\s+", "");

…

  private static void writeDataframeToBigtable(Dataset<Row> dataframe, String catalog,
        String createNewTable) {
      dataframe
          .write()
          .format("bigtable")
          .option("catalog", catalog)
          .option("spark.bigtable.project.id", projectId)
          .option("spark.bigtable.instance.id", instanceId)
          .option("spark.bigtable.create.new.table", createNewTable)
          .save();
    }

  catalog = ''.join(("""{
        "table":{"name":" """ + bigtable_table_name + """
        ", "tableCoder":"PrimitiveType"},
        "rowkey":"wordCol",
        "columns":{
          "word":{"cf":"rowkey", "col":"wordCol", "type":"string"},
          "count":{"cf":"example_family", "col":"countCol", "type":"long"}
        }
        }""").split())
  …

  input_data = spark.createDataFrame(data)
  print('Created the DataFrame:')
  input_data.show()

  input_data.write \
        .format('bigtable') \
        .options(catalog=catalog) \
        .option('spark.bigtable.project.id', bigtable_project_id) \
        .option('spark.bigtable.instance.id', bigtable_instance_id) \
        .option('spark.bigtable.create.new.table', create_new_table) \
        .save()
  print('DataFrame was written to Bigtable.')

  …

Lire à partir de Bigtable

Utilisez la fonction .read() pour vérifier que la table a bien été importée dans Bigtable.

  …
  private static Dataset<Row> readDataframeFromBigtable(String catalog) {
      Dataset<Row> dataframe = spark
          .read()
          .format("bigtable")
          .option("catalog", catalog)
          .option("spark.bigtable.project.id", projectId)
          .option("spark.bigtable.instance.id", instanceId)
          .load();
      return dataframe;
    }

  …

  records = spark.read \
        .format('bigtable') \
        .option('spark.bigtable.project.id', bigtable_project_id) \
        .option('spark.bigtable.instance.id', bigtable_instance_id) \
        .options(catalog=catalog) \
        .load()

  print('Reading the DataFrame from Bigtable:')
  records.show()

Compiler votre projet

Générez le fichier JAR utilisé pour exécuter un job dans un cluster Dataproc, Dataproc sans serveur ou une instance Spark locale. Vous pouvez compiler le fichier JAR localement, puis l'utiliser pour envoyer un job. Le chemin d'accès au fichier JAR compilé est défini comme variable d'environnement PATH_TO_COMPILED_JAR lorsque vous envoyez un job.

Cette étape ne s'applique pas aux applications PySpark.

Gérer les dépendances

Le connecteur Bigtable Spark est compatible avec les outils de gestion des dépendances suivants :

• Maven
• sbt
• Gradle

Compiler le fichier JAR

Envoyer une tâche

Envoyez un job Spark à l'aide de Dataproc, Dataproc sans serveur ou d'une instance Spark locale pour lancer votre application.

Définir l'environnement d'exécution

Définissez les variables d'environnement suivantes.

      #Google Cloud
      export BIGTABLE_SPARK_PROJECT_ID=PROJECT_ID
      export BIGTABLE_SPARK_INSTANCE_ID=INSTANCE_ID
      export BIGTABLE_SPARK_TABLE_NAME=TABLE_NAME
      export BIGTABLE_SPARK_DATAPROC_CLUSTER=DATAPROC_CLUSTER
      export BIGTABLE_SPARK_DATAPROC_REGION=DATAPROC_REGION
      export BIGTABLE_SPARK_DATAPROC_ZONE=DATAPROC_ZONE

      #Dataproc Serverless
      export BIGTABLE_SPARK_SUBNET=SUBNET
      export BIGTABLE_SPARK_GCS_BUCKET_NAME=GCS_BUCKET_NAME

      #Scala/Java
      export PATH_TO_COMPILED_JAR=PATH_TO_COMPILED_JAR

      #PySpark
      export GCS_PATH_TO_CONNECTOR_JAR=GCS_PATH_TO_CONNECTOR_JAR
      export PATH_TO_PYTHON_FILE=PATH_TO_PYTHON_FILE
      export LOCAL_PATH_TO_CONNECTOR_JAR=LOCAL_PATH_TO_CONNECTOR_JAR

Remplacez les éléments suivants :

• PROJECT_ID : identifiant permanent du projet Bigtable.
• INSTANCE_ID : identifiant permanent de l'instance Bigtable.
• TABLE_NAME : identifiant permanent de la table.
• DATAPROC_CLUSTER : identifiant permanent du cluster Dataproc.
• DATAPROC_REGION : région Dataproc contenant l'un des clusters de votre instance Dataproc (par exemple, northamerica-northeast2).
• DATAPROC_ZONE : zone dans laquelle le cluster Dataproc est exécuté.
• SUBNET : chemin d'accès complet à la ressource du sous-réseau.
• GCS_BUCKET_NAME : bucket Cloud Storage pour importer les dépendances de charge de travail Spark.
• PATH_TO_COMPILED_JAR : chemin d'accès complet ou relatif au fichier JAR compilé (par exemple, /path/to/project/root/target/<compiled_JAR_name> pour Maven).
• GCS_PATH_TO_CONNECTOR_JAR : bucket gs://spark-lib/bigtable Cloud Storage où se trouve le fichier spark-bigtable_SCALA_VERSION-CONNECTOR_VERSION.jar.
• PATH_TO_PYTHON_FILE : pour les applications PySpark, chemin d'accès au fichier Python qui sera utilisé pour écrire des données dans Bigtable et en lire.
• LOCAL_PATH_TO_CONNECTOR_JAR : pour les applications PySpark, chemin d'accès au fichier JAR du connecteur Bigtable Spark téléchargé.

Envoyer une tâche Spark

Pour les instances Dataproc ou votre configuration Spark locale, exécutez un job Spark pour importer des données dans Bigtable.

Cluster Dataproc

Utilisez le fichier JAR compilé et créez un job de cluster Dataproc qui lit et écrit des données depuis et vers Bigtable.

1. Créez un cluster Dataproc. L'exemple suivant montre un exemple de commande permettant de créer un cluster Dataproc 2.0 avec Debian 10, deux nœuds de calcul et des configurations par défaut.

   gcloud dataproc clusters create \
     $BIGTABLE_SPARK_DATAPROC_CLUSTER --region $BIGTABLE_SPARK_DATAPROC_REGION \
     --zone $BIGTABLE_SPARK_DATAPROC_ZONE \
     --master-machine-type n2-standard-4 --master-boot-disk-size 500 \
     --num-workers 2 --worker-machine-type n2-standard-4 --worker-boot-disk-size 500 \
     --image-version 2.0-debian10 --project $BIGTABLE_SPARK_PROJECT_ID
   

2. Envoyez une tâche.

   Scala/Java

   L'exemple suivant montre la classe spark.bigtable.example.WordCount qui inclut la logique permettant de créer une table de test dans DataFrame, d'écrire la table dans Bigtable, puis de compter le nombre de mots dans la table.

       gcloud dataproc jobs submit spark \
       --cluster=$BIGTABLE_SPARK_DATAPROC_CLUSTER \
       --region=$BIGTABLE_SPARK_DATAPROC_REGION \
       --class=spark.bigtable.example.WordCount \
       --jar=$PATH_TO_COMPILED_JAR \
       -- \
       $BIGTABLE_SPARK_PROJECT_ID \
       $BIGTABLE_SPARK_INSTANCE_ID \
       $BIGTABLE_SPARK_TABLE_NAME \
   

   PySpark

       gcloud dataproc jobs submit pyspark \
       --cluster=$BIGTABLE_SPARK_DATAPROC_CLUSTER \
       --region=$BIGTABLE_SPARK_DATAPROC_REGION \
       --jars=$GCS_PATH_TO_CONNECTOR_JAR \
       --properties='spark.jars.packages=org.slf4j:slf4j-reload4j:1.7.36' \
       $PATH_TO_PYTHON_FILE \
       -- \
       --bigtableProjectId=$BIGTABLE_SPARK_PROJECT_ID \
       --bigtableInstanceId=$BIGTABLE_SPARK_INSTANCE_ID \
       --bigtableTableName=$BIGTABLE_SPARK_TABLE_NAME \
   

Dataproc sans serveur

Utilisez le fichier JAR compilé et créez un job Dataproc qui lit et écrit des données depuis et vers Bigtable avec une instance Dataproc Serverless.

  gcloud dataproc batches submit spark \
  --region=$BIGTABLE_SPARK_DATAPROC_REGION \
  --subnet=$BIGTABLE_SPARK_SUBNET --version=1.1 \
  --deps-bucket=gs://$BIGTABLE_SPARK_GCS_BUCKET_NAME --jar=$PATH_TO_COMPILED_JAR \
  --  \
  $BIGTABLE_SPARK_PROJECT_ID \
  $BIGTABLE_SPARK_INSTANCE_ID \
  $BIGTABLE_SPARK_TABLE_NAME

  gcloud dataproc batches submit pyspark $PATH_TO_PYTHON_FILE \
  --region=$BIGTABLE_SPARK_DATAPROC_REGION \
  --subnet=$BIGTABLE_SPARK_SUBNET --version=1.1 \
  --deps-bucket=gs://$BIGTABLE_SPARK_GCS_BUCKET_NAME \
  --jars=$GCS_PATH_TO_CONNECTOR_JAR \
  --properties='spark.jars.packages=org.slf4j:slf4j-reload4j:1.7.36' \
  -- \
  --bigtableProjectId=$BIGTABLE_SPARK_PROJECT_ID \
  --bigtableInstanceId=$BIGTABLE_SPARK_INSTANCE_ID \
  --bigtableTableName=$BIGTABLE_SPARK_TABLE_NAME

Étincelle locale

Utilisez le fichier JAR téléchargé et créez un job Spark qui lit et écrit des données depuis et vers Bigtable avec une instance Spark locale. Vous pouvez également utiliser l'émulateur Bigtable pour envoyer le job Spark.

Utiliser l'émulateur Bigtable

Si vous décidez d'utiliser l'émulateur Bigtable, procédez comme suit :

1. Exécutez la commande suivante pour démarrer l'émulateur :

   gcloud beta emulators bigtable start
   

   Par défaut, l'émulateur choisit la paire hôte/port localhost:8086.

2. Définissez la variable d'environnement BIGTABLE_EMULATOR_HOST :

   export BIGTABLE_EMULATOR_HOST=localhost:8086
   

3. Envoyez la tâche Spark.

Pour en savoir plus sur l'utilisation de l'émulateur Bigtable, consultez Tester à l'aide de l'émulateur.

Envoyer une tâche Spark

Utilisez la commande spark-submit pour envoyer une tâche Spark, que vous utilisiez ou non un émulateur Bigtable local.

  spark-submit $PATH_TO_COMPILED_JAR \
  $BIGTABLE_SPARK_PROJECT_ID \
  $BIGTABLE_SPARK_INSTANCE_ID \
  $BIGTABLE_SPARK_TABLE_NAME

  spark-submit \
  --jars=$LOCAL_PATH_TO_CONNECTOR_JAR \
  --packages=org.slf4j:slf4j-reload4j:1.7.36 \
  $PATH_TO_PYTHON_FILE \
  --bigtableProjectId=$BIGTABLE_SPARK_PROJECT_ID \
  --bigtableInstanceId=$BIGTABLE_SPARK_INSTANCE_ID \
  --bigtableTableName=$BIGTABLE_SPARK_TABLE_NAME

Vérifier les données du tableau

Exécutez la commande cbt CLI suivante pour vérifier que les données sont écrites dans Bigtable. La CLI cbt est un composant de Google Cloud CLI. Pour en savoir plus, consultez la présentation de la CLI cbt.

    cbt -project=$BIGTABLE_SPARK_PROJECT_ID -instance=$BIGTABLE_SPARK_INSTANCE_ID \
    read $BIGTABLE_SPARK_TABLE_NAME

Solutions supplémentaires

Utilisez le connecteur Bigtable Spark pour des solutions spécifiques, comme la sérialisation de types Spark SQL complexes, la lecture de lignes spécifiques et la génération de métriques côté client.

Lire une ligne DataFrame spécifique à l'aide d'un filtre

Lorsque vous utilisez des DataFrames pour lire des données depuis Bigtable, vous pouvez spécifier un filtre pour ne lire que des lignes spécifiques. Les filtres simples tels que ==, <= et startsWith sur la colonne de clé de ligne sont appliqués côté serveur pour éviter une analyse complète de la table. Les filtres sur les clés de ligne composées ou les filtres complexes tels que le filtre LIKE sur la colonne de clé de ligne sont appliqués côté client.

Si vous lisez de grandes tables, nous vous recommandons d'utiliser des filtres de clé de ligne simples pour éviter d'effectuer une analyse complète de la table. L'exemple d'instruction suivant montre comment effectuer une lecture à l'aide d'un filtre simple. Assurez-vous d'utiliser dans votre filtre Spark le nom de la colonne DataFrame convertie en clé de ligne :

    dataframe.filter("id == 'some_id'").show()
  

Lorsque vous appliquez un filtre, utilisez le nom de la colonne DataFrame au lieu du nom de la colonne de la table Bigtable.

Sérialiser des types de données complexes à l'aide d'Apache Avro

Le connecteur Bigtable Spark permet d'utiliser Apache Avro pour sérialiser des types Spark SQL complexes, tels que ArrayType, MapType ou StructType. Apache Avro fournit une sérialisation des données pour les données d'enregistrement couramment utilisées pour le traitement et le stockage de structures de données complexes.

Utilisez une syntaxe telle que "avro":"avroSchema" pour spécifier qu'une colonne de Bigtable doit être encodée à l'aide d'Avro. Vous pouvez ensuite utiliser .option("avroSchema", avroSchemaString) lors de la lecture ou de l'écriture dans Bigtable pour spécifier le schéma Avro correspondant à cette colonne au format chaîne. Vous pouvez utiliser différents noms d'options (par exemple, "anotherAvroSchema") pour différentes colonnes et transmettre des schémas Avro pour plusieurs colonnes.

def catalogWithAvroColumn = s"""{
                    |"table":{"name":"ExampleAvroTable"},
                    |"rowkey":"key",
                    |"columns":{
                    |"col0":{"cf":"rowkey", "col":"key", "type":"string"},
                    |"col1":{"cf":"cf1", "col":"col1", "avro":"avroSchema"}
                    |}
                    |}""".stripMargin

Utiliser des métriques côté client

Étant donné que le connecteur Bigtable Spark est basé sur le client Bigtable pour Java, les métriques côté client sont activées par défaut dans le connecteur. Pour en savoir plus sur l'accès à ces métriques et leur interprétation, consultez la documentation sur les métriques côté client.

Utiliser le client Bigtable pour Java avec des fonctions RDD de bas niveau

Comme le connecteur Bigtable Spark est basé sur le client Bigtable pour Java, vous pouvez utiliser directement le client dans vos applications Spark et effectuer des requêtes de lecture ou d'écriture distribuées dans les fonctions RDD de bas niveau telles que mapPartitions et foreachPartition.

Pour utiliser les classes du client Bigtable pour Java, ajoutez le préfixe com.google.cloud.spark.bigtable.repackaged aux noms de package. Par exemple, au lieu d'utiliser le nom de classe com.google.cloud.bigtable.data.v2.BigtableDataClient, utilisez com.google.cloud.spark.bigtable.repackaged.com.google.cloud.bigtable.data.v2.BigtableDataClient.

Pour en savoir plus sur le client Bigtable pour Java, consultez Client Bigtable pour Java.

Étapes suivantes

• Découvrez comment ajuster votre tâche Spark dans Dataproc.
• Utilisez les classes du client Bigtable pour Java avec le connecteur Bigtable Spark.