Apache Iceberg-REST-Katalogendpunkt – Konzepte

Lakehouse for Apache Iceberg verwaltet Metadaten über den Lakehouse-Laufzeitkatalog. Wenn Sie den Apache Iceberg REST-Katalogendpunkt 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 wurde für die Integration in Iceberg-kompatible Abfrage-Engines entwickelt. Er unterstützt Standardtabellenformate und entspricht offenen APIs.

Unterstützte Tabellenformate

Apache Iceberg V2-Tabellen (allgemeine Verfügbarkeit) und V3-Tabellen (Vorschau) werden unterstützt. Iceberg V1-Tabellen werden nicht unterstützt. Bevor Sie vorhandene V1-Tabellen mit dem Apache Iceberg REST-Katalogendpunkt verwenden, 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 den Apache Iceberg REST-Katalog. Client-Abfrage-Engines interagieren mit dem Katalog über Standard-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 Als Container der obersten Ebene können Sie mit einem Katalog Namespaces und Tabellen in logischen Gruppen organisieren, indem Sie sie in verschiedene Kataloge aufteilen. Jeder Katalog wird durch einen bestimmten Warehouse-Speicherort (z. B. einen Cloud Storage-Bucket oder einen BigQuery-Föderationsproxy) gesichert, an dem die zugrunde liegenden Metadaten und Datendateien gespeichert werden.
Namespace Eine logische Gruppierung zum Organisieren von Tabellen in einem Katalog, die 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 Bucket (gs://) konfigurieren.

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

Katalog mit mehreren Buckets (bl://) (empfohlen)

Mit diesem Ansatz 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 CATALOG_TYPE_BIGLAKE Konfiguration.

Wichtige Gesichtspunkte:

  • Standardspeicherort: Sie geben einen Pfad zu einem Bucket (default_location) oder einen Unterpfad (z. B. gs://my-bucket/path) an, der als Standardspeicher ort dienen 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 angegebenen Speicherort 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 sich alle Ressourcen, die mit dieser Konfiguration erstellt wurden, unter diesem Pfad befinden (z. B. können unter gs://my-bucket/another/path keine Namespaces oder Tabellen gehostet werden).
  • Anforderungen an geografische Regionengruppen: Obwohl Buckets projekt- und regionsübergreifend sein und unterschiedliche Konfigurationen haben können (z. B. einzelne Region, biregional oder multiregional), müssen sich alle Cloud Storage-Speicherorte sowohl am standardmäßigen Standort als auch an den eingeschränkten Speicherorten in derselben geografischen Regionengruppe befinden (z. B. USA, Europa, Kanada oder Asien). Sie können beispielsweise keinen Bucket mit mehreren Regionen 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 Standardspeicherorten oder eingeschränkten Speicherorten). 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ö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 wurden, erhalten automatisch ein zufälliges String-Suffix an ihre physischen Pfade angehängt, um Konflikte zu vermeiden (z. B. gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}). Weitere Informationen finden Sie unter Tabellenverwaltung und Sicherheits regeln.

Katalog mit einem Bucket (gs://)

Dies ist der Legacy-Ansatz, bei dem der Katalog Apache Iceberg-Metadaten und ‑Datendateien direkt in einem einzelnen Cloud Storage-Bucket verwaltet, den Sie angeben. In der zugrunde liegenden API entspricht dies der CATALOG_TYPE_GCS_BUCKET Konfiguration.

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

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

Wichtige Gesichtspunkte:

  • Einschränkungen des Legacy-Katalogtyps. Die Verwendung der Legacy-Konfiguration mit einem Bucket wird für neue Projekte dringend abgeraten. Diese Konfiguration hat mehrere kritische Einschränkungen:

    • Katalogname: Ist an den zugrunde liegenden Cloud Storage-Bucket-Namen gebunden.
    • Projekt: Ist an das Projekt des Buckets gebunden (projektübergreifende Kataloge werden nicht unterstützt).
    • Region: Wird ausschließlich vom Speicherort des Buckets abgeleitet und kann nicht angepasst werden.
    • Speicher: Beschränkt Ihren Katalog auf einen einzelnen Bucket (keine eingeschränkten Speicherorte).

  • Beschränkung auf einen Katalog pro Bucket: Bei diesem Legacy-Katalogtyp kann es nur einen Katalog pro Bucket geben und der Katalogname muss mit dem Bucket-Namen übereinstimmen.

  • Auf Katalog mit mehreren Buckets (bl://) aktualisieren (empfohlen): Sie können einen vorhandenen Katalog mit einem Bucket (gs://) auf einen Katalog mit mehreren Buckets (bl://) aktualisieren (empfohlen). Der aktualisierte Katalog behält den Namen des ursprünglichen Buckets bei. Danach können Sie mehrere Buckets mit dem Katalog verknüpfen und eingeschränkte Speicherorte 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 (bl://) (empfohlen): Die Katalogregion wird abgeleitet vom Bucket, der in default_location konfiguriert ist.
  • Katalog mit einem Bucket (gs://): 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 stimmt mit der Dual-Region des Buckets überein (z. B. ASIA1 oder NAM4).
  • Multi-Region: Die Katalogregion wird auf einen bestimmten regionalen Standort innerhalb des geografischen Bereichs der Multi-Region festgelegt. Standardmäßig stimmt dies möglicherweise nicht mit gängigen BigQuery-Multi-Regionen wie US und EU überein (z. B. wird ein Bucket mit mehreren Regionen in den USA US auf us-central1 oder us-east4 abgebildet).

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 Multi-Regionen

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

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

Wenn der default_location-Bucket:

  • Ein Bucket mit mehreren Regionen in den USA (US) oder in der EU (EU).
  • Ein Bucket mit einer einzelnen Region innerhalb dieser Multi-Regionen (z. B. us-central1 oder europe-west4).
  • Ein Bucket mit einer Dual-Region oder einer benutzerdefinierten Dual-Region innerhalb dieser Bereiche (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

Beim Abfragen von Lakehouse-Laufzeitkatalogtabellen aus BigQuery verwenden Sie eine vierteilige Namensstruktur, die oft bezeichnet wird als P.C.N.T:

  • Projekt: 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).
  • Table: Der Name der Tabelle.

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

Weitere Informationen