Concepts liés aux points de terminaison du catalogue REST Apache Iceberg

Lakehouse pour Apache Iceberg gère les métadonnées via le catalogue 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 des 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ête compatibles avec Iceberg en prenant en charge les formats de table standards et en respectant les API ouvertes.

Formats de tableaux acceptés

Les tables Apache Iceberg V2 (disponibilité générale) et V3 (preview) sont compatibles. Les tables Iceberg V1 ne sont pas acceptées. 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 Mettre à niveau les tables Iceberg V1 vers V2.

Conformité de l'API et opérations REST

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

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 offre une vue d'ensemble de ces ressources :

Ressource Description
Catalogue Un catalogue est un conteneur de premier niveau qui vous permet d'organiser les espaces de noms et les tables en groupes logiques en les divisant en différents catalogues. Chaque catalogue est associé à un emplacement de stockage d'entrepôt désigné (tel qu'un bucket Cloud Storage ou un proxy de fédération BigQuery) qui stocke ses métadonnées et fichiers de données sous-jacents.
Espace de noms Il s'agit d'un regroupement logique utilisé pour organiser les tables dans un catalogue. Il fonctionne comme des bases de données, des schémas ou des répertoires.
Table Les tables contiennent des définitions de lignes et de colonnes pouvant faire l'objet de requêtes.

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 multibucket (bl://, recommandé) ou un catalogue à un seul bucket (gs://).

Les deux options sont compatibles avec la distribution d'identifiants pour un contrôle des accès précis.

Multi-bucket (bl://) (recommandé)

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

Remarques :

  • Emplacement par défaut : vous indiquez le chemin d'accès à un bucket (default_location) ou à un sous-chemin d'accès (tel que gs://my-bucket/path) qui servira d'emplacement de stockage par défaut. Toutes les ressources de catalogue (espaces de noms et tables) doivent se trouver sous le chemin d'accès 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 restricted_locations facultative 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 d'accès (tel que gs://my-bucket/path), toutes les ressources créées à l'aide de cette configuration doivent se trouver sous ce chemin d'accès (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 interprojets, interrégionaux et avoir des configurations différentes (par exemple, une seule région, deux régions ou plusieurs régions), tous les emplacements Cloud Storage de l'emplacement par défaut et des emplacements restreints doivent appartenir au 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 aux États-Unis 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érentes zones géographiques par défaut ou zones géographiques restreintes). Toutefois, cette configuration est fortement déconseillée, car elle peut entraîner des conflits de métadonnées, des écrasements de données accidentels 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 leur chemin physique pour éviter les conflits (par exemple, gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}). Pour en savoir plus, consultez Règles de gestion et de sécurité des tables.

Un seul bucket (gs://)

Il s'agit de l'ancienne approche, où 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 configuration CATALOG_TYPE_GCS_BUCKET.

Pour les catalogues de bucket Cloud Storage, 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 celui de votre bucket sont tous les deux iceberg-bucket. Vous l'utiliserez plus tard 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 des anciens types de catalogues Nous vous déconseillons vivement d'utiliser l'ancienne configuration à un seul bucket 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 acceptés).
    • 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 ce type de catalogue hérité, 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 multibucket (bl://) (recommandé) : vous pouvez mettre à niveau un catalogue monobucket (gs://) existant vers un catalogue multibucket (bl://) (recommandé). Le catalogue mis à niveau conserve le nom du bucket d'origine. Vous pouvez ensuite associer plusieurs buckets au catalogue et configurer des zones géographiques restreintes.

Régions des buckets et des catalogues

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

  • 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 à celle du bucket.
  • Birégion : la région du catalogue correspond à la région double 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 l'achemine vers la région principale du catalogue. Si vous interrogez des tables dans une région virtuelle spécifique (par exemple, US ou EU) et que les métadonnées du catalogue ne sont pas présentes à cet emplacement, la requête échoue.

Régions principales pour les emplacements multirégionaux

Pour autoriser BigQuery à interroger vos tables de catalogue à partir de la région multirégionale 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 :

  • Bucket multirégional US ou EU.
  • Un bucket monorégional dans ces régions multirégionales (par exemple, us-central1 ou europe-west4).
  • Un bucket birégional ou birégional personnalisé dans ces zones (par exemple, NAM4 ou EUR4).

La réplique 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 Créer un catalogue.

Interroger des catalogues à partir de BigQuery

Lorsque vous interrogez des tables du 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 projet Google Cloud propriétaire du catalogue.
  • Catalogue : nom du catalogue d'environnements d'exécution Lakehouse.
  • Espace de noms : 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