Utiliser des vecteurs de suppression binaires dans les tables Iceberg V3

Le catalogue d'exécution Lakehouse est compatible avec les tables Apache Iceberg V3. Une fonctionnalité essentielle de la spécification Apache Iceberg V3 est la suppression binaire des vecteurs. Cette optimisation stocke les suppressions au niveau des lignes dans des fichiers .puffin. Au lieu d'effectuer des jointures coûteuses au moment de la requête, 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 des manières suivantes :

  • Écritures à volume élevé : améliore les performances d'écriture pour les tables avec des écritures à volume élevé.
  • Lectures efficaces : améliore 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 de modification (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 Google Cloud projet.

  2. Activez l'API BigLake.

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur d'utilisation du service (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 via 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. Assurez-vous de créer l'espace de noms et le catalogue avant de continuer.

Limites

Les tables Iceberg V3 du catalogue 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 compatibles.
  • Suivi de la provenance des lignes : le suivi de la provenance des lignes n'est pas compatible.
  • Écritures BigQuery : les écritures BigQuery ne sont pas compatibles avec les tables V3. Vous ne pouvez lire les tables V3 qu'à partir de 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).

Configuration requise pour le moteur

Assurez-vous d'utiliser une version de moteur compatible avec Iceberg V3 et les vecteurs de suppression binaires. Apache Spark 3.5 ou version ultérieure est recommandé. 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 table : 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) au lieu 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 du point de terminaison de votre catalogue REST Apache Iceberg.
  • WAREHOUSE_PATH : URI du dossier Cloud Storage dans lequel votre entrepôt de données est stocké, en commençant par gs://.
  • PROJECT_ID: ID de votre Google Cloud projet.

Utiliser des vecteurs de suppression binaires

Pour utiliser des vecteurs de suppression binaires dans les tables Apache Iceberg V3, vous devez créer une table avec la version de formatage 3, 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 Spark SQL.

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 merge-on-read, 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 la version V3

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

Spark 

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

Insérer des données dans la table

Pour s'assurer que les fichiers de vecteurs de suppression binaires sont générés pour les suppressions, le moteur ne doit pas revenir à la copie à l'é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 à l'é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 de vecteurs 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 à partir de 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 été créés en inspectant le répertoire de stockage et les métadonnées d'instantané.

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 trouver des fichiers .puffin, qui stockent les vecteurs de suppression binaires.

Examiner les métadonnées d'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 des propriétés telles que added-delete-files, added-dvs et operation dans le résumé de l'instantané. Cela confirme que des 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",
  ...
}

Étape suivante