Configurer les options du tableau

Vous pouvez utiliser les options de table du catalogue d'environnements d'exécution Lakehouse pour activer l'interopérabilité d'écriture LMD BigQuery et la gestion des tables (optimisation automatique du stockage) pour vos tables Apache Iceberg.

Pour en savoir plus sur les formats de table compatibles et les fonctionnalités d'activation dans le catalogue d'exécution Lakehouse, consultez Comparer les types de tables et Présentation des tables Apache Iceberg.

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

  3. Configurez le catalogue d'environnements d'exécution Lakehouse avec le point de terminaison du catalogue REST Apache Iceberg.

Rôles requis

Pour obtenir les autorisations nécessaires pour configurer les options de table, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet et votre bucket de stockage :

  • Configurez les propriétés de la table en mode de distribution des identifiants : Éditeur BigLake (roles/biglake.editor) - le projet
  • Configurez les propriétés de la table en mode de distribution sans identifiants :
    • Éditeur BigLake (roles/biglake.editor) : le projet
    • Utilisateur d'objets Storage (roles/storage.objectUser) : sur le bucket Cloud Storage

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.

Facteurs de configuration

Tenez compte des exigences et des comportements par défaut suivants lorsque vous configurez les options de table :

Tables Iceberg compatibles

Bien que le catalogue d'environnements d'exécution Lakehouse soit compatible avec les tables Apache Iceberg V2 (DG) et V3 (preview), les fonctionnalités gérées (LMD BigQuery et gestion des tables) ne sont compatibles qu'avec les tables Iceberg V2. Les tables Iceberg V1 ne sont pas compatibles. Pour mettre à niveau des tables V1 existantes, consultez Mettre à niveau des tables Iceberg V1 vers la V2.

Exigence de distribution d'identifiants

Pour accepter la gestion des tables, votre catalogue d'environnements d'exécution Lakehouse doit avoir la distribution d'identifiants activée au niveau du catalogue. Les jobs en arrière-plan de gestion des tables utilisent le compte de service de distribution d'identifiants pour authentifier et mettre à jour les fichiers de données de stockage sous-jacents.

Activer le LMD BigQuery

L'activation des instructions du langage de manipulation de données (LMD) BigQuery débloque l'interopérabilité d'écriture de BigQuery sur les tables Apache Iceberg créées à l'aide de moteurs Open Source.

Les instructions compatibles incluent INSERT, UPDATE, DELETE et MERGE, ainsi que les instructions LDD standards telles que CREATE TABLE, ALTER TABLE et DROP TABLE, à l'exception de celles qui ne sont pas compatibles avec les tables Apache Iceberg dans BigQuery.

Activer le LMD BigQuery pour les nouvelles tables

Lorsque vous créez une table à partir de BigQuery, le LMD BigQuery et la gestion des tables sont activés par défaut. Lorsque vous créez une table à partir de moteurs Open Source, configurez la propriété de table gcp.biglake.bigquery-dml.enabled = true à l'aide de la syntaxe LDD de votre moteur.

Par exemple, dans Spark SQL :

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

Activer le LMD BigQuery pour les tables existantes

Pour activer le LMD BigQuery sur une table existante, mettez à jour la propriété de la table.

Par exemple, dans Spark SQL :

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

Désactiver le LMD BigQuery

La désactivation du LMD BigQuery rend la table accessible en lecture seule pour BigQuery et arrête la gestion de la table.

Par exemple, dans Spark SQL :

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = false);

Activer la gestion des tables

La gestion des tables automatise les processus en arrière-plan pour optimiser le stockage et gérer le cycle de vie des données et des métadonnées, comme le compactage et la récupération de mémoire.

La gestion des tables vous permet d'effectuer les opérations suivantes :

  • Expiration des instantanés et récupération de mémoire : l'expiration des instantanés gère la conservation et la suppression des fichiers de données et de métadonnées des instantanés de table. Cette opération s'exécute automatiquement en arrière-plan après toute mutation de données. Les instantanés expirent en fonction des propriétés de table Iceberg configurées par l'utilisateur history.expire.max-snapshot-age-ms et history.expire.min-snapshots-to-keep sur la table. Il supprime les entrées d'instantanés arrivées à expiration en créant une définition d'instantané supplémentaire dans un nouveau fichier de métadonnées qui omet les références aux instantanés supprimés.

    • Limitation : l'expiration des instantanés et la récupération de mémoire associée sont ignorées si la table utilise des tags ou des branches. Pour en savoir plus, consultez la section Limites.

    • Limitation : La suppression des fichiers orphelins n'est pas gérée par la gestion des tables. Pour en savoir plus, consultez Limites.

  • Coalesce (compaction) : Coalesce est chargé de maintenir la forme des données en fusionnant les petits fichiers en fichiers plus volumineux. La coalescence s'exécute automatiquement en arrière-plan après toute mutation de données. Les fichiers sont sélectionnés pour le compactage si leur taille moyenne non compressée est inférieure à 50% de la taille de fichier cible de 256 Mo. Chaque opération de fusion produit un nouvel instantané de table. Les jobs de fusion sont généralement interrompus et relancés après toute opération LMD en cours d'exécution. Toutefois, pour éviter une privation indéfinie de l'optimisation du stockage, un job de coalescence est déclenché de force toutes les 24 heures si les données sont éligibles à la coalescence.

  • Surveillance des jobs de gestion des tables : tous les jobs de gestion des tables en arrière-plan sont consignés dans la vue INFORMATION_SCHEMA.JOBS de BigQuery. Vous pouvez interroger cette vue pour suivre ces opérations, de la même manière que vous surveillez d'autres jobs BigQuery. Pour en savoir plus sur l'interrogation des informations sur les jobs, consultez Obtenir des jobs d'optimisation du stockage Iceberg.

    La fréquence des jobs de gestion des tables est directement corrélée à l'activité de mutation des données. Les petites insertions ou mises à jour fréquentes déclenchent des tâches en arrière-plan plus fréquentes. Vous pouvez observer des périodes sans tâches en arrière-plan si aucune écriture n'est effectuée dans la table. À l'inverse, des volumes d'écriture élevés peuvent entraîner une activité de job plus visible dans INFORMATION_SCHEMA.

Choisir d'activer ou non la gestion des tables

Pour les tables Apache Iceberg gérées par le catalogue d'environnements d'exécution Lakehouse et diffusées via le point de terminaison du catalogue REST Apache Iceberg, vous pouvez activer la gestion des tables ou gérer vous-même la maintenance des tables (comme la compaction et l'expiration des instantanés) à l'aide de moteurs Open Source ou tiers.

Activez la gestion des tables (gcp.biglake.table-management.enabled = true) lorsque toutes les conditions suivantes sont remplies :

  • Vous souhaitez automatiser la compression des fichiers en arrière-plan (agglomération), l'expiration des instantanés et la récupération de mémoire après des écritures en flux continu LMD ou Open Source.

  • Votre catalogue utilise le mode de distribution d'identifiants.

  • Une fenêtre de conservation des instantanés et de voyage temporel de sept jours maximum (cinq jours par défaut) répond à vos exigences.

  • Votre table répond aux exigences des fonctionnalités gérées (voir Limites).

Laissez la gestion des tables désactivée (par défaut pour les tables créées à partir de moteurs Open Source, ou définissez gcp.biglake.table-management.enabled = false) et gérez vous-même la maintenance des tables lorsque l'une des conditions suivantes s'applique :

  • Vous exécutez des procédures de compactage ou de maintenance personnalisées dans des moteurs Open Source tels qu'Apache Spark, Apache Flink ou Trino, en particulier si vos tables reposent sur des mises en page de tri linéaire ou de tri en Z que la fusion ne conserve pas.

  • Vos tables utilisent des tags ou des branches d'instantanés Apache Iceberg (qui entraînent l'omission de l'expiration des instantanés par la gestion des tables), ou nécessitent une conservation des instantanés et une fonctionnalité temporelle de plus de sept jours.

  • Votre catalogue utilise les identifiants de l'utilisateur final (autorisations IAM (Identity and Access Management) Cloud Storage directes) au lieu du mode de distribution des identifiants.

  • Vos tables utilisent des fonctionnalités qui ne sont pas compatibles avec les fonctionnalités gérées (auquel cas la gestion des tables et le LMD BigQuery doivent rester désactivés), telles que le format Apache Iceberg version 3, le mode de fusion à la lecture, le partitionnement multicolonne ou IDENTITY, ou des chemins de stockage de données et de métadonnées personnalisés. Pour obtenir la liste complète des fonctionnalités non compatibles, consultez la section Limites.

Activer la gestion des tables pour les nouvelles tables

Lorsque vous créez une table à partir de BigQuery, le LMD et la gestion des tables sont activés par défaut. Lorsque vous créez une table à partir de moteurs Open Source, configurez la propriété gcp.biglake.table-management.enabled. L'activation de la gestion des tables active automatiquement le LMD BigQuery s'il n'est pas déjà activé.

Par exemple, dans Spark SQL :

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

Activer la gestion des tables pour les tables existantes

Pour activer la gestion des tables sur une table existante, mettez à jour la propriété de la table.

Spark SQL 

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

BigQuery 

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "enabled");

Désactiver la gestion des tables

La désactivation de la gestion des tables empêche la mise en file d'attente des futurs jobs d'optimisation en arrière-plan, bien que les jobs actifs en cours se terminent. La désactivation de la gestion des tables ne désactive pas le LMD BigQuery.

Spark SQL 

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = false);

BigQuery 

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "disabled");

Limites

Les limites des fonctionnalités gérées (telles que l'interopérabilité d'écriture BigQuery et la gestion des tables) sont les suivantes :

Limites générales

  • Les fonctionnalités gérées ne sont compatibles qu'avec les tables Apache Iceberg créées dans le catalogue d'environnements d'exécution Lakehouse à l'aide du point de terminaison du catalogue REST Apache Iceberg.
  • Toutes les limites existantes pour les tables Apache Iceberg gérées par BigQuery s'appliquent aux opérations pour lesquelles les fonctionnalités gérées sont activées.
  • Les fonctionnalités gérées ne sont pas compatibles avec les tables au format Apache Iceberg version 3. Seules les tables de format version 2 (spécification Iceberg v2) peuvent être activées pour les fonctionnalités gérées.
  • Les fonctionnalités gérées ne sont pas compatibles avec les tables dotées d'un partitionnement avancé, tel que le partitionnement par STRING, le partitionnement multicolonne ou l'évolution de partition.
  • Les fonctionnalités gérées ne sont pas compatibles avec les tables configurées avec des ordres de tri (par exemple, à l'aide de la procédure WRITE ORDER BY ou du paramètre write.distribution.mode = range).
  • Les fonctionnalités gérées ne sont pas compatibles avec les tables Iceberg v2 utilisant le mode de fusion à la lecture. Seules les tables utilisant le mode de mise à jour, de suppression et de fusion de copie sur écriture peuvent être activées pour les fonctionnalités gérées.
  • Les fonctionnalités gérées ne sont pas compatibles avec les fichiers de données compressés à l'aide des codecs gzip, lz4 ou brotli (write.parquet.compression-codec). Seuls les types de compression zstd et snappy sont compatibles avec les fichiers de données.
  • Les fonctionnalités gérées ne sont pas compatibles avec les tables si le schéma contient des identifiants de clé primaire imbriqués (identifier-field-ids) qui font référence à des chemins d'accès ou des champs imbriqués dans une structure.
  • Les fonctionnalités gérées ne sont pas compatibles avec les tables dont les emplacements de données ou de métadonnées sont personnalisés (write.data.path et write.metadata.path). L'emplacement du bucket Cloud Storage par défaut est requis pour stocker les fichiers de données et de métadonnées.
  • Le clustering BigQuery n'est pas compatible avec les tables Apache Iceberg gérées par le catalogue d'environnements d'exécution Lakehouse.
  • Si une table est créée avec le type de données NUMERIC dans BigQuery, toutes les mises à jour de schéma de Spark échouent, car Spark lit NUMERIC en tant que NUMERIC(38,9). Pour contourner ce problème, lorsque vous créez des tables avec le type NUMERIC dans BigQuery, définissez explicitement la précision sur NUMERIC(38,9).
  • Problème connu : Il n'est pas possible de supprimer une colonne dans BigQuery à l'aide du LDD (ALTER TABLE ... DROP COLUMN), puis de rajouter immédiatement une colonne portant le même nom.

Limites de la fonctionnalité de voyage temporel

  • Lorsque la gestion des tables est activée, la valeur maximale recommandée pour la propriété history.expire.max-snapshot-age-ms est de sept jours.
  • Les configurations BigQuery au niveau du projet ou de l'ensemble de données pour les fonctionnalités temporelles ne s'appliquent pas. Seules les propriétés et les valeurs par défaut de la table Iceberg sont actives.

Limites de la gestion des tables

  • L'expiration des instantanés est ignorée pour l'ensemble de la table si celle-ci contient des instantanés avec des tags ou des branches. La conservation personnalisée définie à l'aide de ALTER... RETAIN x DAYS est ignorée, de même que toutes les valeurs définies pour la propriété history.expire.max-ref-age-ms. Les moteurs Open Source peuvent toujours effectuer l'expiration des instantanés.
  • La gestion des tables n'entraîne pas l'expiration des schémas ni des spécifications de partition. Le fichier metadata.json conserve l'historique complet des schémas et des spécifications de partition, même si aucun instantané ne fait référence à ces ID de schéma.

  • Les fichiers orphelins créés par BigQuery ou des moteurs Open Source ne sont pas nettoyés par la gestion des tables. Les moteurs Open Source peuvent nettoyer les fichiers orphelins (par exemple, en utilisant la procédure Spark remove_orphan_files avec l'option prefix_listing définie sur true).

  • Coalesce n'est pas compatible avec l'ordre Z et le tri linéaire. Si votre table contient ces propriétés, il n'est pas garanti que la mise en page soit conservée après l'exécution de la fusion. Si vos tables contiennent ces propriétés, n'activez pas la gestion des tables.

Limites du partitionnement

  • Lors de la création ou de l'enregistrement de tables à partir de moteurs Open Source, les fonctionnalités gérées ne sont compatibles qu'avec le partitionnement sur les types de champs DATE, DATETIME et TIMESTAMP avec les transformations hour, day, month et year (à l'exception de la transformation hour sur les champs DATE) et les types de champs INTEGER.
  • Les fonctionnalités gérées ne sont pas compatibles avec les tables comportant des transformations IDENTITY. Vous devez spécifier explicitement la transformation.
  • Les commandes CREATE OR REPLACE sur les tables dotées de fonctionnalités gérées ne sont acceptées que si elles utilisent la même spécification de partition. Les remplacements suivants ne sont pas acceptés :
    • Remplacer une table non partitionnée par une table partitionnée.
    • Remplacer une table partitionnée par une table non partitionnée
    • Remplacement d'une table partitionnée par une table utilisant une spécification de partitionnement différente.
  • La dénomination personnalisée des champs de partition n'est pas acceptée. Les tables créées ou enregistrées à partir de moteurs Open Source doivent respecter la convention d'attribution de noms de champ de partition par défaut du moteur (en ajoutant _ et le nom de la transformation, par exemple _hour, _day, _month ou _year). Par exemple, pour un champ nommé time_date utilisant la transformation DAY, la valeur de champ de partition attendue est : json { "field-id": 1, "source-id": 1, "name": "time_date_day", "transform": transform }.

Limites des propriétés de table Iceberg personnalisées

Les propriétés de comportement de table suivantes ne peuvent pas être configurées sur des valeurs autres que celles par défaut lorsque les fonctionnalités gérées sont activées. Les valeurs par défaut sont codées en dur lorsqu'une fonctionnalité gérée est activée :

Propriété Valeur par défaut Détails
format-version 2 Les fonctionnalités gérées ne sont compatibles qu'avec les tables Iceberg v2.
write.format.default parquet Les tables n'acceptent que les fichiers de données au format Parquet.
write.data.path table location + /data Le chemin d'accès au bucket Cloud Storage par défaut configuré pour le point de terminaison du catalogue Apache Iceberg REST est utilisé pour écrire les fichiers de données.
write.metadata.path table location + /metadata Le chemin d'accès au bucket Cloud Storage par défaut configuré pour le point de terminaison du catalogue Apache Iceberg REST est utilisé pour écrire les fichiers de métadonnées.
write.delete.mode copy-on-write Les jobs d'écriture et de gestion des tables BigQuery ne sont compatibles qu'avec la copie sur écriture.
write.update.mode copy-on-write Les jobs d'écriture et de gestion des tables BigQuery ne sont compatibles qu'avec la copie sur écriture.
write.merge.mode copy-on-write Les jobs d'écriture et de gestion des tables BigQuery ne sont compatibles qu'avec la copie sur écriture.
write.delete.isolation-level Détection stricte des conflits Les modifications qui modifient le fichier metadata.json (y compris les conflits de données, les conflits de métadonnées, les lectures fantômes ou les écritures simultanées sans conflit) entraînent l'échec et la nouvelle tentative de la transaction simultanée.
write.update.isolation-level Détection stricte des conflits Même comportement que write.delete.isolation-level.
write.merge.isolation-level Détection stricte des conflits Même comportement que write.delete.isolation-level.

Les propriétés suivantes peuvent être configurées lors de la création ou de la modification de tables à partir de moteurs Open Source :

Propriété Valeur par défaut Détails
write.parquet.compression-codec zstd L'optimisation des écritures et du stockage BigQuery n'est compatible qu'avec les formats de compression zstd et snappy. Les autres formats de compression (comme gzip, brotli et lz4) ne sont pas acceptés.
write.metadata.compression-codec null Peut être configuré sur null ou gzip.
history.expire.max-snapshot-age-ms 432000000 (5 jours) Peut être configuré sur n'importe quel entier positif, mais il est recommandé de ne pas dépasser sept jours (604 800 000 ms) lorsque la gestion des tables est activée. Les jobs de gestion des tables suppriment les instantanés antérieurs à la durée spécifiée.
history.expire.min-snapshots-to-keep 1 Peut être configuré sur n'importe quel entier positif. Les jobs de gestion des tables conservent au moins ce nombre d'instantanés.

D'autres propriétés d'écriture Apache Iceberg, telles que write.target-file-size-bytes et write.parquet.page-size-bytes, peuvent être configurées à partir de moteurs Open Source, mais les écritures BigQuery et les jobs de gestion des tables peuvent ne pas les respecter.

Étapes suivantes