À propos du point de terminaison du catalogue REST Apache Iceberg

Le lakehouse sans frontières 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 et les comportements de routage régionaux.

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 tableau 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 d'API de catalogue REST standards. Pour en savoir plus, consultez Comment Lakehouse implémente l'API du catalogue REST Apache Iceberg.

Hiérarchie des ressources

Le point de terminaison du catalogue REST Apache Iceberg utilise une hiérarchie de ressources pour organiser vos données. Le tableau suivant fournit une vue d'ensemble de ces ressources :

Ressource Description
Catalogue Conteneur de premier niveau, un catalogue 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é à des emplacements de stockage d'entrepôt désignés (tels qu'un ou plusieurs buckets Cloud Storage) qui stockent 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 à plusieurs buckets (recommandé) ou un catalogue à un seul bucket.

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

Lorsque vous configurez des moteurs de requête client (tels que Spark ou Trino) pour qu'ils se connectent au point de terminaison du catalogue REST Apache Iceberg, vous spécifiez le chemin d'accès à l'entrepôt en fonction du type de catalogue :

  • Catalogue à plusieurs buckets : définissez le chemin d'accès à l'entrepôt sur bl://projects/PROJECT_ID/catalogs/CATALOG_ID.
  • Catalogue à un seul bucket : définissez le chemin d'accès à l'entrepôt sur gs://CLOUD_STORAGE_BUCKET_NAME.

Catalogue à plusieurs buckets (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.

Points à prendre en compte :

  • Configuration de l'entrepôt client (bl://) : lorsque vous configurez un client Iceberg pour qu'il se connecte à un catalogue à plusieurs buckets, spécifiez le chemin d'entrepôt à l'aide du format d'URI bl:// : bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Le format bl:// est utilisé exclusivement lors de la configuration du client pour identifier le catalogue. Lorsque vous créez ou configurez le catalogue lui-même dans Google Cloud, les emplacements de stockage (default_location et restricted_locations) sont toujours spécifiés en tant que chemins Cloud Storage (gs://).
  • Nombre maximal de buckets : vous pouvez spécifier jusqu'à 15 buckets par catalogue.
  • Emplacement par défaut : vous indiquez le chemin d'accès à un bucket (default_location) ou à un sous-chemin (tel que gs://my-bucket/path) qui servira d'emplacement de stockage par défaut. Toutes les ressources du 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ù les espaces de noms et les 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 interprojets et 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 par défaut ou zones 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 sont 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.

Catalogue à bucket unique

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 (gs://) que vous spécifiez. Dans l'API sous-jacente, cela correspond à la configuration CATALOG_TYPE_GCS_BUCKET.

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

Par exemple, si vous nommez votre bucket iceberg-bucket, votre catalogue et votre bucket partagent ce nom. Utilisez ce nom lorsque vous interrogez votre catalogue dans BigQuery à l'aide de la syntaxe P.C.N.T, par exemple my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table.

Points à prendre en compte :

  • 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 importantes :

    • 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).

  • Configuration de l'entrepôt client (gs://) : lorsque vous configurez un client Iceberg pour un catalogue à un seul bucket, spécifiez le chemin d'accès au bucket Cloud Storage (gs://CLOUD_STORAGE_BUCKET_NAME) comme emplacement de l'entrepôt.

  • 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 à celui du bucket.

  • Mettre à niveau vers un catalogue multibucket (recommandé) : vous pouvez mettre à niveau un catalogue monobucket existant vers un catalogue multibucket (recommandé). Le catalogue mis à niveau conserve le nom du bucket d'origine. Vous pouvez ensuite associer plusieurs buckets au catalogue et configurer des zones restreintes.

Régions des buckets et des catalogues

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 (recommandé) : la région du catalogue est dérivée du bucket configuré dans default_location.
  • Catalogue à bucket unique : 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.
  • Emplacement birégional : la région du catalogue correspond à la région birégionale 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 correspond à 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 depuis 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 :

  • Un 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).

L'instance répliqué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 Créer un catalogue.

Pour acheminer les requêtes directement vers une région spécifique afin de répondre aux exigences de résidence et de souveraineté des données, vous pouvez utiliser des points de terminaison régionaux (biglake.LOCATION.rep.googleapis.com). Pour en savoir plus, consultez Points de terminaison régionaux Lakehouse.

Interroger des catalogues depuis BigQuery

Lorsque vous interrogez des tables du catalogue 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