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

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

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

Ce document présente les agrégations, montre comment créer un famille de colonnes agrégées, et fournit des exemples montrant comment ajouter une valeur à une cellule d'agrégation. Avant de lire ce document, vous devez connaître les Bigtable présentation et Écritures pour en savoir plus.

Quand utiliser les agrégations

Les agrégations Bigtable sont utiles dans les cas où vous vous intéressez données globales d'une entité et non sous forme de points de données individuels. Si vous utilisez migrer vers Bigtable depuis des bases de données comme Apache Cassandra Redis, vous pouvez utiliser des agrégations Bigtable là où vous utilisaient auparavant des compteurs dans ces systèmes.

Buckets de temps

Vous pouvez utiliser des segments de temps afin d'obtenir les valeurs agrégées pour une période donnée, par exemple une heure, un jour ou une semaine. Au lieu d'agréger les données avant ou après leur écriture vous ajoutez de nouvelles valeurs pour agréger les cellules du tableau.

Par exemple, si vous gérez un service qui aide des organisations caritatives à collecter des fonds, vous pouvez vous souhaitez connaître le nombre de dons en ligne par jour pour chaque campagne, n'ont pas besoin de connaître l'heure exacte de chaque don ou le montant par heure. Dans dans votre tableau, les clés de ligne représentent les ID des organisations caritatives, et vous créez une colonne d'agrégation famille appelée donations. Les qualificatifs de colonne sur cette ligne correspondent aux ID de campagne.

Chaque montant de don reçu pour un jour donné pour une campagne est reçu. il est ajouté à la somme dans la cellule agrégée de la colonne pour ce jour. Chaque annonce pour la cellule utilise un code temporel tronqué au début de la journée, donc que chaque requête ait le même code temporel. Tronquer les codes temporels garantit que tous les dons de ce jour sont ajoutés dans la même cellule. La le lendemain, toutes vos requêtes entrent dans une nouvelle cellule, en utilisant des codes temporels est tronqué à la nouvelle date, et cette tendance se poursuit.

Selon votre cas d'utilisation, vous pouvez choisir de créer des colonnes pour vos nouvelles à la place des agrégats. Selon le nombre de buckets que vous prévoyez vous pouvez envisager une conception de clé de ligne différente.

Pour en savoir plus sur les buckets de temps, consultez la section Concevoir des schémas pour les séries temporelles données.

Simplification des workflows

Les agrégations vous permettent de regrouper vos données dans une table Bigtable sans avoir à utiliser de logiciel d'ETL ou 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 dans Pub/Sub, utilisé Dataflow pour lire les messages et agréger les données avant les écrivant dans Bigtable, vous pouvez les envoyer directement pour agréger des cellules dans Bigtable.

Agréger des familles de colonnes

Pour créer et mettre à jour des cellules agrégées, vous devez disposer d'une ou de plusieurs cellules agrégées familles de colonnes de votre tableau : familles de colonnes ne contenant que des cellules. Vous pouvez les créer en même temps que le tableau, ou ajouter un agrégat à une table qui est déjà utilisée. Lorsque vous créez la colonne d'agrégation, 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 les 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ées, consultez la section Créer une tableau. Ajouter une colonne agrégée à un tableau, consultez la section Ajouter une colonne familles.

Types d'agrégation

Bigtable accepte les types d'agrégation suivants:

  • sum Lorsque vous ajoutez une valeur à une cellule cumulée pour la somme, 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. Le type d'entrée accepté pour les sommes est Int64.
  • min Lorsque vous ajoutez une valeur à une cellule agrégée minimale, la valeur de la cellule est remplacée par la valeur la plus faible entre la nouvelle valeur ajoutée et la valeur actuelle la valeur de la cellule. Le type d'entrée pris en charge pour la valeur minimale est Int64.
  • max Lorsque vous ajoutez une valeur à une cellule agrégée maximale, la valeur de la cellule est remplacée par la valeur la plus élevée entre la nouvelle valeur ajoutée et la valeur actuelle la valeur de la cellule. Le type d'entrée accepté pour "max" 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 du code temporel. Vous utilisez le même horodatage chaque fois que vous ajoutez des données à la cellule. Si vous envoient une valeur à la même clé de ligne, à la même famille de colonnes et au même qualificatif de colonne, mais avec une un horodatage différent, une nouvelle cellule agrégée est créée dans la colonne.

Une requête d'ajout envoyée à une cellule agrégée doit inclure un code temporel.

Type d'entrée

Le type d'entrée de la valeur dans la demande d'ajout doit correspondre au type d'entrée qui la famille de colonnes est créée. Par exemple, si vous envoyez une valeur de chaîne familiale de colonnes configurée pour Int64, la requête est refusé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 plus consultez la documentation API Data référence pour en savoir plus. Les opérations AddToCell sont soumises aux mêmes opérations limites que les autres mutations de table.

Dans une table répliquée, une cellule agrégée converge vers la même valeur totale tous les clusters dans le délai de réplication actuel. La valeur totale correspond au agrégat des AddToCell mutations 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 agrégée. La Les 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: un horodatage Unix en microsecondes, par exemple 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 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 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());
    }
  }
}

Étape suivante