Configurer les options du tableau

La configuration des options de table vous permet d'activer l'interopérabilité d'écriture BigQuery ou la gestion des tables (optimisation automatique du stockage) pour vos tables Apache Iceberg dans le catalogue d'environnements d'exécution Lakehouse. Ces options servent de paramètres de base qui étendent les capacités des opérations sur la table.

En configurant des propriétés de table spécifiques, vous pouvez activer l'interopérabilité en écriture avec le langage DML BigQuery ou activer la gestion automatique des tables (optimisation du stockage).

Lorsque vous utilisez des tables dans le catalogue Lakehouse Runtime, il est utile de comprendre les différents types de tables et leurs fonctionnalités d'activation. Pour en savoir plus sur l'utilisation des tables Apache Iceberg, consultez 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 les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au 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 tableau, 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) : projet
  • Configurez les propriétés de la table en mode sans distribution d'identifiants :
    • Éditeur BigLake (roles/biglake.editor) : projet
    • Utilisateur d'objets Storage (roles/storage.objectUser) : 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.

Points à prendre en compte pour la configuration

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

Tables Iceberg compatibles

Seules les tables Apache Iceberg V2 (disponibilité générale) et V3 (bêta) sont acceptées. Les tables Iceberg V1 ne sont pas acceptées. Pour mettre à niveau les tables V1 existantes, consultez Mettre à niveau les tables Iceberg V1 vers V2.

Exigence de distribution d'identifiants

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

Activer BigQuery DML

L'activation des instructions du langage de manipulation de données (LMD) BigQuery permet l'interopérabilité en écriture depuis 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 automatique 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

Si vous désactivez le LMD BigQuery, la table devient en lecture seule pour BigQuery et la gestion automatique des tables s'arrête.

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 la compaction 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 la table Iceberg configurées par l'utilisateur : history.expire.max-snapshot-age-ms et history.expire.min-snapshots-to-keep. Il supprime les entrées d'instantanés expirées en créant une définition d'instantané supplémentaire, qui se manifeste par un nouveau fichier de métadonnées qui n'inclut plus de 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 automatique des tables. Pour en savoir plus, consultez la section Limites.

  • Regroupement (compaction) : le regroupement est responsable du maintien de la forme des données en fusionnant les petits fichiers en fichiers plus volumineux. Coalesce s'exécute automatiquement en arrière-plan après toute mutation de données. Les fichiers sont sélectionnés pour la compaction si leur taille moyenne non compressée est inférieure à 50% de la taille cible de 256 Mo. Chaque opération de coalescence produit un nouvel instantané de table. Les jobs de fusion cèdent généralement la place aux opérations LMD en cours et les relancent après leur exécution. Toutefois, pour éviter une famine indéfinie de l'optimisation du stockage, un job de fusion est déclenché de force toutes les 24 heures si les données peuvent être fusionnées.

  • Surveillance des jobs de gestion des tables : tous les jobs de gestion des tables en arrière-plan sont enregistré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 jobs 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.

Activer la gestion des tables pour les nouvelles tables

Lorsque vous créez une table à partir de BigQuery, le LMD et la gestion automatique 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.

Par exemple, dans Spark SQL :

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

Désactiver la gestion des tables

Si vous désactivez la gestion des tables, les futurs jobs d'optimisation en arrière-plan ne seront plus mis en file d'attente, mais les jobs actifs en cours seront exécutés. La désactivation de la gestion des tables n'entraîne pas la désactivation du 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 automatique des tables) incluent 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 du runtime 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 au 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 par plusieurs colonnes ou l'évolution des partitions.
  • 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 capacités gérées ne sont pas compatibles avec les tables Iceberg v2 utilisant le mode "merge-on-read". Seules les tables utilisant le mode de mise à jour, de suppression et de fusion "copy-on-write" 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 acceptés pour les fichiers de données.
  • Les capacité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 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, toute mise à jour du schéma à partir de Spark échouera, car Spark lit NUMERIC comme 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 de LDD (ALTER TABLE ... DROP COLUMN), puis de la rajouter immédiatement avec le même nom.

Limites du voyage temporel

  • Lorsque la gestion des tableaux est activée, la valeur maximale recommandée pour la propriété history.expire.max-snapshot-age-ms est de sept jours.
  • Les configurations au niveau du projet ou de l'ensemble de données BigQuery pour la fonctionnalité temporelle 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 période de conservation personnalisée définie à l'aide de ALTER... RETAIN x DAYS est ignorée, et toutes les valeurs définies pour la propriété history.expire.max-ref-age-ms sont ignorées. Les moteurs Open Source peuvent toujours effectuer l'expiration des instantanés.
  • La gestion automatique des tables n'expire pas les schémas ni les 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 automatique des tables. Les moteurs Open Source peuvent nettoyer les fichiers orphelins (par exemple, à l'aide de 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 tableau contient ces propriétés, il n'est pas garanti que la mise en page soit conservée après l'exécution de coalesce. Si vos tables contiennent ces propriétés, la meilleure solution consiste à ne pas activer la gestion des tables.

Limites du partitionnement

  • Lorsque vous créez ou enregistrez des 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 capacités gérées ne sont pas acceptées dans les tables avec des transformations IDENTITY. Les utilisateurs doivent spécifier explicitement la transformation.
  • Les commandes CREATE OR REPLACE sur les tables avec des capacité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.
    • Remplacer une table partitionnée par une table utilisant une spécification de partitionnement différente.
  • Il n'est pas possible de personnaliser le nom des champs de partition. Les tables créées ou enregistrées à partir de moteurs Open Source doivent respecter la convention de dénomination du champ de partition par défaut du moteur (en ajoutant _ et le nom de la transformation, comme _hour, _day, _month ou _year). Par exemple, pour un champ nommé time_date utilisant la transformation DAY, la valeur attendue du champ de partition est la suivante :json { "field-id": 1, "source-id": 1, "name": "time_date_day", "transform": transform }

Limites des propriétés personnalisées des tables Iceberg

Lorsque les fonctionnalités gérées sont activées, les propriétés de comportement du tableau ci-dessous ne peuvent pas être configurées sur des valeurs non définies par défaut. 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 des 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 tâches d'écriture et de gestion de tables BigQuery ne sont compatibles qu'avec la copie lors de l'écriture.
write.update.mode copy-on-write Les tâches d'écriture et de gestion de tables BigQuery ne sont compatibles qu'avec la copie lors de l'écriture.
write.merge.mode copy-on-write Les tâches d'écriture et de gestion de tables BigQuery ne sont compatibles qu'avec la copie lors de l'é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 non conflictuelles) 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 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 de l'écriture et du stockage BigQuery n'est compatible qu'avec les formats de compression zstd et snappy. Les autres formats de compression (tels que 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 de tables suppriment les instantanés plus anciens que 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 de 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 il est possible que les tâches d'écriture et de gestion de tables BigQuery ne les respectent pas.

Étapes suivantes