Configurer les options du tableau

La configuration des options de table vous permet d'activer l'interopérabilité en écriture BigQuery ou la gestion des tables (optimisation automatique du stockage) pour vos tables Apache Iceberg dans le catalogue d'exécution Lakehouse. Ces options servent de paramètres de base qui étendent les fonctionnalité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 BigQuery DML ou la gestion automatique des tables (optimisation du stockage).

Lorsque vous utilisez des tables dans le catalogue d'exécution Lakehouse, 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 tables.

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

  3. Configurez le catalogue 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 :

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.

Points à prendre en compte pour la configuration

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

Tables Iceberg compatibles

Seules les tables Apache Iceberg V2 (DG) et V3 (bêta) sont compatibles. Les tables Iceberg V1 ne sont pas compatibles. Pour mettre à niveau les tables V1 existantes, consultez Mettre à niveau les tables Iceberg V1 vers la version 2.

Exigence concernant la distribution d'identifiants

Pour activer la gestion automatique des tables, la distribution d'identifiants doit être activée au niveau du catalogue dans votre catalogue d'exécution Lakehouse. Les tâches d'arrière-plan de gestion des tables utilisent le compte de service de distribution d'identifiants pour s'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 BigQuery DML pour les nouvelles tables

Lorsque vous créez une table à partir de BigQuery, BigQuery DML 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 BigQuery DML pour les tables existantes

Pour activer BigQuery DML 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 BigQuery DML

La désactivation de BigQuery DML rend la table en lecture seule pour BigQuery et arrête la gestion automatique des tables.

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 d'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 à partir 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. Elle supprime les entrées d'instantané expirées du fichier metadata.json, puis supprime physiquement les fichiers de données et de métadonnées qui appartenaient uniquement aux instantanés expirés et qui ne sont plus référencés par aucun instantané actif.

    • Limite : 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.

    • Limite : 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.

  • Fusion (compaction) : la fusion est chargée de maintenir la forme des données en fusionnant les petits fichiers en fichiers plus volumineux. La fusion 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 fusion produit un nouvel instantané de table. Les tâches de fusion cèdent généralement la place aux opérations LMD en cours et retentent après celles-ci. Toutefois, pour éviter une privation indéfinie de l'optimisation du stockage, une tâche de fusion est déclenchée de force toutes les 24 heures si les données sont éligibles à la fusion.

  • Surveillance des tâches de gestion des tables : toutes les tâches de gestion des tables en arrière-plan sont consignées dans la vue INFORMATION_SCHEMA.JOBS de BigQuery. Vous pouvez interroger cette vue pour suivre ces opérations, comme vous le faites pour les autres tâches BigQuery. Pour en savoir plus sur l'interrogation des informations sur les tâches, consultez Obtenir des tâches d'optimisation du stockage Iceberg.

    La fréquence des tâches 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 d'arrière-plan plus fréquentes. Vous pouvez observer des périodes sans tâches d'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 tâche plus visible dans INFORMATION_SCHEMA.

Activer la gestion des tables pour les nouvelles tables

Lorsque vous créez une table à partir de BigQuery, 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 BigQuery DML 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

La désactivation de la gestion des tables empêche la mise en file d'attente des futures tâches d'optimisation en arrière-plan, bien que les tâches actives en cours se terminent. La désactivation de la gestion des tables ne désactive pas BigQuery DML.

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é en écriture BigQuery et la gestion automatique des tables) incluent les éléments suivants :

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'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 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 disposent d'un partitionnement avancé, tel que le partitionnement par STRING, le partitionnement sur 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 en définissant write.distribution.mode = range).
  • Les fonctionnalités gérées ne sont pas compatibles avec les tables Iceberg v2 utilisant le mode de fusion en lecture. Seules les tables utilisant le mode de mise à jour, de suppression et de fusion en 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 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 par défaut du bucket Cloud Storage est requis pour contenir 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'exécution Lakehouse.
  • Si une table est créée avec le NUMERIC type de données dans BigQuery, toutes les mises à jour de schéma à partir de Spark échoueront, 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 : la suppression d'une colonne dans BigQuery à l'aide de LDD (ALTER TABLE ... DROP COLUMN), suivie immédiatement de l'ajout d'une colonne portant le même nom, n'est pas compatible.

Limites concernant la fonctionnalité temporelle

Limites concernant 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 history.expire.max-ref-age-ms propriété 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 effectuer le nettoyage des fichiers orphelins (par exemple, à l'aide de la procédure Spark remove_orphan_files avec l'option prefix_listing définie sur true).

  • La fusion n'est pas compatible avec le tri linéaire ni l'ordre z. 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, la meilleure solution consiste à ne pas activer la gestion des tables.

Limites concernant le 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, TIMESTAMP, et TIMESTAMPTZ avec les transformations hour, day, month, et year(à l'exception de la transformation hour sur les champs DATE).
  • Les fonctionnalités gérées ne sont pas compatibles avec les tables comportant des transformations IDENTITY. Les utilisateurs doivent spécifier explicitement la transformation.
  • Les commandes CREATE OR REPLACE sur les tables avec des 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 compatibles :
    • 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.
  • La dénomination personnalisée des champs de partition n'est pas compatible. Les tables créées ou enregistrées à partir de moteurs Open Source doivent suivre la convention de dénomination par défaut des champs de partition du moteur (ajout de _ et du nom de la transformation, tel que _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 concernant les 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 non 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 ne sont compatibles qu'avec les fichiers de données au format Parquet.
write.data.path table location + /data Le chemin d'accès par défaut du bucket Cloud Storage configuré pour le catalogue REST Lakehouse est utilisé pour écrire des fichiers de données.
write.metadata.path table location + /metadata Le chemin d'accès par défaut du bucket Cloud Storage configuré pour le catalogue REST Lakehouse est utilisé pour écrire des fichiers de métadonnées.
write.delete.mode copy-on-write Les tâches d'écriture et de gestion des tables BigQuery ne sont compatibles qu'avec la copie sur écriture.
write.update.mode copy-on-write Les tâches d'écriture et de gestion des tables BigQuery ne sont compatibles qu'avec la copie sur écriture.
write.merge.mode copy-on-write Les tâches 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 Les écritures BigQuery et l'optimisation du stockage ne sont compatibles qu'avec les formats de compression zstd et snappy. Les autres formats de compression (tels que gzip, brotli et lz4) ne sont pas compatibles.
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 tâches de gestion des 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 tâches 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 tâches d'écriture et de gestion des tables BigQuery peuvent ne pas les respecter.

Étape suivante