Utiliser l'API BigQuery Storage Write

L'API BigQuery Storage Write est une API de streaming basée sur gRPC permettant d'ingérer des données dans BigQuery à un débit élevé. L'API Storage Write combine les fonctionnalités d'ingestion de flux et de chargement par lot en une seule API. Vous pouvez utiliser l'API Storage Write pour diffuser en streaming des enregistrements dans BigQuery qui sont disponibles pour les requêtes à mesure qu'ils sont écrits, ou pour traiter par lot un grand nombre d'enregistrements de manière arbitraire et les valider en une seule opération atomique.

Avantages de l'utilisation de l'API Storage Write

Sémantique de diffusion "exactement une fois". L'API Storage Write est compatible avec la sémantique "exactement une fois" grâce à l'utilisation de décalages de flux. Contrairement à la méthode insertAll, l'API Storage Write n'écrit jamais deux messages avec le même décalage dans un flux, si le client fournit des décalages de flux lors de l'ajout d'enregistrements.

Transactions au niveau du flux. Vous pouvez écrire des données dans un flux et les valider en tant que transaction unique. Si l'opération de commit échoue, vous pouvez retenter l'opération en toute sécurité. Par exemple, dans un pipeline de traitement par flux, si un nœud de calcul échoue, un autre nœud de calcul peut récupérer la tâche.

Transactions dans plusieurs flux. Plusieurs nœuds de calcul peuvent créer leurs propres flux pour traiter les données de manière indépendante. Lorsque tous les nœuds de calcul sont terminés, vous pouvez valider tous les flux en tant que transaction.

Protocole efficace. L'API Storage Write est plus efficace que l'ancienne méthode insertAll, car elle utilise le streaming gRPC plutôt que REST via HTTP. L'API Storage Write est également compatible avec les formats binaires sous la forme de tampons de protocole, qui constituent un format de communication plus efficace que JSON. Les requêtes d'écriture sont asynchrones avec un ordre garanti.

Détection des mises à jour de schéma. Si le schéma de la table sous-jacente change alors que le client est en streaming, l'API Storage Write informe le client. Le client peut choisir de se reconnecter à l'aide du schéma mis à jour ou de continuer à écrire sur la connexion existante.

Autorisations requises

Pour utiliser l'API Storage Write, vous devez disposer des autorisations bigquery.tables.updateData.

Les rôles IAM (Identity and Access Management) suivants incluent les autorisations bigquery.tables.updateData :

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Présentation de l'utilisation de l'API Storage Write

L'API Storage Write est compatible avec deux modes :

  • Mode commit. Dans ce mode, le client écrit les enregistrements disponibles immédiatement pour les requêtes. Utilisez ce mode pour les charges de travail de streaming.

  • Mode en attente. Dans ce mode, le client écrit un lot d'enregistrements, mis en mémoire tampon dans un état en attente. Une fois l'écriture du client terminée, elle valide chaque flux en attente. Une fois le flux validé, les données écrites sur le flux peuvent être lues. Le commit est une opération atomique. Utilisez ce mode pour les charges de travail par lot, plutôt que les tâches de chargement BigQuery.

Vous pouvez utiliser l'API Storage Write en appelant directement l'API gRPC ou en utilisant la bibliothèque cliente, qui est disponible pour Java. En général, nous vous recommandons d'utiliser la bibliothèque cliente, car elle fournit une interface de programmation plus simple et gère pour vous le RPC bidirectionnel sous-jacent.

La bibliothèque cliente fournit deux objets "writer" :

  • StreamWriterV2 : l'objet StreamWriterV2 accepte les données au format de tampon de protocole.

  • JsonStreamWriter : l'objet JsonStreamWriter accepte les données au format JSON et les convertit en tampons de protocole. Si vous avez déjà des données au format JSON dans votre application, vous pouvez les utiliser à l'aide de JsonStreamWriter. JsonStreamWriter convertit automatiquement les données côté client au format binaire sous-jacent de l'API Storage Write avant de les envoyer via le réseau.

Le modèle de programmation est similaire pour les deux objets "writer". La principale différence réside dans la mise en forme de la charge utile. Les sections suivantes expliquent comment utiliser la bibliothèque cliente pour le mode commit et le mode en attente.

Utiliser l'API Storage Write avec le client Java

Les sections suivantes expliquent comment utiliser le client Java pour écrire des données dans l'API Storage Write.

Écrire dans un flux en mode commit

En mode commit, les enregistrements sont disponibles pour la requête dès que le client reçoit l'accusé de réception du backend. Le mode commit permet d'effectuer une distribution "exactement une fois" dans un flux au moyen de décalages d'enregistrement. L'application peut spécifier le nombre de décalage pour chaque enregistrement. L'opération d'écriture n'est effectuée que si la valeur de décalage correspond au décalage d'ajout suivant. Si aucun décalage n'est fourni, les enregistrements sont ajoutés à la fin actuelle du flux. Dans ce cas, si un ajout renvoie une erreur, toute nouvelle tentative pourrait entraîner l'affichage de l'enregistrement plusieurs fois dans le flux.

Pour écrire des enregistrements en mode commit à l'aide de l'objet JsonStreamWriter, procédez comme suit :

  1. Créez une instance de l'objet BigQueryWriteClient.

  2. Appelez BigQueryWriteClient.createWriteStream pour créer un objet WriteStream. Pour le mode, spécifiez WriteStream.Type.COMMITTED.

  3. Créer une instance JsonStreamWriter. Fournissez un schéma compatible avec le schéma de la table. Vous pouvez créer un schéma manuellement en tant qu'objet TableSchema ou récupérer le schéma à partir de la table BigQuery.

  4. Appelez JsonStreamWriter.append et transmettez un tableau JSONArray d'enregistrements JSONObject. Vous pouvez également spécifier le décalage de l'enregistrement dans le flux. Si vous fournissez le décalage, l'API Storage Write n'écrit jamais deux messages ayant le même décalage. La méthode append est asynchrone. L'ordre est garanti si vous fournissez des décalages.

Java

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Java.

import com.google.api.core.ApiFuture;
import com.google.cloud.bigquery.storage.v1beta2.AppendRowsResponse;
import com.google.cloud.bigquery.storage.v1beta2.BigQueryWriteClient;
import com.google.cloud.bigquery.storage.v1beta2.CreateWriteStreamRequest;
import com.google.cloud.bigquery.storage.v1beta2.JsonStreamWriter;
import com.google.cloud.bigquery.storage.v1beta2.TableName;
import com.google.cloud.bigquery.storage.v1beta2.WriteStream;
import com.google.protobuf.Descriptors.DescriptorValidationException;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import org.json.JSONArray;
import org.json.JSONObject;

public class WriteCommittedStream {

  public static void runWriteCommittedStream()
      throws DescriptorValidationException, InterruptedException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";

    writeCommittedStream(projectId, datasetName, tableName);
  }

  public static void writeCommittedStream(String projectId, String datasetName, String tableName)
      throws DescriptorValidationException, InterruptedException, IOException {

    try (BigQueryWriteClient client = BigQueryWriteClient.create()) {
      // Initialize a write stream for the specified table.
      // For more information on WriteStream.Type, see:
      // https://googleapis.dev/java/google-cloud-bigquerystorage/latest/com/google/cloud/bigquery/storage/v1beta2/WriteStream.Type.html
      WriteStream stream = WriteStream.newBuilder().setType(WriteStream.Type.COMMITTED).build();
      TableName parentTable = TableName.of(projectId, datasetName, tableName);
      CreateWriteStreamRequest createWriteStreamRequest =
          CreateWriteStreamRequest.newBuilder()
              .setParent(parentTable.toString())
              .setWriteStream(stream)
              .build();
      WriteStream writeStream = client.createWriteStream(createWriteStreamRequest);

      // Use the JSON stream writer to send records in JSON format.
      // For more information about JsonStreamWriter, see:
      // https://googleapis.dev/java/google-cloud-bigquerystorage/latest/com/google/cloud/bigquery/storage/v1beta2/JsonStreamWriter.html
      try (JsonStreamWriter writer =
          JsonStreamWriter.newBuilder(writeStream.getName(), writeStream.getTableSchema())
              .build()) {
        // Write two batches to the stream, each with 10 JSON records.
        for (int i = 0; i < 2; i++) {
          // Create a JSON object that is compatible with the table schema.
          JSONArray jsonArr = new JSONArray();
          for (int j = 0; j < 10; j++) {
            JSONObject record = new JSONObject();
            record.put("col1", String.format("record %03d-%03d", i, j));
            jsonArr.put(record);
          }

          // To detect duplicate records, pass the index as the record offset.
          // To disable deduplication, omit the offset or use WriteStream.Type.DEFAULT.
          ApiFuture<AppendRowsResponse> future = writer.append(jsonArr, /*offset=*/ i * 10);
          AppendRowsResponse response = future.get();
        }
      }
      System.out.println("Appended records successfully.");
    } catch (ExecutionException e) {
      // If the wrapped exception is a StatusRuntimeException, check the state of the operation.
      // If the state is INTERNAL, CANCELLED, or ABORTED, you can retry. For more information, see:
      // https://grpc.github.io/grpc-java/javadoc/io/grpc/StatusRuntimeException.html
      System.out.println("Failed to append records. \n" + e.toString());
    }
  }
}

L'objet StreamWriterV2 est semblable à l'objet JsonStreamWriter, mais la méthode StreamWriter.append prend un objet AppendRowsRequest, qui contient une liste de messages de tampon de protocole, plutôt que des objets JSON.

Écrire dans le flux par défaut

L'API Storage Write fournit un flux par défaut qui ajoute des enregistrements en mode commit sans garantie "exactement une fois". Le flux par défaut peut potentiellement accepter un débit plus élevé que la création d'un flux dédié. En outre, le flux par défaut n'est pas soumis à la limite de quota associée à la création de flux d'écriture. N'importe quel nombre de clients peut écrire simultanément dans le flux par défaut.

Le code suivant montre comment utiliser le flux par défaut avec l'objet JsonStreamWriter :

Java

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Java.

import com.google.api.core.ApiFuture;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.storage.v1beta2.AppendRowsResponse;
import com.google.cloud.bigquery.storage.v1beta2.JsonStreamWriter;
import com.google.cloud.bigquery.storage.v1beta2.TableName;
import com.google.cloud.bigquery.storage.v1beta2.TableSchema;
import com.google.protobuf.Descriptors.DescriptorValidationException;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import org.json.JSONArray;
import org.json.JSONObject;

public class WriteToDefaultStream {

  public static void runWriteToDefaultStream()
      throws DescriptorValidationException, InterruptedException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    writeToDefaultStream(projectId, datasetName, tableName);
  }

  public static void writeToDefaultStream(String projectId, String datasetName, String tableName)
      throws DescriptorValidationException, InterruptedException, IOException {
    BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
    Table table = bigquery.getTable(datasetName, tableName);
    TableName parentTable = TableName.of(projectId, datasetName, tableName);
    Schema schema = table.getDefinition().getSchema();
    TableSchema tableSchema = BqToBqStorageSchemaConverter.convertTableSchema(schema);

    // Use the JSON stream writer to send records in JSON format.
    // For more information about JsonStreamWriter, see:
    // https://googleapis.dev/java/google-cloud-bigquerystorage/latest/com/google/cloud/bigquery/storage/v1beta2/JsonStreamWriter.html
    try (JsonStreamWriter writer =
        JsonStreamWriter.newBuilder(parentTable.toString(), tableSchema).build()) {
      // Write two batches to the stream, each with 10 JSON records.
      for (int i = 0; i < 2; i++) {
        // Create a JSON object that is compatible with the table schema.
        JSONArray jsonArr = new JSONArray();
        for (int j = 0; j < 10; j++) {
          JSONObject record = new JSONObject();
          record.put("test_string", String.format("record %03d-%03d", i, j));
          jsonArr.put(record);
        }
        ApiFuture<AppendRowsResponse> future = writer.append(jsonArr);
        AppendRowsResponse response = future.get();
      }
      System.out.println("Appended records successfully.");
    } catch (ExecutionException e) {
      // If the wrapped exception is a StatusRuntimeException, check the state of the operation.
      // If the state is INTERNAL, CANCELLED, or ABORTED, you can retry. For more information, see:
      // https://grpc.github.io/grpc-java/javadoc/io/grpc/StatusRuntimeException.html
      System.out.println("Failed to append records. \n" + e.toString());
    }
  }
}

Ce code est semblable à l'exemple précédent, mais au lieu d'appeler BigQueryWriteClient.createWriteStream pour créer un flux d'écriture, JsonStreamWriter.Builder crée un flux d'écriture par défaut en fonction du nom de la table.

Écrire dans un flux en mode en attente

Le mode en attente permet de charger de façon groupée des données par lots. Il est également utile pour le chargement de lots plus petits, ce qui est un modèle fréquent dans certaines architectures de traitement de données.

Le mode en attente est compatible avec les transactions au niveau du flux. Un flux ne peut être validé qu'une seule fois. Plusieurs nœuds de calcul peuvent fonctionner sur la même unité de données sans que les mêmes données soient écrites deux fois. Le commit est destiné à des opérations atomiques. En cas d'échec, vous pouvez réessayer.

Pour utiliser l'objet JsonStreamWriter en mode en attente, procédez comme suit :

  1. Créez une instance de l'objet BigQueryWriteClient.

  2. Appelez BigQueryWriteClient.createWriteStream pour créer un ou plusieurs objets WriteStream. Pour le mode, spécifiez WriteStream.Type.PENDING.

  3. Appeler StreamWriter.append et transmettre un JSONArray d'enregistrements JSONObject. Si vous souhaitez une détection de messages en double, spécifiez le décalage de l'enregistrement dans le flux.

  4. Lorsque vous avez fini d'écrire dans un flux, appelez BigQueryWriteClient.finalizeWriteStream pour finaliser le flux. Après avoir appelé cette méthode, vous ne pouvez plus écrire d'enregistrements dans ce flux.

  5. Lorsque tous les flux sont finalisés, appelez BigQueryWriteClient.batchCommitWriteStreams avec la liste des flux. Cette méthode valide les données pour ces flux.

  6. Appelez BatchCommitWriteStreamsResponse.hasCommitTime sur l'objet BatchCommitWriteStreamsResponse renvoyé. Si cette méthode renvoie false, le commit a échoué. Appelez la méthode getStreamErrorsList pour obtenir la liste des erreurs pour chaque flux ayant échoué.

Java

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Java décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Java.

import com.google.api.core.ApiFuture;
import com.google.cloud.bigquery.storage.v1beta2.AppendRowsResponse;
import com.google.cloud.bigquery.storage.v1beta2.BatchCommitWriteStreamsRequest;
import com.google.cloud.bigquery.storage.v1beta2.BatchCommitWriteStreamsResponse;
import com.google.cloud.bigquery.storage.v1beta2.BigQueryWriteClient;
import com.google.cloud.bigquery.storage.v1beta2.CreateWriteStreamRequest;
import com.google.cloud.bigquery.storage.v1beta2.FinalizeWriteStreamResponse;
import com.google.cloud.bigquery.storage.v1beta2.JsonStreamWriter;
import com.google.cloud.bigquery.storage.v1beta2.StorageError;
import com.google.cloud.bigquery.storage.v1beta2.TableName;
import com.google.cloud.bigquery.storage.v1beta2.WriteStream;
import com.google.protobuf.Descriptors.DescriptorValidationException;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import org.json.JSONArray;
import org.json.JSONObject;

public class WritePendingStream {

  public static void runWritePendingStream()
      throws DescriptorValidationException, InterruptedException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";

    writePendingStream(projectId, datasetName, tableName);
  }

  public static void writePendingStream(String projectId, String datasetName, String tableName)
      throws DescriptorValidationException, InterruptedException, IOException {
    try (BigQueryWriteClient client = BigQueryWriteClient.create()) {
      // Initialize a write stream for the specified table.
      // For more information on WriteStream.Type, see:
      // https://googleapis.dev/java/google-cloud-bigquerystorage/latest/com/google/cloud/bigquery/storage/v1beta2/WriteStream.Type.html
      WriteStream stream = WriteStream.newBuilder().setType(WriteStream.Type.PENDING).build();
      TableName parentTable = TableName.of(projectId, datasetName, tableName);
      CreateWriteStreamRequest createWriteStreamRequest =
          CreateWriteStreamRequest.newBuilder()
              .setParent(parentTable.toString())
              .setWriteStream(stream)
              .build();
      WriteStream writeStream = client.createWriteStream(createWriteStreamRequest);

      // Use the JSON stream writer to send records in JSON format.
      // For more information about JsonStreamWriter, see:
      // https://googleapis.dev/java/google-cloud-bigquerystorage/latest/com/google/cloud/bigquery/storage/v1beta2/JsonStreamWriter.html
      try (JsonStreamWriter writer =
          JsonStreamWriter.newBuilder(writeStream.getName(), writeStream.getTableSchema())
              .build()) {
        // Write two batches to the stream, each with 10 JSON records.
        for (int i = 0; i < 2; i++) {
          // Create a JSON object that is compatible with the table schema.
          JSONArray jsonArr = new JSONArray();
          for (int j = 0; j < 10; j++) {
            JSONObject record = new JSONObject();
            record.put("col1", String.format("batch-record %03d-%03d", i, j));
            jsonArr.put(record);
          }
          ApiFuture<AppendRowsResponse> future = writer.append(jsonArr);
          AppendRowsResponse response = future.get();
        }
        FinalizeWriteStreamResponse finalizeResponse =
            client.finalizeWriteStream(writeStream.getName());
        System.out.println("Rows written: " + finalizeResponse.getRowCount());
      }

      // Commit the streams.
      BatchCommitWriteStreamsRequest commitRequest =
          BatchCommitWriteStreamsRequest.newBuilder()
              .setParent(parentTable.toString())
              .addWriteStreams(writeStream.getName())
              .build();
      BatchCommitWriteStreamsResponse commitResponse =
          client.batchCommitWriteStreams(commitRequest);
      // If the response does not have a commit time, it means the commit operation failed.
      if (commitResponse.hasCommitTime() == false) {
        for (StorageError err : commitResponse.getStreamErrorsList()) {
          System.out.println(err.getErrorMessage());
        }
        throw new RuntimeException("Error committing the streams");
      }
      System.out.println("Appended and committed records successfully.");
    } catch (ExecutionException e) {
      // If the wrapped exception is a StatusRuntimeException, check the state of the operation.
      // If the state is INTERNAL, CANCELLED, or ABORTED, you can retry. For more information, see:
      // https://grpc.github.io/grpc-java/javadoc/io/grpc/StatusRuntimeException.html
      System.out.println(e);
    }
  }
}

Un modèle architectural d'utilisation du mode en attente consiste à disposer d'un coordinateur et de plusieurs nœuds de calcul. Le coordinateur appelle createWriteStream et le transmet à un nœud de calcul. Chaque nœud de calcul appelle append plusieurs fois si nécessaire, puis appelle finalizeWriteStream. Lorsque tous les nœuds de calcul sont terminés, le coordinateur appelle batchCommitWriteStream. Le commit d'un flux est une opération atomique. Par conséquent, si un nœud de calcul échoue, un autre nœud de calcul peut récupérer la même tâche de traitement et la relancer.

Traiter les erreurs

Si la méthode append génère une exception StatusRuntimeException, vous devez vérifier le code d'état dans l'exception. Le code d'état peut être l'un des suivants :

  • ALREADY_EXISTS : la ligne a déjà été écrite. Cette erreur peut se produire lorsque vous fournissez des décalages de flux. Elle indique qu'un enregistrement en double a été détecté. Vous pouvez ignorer cette erreur en toute sécurité.
  • INTERNAL, CANCELLED ou ABORTED : impossible d'exécuter l'opération. Vous pouvez réessayer l'opération en toute sécurité.
  • INVALID_ARGUMENT : argument non valide. Cette erreur est une erreur d'application.
  • NOT_FOUND : flux ou table introuvable.
  • OUT_OF_RANGE. Le décalage est supérieur au décalage d'écriture actuel. Cette erreur peut se produire si vous fournissez des décalages de flux et qu'une opération d'écriture précédente a échoué. Dans ce cas, vous pouvez réessayer à partir de la dernière écriture réussie. Cette erreur peut également se produire si l'application définit une valeur de décalage incorrecte.
  • PERMISSION_DENIED. L'application n'est pas autorisée à écrire dans cette table.

Si vous recevez une erreur non répertoriée ci-dessus, essayez d'ouvrir une nouvelle connexion en fermant l'objet "writer" et en créant une instance.

Utiliser des schémas

Lorsque vous créez l'objet "writer", vous spécifiez un schéma. Ce schéma doit être compatible avec le schéma de la table BigQuery :

  • Il doit inclure tous les champs obligatoires dans le schéma de la table.
  • Il ne peut pas inclure de champs supplémentaires qui ne figurent pas dans le schéma de la table.
  • Les types de données doivent être compatibles. Pour en savoir plus, consultez la section Conversions de types de données sur cette page.

Lorsque vous utilisez l'objet JsonStreamWriter, vous fournissez le schéma en tant qu'objet TableSchema.

Lorsque vous utilisez l'objet StreamWriterV2, vous fournissez le schéma en tant qu'objet ProtoSchema. L'objet ProtoSchema est un wrapper fin pour un objet google.protobuf.DescriptorProto qui décrit le schéma. Vous pouvez utiliser la classe d'assistance ProtoSchemaConverter pour convertir un objet DescriptorProto en objet ProtoSchema autonome. Vous pouvez également utiliser la classe SchemaCompatibility pour vérifier si l'objet ProtoSchema est compatible avec le schéma de la table BigQuery.

Un schéma de table peut changer après avoir démarré une session d'écriture. Pour en savoir plus sur les modifications de schéma de table, consultez la page Modifier des schémas de table. Si BigQuery détecte une modification dans le schéma, la réponse AppendRows contient le schéma mis à jour. Pour vérifier si le schéma a été mis à jour, appelez la méthode AppendRowsResponse.hasUpdatedSchema.

Avec l'objet JsonStreamWriter, vous pouvez commencer à envoyer des enregistrements utilisant le schéma mis à jour une fois que hasUpdatedSchema a renvoyé true. Vous n'avez pas besoin de fermer la connexion ou de reconfigurer l'objet "writer". Pour l'objet StreamWriterV2, fermez l'instance actuelle et créez une instance avec le schéma mis à jour.

Utiliser directement l'API gRPC

Bien que nous vous recommandons d'utiliser la bibliothèque cliente, vous pouvez également utiliser l'API Storage Write en appelant directement l'API gRPC, comme suit :

  1. Appelez CreateWriteStream pour créer un flux d'écriture. Indiquez le nom de la table parente et le mode (PENDING ou COMMITTED).

  2. Dans une boucle, appelez AppendRows pour ajouter un ou plusieurs enregistrements. Formatez chaque enregistrement en tant que tampon de protocole sérialisé en séquence d'octets. Incluez éventuellement le décalage d'écriture. Le premier appel à AppendRows doit contenir le schéma du flux, spécifié en tant qu'objet DescriptorProto.

  3. En mode en attente, appelez FinalizeWriteStream pour chaque flux. Après avoir appelé cette méthode, vous ne pouvez plus écrire de lignes dans le flux. Cette méthode n'est pas requise en mode commit.

  4. En mode en attente, une fois les flux finalisés, appelez BatchCommitWriteStreams pour effectuer un commit des flux. Une fois que vous avez appelé cette méthode, les données deviennent disponibles pour la lecture. Cette méthode n'est pas requise en mode commit.

Conversions de types de données

Le tableau suivant indique les types de tampons de protocole acceptés pour chaque type de données BigQuery :

Type de données BigQuery Types de tampons de protocole compatibles
BOOL bool, int32, int64, uint32, uint64
BYTES bytes
DATE int32 (rôle à privilégier), int64

La valeur représente le nombre de jours écoulés depuis l'époque Unix (1970-01-01). La plage valide est comprise entre -719162` (0001-01-01) à 2932896 (9999-12-31).

DATETIME string

La valeur doit être une valeur littérale DATETIME.

FLOAT double, float
GEOGRAPHY string

Cette valeur correspond à une géométrie au format WKT ou GeoJson.

INTEGER int32, int64, uint32, enum
NUMERIC, BIGNUMERIC int32, int64, uint32, uint64, double, float, string

Le format d'encodage est documenté dans le dépôt GitHub ZetaSQL.

STRING string, enum
TIME string

La valeur doit être une valeur littérale TIME.

TIMESTAMP int64 (rôle à privilégier), int32, uint32

La valeur est donnée en microsecondes depuis l'époque Unix (1970-01-01).

Quotas de l'API Storage Write

Pour en savoir plus sur les quotas et limites de l'API Storage Write, consultez la page Requêtes de l'API BigQuery Storage Write.

Tarifs de l'API Storage Write

Pour connaître les tarifs, consultez la section Tarifs de l'ingestion de données.

Régions où le service est disponible

La phase de prévisualisation de l'API Storage Write est compatible avec les emplacements suivants.

Zones régionales

Description de la région Nom de la région
Amériques
Caroline du Sud us-east1
Europe
Belgique europe-west1
Asie-Pacifique
Sydney australia-southeast1
Tokyo asia-northeast1

Zones multirégionales

Description de la zone multirégionale Nom de la zone multirégionale
Centres de données dans les États membres de l'Union européenne EU
Centres de données aux États-Unis US