À propos du point de terminaison du catalogue REST Apache Iceberg

Lakehouse pour Apache Iceberg gère les métadonnées via le catalogue d'environnements d'exécution Lakehouse. Lorsque vous utilisez le point de terminaison du catalogue Apache Iceberg REST, le système organise les données dans une hiérarchie de ressources stricte. La configuration du catalogue détermine les types de stockage compatibles, les comportements de routage régionaux et les options de fédération de requêtes.

Fonctionnalités et conformité

Le catalogue d'environnements d'exécution Lakehouse est conçu pour s'intégrer aux moteurs de requêtes compatibles avec Iceberg en acceptant les formats de table standards et en respectant les API ouvertes.

Formats de table compatibles

Les tables Apache Iceberg V2 (disponibilité générale) et V3 (bêta) sont compatibles. Les tables Iceberg V1 ne sont pas compatibles. Avant d'utiliser des tables V1 existantes avec le point de terminaison du catalogue Apache Iceberg REST, vous devez les mettre à niveau vers une version compatible. Pour en savoir plus, consultez la section Mettre à niveau des tables Iceberg V1 vers la version V2.

Conformité de l'API et opérations REST

Le catalogue d'environnements d'exécution Lakehouse implémente l'API de catalogue Apache Iceberg REST, qui est une norme ouverte. Les moteurs de requêtes clients interagissent avec le catalogue à l'aide d'API de catalogue REST standards. Pour en savoir plus, consultez la section Comment Lakehouse implémente l'API de catalogue Apache Iceberg REST.

Hiérarchie des ressources

Le point de terminaison du catalogue Apache Iceberg REST utilise une hiérarchie de ressources pour organiser vos données. Le tableau suivant présente ces ressources de manière générale :

Catalogues et emplacements de stockage

La configuration d'un catalogue détermine son fonctionnement et son intégration aux services Google Cloud. Vous pouvez configurer un catalogue à plusieurs buckets (bl://, recommandé) ou un catalogue à bucket unique (gs://).

Les deux options sont compatibles avec la distribution d'identifiants.

Catalogue à plusieurs buckets (bl://, recommandé)

Cette approche vous permet de nommer votre catalogue indépendamment de tout nom de bucket et de configurer plusieurs buckets pour un seul catalogue. Dans l'API sous-jacente, cela correspond à la CATALOG_TYPE_BIGLAKE configuration.

Remarques :

• Emplacement par défaut : vous fournissez un chemin d'accès à un bucket (default_location) ou à un sous-chemin (tel que gs://my-bucket/path) pour qu'il serve d'emplacement de stockage par défaut. Toutes les ressources du catalogue (espaces de noms et tables) doivent se trouver sous le chemin spécifié. Par exemple, si vous spécifiez gs://my-bucket/path, vous ne pouvez pas héberger d'espaces de noms ni de tables sous gs://my-bucket/another/path. Pour les espaces de noms créés sans emplacement spécifié, default_location est utilisé.
• Emplacements restreints : vous pouvez également fournir une configuration facultative restricted_locations pour les buckets ou chemins supplémentaires où des espaces de noms et des tables peuvent être créés. Si vous spécifiez un sous-chemin (tel que gs://my-bucket/path), toutes les ressources créées à l'aide de cette configuration doivent se trouver sous ce chemin (par exemple, gs://my-bucket/another/path ne peut pas héberger d'espaces de noms ni de tables).
• Exigences concernant les groupes de régions géographiques : bien que les buckets puissent être multiprojets, multirégionaux et avoir des configurations différentes (par exemple, une seule région, une double région ou plusieurs régions), tous les emplacements Cloud Storage de la position par défaut et des emplacements restreints doivent se trouver dans le même groupe de régions géographiques (par exemple, les États-Unis, l'Europe, le Canada ou l'Asie). Par exemple, vous ne pouvez pas configurer un bucket multirégional américain avec un bucket en Europe ou au Canada.
• Plusieurs catalogues par bucket : vous pouvez faire pointer plusieurs catalogues vers le même bucket (par exemple, en utilisant différents emplacements par défaut ou emplacements restreints). Toutefois, cette configuration est fortement déconseillée, car elle peut entraîner des conflits de métadonnées, des écrasements accidentels de données ou des problèmes de sécurité tels que des fuites d'autorisations.
• Espaces de noms : permettent de spécifier des emplacements d'espaces de noms personnalisés, à condition qu'ils se trouvent sous un chemin configuré dans les emplacements par défaut ou restreints. Notez que les tables créées dans ces catalogues seront automatiquement suffixées par une chaîne aléatoire dans leurs chemins physiques pour éviter les conflits (par exemple, gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}). Pour en savoir plus, consultez la section Règles de gestion et de sécurité des tables.

Catalogue à bucket unique (gs://)

Il s'agit de l'ancienne approche dans laquelle le catalogue gère directement les métadonnées et les fichiers de données Apache Iceberg dans un seul bucket Cloud Storage que vous spécifiez. Dans l' API sous-jacente, cela correspond à la CATALOG_TYPE_GCS_BUCKET configuration.

Pour les catalogues à bucket unique, le nom du catalogue est défini sur le nom de votre bucket.

Par exemple, si vous avez créé votre bucket pour stocker votre catalogue et que vous l'avez nommé iceberg-bucket, le nom de votre catalogue et le nom de votre bucket sont tous deux iceberg-bucket. Cela sera utilisé ultérieurement lorsque vous interrogerez votre catalogue dans BigQuery à l'aide de la syntaxe P.C.N.T. Par exemple, my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table.

Remarques :

• Limites de l'ancien type de catalogue. L'utilisation de l'ancienne configuration à bucket unique est fortement déconseillée pour les nouveaux projets. Cette configuration présente plusieurs limites critiques :

  • Nom du catalogue : verrouillé sur le nom du bucket Cloud Storage sous-jacent.
  • Projet : verrouillé sur le projet du bucket (les catalogues multiprojets ne sont pas compatibles).
  • Région : strictement dérivée de l'emplacement du bucket et ne peut pas être personnalisée.
  • Stockage : limite votre catalogue à un seul bucket (aucun emplacement restreint).

• Restriction d'un catalogue par bucket : pour cet ancien type de catalogue, vous ne pouvez avoir qu'un seul catalogue par bucket, et le nom du catalogue doit correspondre au nom du bucket.

• Mettre à niveau vers un catalogue à plusieurs buckets (bl://, recommandé) : vous pouvez mettre à niveau un catalogue à bucket unique (gs://) existant vers un catalogue à plusieurs buckets (bl://, recommandé). Le catalogue mis à niveau conserve le nom du bucket d'origine. Vous pouvez ensuite associer plusieurs buckets au catalogue et configurer des emplacements restreints.

Régions de bucket et de catalogue

La région d'un point de terminaison de catalogue dans le catalogue d'environnements d'exécution Lakehouse est déterminée par la région de son bucket Cloud Storage sous-jacent :

• Catalogue à plusieurs buckets (bl://) (recommandé) : la région du catalogue est dérivée du bucket configuré dans default_location.
• Bucket unique (gs://) : la région du catalogue est strictement dérivée du bucket associé au catalogue et ne peut pas être personnalisée.

La région du catalogue mappée varie en fonction du type de région du bucket :

• Région unique : la région du catalogue correspond exactement à la région du bucket.
• Double région : la région du catalogue correspond à la double région du bucket (par exemple, ASIA1 ou NAM4).
• Multirégion : la région du catalogue est définie sur un emplacement régional spécifique dans le domaine géographique de la multirégion. Par défaut, cela peut ne pas correspondre aux multirégions BigQuery courantes telles que US et EU (par exemple, un bucket multirégional US est mappé sur us-central1 ou us-east4).

Lorsque BigQuery exécute une requête sur des tables dans ces catalogues, il la route vers la région principale du catalogue. Si vous interrogez des tables dans une région virtuelle spécifique (telle que US ou EU) et que les métadonnées du catalogue ne sont pas présentes dans cet emplacement, la requête échoue.

Régions principales pour les multirégions

Pour autoriser BigQuery à interroger les tables de votre catalogue à partir de la multirégion US ou EU, spécifiez US ou EU comme région principale lorsque vous créez le catalogue.

Vous pouvez spécifier une multirégion (US ou EU) comme région principale dans les configurations suivantes :

Si le bucket default_location est :

• un bucket multirégional US ou EU ;
• un bucket à région unique dans ces multirégions (tel que us-central1 ou europe-west4) ;
• un bucket birégional ou birégional personnalisé dans ces zones (tel que NAM4 ou EUR4).

L'instance dupliquée principale est définie lorsque vous créez le catalogue, mais vous pouvez effectuer un basculement de manière dynamique en appelant FailoverCatalog. Pour en savoir plus, consultez la section Créer un catalogue.

Interroger des catalogues à partir de BigQuery

Lorsque vous interrogez des tables de catalogue d'environnements d'exécution Lakehouse à partir de BigQuery, vous utilisez une structure de nommage en quatre parties, souvent appelée P.C.N.T :

• Projet : ID du Google Cloud projet propriétaire du catalogue.
• Catalogue : nom du catalogue d'environnements d'exécution Lakehouse.
• Nom d'espace : espace de noms Apache Iceberg (équivalent à un ensemble de données BigQuery).
• Table : nom de la table.

Par exemple, my-project.lakehouse-catalog-id.my-namespace.my-table.

Étape suivante

• Configurer le point de terminaison du catalogue Apache Iceberg REST