Utiliser des vecteurs de suppression binaires dans les tables Iceberg V3

Les vecteurs de suppression binaires dans les tables Apache Iceberg V3 vous permettent d'enregistrer les suppressions au niveau des lignes dans les fichiers .puffin sans réécrire l'intégralité des fichiers de données. Au lieu d'effectuer des jointures coûteuses au moment de la requête, les moteurs tels que BigQuery, Managed Service pour Apache Spark, Apache Flink et Trino utilisent ces vecteurs pour identifier et ignorer les lignes supprimées lors des lectures.

Compatible avec le catalogue d'environnements d'exécution Lakehouse, cette optimisation peut améliorer les performances de lecture et d'écriture pour les pipelines de capture de données modifiées (CDC) à volume élevé. Il vous aide également à respecter les exigences réglementaires telles que le RGPD (droit à l'oubli) en supprimant des enregistrements individuels sans avoir à réécrire les fichiers de données.

Avant de commencer

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

  2. Activez l'API BigLake si ce n'est pas déjà fait.

    Rôles requis pour activer les API

    Pour activer des API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). 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 :

  • Créer et gérer des tables Iceberg V3 :
    • Administrateur BigLake (roles/biglake.admin) : votre projet
    • Administrateur de l'espace de stockage (roles/storage.admin) : 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. Assurez-vous d'avoir bien créé l'espace de noms et le catalogue avant de continuer.

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, Nanosecond timestamp, les valeurs par défaut et les types de données inconnus) ne sont pas acceptés.
  • Suivi de la traçabilité des lignes : le suivi de la traçabilité des lignes n'est pas disponible.
  • Écritures BigQuery : les écritures BigQuery ne sont pas compatibles avec les tables V3. Vous ne pouvez lire que les tables V3 à 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).

Exigences relatives au moteur

Assurez-vous d'utiliser une version de moteur compatible avec Iceberg V3 et les vecteurs de suppression binaire. 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 de respecter les 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) plutôt que de réécrire les fichiers de données d'origine (copie sur é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 où est stocké votre entrepôt de données, commençant par gs://.
  • PROJECT_ID : ID de votre projet Google Cloud .

Utiliser des vecteurs de suppression binaires

Pour utiliser des vecteurs de suppression binaires dans des 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 l'interroger. 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, 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. Le passage d'une table de la version 3 à la version 2 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 des fichiers de vecteurs de suppression binaire sont générés pour les suppressions, le moteur ne doit pas revenir à la copie sur écriture. Pour cela, une quantité importante de données doit généralement être présente 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. Comme 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. Comme 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 vecteur de suppression binaire 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 effectuez une requête à 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 des vecteurs de suppression binaire

Vous pouvez vérifier que les vecteurs de suppression binaire ont bien été créés en inspectant le répertoire de stockage et les métadonnées de l'instantané.

Rechercher des 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'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 des propriétés telles que added-delete-files, added-dvs et operation dans le résumé 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