Valeurs agrégées au moment de l'écriture

Preview

Ce produit ou cette fonctionnalité est soumis aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent bénéficier d'une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Si vous souhaitez agréger vos données dans Bigtable au moment de l'écriture, vous pouvez utiliser des agrégations. Les agrégats sont des cellules de table Bigtable qui agrègent les valeurs des cellules à mesure que les données sont écrites. Lorsque vous ajoutez une valeur, une fonction d'agrégation fusionne la valeur avec la valeur agrégée déjà dans la cellule. D'autres bases de données font référence à des fonctionnalités similaires en tant que compteurs ou compteurs distribués.

Bigtable offre le type d'agrégation sum. Lorsque vous ajoutez une valeur à une cellule d'agrégation, la valeur de la cellule est remplacée par la somme de la valeur nouvellement ajoutée et de la valeur actuelle de la cellule.

Pendant la phase Preview, vous pouvez utiliser des agrégats à l'aide de la CLI cbt et des bibliothèques clientes Bigtable pour C++, Go et Java.

Ce document présente les agrégations, montre comment créer une famille de colonnes d'agrégation et fournit des exemples montrant comment ajouter une valeur à une cellule d'agrégation. Avant de lire ce document, vous devez avoir pris connaissance de la présentation de Bigtable et des écritures.

Quand utiliser des agrégations ?

Les agrégations Bigtable sont utiles dans les cas où vous vous intéressez aux données d'une entité sous forme agrégée et non en tant que points de données individuels. Si vous migrez vers Bigtable à partir de bases de données telles qu'Apache Cassandra ou Redis, vous pouvez utiliser les agrégations Bigtable aux endroits où vous dépendiez auparavant de compteurs dans ces systèmes.

Buckets de temps

Vous pouvez utiliser des buckets de temps pour obtenir des valeurs agrégées pour une période donnée, telle qu'une heure, un jour ou une semaine. Au lieu d'agréger des données avant ou après leur écriture dans votre table, vous ajoutez des valeurs pour agréger les cellules de la table.

Par exemple, si vous gérez un service qui aide des associations à collecter des fonds, vous souhaiterez peut-être connaître le montant des dons en ligne quotidiens pour chaque campagne, mais vous n'avez pas besoin de connaître l'heure exacte de chaque don ni le montant par heure. Dans votre table, les clés de ligne représentent les ID d'organisations caritatives. Vous créez une famille de colonnes agrégée appelée donations. Les qualificatifs de colonne de la ligne correspondent aux ID de campagne.

Lorsque chaque montant de don reçu pour un jour donné pour une campagne est reçu, il est ajouté à la somme dans la cellule d'agrégation de la colonne pour ce jour. Chaque requête d'ajout pour la cellule utilise un horodatage tronqué au début de la journée, de sorte qu'en réalité, chaque requête ait le même horodatage. La troncation des codes temporels garantit que tous les dons de ce jour sont ajoutés à la même cellule. Le jour suivant, toutes vos requêtes sont envoyées dans une nouvelle cellule, avec des horodatages qui sont tronqués à la nouvelle date, et ce schéma se poursuit.

En fonction de votre cas d'utilisation, vous pouvez choisir de créer des colonnes pour vos nouvelles données agrégées. Pour en savoir plus sur les buckets temporels, consultez la page Conception de schémas pour les données de séries temporelles.

Simplifier les workflows

Les agrégats vous permettent d'agréger vos données dans votre table Bigtable sans avoir à utiliser un ETL ou un logiciel de traitement par flux pour agréger vos données avant ou après leur écriture dans Bigtable. Par exemple, si votre application a déjà publié des messages sur Pub/Sub, puis utilisé Dataflow pour lire les messages et agréger les données avant de les écrire dans Bigtable, vous pouvez envoyer les données directement pour agréger des cellules dans Bigtable.

Agréger les familles de colonnes

Pour créer et mettre à jour des cellules agrégées, vous devez avoir une ou plusieurs familles de colonnes agrégées dans votre table (familles de colonnes ne contenant que des cellules agrégées). Vous pouvez les créer lorsque vous créez une table ou ajouter une famille de colonnes agrégées à une table déjà utilisée. Lorsque vous créez la famille de colonnes, vous spécifiez le type d'agrégation, par exemple somme.

Vous ne pouvez pas convertir une famille de colonnes contenant des données non agrégées en famille de colonnes agrégées. Les colonnes des familles de colonnes agrégées ne peuvent pas contenir de cellules non agrégées, et les familles de colonnes standards ne peuvent pas contenir de cellules agrégées.

Pour créer une table avec une famille de colonnes agrégée, consultez la section Créer une table. Pour ajouter une famille de colonnes agrégée à une table, consultez la section Ajouter des familles de colonnes.

Types d'agrégation

Bigtable accepte le type d'agrégation sum. Le type d'entrée accepté pour les sommes est Int64.

Horodatages

Une cellule agrégée est définie par une clé de ligne, une famille de colonnes, un qualificatif de colonne et un code temporel. Le même code temporel est utilisé chaque fois que vous ajoutez des données à la cellule. Si vous envoyez une valeur à la même clé de ligne, la même famille de colonnes et le même qualificatif de colonne, mais avec un horodatage différent, une cellule agrégée est créée dans la colonne.

Une demande d'ajout envoyée à une cellule d'agrégation doit inclure un horodatage.

Type d'entrée

Le type d'entrée de la valeur dans la requête d'ajout doit correspondre au type d'entrée avec lequel la famille de colonnes est créée. Par exemple, si vous envoyez une valeur de chaîne à une famille de colonnes configurée pour Int64, la requête est rejetée.

AddToCell

Une requête d'ajout envoie une mutation AddToCell dans l'API Bigtable Data. En revanche, une requête d'écriture non agrégée envoie une mutation SetCell. Pour en savoir plus, consultez la documentation de référence de l'API de données. Les opérations AddToCell sont soumises aux mêmes limites d'opérations que les autres mutations de table.

Dans une table répliquée, une cellule agrégée converge sur la même valeur totale dans tous les clusters dans le délai de réplication actuel. La valeur totale correspond à l'agrégation de toutes les mutations AddToCell envoyées à cette cellule dans tous les clusters depuis la dernière opération de suppression ou depuis la création de la cellule.

Ajouter des exemples de requêtes

Les exemples suivants vous montrent comment ajouter une valeur à une cellule d'agrégation. Ces exemples s'ajoutent à la somme d'une famille de colonnes qui attend le type d'entrée Int64.

cbt

cbt addtocell TABLE_ID ROW_KEY FAMILY_NAME:COLUMN_QUALIFER=VALUE@TIMESTAMP

Remplacez les éléments suivants :

• TABLE_ID : identifiant permanent de la table.
• ROW_KEY: clé de ligne
• FAMILY_NAME: nom de la famille de colonnes agrégées
• COLUMN_QUALIFIER: identifiant de la colonne
• VALUE: valeur à ajouter à la cellule.
• TIMESTAMP: horodatage Unix en microsecondes, tel que 1710868850000000

Exemple :

cbt addtocell mobile-data device-1 updates:week12=100@1710868850000000

Go

Pour savoir comment installer et utiliser la bibliothèque cliente pour Bigtable, consultez la page Bibliothèques clientes Bigtable.

Pour vous authentifier auprès de Bigtable, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/bigtable"
)

func writeAggregate(w io.Writer, projectID, instanceID string, tableName string) error {
	// projectID := "my-project-id"
	// instanceID := "my-instance-id"
	// tableName := "mobile-time-series"

	ctx := context.Background()
	client, err := bigtable.NewClient(ctx, projectID, instanceID)
	if err != nil {
		return fmt.Errorf("bigtable.NewClient: %w", err)
	}
	defer client.Close()
	tbl := client.Open(tableName)
	columnFamilyName := "view_count"
	viewTimestamp, err := time.Parse(time.RFC3339, "2024-03-13T12:41:34Z")
	if err != nil {
		return err
	}
	hourlyBucket := viewTimestamp.Truncate(time.Hour)

	mut := bigtable.NewMutation()
	mut.AddIntToCell(columnFamilyName, "views", bigtable.Time(hourlyBucket), 1)

	rowKey := "page#index.html"
	if err := tbl.Apply(ctx, rowKey, mut); err != nil {
		return fmt.Errorf("Apply: %w", err)
	}

	fmt.Fprintf(w, "Successfully wrote row: %s\n", rowKey)
	return nil
}

Java

Pour savoir comment installer et utiliser la bibliothèque cliente pour Bigtable, consultez la page Bibliothèques clientes Bigtable.

Pour vous authentifier auprès de Bigtable, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

import com.google.cloud.bigtable.data.v2.BigtableDataClient;
import com.google.cloud.bigtable.data.v2.models.RowMutation;
import java.time.Instant;
import java.time.temporal.ChronoUnit;

public class WriteAggregate {
  private static final String COUNT_COLUMN_FAMILY_NAME = "view_count";
  private static final long MICROS_PER_MILLI = 1000;

  public static void writeAggregate(String projectId, String instanceId, String tableId) {
    // String projectId = "my-project-id";
    // String instanceId = "my-instance-id";
    // String tableId = "page-view-counter";

    try (BigtableDataClient dataClient = BigtableDataClient.create(projectId, instanceId)) {

      String rowKey = "page#index.html";
      Instant viewTimestamp = Instant.parse("2024-03-13T12:41:34.123Z");

      // Bucket the views for an hour into a single count, giving us an hourly view count for a
      // given page.
      Instant hourlyBucket = viewTimestamp.truncatedTo(ChronoUnit.HOURS);
      long hourlyBucketMicros = hourlyBucket.toEpochMilli() * MICROS_PER_MILLI;

      RowMutation rowMutation =
          RowMutation.create(tableId, rowKey)
              .addToCell(COUNT_COLUMN_FAMILY_NAME, "views", hourlyBucketMicros, 1);

      dataClient.mutateRow(rowMutation);
      System.out.printf("Successfully wrote row %s", rowKey);

    } catch (Exception e) {
      System.out.println("Error during WriteAggregate: \n" + e.toString());
    }
  }
}

Étapes suivantes

• Passer en revue les concepts liés à la conception de schémas
• Découvrez comment utiliser une fonction Cloud pour accéder aux données Bigtable.