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 (disponibilité générale) 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é en é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 conserve la forme des données et les performances des requêtes en fusionnant les petits fichiers fragmentés en fichiers plus volumineux. La coalescence est évaluée en arrière-plan après les mutations de données. Les fichiers sont éligibles au compactage si leur taille moyenne non compressée est inférieure à 50 % de la taille du 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 fusion est déclenché de force toutes les 24 heures si les données sont éligibles au compactage.

    Les mutations de données, les insertions ou les instruction LMD ne déclenchent pas toutes un job d'optimisation du stockage. Les jobs d'optimisation du stockage s'exécutent dans votre projet et consomment des ressources de calcul. Pour éviter des coûts de calcul inutiles, BigQuery évalue la forme de la table pour déterminer si une optimisation est nécessaire et l'ignore dans les conditions suivantes :

    • Les fichiers de données sont déjà dans un format optimal : si les fichiers sont déjà de taille appropriée (la taille moyenne non compressée est d'au moins 50 % de la taille de fichier cible de 256 Mo), aucune compaction n'est nécessaire.
    • Les seuils ne sont pas atteints : l'optimisation est ignorée si la table n'a pas accumulé suffisamment de petits fichiers ou ne dépasse pas les seuils de taille minimale de la table (par exemple, les tables de moins de 1 Go).

    Lorsque l'optimisation du stockage est ignorée, car les données sont déjà dans un état optimal, aucun job en arrière-plan n'est exécuté.

  • 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 corrélée à l'activité de mutation des données et à la fragmentation des fichiers. Les insertions ou mises à jour fréquentes de petites quantités de données déclenchent des tâches en arrière-plan plus fréquentes. Vous pouvez observer des périodes sans jobs en arrière-plan s'il n'y a pas d'écritures dans la table. Si l'optimisation du stockage est ignorée (par exemple, parce que les données ont été chargées par lots volumineux et que les fichiers sont déjà optimaux), aucune tâche n'apparaît dans INFORMATION_SCHEMA.JOBS pour cette opération, ce qui est le comportement attendu.

    Pour observer les jobs de gestion des tables dans un environnement de test ou de développement, insérez plusieurs petits lots de données au fil du temps dans une table d'une taille totale supérieure à 1 Go. Cela crée de petits fichiers fragmentés qui sont inférieurs au seuil de taille cible de 50 % et déclenchent le compactage.

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 compression 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 Open Source ou LMD.

  • 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 préserve pas.

  • Vos tables utilisent des tags ou des branches d'instantanés Apache Iceberg (ce qui entraîne 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 les 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 (comme 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 qui utilisent un partitionnement avancé, comme 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 : La suppression d'une colonne dans BigQuery à l'aide du LDD (ALTER TABLE ... DROP COLUMN) suivie immédiatement de l'ajout d'une colonne portant le même nom n'est pas acceptée.

Limites de la fonctionnalité de voyage temporel

  • Lorsque la gestion des tables est activée, la valeur maximale autorisée pour la propriété history.expire.max-snapshot-age-ms est de 30 jours (2592000000 ms) et la valeur maximale recommandée est de 7 jours (604800000 ms). La valeur maximale autorisée pour la propriété history.expire.min-snapshots-to-keep est 100.
  • 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 des tables 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 ni 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 compatibles 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 lorsque n'importe quelle 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 Comportement identique à write.delete.isolation-level.
write.merge.isolation-level Détection stricte des conflits Comportement identique à write.delete.isolation-level.

Vous pouvez configurer les propriétés suivantes lorsque vous créez ou modifiez des 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 non négatif jusqu'à 2592000000 (30 jours) lorsque la gestion des tables est activée, avec une recommandation de 7 jours (604800000 ms) maximum. 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 jusqu'à 100 lorsque la gestion des tables est activée. 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 tâches de gestion des tables peuvent ne pas les respecter.

Étapes suivantes