À propos du point de terminaison du catalogue REST Apache Iceberg

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

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 table compatibles

Les tables Apache Iceberg V2 (disponibilité générale) et V3 (preview) sont compatibles. Les tables Iceberg V1 ne sont pas compatibles. Avant d'utiliser des tables V1 existantes avec le point de terminaison du catalogue REST Apache Iceberg, vous devez les mettre à niveau vers une version compatible. Pour en savoir plus, consultez 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 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 REST Catalog 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 présente ces ressources de manière générale :

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 répartissant dans différents catalogues. Chaque catalogue est associé à des emplacements de stockage d'entrepôt désignés (par exemple, un ou plusieurs buckets Cloud Storage) qui stockent ses métadonnées et ses fichiers de données sous-jacents.
Espace de noms Regroupement logique utilisé pour organiser les tables dans un catalogue, qui 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 qui peuvent être interrogées.

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 (comme 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 de l'entrepôt sur bl://projects/PROJECT_ID/catalogs/CATALOG_ID.
  • Catalogue à bucket unique : définissez le chemin d'accès de 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.

Remarques :

  • Configuration de l'entrepôt client (bl://) : lorsque vous configurez un client Iceberg pour qu'il se connecte à un catalogue multibucket, spécifiez le chemin d'accès à l'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. Lors de la création ou de la configuration du catalogue dans Google Cloud, les emplacements de stockage (default_location et restricted_locations) sont toujours spécifiés en tant que chemins d'accès Cloud Storage (gs://).
  • Nombre maximal d'emplacements de stockage : en plus de default_location, vous pouvez spécifier jusqu'à 128 buckets Cloud Storage ou sous-chemins dans restricted_locations par catalogue.
  • 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 servir 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 d'accès 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 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 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 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é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 d'accès configuré dans les emplacements par défaut ou restreints. Notez qu'une chaîne aléatoire est automatiquement ajoutée en suffixe au chemin d'accès physique des tables créées dans ces catalogues pour éviter les conflits (par exemple, gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}). Pour en savoir plus, consultez Gestion des tables et règles de sécurité.

Catalogue à bucket unique

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

Pour les catalogues à bucket unique, 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 partageront 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.

Remarques :

  • Limites des types de catalogues anciens. 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 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 à bucket unique, 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 ancien, vous ne pouvez avoir qu'un seul catalogue par bucket, et le nom du catalogue doit correspondre au nom du bucket.

  • Passer à un catalogue à plusieurs buckets (recommandé) : vous pouvez mettre à niveau un catalogue à bucket unique existant vers un catalogue à plusieurs buckets (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 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é 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 à l'emplacement birégional du bucket (par exemple, ASIA1 ou NAM4).
  • Multirégional : la région du catalogue est définie sur un emplacement régional spécifique dans le domaine géographique multirégional. Par défaut, cela peut ne pas correspondre aux emplacements multirégionaux BigQuery courants tels que US et EU (par exemple, un bucket multirégional US est mappé à us-central1 ou us-east4).

Lorsque BigQuery exécute une requête sur des tables de 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 dans cet emplacement, la requête échoue.

Régions principales pour les emplacements multirégionaux

Pour permettre à BigQuery d'interroger vos tables de catalogue à partir de l'emplacement multirégional US ou EU, spécifiez US ou EU comme région principale lorsque vous créez le catalogue.

Vous pouvez spécifier un emplacement multirégional (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égional au sein de ces emplacements multirégionaux (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'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