Utiliser des vecteurs de suppression binaires dans les tables Iceberg V3

Le catalogue d'environnements d'exécution Lakehouse est compatible avec les tables Apache Iceberg V3. Les vecteurs de suppression binaire sont une fonctionnalité essentielle de la spécification Apache Iceberg V3. Cette optimisation stocke les suppressions au niveau des lignes dans des fichiers .puffin. Au lieu d'effectuer des jointures coûteuses au moment de l'exécution des requêtes, BigQuery et les moteurs Open Source (tels qu'Apache Spark, Apache Flink et Trino) utilisent ces vecteurs pour identifier et ignorer rapidement les lignes supprimées.

L'utilisation de vecteurs de suppression binaires peut améliorer les performances de différentes manières :

  • Écritures à volume élevé : améliore les performances d'écriture pour les tables avec des écritures à volume élevé.
  • Lectures efficaces : améliorent la vitesse des requêtes en permettant à BigQuery et aux moteurs Open Source d'identifier et d'ignorer les lignes supprimées.

Cela est particulièrement utile pour gérer les mises à jour et les suppressions à volume élevé dans les pipelines de capture des données modifiées (CDC, Change Data Capture), ou pour répondre aux exigences réglementaires telles que le RGPD (droit à l'oubli) en supprimant des lignes spécifiques sans avoir à réécrire des fichiers de données entiers.

Avant de commencer

  1. Vérifiez que la facturation est activée pour votre projet Google Cloud .

  2. Activez l'API BigLake.

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

    Activer l'API

Rôles requis

Pour obtenir les autorisations nécessaires pour créer et gérer des tables Iceberg V3, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet et votre bucket de stockage :

  • Tous :
    • Administrateur BigLake (roles/biglake.admin) – votre projet
    • Administrateur de l'espace de stockage (roles/storage.admin) : le bucket Cloud Storage cible

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.

Configurer le catalogue REST Iceberg

Avant de créer une table Iceberg V3, vous devez configurer le catalogue REST Iceberg, ce qui inclut la création d'un espace de noms et d'un catalogue.

La configuration du catalogue REST Iceberg peut prendre un certain temps. Avant de continuer, assurez-vous de créer l'espace de noms et le catalogue.

Limites

Les tables Iceberg V3 du catalogue d'environnements d'exécution Lakehouse présentent les limites suivantes :

  • Nouveaux types de données V3 : les nouveaux types de données Iceberg V3 (tels que Variant, Geography, Timestamp en nanosecondes, valeurs par défaut et types de données inconnus) ne sont pas acceptés.
  • Suivi de la lignée des lignes : le suivi de la lignée des lignes n'est pas disponible.
  • Écritures BigQuery : les écritures BigQuery ne sont pas compatibles avec les tables V3. Vous ne pouvez lire les tables V3 que depuis BigQuery. Pour créer des tables V3 et y écrire des données, vous devez utiliser des moteurs Open Source (tels qu'Apache Spark, Apache Flink ou Trino).

Exigences concernant le moteur

Assurez-vous d'utiliser une version du moteur compatible avec Iceberg V3 et les vecteurs de suppression binaire. Nous vous recommandons d'utiliser Apache Spark 3.5 ou version ultérieure. Les exemples de ce guide utilisent iceberg-spark-runtime-3.5_2.12:1.10.1.

Lorsque vous configurez votre table et votre session de moteur, assurez-vous des points suivants :

  • Version du format de tableau : doit être définie sur format-version='3'.
  • Mode de suppression : doit être défini sur merge-on-read. Ce mode garantit que les suppressions sont écrites dans des fichiers distincts (les vecteurs de suppression) plutôt que de réécrire les fichiers de données d'origine (copie à l'écriture).

Exemple de configuration de session Spark

La configuration suivante active les extensions Iceberg nécessaires et configure la connexion au catalogue REST :

spark-sql \
    --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.10.1,org.apache.iceberg:iceberg-gcp:1.10.1 \
    --jars https://storage-download.googleapis.com/maven-central/maven2/org/apache/iceberg/iceberg-gcp-bundle/1.10.1/iceberg-gcp-bundle-1.10.1.jar \
    --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
    --conf spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog \
    --conf spark.sql.catalog.CATALOG_NAME.type=rest \
    --conf spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog \
    --conf spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH \
    --conf spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID \
    --conf spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager \
    --conf spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO \
    --conf spark.sql.defaultCatalog=CATALOG_NAME

Remplacez les éléments suivants :

  • CATALOG_NAME : nom de votre point de terminaison de catalogue REST Apache Iceberg.
  • WAREHOUSE_PATH : URI du dossier Cloud Storage dans lequel votre entrepôt de données est stocké, commençant par gs://.
  • PROJECT_ID : ID de votre projet Google Cloud .

Utiliser des vecteurs de suppression binaire

Pour utiliser des vecteurs de suppression binaires dans les tables Apache Iceberg V3, vous devez créer une table avec la version 3 du format, la remplir avec des données, effectuer des modifications de base de données standards et interroger la table. Vous pouvez exécuter toutes les instructions de création, d'insertion, de suppression et de mise à jour à l'aide de SparkSQL.

Créer une table Iceberg avec des vecteurs de suppression binaires

Créez une table en spécifiant format-version='3' et les modes de suppression, de mise à jour et de fusion merge-on-read dans les propriétés de la table. Exécutez l'instruction suivante dans Spark SQL :

Spark 

CREATE NAMESPACE IF NOT EXISTS my_namespace;
USE my_namespace;

CREATE TABLE my_namespace.mytable_v3 (
   id BIGINT,
   city STRING,
   state STRING
) TBLPROPERTIES (
   'format-version'='3',
   'write.delete.mode'='merge-on-read',
   'write.update.mode'='merge-on-read',
   'write.merge.mode'='merge-on-read'
);

Mettre à niveau une table Iceberg V2 vers V3

Vous pouvez mettre à niveau une table Iceberg V2 existante vers la version V3 à l'aide d'instructions ALTER TABLE. Il n'est pas possible de rétrograder une table de la version V3 vers la version V2. Exécutez l'instruction suivante dans SparkSQL :

Spark 

ALTER TABLE my_namespace.mytable_v2 SET TBLPROPERTIES ('format-version' = '3');

Insérer des données dans la table

Pour s'assurer que des fichiers vectoriels de suppression binaire sont générés pour les suppressions, le moteur ne doit pas revenir à la copie sur écriture. Cela nécessite généralement une quantité importante de données dans la table avant l'opération de suppression. Par exemple, Apache Spark peut optimiser les petites suppressions en revenant à la copie sur écriture. Remplissez la table en exécutant les instructions suivantes dans Spark SQL :

Spark 

-- Create a temporary view with a large number of rows (100,000 rows)
CREATE OR REPLACE TEMPORARY VIEW large_source AS
SELECT
  id,
  CAST(id AS STRING) as city,
  'WA' as state
FROM (
  SELECT row_number() OVER (ORDER BY (SELECT NULL)) as id
  FROM (SELECT 0 FROM range(1000)) a
  CROSS JOIN (SELECT 0 FROM range(100)) b
);

-- Overwrite the existing table with the generated data
INSERT OVERWRITE my_namespace.mytable_v3 SELECT * FROM large_source;

Supprimer des données

Exécutez une instruction DELETE dans Spark SQL. Étant donné que la table est configurée pour merge-on-read et qu'elle contient suffisamment de données, Spark génère des fichiers de suppression à l'aide de vecteurs de suppression binaires.

Spark 

DELETE FROM my_namespace.mytable_v3 WHERE id = 5000;

Mettre à jour des données

Exécutez une instruction UPDATE dans Spark SQL. Étant donné que la table est configurée pour merge-on-read et qu'elle contient suffisamment de données, Spark génère des fichiers de suppression à l'aide de vecteurs de suppression binaires.

Spark 

UPDATE my_namespace.mytable_v3 SET state = 'NY' WHERE id = 1;

Interroger la table

Les requêtes sur la table utilisent automatiquement les fichiers vectoriels de suppression binaires pour exclure les lignes supprimées. Vous pouvez interroger la table à l'aide d'Apache Spark ou de BigQuery.

Spark 

-- Should be less than the initial 100,000 rows
SELECT count(*) FROM my_namespace.mytable_v3;

-- Should return no results
SELECT * FROM my_namespace.mytable_v3 WHERE id = 5000;

-- Should return 'NY'
SELECT * FROM my_namespace.mytable_v3 WHERE id = 1;

BigQuery

Lorsque vous interrogez BigQuery, utilisez l'identifiant de table complet PROJECT_ID.CATALOG_NAME.my_namespace.mytable_v3.

bq query --nouse_legacy_sql \
    'SELECT * FROM `PROJECT_ID.CATALOG_NAME.my_namespace.mytable_v3` LIMIT 10'

Vérifier la création de vecteurs de suppression binaires

Vous pouvez vérifier que les vecteurs de suppression binaires ont bien été créés en inspectant le répertoire de stockage et les métadonnées du snapshot.

Rechercher les fichiers .puffin

Accédez au répertoire de données de la table dans votre entrepôt Cloud Storage (par exemple, gs://WAREHOUSE_BUCKET/my_namespace/mytable_v3/data). Vous devriez y trouver des fichiers .puffin, qui stockent les vecteurs de suppression binaires.

Examiner les métadonnées d'un instantané

Les métadonnées d'instantané dans les fichiers JSON de la table Iceberg contiennent des informations sur l'opération de suppression. Recherchez les propriétés telles que added-delete-files, added-dvs et operation dans le récapitulatif de l'instantané. Cela confirme que les fichiers de suppression ont été ajoutés.

"summary": {
  "operation": "delete",
  "added-delete-files": "1",
  "added-dvs": "1",
  "added-files-size": "42",
  "added-position-deletes": "1",
  ...
}

Étapes suivantes