Apache Iceberg-REST-Katalogendpunkt

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

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 V2-Tabellen (GA) und V3-Tabellen (Vorabversion) 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-V1-Tabellen auf V2 aktualisieren.

API-Compliance und REST-Vorgänge

Der Lakehouse-Laufzeitkatalog implementiert die offene Standard-API für Apache Iceberg REST-Kataloge. Clientabfrage-Engines interagieren mit dem Katalog über Standard-REST-Katalog-APIs. Weitere Informationen finden Sie unter So implementiert Lakehouse die Apache Iceberg REST Catalog API.

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 Der Katalog ist der Container auf oberster Ebene. Er ermöglicht es Ihnen, Namespaces und Tabellen in logische Gruppen zu organisieren, indem Sie sie in verschiedene Kataloge aufteilen. Jeder Katalog wird durch bestimmte Warehouse-Speicherorte (z. B. einen oder mehrere Cloud Storage-Buckets) unterstützt, in denen die zugrunde liegenden Metadaten und Datendateien gespeichert werden.
Namespace Eine logische Gruppierung, die zum Organisieren von Tabellen in einem Katalog verwendet wird. 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 wie er in Google Cloud-Dienste eingebunden wird. Sie können einen Katalog mit mehreren Buckets (empfohlen) oder einen Katalog mit einem einzelnen Bucket konfigurieren.

Beide Optionen unterstützen die Bereitstellung von Anmeldedaten.

Wenn Sie Client-Abfrage-Engines (z. B. Spark oder Trino) für die Verbindung mit dem Apache Iceberg REST-Katalogendpunkt konfigurieren, geben Sie den Warehouse-Pfad basierend auf dem Katalogtyp an:

  • Katalog mit mehreren Buckets: Legen Sie den Warehouse-Pfad auf bl://projects/PROJECT_ID/catalogs/CATALOG_ID fest.
  • Katalog mit einem Bucket: Legen Sie den Warehouse-Pfad auf gs://CLOUD_STORAGE_BUCKET_NAME fest.

Katalog mit mehreren Buckets (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:

  • Client-Warehouse-Konfiguration (bl://): Wenn Sie einen Iceberg-Client für die Verbindung mit einem Katalog mit mehreren Buckets konfigurieren, geben Sie den Warehouse-Pfad im bl://-URI-Format an: bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Das Format bl:// wird ausschließlich während der Clientkonfiguration verwendet, um den Katalog zu identifizieren. Beim Erstellen oder Konfigurieren des Katalogs in Google Cloud werden die Speicherorte (default_location und restricted_locations) immer als Cloud Storage-Pfade (gs://) angegeben.
  • Maximale Anzahl von Speicherorten: Zusätzlich zu default_location können Sie pro Katalog bis zu 128 Cloud Storage-Buckets oder Unterpfade in restricted_locations angeben.
  • Standardspeicherort: Sie geben einen Pfad zu einem Bucket (default_location) oder einen Unterpfad (z. B. gs://my-bucket/path) an, der als Standardspeicherort dienen soll. Alle Katalogressourcen (Namespaces und Tabellen) müssen sich im 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 Standorte: 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, unter diesem Pfad liegen (z. B. kann gs://my-bucket/another/path keine Namespaces oder Tabellen hosten).
  • Anforderungen an geografische Regionsgruppen: Buckets können projekt- und regionsübergreifend sein und unterschiedliche Konfigurationen haben (z. B. einzelne Region, Dual-Region oder Multiregion). Alle Cloud Storage-Standorte am Standardstandort und an eingeschränkten Standorten müssen sich jedoch in derselben geografischen Regionsgruppe befinden (z. B. USA, Europa, Kanada oder Asien). 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 auf denselben Bucket verweisen lassen (z. B. mit unterschiedlichen Standardstandorten oder eingeschränkten Standorten). Diese Konfiguration wird jedoch dringend abgeraten, da sie zu Metadatenkonflikten, versehentlichem Überschreiben von Daten oder Sicherheitsproblemen wie dem Verlust von Berechtigungen führen kann.
  • Namespaces: Ermöglicht die Angabe benutzerdefinierter Namespace-Speicherorte, sofern sie sich unter einem Pfad befinden, der in den Standard- oder eingeschränkten Speicherorten konfiguriert ist. Beachten Sie, dass Tabellen, die in diesen Katalogen erstellt werden, automatisch ein zufälliges String-Suffix an ihre physischen Pfade angehängt bekommen, um Konflikte zu vermeiden (z. B. gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}). Weitere Informationen finden Sie unter Tabellenverwaltung und Sicherheitsregeln.

Katalog mit einem Bucket

Dies ist der Legacy-Ansatz, bei dem der Katalog Apache Iceberg-Metadaten und -Datendateien direkt in einem von Ihnen angegebenen Cloud Storage-Bucket (gs://) verwaltet. In der zugrunde liegenden API entspricht dies der Konfiguration CATALOG_TYPE_GCS_BUCKET.

Bei Katalogen mit einem einzelnen Bucket wird der Katalogname auf den Namen Ihres Buckets festgelegt.

Wenn Sie Ihren Bucket beispielsweise iceberg-bucket nennen, haben sowohl Ihr Katalog als auch Ihr Bucket diesen Namen. Verwenden Sie diesen Namen, 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 des alten Katalogtyps. Die Verwendung der Legacy-Konfiguration mit einem einzelnen Bucket wird für neue Projekte dringend abgeraten. Diese Konfiguration hat mehrere kritische Einschränkungen:

    • Katalogname: Ist an den Namen des zugrunde liegenden Cloud Storage-Bucket gebunden.
    • Projekt: Ist auf das Projekt des Buckets festgelegt (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).

  • Client-Warehouse-Konfiguration (gs://): Wenn Sie einen Iceberg-Client für einen Katalog mit einem einzelnen Bucket konfigurieren, geben Sie den Cloud Storage-Bucket-Pfad (gs://CLOUD_STORAGE_BUCKET_NAME) als Warehouse-Speicherort an.

  • Einschränkung „Ein Katalog pro Bucket“: Bei diesem Legacy-Katalogtyp können Sie nur einen Katalog pro Bucket haben. Der Katalogname muss mit dem Bucket-Namen übereinstimmen.

  • Upgrade auf einen Katalog mit mehreren Buckets durchführen (empfohlen): Sie können ein Upgrade eines vorhandenen Katalogs mit einem Bucket auf einen Katalog mit mehreren Buckets durchführen (empfohlen). Der aktualisierte Katalog behält den Namen des ursprünglichen Buckets bei. Anschließend 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:

  • Katalog mit mehreren Buckets (empfohlen): Die Katalogregion wird aus dem Bucket abgeleitet, der in default_location konfiguriert ist.
  • Katalog mit einem Bucket: Die Katalogregion wird ausschließlich vom Bucket abgeleitet, der mit dem Katalog verknüpft ist, 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 der geografischen Domain der Multiregion festgelegt. Standardmäßig entspricht dies möglicherweise nicht den gängigen BigQuery-Multiregionen wie US und EU. Ein multiregionaler US-Bucket 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 Standort nicht vorhanden sind, schlägt die Abfrage fehl.

Primäre Regionen für Multiregionen

Damit BigQuery Ihre Katalogtabellen aus der multiregionalen Region US oder EU abfragen kann, geben Sie beim Erstellen des Katalogs US oder EU als primäre Region an.

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

Wenn der Bucket default_location:

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

Das primäre Replikat wird beim Erstellen des Katalogs definiert. Sie können jedoch durch Aufrufen von FailoverCatalog dynamisch ein Failover ausführen. Weitere Informationen finden Sie unter Katalog erstellen.

Wenn Sie Anfragen direkt an eine bestimmte Region weiterleiten möchten, um die Anforderungen an den Datenstandort und die Datenhoheit zu erfüllen, können Sie regionale Endpunkte (biglake.LOCATION.rep.googleapis.com) verwenden. Weitere Informationen finden Sie unter Regionale Lakehouse-Endpunkte.

Kataloge aus BigQuery abfragen

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

  • Projekt: Die Google Cloud -Projekt-ID, zu der der Katalog gehört.
  • Katalog: 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