Iceberg-Tabelle in Lakehouse mit der Google Cloud CLI erstellen und abfragen

Iceberg-Tabelle in Lakehouse mit der Google Cloud CLI erstellen und abfragen

Mit Borderless Lakehouse können Sie Apache Iceberg-Tabellen inGoogle Cloud und Open-Source-Engines wie Apache Spark, Trino und Apache Flink freigeben. Der Lakehouse-Laufzeitkatalog verfolgt Metadaten, einschließlich Schemas, Snapshots und Cloud Storage-Speicherorten, über den Apache Iceberg REST-Katalogendpunkt.

In dieser Kurzanleitung konfigurieren Sie mit der Google Cloud CLI einen Katalog mit mehreren Buckets und führen einen PySpark-Job in Managed Service for Apache Spark aus. Nachdem der Job eine Iceberg-Tabelle erstellt hat, können Sie sie direkt in BigQuery mit der vierteiligen Syntax P.C.N.T (Project.Catalog.Namespace.Table) abfragen, ohne Daten zu verschieben oder zu registrieren.

Hinweis

Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie einfach ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.
Installieren Sie die Google Cloud CLI.
Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.
Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:
gcloud init
Google Cloud -Projekt erstellen oder auswählen.
Erforderliche Rollen zum Auswählen oder Erstellen eines Projekts
• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Project Creator“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Informationen zum Zuweisen von Rollen
Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.
• Erstellen Sie ein Projekt in Google Cloud :

  gcloud projects create PROJECT_ID

  Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud -Projekt, das Sie erstellen.

• Wählen Sie das von Ihnen erstellte Projekt Google Cloud aus:

  gcloud config set project PROJECT_ID

  Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .
Prüfen Sie, ob die Abrechnung für Ihr Google Cloud -Projekt aktiviert ist.
Aktivieren Sie die APIs für BigLake, Managed Service for Apache Spark, Cloud Storage, BigQuery und Compute Engine, falls sie noch nicht aktiviert sind:
Erforderliche Rollen zum Aktivieren von APIs
Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen
gcloud services enable biglake.googleapis.com dataproc.googleapis.com storage.googleapis.com bigquery.googleapis.com compute.googleapis.com
Weisen Sie Ihrem Nutzerkonto Rollen zu. Führen Sie den folgenden Befehl für jede der folgenden IAM-Rollen einmal aus: roles/biglake.admin, roles/storage.admin, roles/dataproc.editor, roles/resourcemanager.projectIamAdmin, roles/bigquery.jobUser
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Ersetzen Sie Folgendes:
• PROJECT_ID: Ihre Projekt-ID.
• USER_IDENTIFIER: Die Kennung für Ihr Nutzerkonto. Beispiel: [e-mail]
• ROLE: Die IAM-Rolle, die Sie Ihrem Nutzerkonto zuweisen.

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Google Cloud -Projekt erstellen oder auswählen.

Erforderliche Rollen zum Auswählen oder Erstellen eines Projekts

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Project Creator“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Informationen zum Zuweisen von Rollen

Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

• Erstellen Sie ein Projekt in Google Cloud :

  gcloud projects create PROJECT_ID

  Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud -Projekt, das Sie erstellen.

• Wählen Sie das von Ihnen erstellte Projekt Google Cloud aus:

  gcloud config set project PROJECT_ID

  Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

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

Aktivieren Sie die APIs für BigLake, Managed Service for Apache Spark, Cloud Storage, BigQuery und Compute Engine, falls sie noch nicht aktiviert sind:

Erforderliche Rollen zum Aktivieren von APIs

Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

gcloud services enable biglake.googleapis.com dataproc.googleapis.com storage.googleapis.com bigquery.googleapis.com compute.googleapis.com

Weisen Sie Ihrem Nutzerkonto Rollen zu. Führen Sie den folgenden Befehl für jede der folgenden IAM-Rollen einmal aus: roles/biglake.admin, roles/storage.admin, roles/dataproc.editor, roles/resourcemanager.projectIamAdmin, roles/bigquery.jobUser

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Ersetzen Sie Folgendes:

• PROJECT_ID: Ihre Projekt-ID.
• USER_IDENTIFIER: Die Kennung für Ihr Nutzerkonto. Beispiel: [e-mail]
• ROLE: Die IAM-Rolle, die Sie Ihrem Nutzerkonto zuweisen.

Umgebung einrichten und Bucket erstellen

Öffnen Sie Cloud Shell und erstellen Sie einen Cloud Storage-Bucket für ein PySpark-Skript und Iceberg-Tabellendaten:

1. Klicken Sie in der Google Cloud Console auf Cloud Shell aktivieren.

   Cloud Shell aktivieren

2. Klicken Sie auf Autorisieren, wenn Sie dazu aufgefordert werden.

3. Legen Sie Umgebungsvariablen für Ihr Projekt, Ihre Region, Ihren Bucket und Ihren Katalognamen fest, damit Sie sie in dieser Kurzanleitung wiederverwenden können:

   export PROJECT_ID=$(gcloud config get-value project)
   export REGION="us-central1"
   export BUCKET_NAME="${PROJECT_ID}-lakehouse-quickstart"
   export LAKEHOUSE_CATALOG_ID="quickstart_catalog"

4. Erstellen Sie einen Cloud Storage-Bucket in der ausgewählten Region:

   gcloud storage buckets create gs://${BUCKET_NAME} \
       --project=${PROJECT_ID} \
       --location=${REGION}

Berechtigungen für das Spark-Dienstkonto gewähren

Standardmäßig führt Managed Service for Apache Spark Batchjobs mit dem Compute Engine-Standarddienstkonto Ihres Projekts aus. Weisen Sie diesem Dienstkonto die folgenden IAM-Rollen zu, damit es Ihr PySpark-Script aus Cloud Storage lesen und mit dem Lakehouse-Laufzeitkatalog und BigQuery interagieren kann:

Rolle	Ressource	Zweck
Dataproc-Worker (roles/dataproc.worker)	Projekt	Managed Service for Apache Spark-Batcharbeitslasten ausführen.
Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)	Projekt	Projekt-APIs und ‑Kontingente verwenden.
BigLake-Bearbeiter (roles/biglake.editor)	Projekt	Katalogressourcen erstellen und Anmeldedaten für den bereitgestellten Speicher anfordern.
BigQuery-Dateneditor (roles/bigquery.dataEditor)	Projekt	BigQuery-Metadaten für Ihre Tabellen verwalten
Storage-Objekt-Betrachter (roles/storage.objectViewer)	Bucket	Lesen Sie Ihr PySpark-Script aus Ihrem Cloud Storage-Bucket.

Beachten Sie, dass das Spark-Dienstkonto nur die Rolle Storage-Objekt-Betrachter (roles/storage.objectViewer) benötigt, um Ihr PySpark-Skript zu lesen. Es ist kein direkter Schreibzugriff auf Ihren Bucket erforderlich, da der Lakehouse-Laufzeitkatalog beim Ausführen des Jobs temporäre, tabellenspezifische Schreibanmeldedaten bereitstellt.

Führen Sie in Cloud Shell das folgende Script aus, um diese Rollen zuzuweisen:

PROJECT_NUMBER=$(gcloud projects describe ${PROJECT_ID} \
    --format='value(projectNumber)')
SPARK_SA="${PROJECT_NUMBER}[e-mail]"

for ROLE in \
    "roles/dataproc.worker" \
    "roles/serviceusage.serviceUsageConsumer" \
    "roles/biglake.editor" \
    "roles/bigquery.dataEditor"; do
  gcloud projects add-iam-policy-binding ${PROJECT_ID} \
      --member="serviceAccount:${SPARK_SA}" \
      --role="${ROLE}"
done

gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
    --member="serviceAccount:${SPARK_SA}" \
    --role="roles/storage.objectViewer"

Katalog im Lakehouse-Laufzeitkatalog erstellen

Erstellen Sie im Lakehouse-Laufzeitkatalog einen Katalog für Ihre Apache Iceberg-Tabellen.

1. Erstellen Sie in Cloud Shell einen Katalog mit mehreren Buckets. In einem Katalog mit mehreren Buckets können Sie Ihren Katalog unabhängig von einem Bucket-Namen benennen und mehrere Cloud Storage-Buckets mit einem einzigen Katalog verknüpfen. Aktivieren Sie den Modus für die Bereitstellung von Anmeldedaten, damit der Lakehouse-Laufzeitkatalog in Ihrem Namen sichere temporäre Speicheranmeldedaten an Spark ausgeben kann.

   gcloud biglake iceberg catalogs create ${LAKEHOUSE_CATALOG_ID} \
       --project=${PROJECT_ID} \
       --catalog-type=biglake \
       --default-location=gs://${BUCKET_NAME} \
       --credential-mode=vended-credentials

2. Gewähren Sie dem Katalog Zugriff auf Ihren Bucket:

   Bei der Bereitstellung von Anmeldedaten benötigt das automatisch bereitgestellte Dienstkonto des Katalogs die Rolle Storage-Objekt-Nutzer (roles/storage.objectUser) für Ihren Bucket, damit es temporäre Zugriffstokens für Client-Engines generieren kann.

   # Retrieve the auto-provisioned catalog service account email
   CATALOG_SA=$(gcloud biglake iceberg catalogs describe ${LAKEHOUSE_CATALOG_ID} \
       --project=${PROJECT_ID} \
       --format='value(biglake-service-account)')
   
   # Grant the Storage Object User role to the catalog service account on your bucket
   gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
       --member="serviceAccount:${CATALOG_SA}" \
       --role="roles/storage.objectUser"

Iceberg-Tabelle mit einem PySpark-Job erstellen

Nachdem Sie den Katalog und die Berechtigungen eingerichtet haben, können Sie einen PySpark-Job in Managed Service for Apache Spark ausführen, um eine Iceberg-Tabelle zu erstellen und einige Beispieldaten einzufügen.

PySpark-Script erstellen und hochladen

1. Erstellen Sie in Cloud Shell eine Datei mit dem Namen quickstart.py:

   cat << 'EOF' > quickstart.py
   from pyspark.sql import SparkSession
   
   spark = SparkSession.builder.appName("quickstart").getOrCreate()
   
   # Create a namespace
   spark.sql("CREATE NAMESPACE IF NOT EXISTS `quickstart_catalog`.quickstart_namespace")
   
   # Create the table
   spark.sql("""
       CREATE OR REPLACE TABLE `quickstart_catalog`.quickstart_namespace.quickstart_table (
           id INT,
           name STRING
       )
       USING iceberg
   """)
   
   # Insert data into the table
   spark.sql("""
       INSERT INTO `quickstart_catalog`.quickstart_namespace.quickstart_table
       VALUES (1, 'one'), (2, 'two'), (3, 'three')
   """)
   EOF

   Dieses Script startet eine Spark-Sitzung, erstellt einen Namespace namens quickstart_namespace und eine Iceberg-Tabelle namens quickstart_table und fügt drei Zeilen mit Beispieldaten ein. Da in den SQL-Anweisungen kein Bucket-Pfad (LOCATION) angegeben ist, speichert der Lakehouse-Laufzeitkatalog die Namespace- und Tabellendateien automatisch im --default-location-Bucket (gs://${BUCKET_NAME}) Ihres Katalogs.

2. Kopieren Sie quickstart.py in Ihren Cloud Storage-Bucket, damit Managed Service for Apache Spark darauf zugreifen kann:

   gcloud storage cp quickstart.py gs://${BUCKET_NAME}/quickstart.py

PySpark-Script ausführen

Senden Sie Ihr PySpark-Script als Managed Service for Apache Spark-Batchjob, der Ihren Code mit vorinstallierten Iceberg-Bibliotheken ausführt, ohne dass ein Cluster bereitgestellt werden muss.

Mit dem Flag --properties wird Spark so konfiguriert, dass es über den Apache Iceberg REST-Katalogendpunkt eine Verbindung zu Ihrem Katalog im Lakehouse-Laufzeitkatalog herstellt:

1. Senden Sie den Batchjob in Cloud Shell:

   gcloud dataproc batches submit pyspark gs://${BUCKET_NAME}/quickstart.py \
       --project=${PROJECT_ID} \
       --region=${REGION} \
       --version=2.2 \
       --properties="spark.sql.catalog.quickstart_catalog=org.apache.iceberg.spark.SparkCatalog,\
   spark.sql.catalog.quickstart_catalog.type=rest,\
   spark.sql.catalog.quickstart_catalog.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
   spark.sql.catalog.quickstart_catalog.warehouse=bl://projects/${PROJECT_ID}/catalogs/${LAKEHOUSE_CATALOG_ID},\
   spark.sql.catalog.quickstart_catalog.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
   spark.sql.catalog.quickstart_catalog.header.x-goog-user-project=${PROJECT_ID},\
   spark.sql.catalog.quickstart_catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
   spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
   spark.sql.catalog.quickstart_catalog.header.X-Iceberg-Access-Delegation=vended-credentials,\
   spark.sql.catalog.quickstart_catalog.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token"

   Zusätzlich zu den Standard-Iceberg-Einstellungen (SparkCatalog, type=rest und IcebergSparkSessionExtensions) konfigurieren diese Attribute die Verbindung zum Lakehouse-Laufzeitkatalog:

   • uri und warehouse (bl://...): Verbinden Sie Spark mit dem Apache Iceberg REST-Katalogendpunkt des Lakehouse-Laufzeitkatalogs und leiten Sie Anfragen an Ihren Katalog mit mehreren Buckets weiter.
   • rest.auth.type und header.x-goog-user-project: Authentifizieren Sie REST-Anfragen mit den Anmeldedaten des Spark-Dienstkontos und rechnen Sie das API-Kontingent über Ihr Projekt ab.
   • header.X-Iceberg-Access-Delegation, io-impl und gcs.oauth2.refresh-credentials-endpoint: Fordern Sie temporäre, bereitgestellte Cloud Storage-Anmeldedaten vom Katalog an und konfigurieren Sie den GCSFileIO-Client von Iceberg so, dass Datendateien mit diesen Tokens geschrieben werden.

   Weitere Informationen zu diesen Einstellungen finden Sie unter Clientanwendung konfigurieren und in der Dokumentation zur Apache Iceberg Spark-Konfiguration.

   Wenn der Job abgeschlossen ist, sieht die Ausgabe in etwa so aus:

   Batch [cb9d84e9489d408baca4f9e7ab4c64ff] finished.
   metadata:
     '@type': type.googleapis.com/google.cloud.dataproc.v1.BatchOperationMetadata
     batch: projects/PROJECT_ID/locations/us-central1/batches/cb9d84e9489d408baca4f9e7ab4c64ff
     batchUuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9
     createTime: '2026-01-24T00:10:50.224097Z'
     description: Batch
     labels:
       goog-dataproc-batch-id: cb9d84e9489d408baca4f9e7ab4c64ff
       goog-dataproc-batch-uuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9
       goog-dataproc-drz-resource-uuid: batch-54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9
       goog-dataproc-location: us-central1
     operationType: BATCH
     name: projects/PROJECT_ID/regions/us-central1/operations/32287926-5f61-3572-b54a-fbad8940d6ef
   

Tabelle über BigQuery abfragen

Nachdem Spark Ihre Iceberg-Tabelle geschrieben hat, können Sie sie sofort in BigQuery mit der vierteiligen P.C.N.T-Syntax (Project.Catalog.Namespace.Table) abfragen:

1. Führen Sie in Cloud Shell den folgenden bq query-Befehl aus:

   bq query --project_id=${PROJECT_ID} --location=${REGION} --use_legacy_sql=false \
       "SELECT * FROM \`${PROJECT_ID}.${LAKEHOUSE_CATALOG_ID}.quickstart_namespace.quickstart_table\`"

   In der Ausgabe werden die drei Zeilen angezeigt, die Sie mit Ihrem PySpark-Job eingefügt haben:

   +----+-------+
   | id | name  |
   +----+-------+
   |  1 | one   |
   |  2 | two   |
   |  3 | three |
   +----+-------+
   

Da der Lakehouse-Laufzeitkatalog die Iceberg-Metadaten verfolgt und den Speicherzugriff verwaltet, liest BigQuery die zugrunde liegenden Dateien in Cloud Storage, sobald Spark den Snapshot committet.

An dieser Stelle können Sie auch mit einer anderen Iceberg-kompatiblen Engine wie Trino, Flink oder einem selbstverwalteten Spark-Cluster aus quickstart_table lesen oder in quickstart_table schreiben. Da die Bereitstellung von Anmeldedaten für Ihren Katalog aktiviert ist, benötigt eine externe Engine nur die Rolle BigLake-Betrachter (roles/biglake.viewer) für Ihr Projekt, um die Tabelle zu lesen, oder die Rolle BigLake-Editor (roles/biglake.editor), um auch Daten zu schreiben und neue Snapshots zu committen. Informationen zum Verbinden anderer Engines finden Sie unter Apache Iceberg REST-Katalogendpunkt einrichten.

Bereinigen

Löschen Sie die in dieser Kurzanleitung erstellten Ressourcen, um unnötige Kosten für Ihr Google Cloud -Konto zu vermeiden. Durch das Löschen der Tabelle, des Namespace und des Katalogs wird die Metadatenregistrierung aus dem Lakehouse-Laufzeitkatalog entfernt. Durch das Löschen des Buckets werden die zugrunde liegenden Parquet-Daten und Iceberg-Metadatendateien gelöscht, die in Cloud Storage gespeichert sind:

1. Löschen Sie in Cloud Shell die Tabelle aus Ihrem Katalog:

   gcloud biglake iceberg tables delete quickstart_table \
       --project=${PROJECT_ID} \
       --catalog=${LAKEHOUSE_CATALOG_ID} \
       --namespace=quickstart_namespace \
       --quiet

2. Löschen Sie den Namespace aus Ihrem Katalog:

   gcloud biglake iceberg namespaces delete quickstart_namespace \
       --project=${PROJECT_ID} \
       --catalog=${LAKEHOUSE_CATALOG_ID} \
       --quiet

3. Löschen Sie Ihren Katalog:

   gcloud biglake iceberg catalogs delete ${LAKEHOUSE_CATALOG_ID} \
       --project=${PROJECT_ID} --quiet

4. Löschen Sie den Cloud Storage-Bucket und seinen Inhalt:

   gcloud storage rm -r gs://${BUCKET_NAME}

Nächste Schritte

• In der Kurzanleitung Iceberg-Tabelle mit der Google Cloud Console erstellen und abfragen erfahren Sie, wie Sie Namespaces und Iceberg-Tabellen in der Benutzeroberfläche erstellen und Daten mit der BigQuery-Datenbearbeitungssprache (Data Manipulation Language, DML) ändern.
• Probieren Sie das Codelab zum Einrichten des cloudübergreifenden Datenzugriffs aus, um Daten in Amazon Web Services (AWS), AlloyDB for PostgreSQL und Cloud Storage ohne ETL abzufragen.
• Kataloge mit mehreren Buckets und Apache Iceberg REST-Katalogendpunkt
• Kataloge im Lakehouse-Laufzeitkatalog verwalten
• Von Lakehouse verwaltete Apache Iceberg-Tabellen