Lakehouse Iceberg-REST-Katalog einrichten

Für neue Workflows empfehlen wir die Verwendung des Endpunkts Apache Iceberg REST-Katalog im Lakehouse-Laufzeitkatalog.

Dieser Endpunkt dient als zentrale Informationsquelle und ermöglicht eine nahtlose Interoperabilität zwischen Ihren Abfrage-Engines. Damit können Engines wie Apache Spark Ihre Google Cloud Lakehouse-Tabellen einheitlich ermitteln, lesen und verwalten.

Dieser Ansatz ist eine gute Wahl, wenn Sie Open-Source-Engines für den Zugriff auf Daten in Cloud Storage verwenden und Interoperabilität mit anderen Engines, einschließlich BigQuery, benötigen. Es unterstützt Funktionen wie Credential Vending für eine detaillierte Zugriffssteuerung und regionenübergreifende Replikation und Notfallwiederherstellung.

Im Gegensatz dazu ist der benutzerdefinierte Apache Iceberg-Katalog für BigQuery-Endpunkt eine frühere Integration. Vorhandene Workflows können weiterhin darauf zugreifen, aber der REST-Katalog bietet eine standardisierte und funktionsreiche Umgebung.

Hinweis

Machen Sie sich mit dem Lakehouse-Laufzeitkatalog und der Übersicht über Iceberg-REST-Katalogendpunkte vertraut, bevor Sie fortfahren.

  1. Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

  2. Aktivieren Sie die BigLake API.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen

    API aktivieren

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Verwenden des Apache Iceberg REST-Katalogendpunkts im Lakehouse-Laufzeitkatalog benötigen:

  • Administrativen Aufgaben ausführen, z. B. den Nutzerzugriff auf den Katalog, den Speicherzugriff und den Modus für die Bereitstellung von Anmeldedaten des Katalogs verwalten:
  • Tabellendaten im Credential Vending-Modus lesen: BigLake-Betrachter (roles/biglake.viewer) für das Projekt. Wenn Sie Abfrage-Engines wie Managed Service for Apache Spark, Managed Service for Apache Spark oder Dataflow zum Lesen von Tabellendaten verwenden, weisen Sie diese Rolle dem Dienstkonto zu, mit dem Sie Jobs in dieser Engine ausführen.
  • Tabellendaten im Credential Vending-Modus schreiben: BigLake-Editor (roles/biglake.editor) für das Projekt. Wenn Sie Abfrage-Engines wie Managed Service for Apache Spark, Managed Service for Apache Spark oder Dataflow zum Schreiben von Tabellendaten verwenden, weisen Sie diese Rolle dem Dienstkonto zu, mit dem Sie Jobs in dieser Engine ausführen.
  • Verwenden Sie das automatisch bereitgestellte Dienstkonto für den Lakehouse-Laufzeitkatalog im Credential Vending-Modus: Storage Object User (roles/storage.objectUser) für den Ziel-Cloud Storage-Bucket. Nachdem Sie den Katalog erstellt haben, weisen Sie dem automatisch bereitgestellten Dienstkonto des Lakehouse-Laufzeitkatalogs die Rolle „Storage Object User“ (roles/storage.objectUser) für Ihren Speicher-Bucket zu.
  • Katalogressourcen und Tabellendaten im Modus ohne Bereitstellung von Anmeldedaten lesen:
  • Katalogressourcen verwalten und Tabellendaten im Modus ohne Bereitstellung von Anmeldedaten schreiben:
  • DML-Vorgänge (Datenbearbeitungssprache) mit der BigQuery-Katalogföderation ausführen:
    • BigQuery-Datenbearbeiter (roles/bigquery.dataEditor) für das Projekt
    • Storage-Administrator (roles/storage.admin) für den Cloud Storage-Bucket. Wenn Sie Abfrage-Engines wie Managed Service for Apache Spark verwenden, um DML-Vorgänge auszuführen, weisen Sie dem Dienstkonto, mit dem Sie Jobs in dieser Engine ausführen, diese Rollen zu.

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Beschränkungen

Der Apache Iceberg-REST-Katalogendpunkt unterliegt den folgenden Einschränkungen:

Allgemeine Einschränkungen

  • Trino wird nur mit der BigQuery-Katalogföderation unterstützt, wenn Sie Managed Service for Apache Spark auf Compute Engine-Image-Versionen 2.3.16 und höher verwenden.
  • Wenn Sie den Modus für die Bereitstellung von Anmeldedaten verwenden, müssen Sie das Attribut io-impl auf org.apache.iceberg.gcp.gcs.GCSFileIO festlegen. Der Standardwert org.apache.iceberg.hadoop.HadoopFileIO wird nicht unterstützt.

Tabellenbeschränkungen

  • Tabellen, die über den Apache Iceberg REST-Katalogendpunkt verwaltet werden, unterstützen keine detaillierte Zugriffssteuerung (Fine-Grained Access Control, FGAC), z. B. Sicherheit auf Zeilen- und Spaltenebene.

Dateneinschränkungen

  • Es werden nur Parquet-Dateien unterstützt. Weitere Informationen dazu, wie BigQuery Parquet-Dateien verarbeitet, finden Sie unter Parquet-Daten aus Cloud Storage laden.
  • Die Dateigröße für Iceberg-metadata.json-Dateien ist auf 1 MB begrenzt. Wenn Sie eine Erhöhung dieses Limits beantragen möchten, wenden Sie sich an Ihr Google-Account-Team.

Abfragebeschränkungen

  • Ansichten über Apache Iceberg-Tabellen, die vom Apache Iceberg REST-Katalogendpunkt verwaltet werden, können nicht in BigQuery erstellt werden.
  • Apache Iceberg-Metadatentabellen (z. B. .snapshots oder .files) können in BigQuery nicht mit fünfteiligen Namens-IDs abgefragt werden. Sie können diese Tabellen mit Spark abfragen.

Iceberg-REST-Katalogendpunkt einrichten

Bevor Sie Ihren Katalog einrichten, sollten Sie sich die Übersicht über Apache Iceberg REST-Katalogendpunkte ansehen, um die Ressourcenhierarchie, die Katalogtypen und die Namensstruktur zu verstehen.

Im Folgenden finden Sie die allgemeinen Schritte, die Sie ausführen müssen, wenn Sie den Apache Iceberg REST-Katalogendpunkt im Lakehouse-Laufzeitkatalog verwenden:

  1. Wählen Sie anhand der Übersicht über Iceberg-REST-Katalogendpunkte den Speicherort Ihres Katalog-Data Warehouse aus (entweder Cloud Storage oder BigQuery).
  2. Wenn Sie ein gs://-Warehouse in Cloud Storage verwenden, erstellen Sie einen Katalog, der auf den Speicherort Ihres Warehouses verweist.
  3. Konfigurieren Sie Ihre Clientanwendung für die Verwendung des Apache Iceberg-REST-Katalogendpunkts.
  4. Erstellen Sie einen Namespace oder ein Schema, um Ihre Tabellen zu organisieren.
  5. Tabellen mit dem konfigurierten Client erstellen und abfragen

Katalog erstellen

Sie können einen Katalog erstellen, der entweder Anmeldedaten von Endnutzern oder den Modus für die Bereitstellung von Anmeldedaten verwendet.

  • Mit Endnutzeranmeldedaten übergibt der Katalog die Identität des Endnutzers, der darauf zugreift, zur Autorisierungsprüfung an Cloud Storage.

  • Die Bereitstellung von Anmeldedaten ist ein Mechanismus zur Delegierung des Speicherzugriffs, mit dem Administratoren des Lakehouse-Laufzeitkatalogs Berechtigungen direkt für Ressourcen des Lakehouse-Laufzeitkatalogs steuern können. Dadurch ist es nicht erforderlich, dass Katalognutzer direkten Zugriff auf Cloud Storage-Buckets haben. Damit können Lakehouse-Administratoren in Google Cloud Nutzern Berechtigungen für bestimmte Datendateien erteilen.

Hinweise

Machen Sie sich mit den Standortanforderungen vertraut, bevor Sie einen Katalog erstellen.

  • Wenn Sie einen Namespace erstellen, wird automatisch dieselbe Region wie für Ihren Katalog verwendet.

  • Wenn Ihr Katalog einen multiregionalen Bucket verwendet und Sie ihn mit den BigQuery-Multiregionen (US oder EU) verwenden möchten, müssen Sie den Katalog löschen und neu erstellen, um den primären Standort anzugeben.

Anmeldedaten für Endnutzer

Console

  1. Öffnen Sie in der Google Cloud Console die Seite Lakehouse.

    Lakehouse aufrufen

  2. Klicken Sie auf Katalog erstellen.

  3. Geben Sie im Feld Cloud Storage-Bucket auswählen den Namen des Cloud Storage-Buckets ein, der für Ihren Katalog verwendet werden soll. Alternativ können Sie auf Durchsuchen klicken, um einen vorhandenen Bucket auszuwählen oder einen neuen zu erstellen. Sie können nur einen Katalog pro Cloud Storage-Bucket haben.

  4. Wählen Sie unter Authentication method (Authentifizierungsmethode) die Option End-user credentials (Anmeldedaten von Endnutzern) aus.

  5. Klicken Sie auf Erstellen.

gcloud

Führen Sie den Befehl gcloud biglake iceberg catalogs create aus.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user \
    [--primary-location LOCATION]

Ersetzen Sie Folgendes:

  • CATALOG_NAME: ein Name für Ihren Katalog. Bei Apache Iceberg-Tabellen, die vom Lakehouse-Laufzeitkatalog unterstützt werden, stimmt dieser Name häufig mit der Cloud Storage-Bucket-ID überein, die mit dem REST-Katalog verwendet wird. Wenn Ihr Bucket beispielsweise gs://bucket-id ist, lautet der Katalognamen möglicherweise bucket-id. Dieser Name wird auch als Katalog-ID verwendet, wenn diese Tabellen in BigQuery abgefragt werden.
  • PROJECT_ID: Projekt-ID in Google Cloud .
  • LOCATION: (Optional) Die primäre Region für den Katalog, um die Interoperabilität mit BigQuery zu gewährleisten. Für Cloud Storage-Buckets in der Region USA (z. B. US oder us-central1) oder in der Region EU (z. B. EU oder europe-west4) geben Sie US bzw. EU an, damit der Katalog aus den entsprechenden BigQuery-Multiregionen aufgerufen und abgefragt werden kann. Weitere Informationen finden Sie unter Bucket- und Katalogregionen.

Modus für Bereitstellung von Anmeldedaten

Ein Katalogadministrator aktiviert die Bereitstellung von Anmeldedaten beim Erstellen oder Aktualisieren eines Katalogs. Als Katalognutzer können Sie dann den Apache Iceberg-REST-Katalogendpunkt anweisen, eingeschränkte Speicheranmeldedaten zurückzugeben. Dazu geben Sie die Zugriffsdelegierung an, wenn Sie den Apache Iceberg-REST-Katalogendpunkt konfigurieren.

Für das automatisch bereitgestellte Dienstkonto des Lakehouse-Laufzeitkatalogs ist die explizite Rolle „Storage Object User“ (roles/storage.objectUser) für den Ziel-Cloud Storage-Bucket erforderlich. Standardmäßig wird sie mit Betrachterzugriff erstellt. Ohne diese Rolle haben die bereitgestellten Anmeldedaten nicht genügend Berechtigungen, um in den Speicher zu schreiben. Wenn Sie Tools wie gcloud oder Terraform verwenden, müssen Sie diese Rolle manuell zuweisen.

Console

  1. Öffnen Sie in der Google Cloud Console die Seite Lakehouse.

    Lakehouse aufrufen

  2. Klicken Sie auf  Katalog erstellen. Die Seite Katalog erstellen wird geöffnet.

  3. Geben Sie unter Cloud Storage-Bucket auswählen den Namen des Cloud Storage-Buckets ein, der für Ihren Katalog verwendet werden soll. Alternativ können Sie auf Durchsuchen klicken, um einen Bucket aus einer Liste vorhandener Buckets auszuwählen oder einen neuen Bucket zu erstellen. Sie können nur einen Katalog pro Cloud Storage-Bucket haben.

  4. Wählen Sie unter Authentication method (Authentifizierungsmethode) die Option Credential vending mode (Modus für Bereitstellung von Anmeldedaten) aus.

  5. Klicken Sie auf Erstellen.

    Ihr Katalog wird erstellt und die Seite Katalogdetails wird geöffnet.

  6. Klicken Sie unter Authentifizierungsmethode auf Bucket-Berechtigungen festlegen.

  7. Klicken Sie im Dialogfeld auf Bestätigen.

    So wird überprüft, ob das Dienstkonto Ihres Katalogs die Rolle „Storage-Objekt-Administrator“ für Ihren Speicher-Bucket hat.

gcloud

Führen Sie den Befehl gcloud biglake iceberg catalogs create aus.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode vended-credentials \
    [--primary-location LOCATION]

Ersetzen Sie Folgendes:

  • CATALOG_NAME: ein Name für Ihren Katalog. Dieser Name entspricht oft der Cloud Storage-Bucket-ID, die mit dem REST-Katalog verwendet wird. Wenn Ihr Bucket beispielsweise gs://bucket-id ist, lautet der Katalogname möglicherweise bucket-id. Dieser Name wird auch als Katalog-ID verwendet, wenn diese Tabellen in BigQuery abgefragt werden.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID.

  • LOCATION: (Optional) Die primäre Region für den Katalog, um die Interoperabilität mit BigQuery zu gewährleisten. Geben Sie für Cloud Storage-Buckets in der Region „US“ (z. B. US oder us-central1) oder in der Region „EU“ (z. B. EU oder europe-west4) US bzw. EU an, damit der Katalog aus den entsprechenden BigQuery-Multiregionen aufgerufen und abgefragt werden kann. Weitere Informationen finden Sie unter Bucket- und Katalogregionen.

    Nachdem Sie den Katalog erstellt haben, weisen Sie dem automatisch bereitgestellten Dienstkonto des Lakehouse-Laufzeitkatalogs die Rolle Storage Object User (roles/storage.objectUser) für Ihren Speicher-Bucket explizit zu.

Clientanwendung konfigurieren

Nachdem Sie einen Katalog erstellt haben, konfigurieren Sie Ihre Clientanwendung für die Verwendung des Katalogs. In diesen Beispielen wird gezeigt, wie Sie die Konfiguration mit oder ohne Bereitstellung von Anmeldedaten vornehmen.

Cluster

Wenn Sie Spark mit dem Apache Iceberg REST-Katalogendpunkt in Managed Service for Apache Spark verwenden möchten, können Sie die Konfiguration mit Eigenschaften vereinfachen oder die Sitzung manuell konfigurieren.

Cluster mit der Katalog-Property erstellen:

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION \
    --properties="dataproc:dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Ersetzen Sie Folgendes:

  • CLUSTER_NAME: Ein Name für Ihren Cluster.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID
  • REGION: Die Region des Managed Service for Apache Spark-Clusters.
  • DATAPROC_VERSION: Die Image-Version von Managed Service for Apache Spark, z. B. 2.2.
  • CATALOG_NAME: Ein Name für den Lakehouse-Katalog, der in Spark verwendet werden soll. Er kann mit CATALOG_ID identisch sein.
  • CATALOG_ID: Die ID des von Ihnen erstellten Lakehouse-Katalogs.

Erstellen Sie dann eine Spark-Sitzung, ohne manuelle Katalogparameter anzugeben:

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

Manuelle Konfiguration

Wenn Sie das Clusterattribut nicht verwenden, erstellen Sie einen Cluster wie oben beschrieben (ohne das Flag --properties) und konfigurieren Sie dann Ihre Spark-Sitzung manuell:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Ersetzen Sie Folgendes:

  • CATALOG_NAME: Der Name des Apache Iceberg-REST-Katalogendpunkts.
  • APP_NAME: Ein Name für Ihre Spark-Sitzung.
  • REST_API_VERSION: auf v1 für die stabile Version der API festgelegt. Auf v1beta setzen, wenn Sie ein bekanntes Problem bei der Generierung des Datenursprungs umgehen müssen.
  • WAREHOUSE_PATH: Der Pfad zu Ihrem Warehouse. Verwenden Sie gs://CLOUD_STORAGE_BUCKET_NAME. Informationen zur Verwendung der BigQuery-Katalogföderation finden Sie unter Katalogföderation mit BigQuery verwenden.
  • PROJECT_ID: Das Projekt, das für die Verwendung des Apache Iceberg REST-Katalogendpunkts abgerechnet wird. Dies kann sich vom Projekt unterscheiden, zu dem der Cloud Storage-Bucket gehört. Weitere Informationen zur Projektkonfiguration bei Verwendung einer REST API finden Sie unter Systemparameter.

Mit Bereitstellung von Anmeldedaten konfigurieren

Wenn Sie die Bereitstellung von Anmeldedaten verwenden möchten, müssen Sie einen Katalog im Modus für die Bereitstellung von Anmeldedaten verwenden und den Header X-Iceberg-Access-Delegation mit dem Wert vended-credentials zu Iceberg-REST-Kataloganfragen hinzufügen. Fügen Sie dazu die folgende Zeile zum SparkSession-Builder hinzu: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Beispiel mit Bereitstellung von Anmeldedaten

Im folgenden Beispiel wird die Abfrage-Engine mit der Bereitstellung von Anmeldedaten konfiguriert:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Weitere Informationen finden Sie in der Apache Iceberg-Dokumentation im Abschnitt Headers in the RESTCatalog section.

Managed Service for Apache Spark-Cluster unterstützen Google-Autorisierungsabläufe für Apache Iceberg in den folgenden Versionen:

  • Managed Service for Apache Spark in Compute Engine 2.2-Image-Versionen 2.2.65 und höher.
  • Managed Service for Apache Spark in Compute Engine 2.3-Image-Versionen 2.3.11 und höher.

Serverlos

Senden Sie eine PySpark-Batcharbeitslast an Managed Service for Apache Spark. Verwenden Sie dazu Attribute, um die Konfiguration zu vereinfachen (empfohlen), oder geben Sie alle Parameter an.

Senden Sie einen Batchjob mit der Katalog-Property:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="dataproc:dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Manuelle Konfiguration

Wenn Sie alle Properties lieber manuell angeben möchten, verwenden Sie die folgende Konfiguration:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

Ersetzen Sie Folgendes:

  • PYSPARK_FILE: Der gs:// Cloud Storage-Pfad zu Ihrer PySpark-Anwendungsdatei.
  • PROJECT_ID: Projekt-ID in Google Cloud .
  • REGION: die Region für die Managed Service for Apache Spark-Batcharbeitslast.
  • RUNTIME_VERSION: die Laufzeitversion von Managed Service for Apache Spark, z. B. 2.2.
  • CATALOG_NAME: Der Name des Apache Iceberg-REST-Katalogendpunkts.
  • REST_API_VERSION: auf v1 für die stabile Version der API festgelegt. Auf v1beta setzen, wenn Sie ein bekanntes Problem bei der Generierung des Datenursprungs umgehen müssen.
  • WAREHOUSE_PATH: Der Pfad zu Ihrem Warehouse. Verwenden Sie gs://CLOUD_STORAGE_BUCKET_NAME. Informationen zur Verwendung der BigQuery-Katalogföderation finden Sie unter Katalogföderation mit BigQuery verwenden.

Mit Bereitstellung von Anmeldedaten konfigurieren

Wenn Sie die Bereitstellung von Anmeldedaten verwenden möchten, müssen Sie einen Katalog im Modus für die Bereitstellung von Anmeldedaten verwenden und den Header X-Iceberg-Access-Delegation den Apache Iceberg-REST-Katalogendpunktanfragen mit dem Wert vended-credentials hinzufügen. Fügen Sie dazu die folgende Zeile den Managed Service for Apache Spark-Konfigurationen hinzu: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Beispiel mit Bereitstellung von Anmeldedaten

Im folgenden Beispiel wird die Abfrage-Engine mit der Bereitstellung von Anmeldedaten konfiguriert:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=gs://CLOUD_STORAGE_BUCKET_NAME,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
    spark.sql.catalog.CATALOG_NAME.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token, \
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

Weitere Informationen finden Sie im Abschnitt Headers in the RESTCatalog der Apache Iceberg-Dokumentation.

Managed Service for Apache Spark unterstützt Google-Autorisierungsabläufe für Apache Iceberg in den folgenden Laufzeitversionen:

  • Managed Service for Apache Spark 2.2-Laufzeiten 2.2.60 und höher
  • Managed Service for Apache Spark 2.3-Laufzeiten 2.3.10 und höher

Trino

Wenn Sie Trino mit dem Apache Iceberg REST-Katalogendpunkt verwenden möchten, erstellen Sie einen Managed Service for Apache Spark-Cluster mit der Trino-Komponente und konfigurieren Sie die Katalogeigenschaften mit dem Flag gcloud dataproc clusters create --properties. Im folgenden Beispiel wird ein Trino-Katalog mit dem Namen CATALOG_NAME erstellt:

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=REGION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=WAREHOUSE_PATH,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.biglake.project-id=PROJECT_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager"

Ersetzen Sie Folgendes:

  • CLUSTER_NAME: ein Name für Ihren Cluster.
  • REGION: Die Region des Managed Service for Apache Spark-Clusters.
  • DATAPROC_VERSION: Die Image-Version von Managed Service for Apache Spark, z. B. 2.2.
  • NETWORK_ID: Cluster-Netzwerk-ID. Weitere Informationen finden Sie unter Netzwerkkonfiguration für Managed Service for Apache Spark-Cluster.
  • CATALOG_NAME: Der Name Ihres Trino-Katalogs mit dem Apache Iceberg-REST-Katalogendpunkt.
  • REST_API_VERSION: auf v1 für die stabile Version der API festgelegt. Auf v1beta setzen, wenn Sie ein bekanntes Problem bei der Generierung des Datenursprungs umgehen müssen.
  • WAREHOUSE_PATH: Der Pfad zu Ihrem Warehouse. Verwenden Sie gs://CLOUD_STORAGE_BUCKET_NAME.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID für den Lakehouse-Laufzeitkatalog.

Stellen Sie nach dem Erstellen des Clusters eine Verbindung zur Haupt-VM-Instanz her und verwenden Sie die Trino-Befehlszeile:

trino --catalog=CATALOG_NAME

Managed Service for Apache Spark Trino unterstützt Google-Autorisierungsabläufe für Apache Iceberg in den folgenden Versionen:

  • Managed Service for Apache Spark in Compute Engine 2.2-Laufzeitversionen 2.2.65 und höher
  • Managed Service for Apache Spark in Compute Engine-Laufzeitversionen 2.3 2.3.11 und höher
  • Managed Service for Apache Spark in Compute Engine 3.0 wird nicht unterstützt.

Mit Bereitstellung von Anmeldedaten konfigurieren

Die Bereitstellung von Anmeldedaten wird nur in Trino-Version 481 und höher unterstützt.

Apache Iceberg 1.10 oder höher

Open-Source-Versionen von Apache Iceberg 1.10 und höher bieten integrierte Unterstützung für Google-Autorisierungsabläufe in GoogleAuthManager. Im Folgenden sehen Sie ein Beispiel für die Konfiguration von Spark für die Verwendung des Lakehouse-Laufzeitkatalogs und des Apache Iceberg-REST-Katalogendpunkts.

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Ersetzen Sie Folgendes:

  • CATALOG_NAME: Der Name des Apache Iceberg-REST-Katalogendpunkts.
  • APP_NAME: Ein Name für Ihre Spark-Sitzung.
  • REST_API_VERSION: auf v1 für die stabile Version der API festgelegt. Auf v1beta setzen, wenn Sie ein bekanntes Problem bei der Generierung des Datenursprungs umgehen müssen.
  • WAREHOUSE_PATH: Der Pfad zu Ihrem Warehouse. Verwenden Sie gs://CLOUD_STORAGE_BUCKET_NAME. Informationen zur Verwendung der BigQuery-Katalogföderation finden Sie unter Katalogföderation mit BigQuery verwenden.
  • PROJECT_ID: Das Projekt, das für die Verwendung des Apache Iceberg-REST-Katalogendpunkts abgerechnet wird. Dies kann sich vom Projekt unterscheiden, zu dem der Cloud Storage-Bucket gehört. Weitere Informationen zur Projektkonfiguration bei Verwendung einer REST API finden Sie unter Systemparameter.

Mit Bereitstellung von Anmeldedaten konfigurieren

Im vorherigen Beispiel wird keine Bereitstellung von Anmeldedaten verwendet. Wenn Sie die Bereitstellung von Anmeldedaten verwenden möchten, müssen Sie einen Katalog im Modus für die Bereitstellung von Anmeldedaten verwenden und den Header X-Iceberg-Access-Delegation mit dem Wert vended-credentials zu den Apache Iceberg REST-Katalogendpunktanfragen hinzufügen. Fügen Sie dazu die folgende Zeile zum SparkSession-Builder hinzu: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Beispiel mit Bereitstellung von Anmeldedaten

Im folgenden Beispiel wird die Abfrage-Engine mit der Bereitstellung von Anmeldedaten konfiguriert:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Weitere Informationen finden Sie im Abschnitt Headers in the RESTCatalog der Apache Iceberg-Dokumentation.

Frühere Apache Iceberg-Releases

Für Open-Source-Apache Iceberg-Releases vor Version 1.10 können Sie die standardmäßige OAuth-Authentifizierung konfigurieren, indem Sie eine Sitzung mit Folgendem konfigurieren:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.9.1,org.apache.iceberg:iceberg-gcp-bundle:1.9.1') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Ersetzen Sie Folgendes:

  • CATALOG_NAME: Der Name des Apache Iceberg-REST-Katalogendpunkts.
  • APP_NAME: Ein Name für Ihre Spark-Sitzung.
  • REST_API_VERSION: auf v1 für die stabile Version der API festgelegt. Auf v1beta setzen, wenn Sie ein bekanntes Problem bei der Generierung des Datenursprungs umgehen müssen.
  • WAREHOUSE_PATH: Der Pfad zu Ihrem Warehouse. Verwenden Sie gs://CLOUD_STORAGE_BUCKET_NAME. Informationen zur Verwendung der BigQuery-Katalogföderation finden Sie unter Katalogföderation mit BigQuery verwenden.
  • PROJECT_ID: Das Projekt, das für die Verwendung des Apache Iceberg-REST-Katalogendpunkts abgerechnet wird. Dies kann sich vom Projekt unterscheiden, zu dem der Cloud Storage-Bucket gehört. Weitere Informationen zur Projektkonfiguration bei Verwendung einer REST API finden Sie unter Systemparameter.
  • TOKEN: Ihr Authentifizierungstoken, das eine Stunde lang gültig ist, z. B. ein mit gcloud auth application-default print-access-token generiertes Token.

Mit Bereitstellung von Anmeldedaten konfigurieren

Im vorherigen Beispiel wird keine Bereitstellung von Anmeldedaten verwendet. Wenn Sie die Bereitstellung von Anmeldedaten verwenden möchten, müssen Sie einen Katalog im Modus für die Bereitstellung von Anmeldedaten verwenden und den Header X-Iceberg-Access-Delegation mit dem Wert vended-credentials zu den Apache Iceberg REST-Katalogendpunktanfragen hinzufügen. Fügen Sie dazu die folgende Zeile zum SparkSession-Builder hinzu: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Beispiel mit Bereitstellung von Anmeldedaten

Im folgenden Beispiel wird die Abfrage-Engine mit der Bereitstellung von Anmeldedaten konfiguriert:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Weitere Informationen finden Sie im Abschnitt Headers in the RESTCatalog der Apache Iceberg-Dokumentation.

Namespace oder Schema erstellen

Nachdem Sie Ihren Client konfiguriert haben, erstellen Sie einen Namespace oder ein Schema, um Ihre Tabellen zu organisieren. Die Syntax zum Erstellen eines Namespace oder Schemas variiert je nach Abfrage-Engine. In den folgenden Beispielen wird gezeigt, wie Sie sie mit Spark und Trino erstellen.

Spark

Cloud Storage-Warehouse

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME;")
spark.sql("USE NAMESPACE_NAME;")

Ersetzen Sie NAMESPACE_NAME durch einen Namen für den Namespace.

Trino

Cloud Storage-Warehouse

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;
USE CATALOG_NAME.SCHEMA_NAME;

Ersetzen Sie Folgendes:

  • CATALOG_NAME: Der Name Ihres Trino-Katalogs mit dem Apache Iceberg-REST-Katalogendpunkt.
  • SCHEMA_NAME: Ein Name für Ihr Schema.

Nächste Schritte