Apache Iceberg-REST-Katalogendpunkt – Konzepte

In Lakehouse for Apache Iceberg werden Metadaten über den Lakehouse-Laufzeitkatalog verwaltet. Wenn Sie den Apache Iceberg REST-Katalog-Endpunkt verwenden, werden die Daten in einer strengen Ressourcenhierarchie organisiert. Die Katalogkonfiguration bestimmt die unterstützten Speichertypen, das regionale Routingverhalten und die Optionen für die Abfrageföderation.

Funktionen und Compliance

Der Lakehouse-Laufzeitkatalog ist so konzipiert, dass er sich in Iceberg-kompatible Abfrage-Engines einbinden lässt. Dazu werden Standardtabellenformate unterstützt und offene APIs eingehalten.

Unterstützte Tabellenformate

Apache Iceberg-Tabellen der Version 2 (allgemein verfügbar) und Version 3 (Vorschau) werden unterstützt. Iceberg V1-Tabellen werden nicht unterstützt. Bevor Sie vorhandene V1-Tabellen mit dem Apache Iceberg-REST-Katalogendpunkt verwenden können, müssen Sie sie auf eine unterstützte Version aktualisieren. Weitere Informationen finden Sie unter Iceberg-Tabellen der Version 1 auf Version 2 aktualisieren.

API-Konformität und REST-Vorgänge

Der Lakehouse-Laufzeitkatalog implementiert den offenen Standard Apache Iceberg REST Catalog API. Client-Abfrage-Engines interagieren mit dem Katalog über standardmäßige REST-Katalog-APIs. Weitere Informationen finden Sie unter Implementierung der Apache Iceberg REST-Katalog-API in Lakehouse.

Ressourcenhierarchie

Der Apache Iceberg-REST-Katalogendpunkt verwendet eine Hierarchie von Ressourcen, um Ihre Daten zu organisieren. Die folgende Tabelle bietet einen allgemeinen Überblick über diese Ressourcen:

Ressource Beschreibung
Katalog Mit dem Container der obersten Ebene, einem Katalog, können Sie Namespaces und Tabellen in logischen Gruppen organisieren, indem Sie sie in verschiedene Kataloge aufteilen. Jeder Katalog wird durch einen bestimmten Speicherort für das Data Warehouse (z. B. einen Cloud Storage-Bucket oder einen BigQuery-Föderationsproxy) unterstützt, in dem die zugrunde liegenden Metadaten und Datendateien gespeichert werden.
Namespace Eine logische Gruppierung, mit der Tabellen in einem Katalog organisiert werden. Sie funktioniert wie Datenbanken, Schemas oder Verzeichnisse.
Tabelle Tabellen enthalten Definitionen von Zeilen und Spalten, die abgefragt werden können.

Kataloge und Speicherorte

Die Konfiguration eines Katalogs bestimmt, wie er funktioniert und in Google Cloud-Dienste eingebunden wird. Sie können einen Katalog mit mehreren Buckets (bl://) (empfohlen) oder einen Katalog mit einem einzelnen Bucket (gs://) konfigurieren.

Beide Optionen unterstützen die Bereitstellung von Anmeldedaten für die detaillierte Zugriffssteuerung.

Mehrere Buckets (bl://) (empfohlen)

So können Sie Ihren Katalog unabhängig von einem Bucket-Namen benennen und mehrere Buckets für einen einzelnen Katalog konfigurieren. In der zugrunde liegenden API entspricht dies der Konfiguration CATALOG_TYPE_BIGLAKE.

Wichtige Hinweise:

  • Standardspeicherort: Sie geben einen Pfad zu einem Bucket (default_location) oder einen Unterpfad (z. B. gs://my-bucket/path) an, der als Standardspeicherort verwendet werden soll. Alle Katalogressourcen (Namespaces und Tabellen) müssen sich unter dem angegebenen Pfad befinden. Wenn Sie beispielsweise gs://my-bucket/path angeben, können Sie keine Namespaces oder Tabellen unter gs://my-bucket/another/path hosten. Für Namespaces, die ohne Angabe eines Standorts erstellt wurden, wird default_location verwendet.
  • Eingeschränkte Speicherorte: Sie können auch eine optionale restricted_locations-Konfiguration für zusätzliche Buckets oder Pfade angeben, in denen Namespaces und Tabellen erstellt werden können. Wenn Sie einen Unterpfad angeben (z. B. gs://my-bucket/path), müssen alle Ressourcen, die mit dieser Konfiguration erstellt werden, sich unter diesem Pfad befinden. gs://my-bucket/another/path kann beispielsweise keine Namespaces oder Tabellen hosten.
  • Anforderungen an geografische Regionengruppen: Obwohl Buckets projekt- und regionenübergreifend sein und unterschiedliche Konfigurationen (z. B. Single-Region, Dual-Region oder Multi-Region) haben können, müssen sich alle Cloud Storage-Standorte am Standardspeicherort und an eingeschränkten Standorten in derselben geografischen Regionengruppe (z. B. USA, Europa, Kanada oder Asien) befinden. Sie können beispielsweise keinen multiregionalen Bucket in den USA mit einem Bucket in Europa oder Kanada konfigurieren.
  • Mehrere Kataloge pro Bucket: Sie können mehrere Kataloge haben, die auf denselben Bucket verweisen, z. B. mit unterschiedlichen Standardspeicherorten oder eingeschränkten Speicherorten. Diese Konfiguration wird jedoch dringend abgeraten, da sie zu Metadatenkonflikten, unbeabsichtigten Datenüberschreibungen oder Sicherheitsproblemen wie Berechtigungslecks führen kann.
  • Namespaces: Ermöglichen die Angabe benutzerdefinierter Namespace-Speicherorte, sofern sie sich unter einem Pfad befinden, der in den Standard- oder eingeschränkten Speicherorten konfiguriert ist. Tabellen, die in diesen Katalogen erstellt werden, haben automatisch ein zufälliges String-Suffix in ihren physischen Pfaden, um Konflikte zu vermeiden (z. B. gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}). Weitere Informationen finden Sie unter Regeln für die Tabellenverwaltung und ‑sicherheit.

Einzelner Bucket (gs://)

Bei diesem Legacy-Ansatz werden Apache Iceberg-Metadaten und Datendateien direkt vom Katalog in einem einzelnen Cloud Storage-Bucket verwaltet, den Sie angeben. In der zugrunde liegenden API entspricht dies der Konfiguration CATALOG_TYPE_GCS_BUCKET.

Bei Cloud Storage-Bucket-Katalogen wird der Katalogname auf den Namen Ihres Buckets festgelegt.

Wenn Sie beispielsweise einen Bucket zum Speichern Ihres Katalogs erstellt und ihn iceberg-bucket genannt haben, lauten sowohl der Katalogname als auch der Bucket-Name iceberg-bucket. Diese wird später verwendet, wenn Sie Ihren Katalog in BigQuery mit der P.C.N.T.-Syntax abfragen. z. B. my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table.

Wichtige Hinweise:

  • Einschränkungen für alte Katalogtypen Die Verwendung der alten Konfiguration mit einem einzelnen Bucket wird für neue Projekte dringend abgeraten. Diese Konfiguration hat mehrere kritische Einschränkungen:

    • Katalogname: Entspricht dem Namen des zugrunde liegenden Cloud Storage-Bucket.
    • Projekt: Auf das Projekt des Buckets beschränkt (projektübergreifende Kataloge werden nicht unterstützt).
    • Region: Wird ausschließlich vom Standort des Buckets abgeleitet und kann nicht angepasst werden.
    • Speicher: Beschränkt Ihren Katalog auf einen einzelnen Bucket (keine eingeschränkten Standorte).

  • Einschränkung: Ein Katalog pro Bucket: Bei diesem alten Katalogtyp ist nur ein Katalog pro Bucket möglich und der Katalogname muss mit dem Bucket-Namen übereinstimmen.

  • Auf Multi-Bucket-Katalog (bl://) upgraden (empfohlen): Sie können einen vorhandenen Single-Bucket-Katalog (gs://) auf einen Multi-Bucket-Katalog (bl://) upgraden (empfohlen). Der aktualisierte Katalog behält den Namen des ursprünglichen Buckets bei. Danach können Sie dem Katalog mehrere Buckets zuordnen und eingeschränkte Standorte konfigurieren.

Bucket- und Katalogregionen

Die Region eines Katalogendpunkts im Lakehouse-Laufzeitkatalog wird durch die Region des zugrunde liegenden Cloud Storage-Bucket bestimmt:

  • Mehrere Buckets (bl://) (empfohlen): Die Katalogregion wird aus dem Bucket abgeleitet, der in default_location konfiguriert ist.
  • Einzelner Bucket (gs://): Die Katalogregion wird ausschließlich aus dem mit dem Katalog verknüpften Bucket abgeleitet und kann nicht angepasst werden.

Die zugeordnete Katalogregion variiert je nach Regionstyp des Buckets:

  • Einzelne Region: Die Katalogregion stimmt genau mit der Region des Buckets überein.
  • Dual-Region: Die Katalogregion entspricht der Dual-Region des Buckets (z. B. ASIA1 oder NAM4).
  • Multiregional: Die Katalogregion ist auf einen bestimmten regionalen Standort innerhalb des geografischen Bereichs der multiregionalen Region festgelegt. Standardmäßig stimmt dies möglicherweise nicht mit gängigen multiregionalen BigQuery-Standorten wie US und EU überein. Ein multiregionaler Bucket in US wird beispielsweise us-central1 oder us-east4 zugeordnet.

Wenn BigQuery eine Abfrage für Tabellen in diesen Katalogen ausführt, wird die Abfrage an die primäre Region des Katalogs weitergeleitet. Wenn Sie Tabellen in einer bestimmten virtuellen Region (z. B. US oder EU) abfragen und die Katalogmetadaten an diesem Speicherort nicht vorhanden sind, schlägt die Abfrage fehl.

Primäre Regionen für multiregionale Standorte

Damit BigQuery Ihre Katalogtabellen aus der Multi-Region US oder EU abfragen kann, geben Sie US oder EU als primäre Region an, wenn Sie den Katalog erstellen.

Sie können eine Multiregion (US oder EU) als primäre Region in den folgenden Konfigurationen angeben:

Wenn der Bucket default_location:

  • Ein US- oder EU-Multiregionen-Bucket.
  • Ein Bucket in einer einzelnen Region innerhalb dieser Multiregionen (z. B. us-central1 oder europe-west4).
  • Ein Bucket vom Typ „Dual-Region“ oder „Benutzerdefinierte Dual-Region“ in diesen Bereichen, z. B. NAM4 oder EUR4.

Das primäre Replikat wird beim Erstellen des Katalogs definiert. Sie können jedoch dynamisch ein Failover durchführen, indem Sie FailoverCatalog aufrufen. Weitere Informationen finden Sie unter Katalog erstellen.

Kataloge aus BigQuery abfragen

Wenn Sie Tabellen des Lakehouse-Laufzeitkatalogs über BigQuery abfragen, verwenden Sie eine vierteilige Namensstruktur, die oft als P.C.N.T bezeichnet wird:

  • Project: Die Google Cloud Projekt-ID des Projekts, zu dem der Katalog gehört.
  • Catalog: Der Name des Lakehouse-Laufzeitkatalogs.
  • Namespace: Der Apache Iceberg-Namespace (entspricht einem BigQuery-Dataset).
  • Tabelle: Der Name der Tabelle.

Beispiel: my-project.lakehouse-catalog-id.my-namespace.my-table.

Weitere Informationen