Modèle Spanner vers BigQuery

Le modèle Spanner vers BigQuery est un pipeline par lots qui lit les données d'une table Spanner et les écrit dans BigQuery.

Conditions requises pour ce pipeline

  • La table source Spanner doit exister avant l'exécution du pipeline.
  • L'ensemble de données BigQuery doit exister avant l'exécution du pipeline.
  • Créez un fichier JSON décrivant votre schéma BigQuery.

    Le fichier doit contenir un tableau JSON de niveau supérieur intitulé fields. Le contenu du tableau fields doit respecter le format suivant :
    {"name": "COLUMN_NAME", "type": "DATA_TYPE"}.

    Le code JSON suivant décrit un exemple de schéma BigQuery :

    {
      "fields": [
        {
          "name": "location",
          "type": "STRING"
        },
        {
          "name": "name",
          "type": "STRING"
        },
        {
          "name": "age",
          "type": "STRING"
        },
        {
          "name": "color",
          "type": "STRING"
        },
        {
          "name": "coffee",
          "type": "STRING"
        }
      ]
    }

    Le modèle par lots Spanner vers BigQuery n'est pas compatible avec l'importation de données dans les champs STRUCT (Enregistrement) de la table BigQuery cible.

Paramètres de modèle

Paramètres obligatoires

  • spannerInstanceId : ID d'instance de la base de données Spanner à lire.
  • spannerDatabaseId : ID de la base de données Spanner à exporter.
  • outputTableSpec : emplacement de la table de sortie BigQuery dans laquelle écrire la sortie. Par exemple, <PROJECT_ID>:<DATASET_NAME>.<TABLE_NAME>. Selon la propriété createDisposition spécifiée, la table de sortie peut être créée automatiquement à l'aide du schéma Avro fourni par l'utilisateur.

Paramètres facultatifs

  • spannerProjectId : ID du projet dans lequel se trouve la base de données Spanner. La valeur par défaut de ce paramètre correspond au projet dans lequel le pipeline Dataflow est exécuté.
  • spannerTableId : nom de la table de la base de données Spanner à exporter. Ignoré si la valeur de sqlQuery est définie.
  • spannerRpcPriority : priorité des requêtes (https://cloud.google.com/spanner/docs/reference/rest/v1/RequestOptions) pour les appels Spanner. Les valeurs possibles sont HIGH, MEDIUM et LOW. La valeur par défaut est HIGH.
  • sqlQuery : requête SQL à utiliser pour lire les données de la base de données Spanner. Obligatoire si spannerTableId est vide.
  • bigQuerySchemaPath : chemin d'accès Cloud Storage (gs://) au fichier JSON qui définit votre schéma BigQuery. Ce paramètre est obligatoire si la propriété Create Disposition n'est pas définie sur CREATE_NEVER. Par exemple, gs://your-bucket/your-schema.json.
  • writeDisposition : valeur WriteDisposition de BigQuery (https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfigurationload). Par exemple, WRITE_APPEND, WRITE_EMPTY ou WRITE_TRUNCATE. La valeur par défaut est WRITE_APPEND.
  • createDisposition : valeur CreateDisposition de BigQuery (https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfigurationload). Par exemple, CREATE_IF_NEEDED et CREATE_NEVER. La valeur par défaut est CREATE_IF_NEEDED.
  • useStorageWriteApi : si la valeur est true, le pipeline utilise l'API BigQuery Storage Write (https://cloud.google.com/bigquery/docs/write-api). La valeur par défaut est false. Pour en savoir plus, consultez la page "Utiliser l'API Storage Write" (https://beam.apache.org/documentation/io/built-in/google-bigquery/#storage-write-api).
  • useStorageWriteApiAtLeastOnce : spécifie la sémantique d'écriture, lorsque vous utilisez l'API Storage Write. Pour utiliser la sémantique de type "au moins une fois" (https://beam.apache.org/documentation/io/built-in/google-bigquery/#at-least-once-semantics), définissez ce paramètre sur true. Pour utiliser la sémantique de type "exactement une fois", définissez le paramètre sur false. Ce paramètre ne s'applique que lorsque la valeur de useStorageWriteApi est définie sur true. La valeur par défaut est false.

Exécuter le modèle

Console

  1. Accédez à la page Dataflow Créer un job à partir d'un modèle.
  2. Accéder à la page Créer un job à partir d'un modèle
  3. Dans le champ Nom du job, saisissez un nom de job unique.
  4. Facultatif : pour Point de terminaison régional, sélectionnez une valeur dans le menu déroulant. La région par défaut est us-central1.

    Pour obtenir la liste des régions dans lesquelles vous pouvez exécuter un job Dataflow, consultez la page Emplacements Dataflow.

  5. Dans le menu déroulant Modèle Dataflow, sélectionnez the Spanner to BigQuery template.
  6. Dans les champs fournis, saisissez vos valeurs de paramètres.
  7. Cliquez sur Run Job (Exécuter la tâche).

gcloud

Dans le shell ou le terminal, exécutez le modèle :

gcloud dataflow flex-template run JOB_NAME \
    --template-file-gcs-location=gs://dataflow-templates-REGION_NAME/VERSION/flex/Cloud_Spanner_to_BigQuery_Flex \
    --project=PROJECT_ID \
    --region=REGION_NAME \
    --parameters \
       spannerInstanceId=SPANNER_INSTANCE_ID,\
       spannerDatabaseId=SPANNER_DATABASE_ID,\
       spannerTableId=SPANNER_TABLE_ID,\
       sqlQuery=SQL_QUERY,\
       outputTableSpec=OUTPUT_TABLE_SPEC,\

Remplacez les éléments suivants :

  • JOB_NAME : nom de job unique de votre choix
  • VERSION : version du modèle que vous souhaitez utiliser

    Vous pouvez utiliser les valeurs suivantes :

  • REGION_NAME : région dans laquelle vous souhaitez déployer votre job Dataflow, par exemple us-central1
  • SPANNER_INSTANCE_ID : ID d'instance Spanner
  • SPANNER_DATABASE_ID : ID de la base de données Spanner
  • SPANNER_TABLE_ID : nom de la table Spanner
  • SQL_QUERY : requête SQL
  • OUTPUT_TABLE_SPEC : emplacement de la table BigQuery

API

Pour exécuter le modèle à l'aide de l'API REST, envoyez une requête HTTP POST. Pour en savoir plus sur l'API, ses autorisations et leurs champs d'application, consultez la section projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch
{
   "launchParameter": {
     "jobName": "JOB_NAME",
     "parameters": {
       "spannerInstanceId": "SPANNER_INSTANCE_ID",
       "spannerDatabaseId": "SPANNER_DATABASE_ID",
       "spannerTableId": "SPANNER_TABLE_ID",
       "sqlQuery": "SQL_QUERY",
       "outputTableSpec": "OUTPUT_TABLE_SPEC",
     },
     "containerSpecGcsPath": "gs://dataflow-templates-LOCATION/VERSION/flex/Cloud_Spanner_to_BigQuery_Flex",
     "environment": { "maxWorkers": "10" }
  }
}

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet Google Cloud dans lequel vous souhaitez exécuter le job Dataflow
  • JOB_NAME : nom de job unique de votre choix
  • VERSION : version du modèle que vous souhaitez utiliser

    Vous pouvez utiliser les valeurs suivantes :

  • LOCATION : région dans laquelle vous souhaitez déployer votre job Dataflow, par exemple us-central1
  • SPANNER_INSTANCE_ID : ID d'instance Spanner
  • SPANNER_DATABASE_ID : ID de la base de données Spanner
  • SPANNER_TABLE_ID : nom de la table Spanner
  • SQL_QUERY : requête SQL
  • OUTPUT_TABLE_SPEC : emplacement de la table BigQuery

Étapes suivantes