Iceberg-REST-Katalog von BigLake Metastore verwenden

Der Apache Iceberg REST-Katalog in BigLake Metastore ist die empfohlene Methode, um BigLake Metastore für neue Arbeitsabläufe zu verwenden. Es sorgt für Interoperabilität zwischen Ihren Abfragemodulen, indem es eine einzige Quelle der Wahrheit für alle Ihre Iceberg-Daten bietet. Damit können Abfrage-Engines wie Apache Spark Iceberg-Tabellen auf konsistente Weise erkennen, Metadaten daraus lesen und sie 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 sowie regionenübergreifende Replikation und Notfallwiederherstellung.

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

Hinweise

Machen Sie sich mit dem BigLake Metastore vertraut, bevor Sie fortfahren.

  1. Verify that billing is enabled for your Google Cloud project.

  2. Enable the BigLake API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zur Verwendung des Iceberg-REST-Katalogs im BigLake-Metastore 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
  • Tabellendaten im Credential Vending-Modus schreiben: BigLake-Editor (roles/biglake.editor) für das Projekt
  • Katalogressourcen und Tabellendaten im Modus ohne Bereitstellung von Anmeldedaten lesen:
  • Katalogressourcen verwalten und Tabellendaten im Modus ohne Bereitstellung von Anmeldedaten schreiben:

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

Für den Iceberg REST-Katalog gelten die folgenden Einschränkungen:

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

Katalogressourcen

Der Apache Iceberg REST-Katalog in BigLake Metastore verwendet eine Hierarchie von Ressourcen, um Ihre Daten zu organisieren.

Apache Iceberg REST-Katalogressourcen

Die folgende Tabelle bietet einen allgemeinen Überblick über die Ressourcen, die vom Apache Iceberg REST-Katalog im BigLake Metastore verwendet werden.

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

Unterstützte Kataloge

Wenn Sie Ihren Client konfigurieren, geben Sie einen Warehouse-Standort an. Diese Auswahl bestimmt, wie Ihr Katalog funktioniert und in andere Google Cloud-Dienste eingebunden wird.

Katalogtyp Beschreibung
Cloud Storage-Bucket Alle Daten in einem Katalog werden in einem einzelnen Cloud Storage-Bucket gespeichert. Wenn Daten in mehreren Buckets freigegeben werden, sind mehrere Kataloge erforderlich.
BigQuery-Föderation Ermöglicht die Verwendung des Iceberg-REST-Katalogs zum Verwalten und Abfragen von Tabellen, die für BigQuery sichtbar sind. Weitere Informationen finden Sie unter Katalogföderation mit BigQuery verwenden.

Details zum Katalog-Warehouse

Empfohlen

  • Cloud Storage-Bucket-Warehouse (gs://): Bei diesem Standardansatz werden Iceberg-Metadaten und ‑Datendateien direkt vom Katalog in einem von Ihnen angegebenen Cloud Storage-Bucket verwaltet. Mit dieser Option haben Sie die direkte Kontrolle über Ihr Datenlayout und unterstützen Credential Vending für eine detaillierte Zugriffssteuerung. So können Sie BigLake-Tabellen für Apache Iceberg erstellen und verwalten.

    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. Das wird später verwendet, wenn Sie Ihren Katalog in BigQuery mit der P.C.N.T.-Syntax abfragen. Beispiel: my-project.biglake-catalog-id.quickstart_namespace.quickstart_table.

Legacy

  • BigQuery-Föderation (bq://): Mit diesem Ansatz können Sie den Iceberg REST-Katalog verwenden, um Tabellen zu verwalten und abzufragen, die für BigQuery sichtbar sind, ohne eine Katalogressource erstellen zu müssen. Weitere Informationen finden Sie unter Katalogföderation mit BigQuery verwenden.

Namensstruktur für P.C.N.T.

Wenn Sie BigLake Metastore-Tabellen in 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 BigLake Metastore-Katalogs.
  • Namespace: Der Iceberg-Namespace (entspricht einem BigQuery-Dataset).
  • Tabelle: Der Name der Tabelle.

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

Iceberg REST-Katalog einrichten

Im Folgenden finden Sie die allgemeinen Schritte, die Sie ausführen müssen, wenn Sie den Apache Iceberg REST-Katalog in BigLake Metastore verwenden:

  1. Sie müssen den Speicherort für Ihr Katalog-Data Warehouse auswählen, entweder Cloud Storage oder BigQuery.
  2. Wenn Sie ein gs://-Data Warehouse in Cloud Storage verwenden, erstellen Sie einen Katalog, der auf den Speicherort Ihres Data Warehouse verweist.
  3. Konfigurieren Sie Ihre Clientanwendung für die Verwendung des Iceberg-REST-Katalogs.
  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 BigLake Metastore-Administratoren Berechtigungen direkt für BigLake Metastore-Ressourcen steuern können. Dadurch ist kein direkter Zugriff von Katalogusern auf Cloud Storage-Buckets mehr erforderlich. Damit können BigLake-Administratoren Nutzern Berechtigungen für bestimmte Datendateien erteilen.

Anmeldedaten für Endnutzer

Console

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

    Zu BigLake wechseln

  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 beta biglake iceberg catalogs create aus.

gcloud beta biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user

Ersetzen Sie Folgendes:

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 Iceberg REST-Katalog anweisen, eingeschränkte Speicheranmeldedaten zurückzugeben, indem Sie die Zugriffsdelegierung angeben, wenn Sie den Iceberg REST-Katalog konfigurieren.

Console

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

    Zu BigLake wechseln

  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 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 geprüft, ob das Dienstkonto Ihres Katalogs die Rolle „Storage Object User“ für Ihren Speicher-Bucket hat.

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 Iceberg-REST-Katalog in Dataproc verwenden möchten, müssen Sie zuerst einen Cluster erstellen, der die Iceberg-Komponente enthält:

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION

Ersetzen Sie Folgendes:

  • CLUSTER_NAME: ein Name für Ihren Cluster.
  • PROJECT_ID: Projekt-ID in Google Cloud .
  • REGION: die Region für den Dataproc-Cluster.
  • DATAPROC_VERSION: die Dataproc-Image-Version, z. B. 2.2.

Nachdem Sie den Cluster erstellt haben, konfigurieren Sie Ihre Spark-Sitzung für die Verwendung des Iceberg-REST-Katalogs:

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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Ersetzen Sie Folgendes:

  • CATALOG_NAME: Der Name Ihres Iceberg-REST-Katalogs.
  • APP_NAME: Ein Name für Ihre Spark-Sitzung.
  • 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 Iceberg REST-Katalogs abgerechnet wird. Dies kann sich vom Projekt unterscheiden, in dem sich der Cloud Storage-Bucket befindet. Weitere Informationen zur Projektkonfiguration bei Verwendung einer REST API finden Sie unter Systemparameter.

Konfiguration mit der Bereitstellung von Anmeldedaten

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 zu Iceberg-REST-Kataloganfragen mit dem Wert vended-credentials 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Weitere Informationen finden Sie in der Iceberg-Dokumentation im Abschnitt Header in RESTCatalog.

Dataproc-Cluster unterstützen Google-Autorisierungsabläufe für Iceberg in den folgenden Versionen:

  • Dataproc in Compute Engine-Image-Versionen 2.2.65 und höher.
  • Dataproc in Compute Engine-Image-Versionen 2.3.11 und höher.

Serverlos

Senden Sie eine PySpark-Batcharbeitslast an Google Cloud Serverless for Apache Spark mit der folgenden 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/v1/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,\
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false"

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 Dataproc-Batcharbeitslast.
  • RUNTIME_VERSION: die Laufzeitversion von Serverless for Apache Spark, z. B. 2.2.
  • CATALOG_NAME: Der Name Ihres Iceberg-REST-Katalogs.
  • 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.

Konfiguration mit der Bereitstellung von Anmeldedaten

Wenn Sie die Bereitstellung von Anmeldedaten verwenden möchten, müssen Sie einen Katalog im Bereitstellungsmodus für 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 zu den Serverless 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/v1/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.rest-metrics-reporting-enabled=false,
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

Weitere Informationen finden Sie in der Iceberg-Dokumentation im Abschnitt Header in RESTCatalog.

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

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

Trino

Wenn Sie Trino mit dem Iceberg-REST-Katalog verwenden möchten, erstellen Sie einen Dataproc-Cluster mit der Trino-Komponente und konfigurieren Sie die Katalogattribute 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/v1/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 Dataproc-Clusters.
  • DATAPROC_VERSION: Dataproc-Image-Version, z. B. 2.2.
  • NETWORK_ID: Cluster-Netzwerk-ID. Weitere Informationen finden Sie unter Dataproc-Cluster-Netzwerkkonfiguration.
  • CATALOG_NAME: Der Name Ihres Trino-Katalogs, der den Iceberg REST-Katalog verwendet.
  • WAREHOUSE_PATH: Der Pfad zu Ihrem Warehouse. Verwenden Sie gs://CLOUD_STORAGE_BUCKET_NAME.
  • PROJECT_ID: Ihre Google Cloud Projekt-ID, die für BigLake Metastore verwendet werden soll.

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

trino --catalog=CATALOG_NAME

Dataproc Trino unterstützt Google-Autorisierungsabläufe für Iceberg in den folgenden Versionen:

  • Dataproc in Compute Engine-Laufzeitversionen 2.2.65 und höher
  • Dataproc in Compute Engine-Laufzeitversionen 2.3.11 und höher
  • Dataproc auf Compute Engine 3.0 wird nicht unterstützt.

Konfiguration mit der Bereitstellung von Anmeldedaten

Die Bereitstellung von Anmeldedaten wird in Dataproc Trino nicht unterstützt.

Iceberg 1.10 oder höher

Open-Source-Versionen von 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 Apache Spark zur Verwendung des Iceberg REST-Katalogs von BigLake Metastore.

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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Ersetzen Sie Folgendes:

  • CATALOG_NAME: Der Name Ihres Iceberg-REST-Katalogs.
  • APP_NAME: Ein Name für Ihre Spark-Sitzung.
  • 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 Iceberg REST-Katalogs 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.

Konfiguration mit der Bereitstellung von Anmeldedaten

Im vorherigen Beispiel wird die Bereitstellung von Anmeldedaten nicht verwendet. Wenn Sie die Bereitstellung von Anmeldedaten verwenden möchten, müssen Sie einen Katalog im Bereitstellungsmodus für Anmeldedaten verwenden und den Header X-Iceberg-Access-Delegation zu Iceberg REST-Kataloganfragen mit dem Wert vended-credentials 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Weitere Informationen finden Sie in der Iceberg-Dokumentation im Abschnitt Header in RESTCatalog.

Frühere Iceberg-Releases

Für Open-Source-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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Ersetzen Sie Folgendes:

  • CATALOG_NAME: Der Name Ihres Iceberg-REST-Katalogs.
  • APP_NAME: Ein Name für Ihre Spark-Sitzung.
  • 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 Iceberg REST-Katalogs abgerechnet wird. Dies kann sich vom Projekt unterscheiden, 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 die Bereitstellung von Anmeldedaten nicht verwendet. Wenn Sie die Bereitstellung von Anmeldedaten verwenden möchten, müssen Sie einen Katalog im Bereitstellungsmodus für Anmeldedaten verwenden und den Header X-Iceberg-Access-Delegation zu Iceberg REST-Kataloganfragen mit dem Wert vended-credentials 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Weitere Informationen finden Sie in der Iceberg-Dokumentation im Abschnitt Header in RESTCatalog.

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, der den Iceberg REST-Katalog verwendet.
  • SCHEMA_NAME: Ein Name für Ihr Schema.

Tabellen in BigQuery abfragen

Wie Sie Tabellen abfragen, die Sie über den Iceberg REST-Katalog in BigQuery erstellen, hängt davon ab, ob Sie ein Cloud Storage-Bucket-Warehouse oder die BigQuery-Föderation verwenden.

  • Cloud Storage-Bucket-Warehouse: Wenn Sie Ihren Client mit einem gs://-Warehouse-Pfad konfiguriert haben, fragen Sie Tabellen aus BigQuery mit dem vierteiligen Namen (P.C.N.T) project.catalog.namespace.table ab. Die Komponente catalog ist der Name Ihrer BigLake Metastore-Katalogressource. Weitere Informationen finden Sie unter Tabelle abfragen.

  • BigQuery-Föderation: Wenn Sie Ihren Client mit einem bq://-Warehouse-Pfad konfiguriert haben, sind die von Ihnen erstellten Tabellen in BigQuery sichtbar und können direkt mit Standard-BigQuery-SQL abgefragt werden:

    SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

    Ersetzen Sie Folgendes:

    • NAMESPACE_NAME: Der Name Ihres Namespace.
    • TABLE_NAME: der Name Ihrer Tabelle.

Katalogföderation mit BigQuery verwenden

Sie können die Iceberg-REST-Katalogschnittstelle verwenden, um Tabellen zu verwalten und abzufragen, die für BigQuery sichtbar sind. Für BigQuery-Föderationskataloge müssen Sie keine Katalogressource erstellen. Sie können in jedem Projekt verwendet werden, in dem die BigQuery API aktiviert ist. Damit können Sie:

Da diese Ressourcen von BigQuery verwaltet werden, benötigen Sie die entsprechenden erforderlichen Berechtigungen. Die Bereitstellung von Anmeldedaten wird für föderierte Kataloge nicht unterstützt.

Um die Föderation zu aktivieren, konfigurieren Sie Ihren Client mit dem Warehouse-Format bq://projects/PROJECT_ID im Feld WAREHOUSE_PATH in den Clientkonfigurationsbeispielen unter Iceberg-REST-Katalog verwenden. Sie können auch einen BigQuery-Standort angeben, um zukünftige Anfragen auf einen einzelnen Standort zu beschränken. Verwenden Sie dazu das Format bq://projects/PROJECT_ID/locations/LOCATION.

Nachdem Sie Ihren Client für die Föderation konfiguriert haben, können Sie einen Namespace für Ihre föderierten Tabellen erstellen.

Spark

Wenn Sie die BigQuery-Katalogföderation verwenden möchten, fügen Sie die Klauseln LOCATION und DBPROPERTIES ein:

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME LOCATION 'gs://BUCKET_NAME/NAMESPACE_NAME' WITH DBPROPERTIES ('gcp-region' = 'LOCATION');")
spark.sql("USE NAMESPACE_NAME;")

Ersetzen Sie Folgendes:

  • NAMESPACE_NAME: Ein Name für Ihren Namespace.
  • BUCKET_NAME: Der Cloud Storage-Bucket, den Sie mit Ihrem Katalog verwenden.
  • LOCATION: Ein BigQuery-Standort. Der Standardwert ist der multiregionale Standort US.

Trino

Wenn Sie die BigQuery-Katalogföderation verwenden möchten, müssen Sie die Attribute LOCATION und gcp-region angeben:

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME WITH ( LOCATION = 'gs://BUCKET_NAME/SCHEMA_NAME', "gcp-region" = 'LOCATION');
USE CATALOG_NAME.SCHEMA_NAME;

Ersetzen Sie Folgendes:

  • CATALOG_NAME: Der Name Ihres Trino-Katalogs, der den Iceberg REST-Katalog verwendet.
  • SCHEMA_NAME: Ein Name für Ihr Schema.
  • BUCKET_NAME: Der Cloud Storage-Bucket, den Sie mit Ihrem Katalog verwenden.
  • LOCATION: Ein BigQuery-Standort. Der Standardwert ist der multiregionale Standort US.

Preise

Preisdetails finden Sie unter BigLake-Preise.

Nächste Schritte