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

Le catalogue du runtime Lakehouse permet de gérer de manière centralisée les métadonnées de Google Cloud Lakehouse. Ce document décrit les concepts de base du catalogue du runtime Lakehouse, en se concentrant sur le point de terminaison du catalogue REST Apache Iceberg, sa hiérarchie de ressources et les autres types de catalogues compatibles.

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

Types de catalogues acceptés

Lorsque vous configurez votre client, vous spécifiez un emplacement d'entrepôt. Ce choix détermine le fonctionnement de votre catalogue et son intégration aux autres servicesGoogle Cloud . Le tableau suivant décrit les types de catalogues compatibles :

Type de catalogue Description
Bucket Cloud Storage Toutes les données d'un catalogue sont stockées dans un seul bucket Cloud Storage. Si les données sont partagées entre plusieurs buckets, plusieurs catalogues sont nécessaires.
Fédération du catalogue BigQuery Vous permet d'utiliser le point de terminaison du catalogue Apache Iceberg REST pour gérer et interroger les tables visibles par BigQuery. Pour en savoir plus, consultez Fédération de catalogues avec BigQuery.

Détails de l'entrepôt

Recommandé

  • Entrepôt de buckets Cloud Storage (gs://) : il s'agit de l'approche standard, où le catalogue gère directement les métadonnées et les fichiers de données Apache Iceberg dans un bucket Cloud Storage que vous spécifiez. Cette option vous permet de contrôler directement la mise en page de vos données et est compatible avec la distribution d'identifiants pour un contrôle précis des accès. Cela vous permet de créer et de gérer des tables de catalogue REST Iceberg Lakehouse.

    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.

Alternative

  • Fédération du catalogue BigQuery (bq://) : cette approche vous permet d'utiliser le point de terminaison du catalogue REST Apache Iceberg pour gérer et interroger les tables visibles par BigQuery, sans avoir à créer de ressource de catalogue. Pour en savoir plus, consultez Fédération de catalogues avec BigQuery.

Régions des buckets et des catalogues

Pour les entrepôts de bucket Cloud Storage dans le catalogue Lakehouse Runtime, le système sélectionne la région du catalogue pour qu'elle corresponde à la région du bucket sous-jacent :

  • Buckets à région unique : la région du catalogue correspond exactement à celle du bucket.

  • Buckets birégionaux : incluent les régions doubles prédéfinies et définies par l'utilisateur, telles que ASIA1 et NAM4. La région du catalogue correspond aux régions doubles.

  • Buckets multirégionaux : le système sélectionne des emplacements régionaux pour le catalogue dans le domaine géographique de la région multiple. Par défaut, ces emplacements peuvent ne pas correspondre aux emplacements BigQuery courants, tels que US et EU. Il s'agit plutôt d'emplacements régionaux au sein du domaine géographique (par exemple, us-central1 et us-east4 pour un bucket multirégional US).

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 exécutez une requête dans une région virtuelle spécifique (comme US ou EU) et que les métadonnées du catalogue ne sont pas présentes dans cet emplacement, la requête peut échouer.

Spécifier des régions principales pour les emplacements multirégionaux aux États-Unis et dans l'UE

Pour les catalogues qui utilisent un bucket multirégional US ou EU, vous pouvez spécifier la région principale lorsque vous créez le catalogue pour vous assurer que BigQuery peut y accéder depuis les régions correspondantes.

  • Emplacement multirégional Cloud Storage dans l'UE : spécifiez EU ou europe-west4.
  • Emplacement multirégional Cloud Storage aux États-Unis : spécifiez US ou us-central1.

Le système sélectionne la réplique principale d'un catalogue lorsque vous le créez, mais vous pouvez la mettre à jour de manière dynamique en appelant FailoverCatalog. Pour en savoir plus sur la définition des emplacements principaux, consultez Utiliser le point de terminaison du catalogue Apache Iceberg REST.

Interroger les catalogues

Lorsque vous interrogez des tables de catalogue du runtime Lakehouse depuis 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 du runtime 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.

Fédération de catalogues avec BigQuery

Vous pouvez utiliser l'interface de point de terminaison du catalogue Apache Iceberg REST pour gérer et interroger les tables visibles par BigQuery.

Les catalogues de fédération de catalogue BigQuery ne nécessitent pas la création d'une ressource de catalogue. Ils peuvent être utilisés dans n'importe quel projet pour lequel l'API BigQuery est activée. Vous pourrez ainsi :

Étant donné que ces ressources sont gérées par BigQuery, vous devez disposer des autorisations requises. La distribution d'identifiants n'est pas compatible avec les catalogues fédérés.

Pour activer la fédération, configurez votre client avec le format d'entrepôt bq://projects/PROJECT_ID dans le champ WAREHOUSE_PATH des exemples de configuration du client dans Utiliser le point de terminaison du catalogue REST Apache Iceberg. Vous pouvez également choisir d'inclure un emplacement BigQuery pour limiter les futures requêtes à un seul emplacement au format bq://projects/PROJECT_ID/locations/LOCATION.

Étape suivante