Crea un lakehouse con Spark e il catalogo di runtime Lakehouse

Un'architettura lakehouse combina la flessibilità di un data lake con le funzionalità di gestione dei dati di un data warehouse. Questo documento mostra come configurare un lakehouse su Google Cloud. Utilizzi Apache Iceberg come formato della tabella, Managed Service for Apache Spark per l'elaborazione e il catalogo di runtime Lakehouse Iceberg REST Catalog per la gestione unificata dei metadati.

Questa architettura utilizza formati di tabella aperti come Iceberg per aggiungere funzionalità di data warehousing, come transazioni ed evoluzione dello schema, ai dati in Cloud Storage. Questo approccio crea una Single Source Of Truth per i tuoi dati a cui possono accedere vari motori.

Questo documento riguarda i cataloghi che crei nel catalogo di runtime Lakehouse. Per eseguire query sulle tabelle Iceberg gestite da AWS Glue Data Catalog, Databricks Unity Catalog o Snowflake Horizon Catalog tramite i cataloghi federati del catalogo di runtime Lakehouse, consulta Esegui query sui cataloghi federati con Spark.

Diagramma che mostra i componenti di un'architettura lakehouse, tra cui Managed Service for Apache Spark, Cloud Storage e il catalogo REST Lakehouse.
Diagramma dell'architettura lakehouse.

Informazioni sul catalogo di runtime Lakehouse

Il catalogo di runtime Lakehouse è un metastore serverless completamente gestito basato sul catalogo di runtime Lakehouse. Archivia i metadati delle tabelle per i formati di tabella aperti come Iceberg ed espone i seguenti endpoint:

  • Endpoint del catalogo REST Iceberg: consente a Spark e ad altri motori di leggere e scrivere tabelle Iceberg tramite il protocollo REST Iceberg standard.
  • Endpoint del catalogo Hive: consente ai Workload Manager Spark e Hive di gestire tabelle Hive e Spark standard, come le tabelle Parquet, ORC, Avro e Delta Lake, senza un Hive Metastore in hosting autonomo.

A partire dalle versioni di immagine e runtime di Managed Service for Apache Spark 4.0, il catalogo di runtime Lakehouse è il catalogo Spark predefinito, quindi puoi creare ed eseguire query sulle tabelle Iceberg senza alcuna configurazione del catalogo.

Vantaggi rispetto al metastore Hive

Per impostazione predefinita, Apache Spark open source archivia i metadati delle tabelle in un metastore Hive che viene eseguito con il cluster, ad esempio un database Apache Derby incorporato o un servizio metastore Hive sul nodo master del cluster. Il catalogo di runtime Lakehouse offre i seguenti vantaggi:

Capacità Metastore Hive Spark Catalogo di runtime Lakehouse
Infrastruttura Viene eseguito sul cluster. Sei tu a dimensionarlo, applicare patch, eseguirne il backup e scalarlo. Serverless e completamente gestita. Nessuna infrastruttura di metastore da gestire.
Durata dei metadati Collegato al cluster. I metadati vengono persi quando elimini un cluster temporaneo e i workload serverless non hanno un metastore permanente. Persiste indipendentemente da cluster, workload batch e sessioni.
Condivisione tra workload Ogni cluster ha il proprio metastore, a meno che tu non configuri e connetta un metastore esterno. I cluster, i workload batch, le sessioni e altri progetti condividono lo stesso catalogo.
Accesso a più motori Spark e Hive. Spark, Hive, BigQuery e qualsiasi motore che supporti il protocollo REST Iceberg.
Formati di tabella Tabelle Hive. Iceberg richiede una configurazione aggiuntiva del catalogo. Tabelle Iceberg tramite l'endpoint del catalogo REST Iceberg e tabelle Hive tramite l'endpoint del catalogo Hive.
Controllo degli accessi Accesso a livello di metastore, spesso gestito separatamente dall'accesso ai dati. Autorizzazioni per tabelle e cataloghi basate su IAM.
Configurazione Proprietà del catalogo manuali in ogni cluster o workload. Attivato per impostazione predefinita per l'immagine e la versione di runtime 4.0 e successive.

Per un elenco dettagliato delle operazioni di Hive Metastore supportate dall'endpoint del catalogo Hive, consulta Confronto delle funzionalità con Hive Metastore.

Prima di iniziare

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that you have the permissions required to complete this guide.

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

  4. Enable the Dataproc, BigLake, BigQuery, and Cloud Storage APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. Crea un bucket Cloud Storage per archiviare i dati Iceberg.
  6. Crea un catalogo nel catalogo di runtime Lakehouse che rimandi al tuo bucket. È consigliato un catalogo con più bucket. Questo passaggio è facoltativo per le versioni di immagini e runtime 4.0 e successive se utilizzi il catalogo iniziale predefinito, che viene creato automaticamente.
  7. (Facoltativo) Per monitorare la provenienza dei dati, abilita l'API Data Lineage (datalineage.googleapis.com).

Ruoli obbligatori

Per eseguire gli esempi in questa pagina sono necessari determinati ruoli IAM (Identity and Access Management). A seconda delle policy dell'organizzazione, questi ruoli potrebbero essere già stati concessi. Per controllare le concessioni dei ruoli, consulta Devi concedere i ruoli?.

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

I ruoli necessari dipendono dal modo in cui viene eseguito il workload. I cluster Managed Service for Apache Spark e i runtime serverless Managed Service for Apache Spark 2.3 e versioni precedenti eseguono i workload come account di servizio. I runtime serverless di Managed Service for Apache Spark 3.0 e versioni successive eseguono i workload con le credenziali dell'utente finale (EUC) per impostazione predefinita, quindi concedi i ruoli di accesso ai dati al tuo account utente anziché a un account di servizio. Se specifichi un service account personalizzato per un runtime 3.0 o successivo, il workload viene eseguito con le credenziali dell'account di servizio. Per saperne di più, consulta Ruoli dei deployment serverless.

Ruoli utente

Per ottenere le autorizzazioni necessarie per creare un cluster Managed Service for Apache Spark, inviare un workload batch o creare una sessione interattiva, chiedi all'amministratore di concederti i seguenti ruoli IAM:

  • Utilizza un cluster o un runtime serverless 2.3 o versioni precedenti:
  • Utilizza un runtime serverless 3.0 o versioni successive: Dataproc Serverless Editor (roles/dataproc.serverlessEditor) sul progetto
  • Utilizza le credenziali dell'account di servizio su un runtime serverless 3.0 o versioni successive: Utente dell'account (roles/iam.serviceAccountUser) sul service account personalizzato

Se utilizzi un runtime serverless di Managed Service for Apache Spark 3.0 o versioni successive con le credenziali dell'utente finale (impostazione predefinita), devi disporre anche dei seguenti ruoli di accesso ai dati:

Per ottenere le autorizzazioni necessarie per leggere e scrivere tabelle nel catalogo con le credenziali dell'utente finale, chiedi all'amministratore di concederti i seguenti ruoli IAM:

  • Leggi e scrivi i dati della tabella in modalità di distribuzione delle credenziali: BigLake Editor (roles/biglake.editor) sul progetto che contiene il catalogo
  • Gestisci le risorse del catalogo e scrivi i dati della tabella in modalità di distribuzione non delle credenziali:
    • BigLake Editor (roles/biglake.editor) sul progetto che contiene il catalogo
    • Storage Object User (roles/storage.objectUser) su tutti i bucket Cloud Storage associati al catalogo

Ruoli del service account

Concedi i seguenti ruoli al account di servizio che esegue il tuo workload. I runtime serverless di Managed Service for Apache Spark 3.0 e versioni successive richiedono questi ruoli solo se il workload viene eseguito con le credenziali del account di servizio.

Per assicurarti che l'account di servizio predefinito di Compute Engine o un account di servizio personalizzato disponga delle autorizzazioni necessarie per eseguire i job di Managed Service for Apache Spark e leggere e scrivere tabelle nel tuo catalogo, chiedi all'amministratore di concedere i seguenti ruoli IAM all'account di servizio predefinito di Compute Engine o a un account di servizio personalizzato:

  • Esegui i job di Managed Service for Apache Spark su un cluster o un runtime serverless 2.3 o versioni precedenti: Dataproc Worker (roles/dataproc.worker) sul progetto
  • Esegui i job Managed Service for Apache Spark su un runtime serverless 3.0 o versioni successive:
  • Leggi e scrivi i dati della tabella in modalità di distribuzione delle credenziali: BigLake Editor (roles/biglake.editor) sul progetto che contiene il catalogo
  • Gestisci le risorse del catalogo e scrivi i dati della tabella in modalità di distribuzione non delle credenziali:
    • BigLake Editor (roles/biglake.editor) sul progetto che contiene il catalogo
    • Storage Object User (roles/storage.objectUser) su tutti i bucket Cloud Storage associati al catalogo

Utilizza il catalogo di runtime Lakehouse

A partire dalla versione dell'immagine e del runtime 4.0, Managed Service for Apache Spark imposta il catalogo di runtime Lakehouse come catalogo Spark predefinito per cluster, workload batch, sessioni interattive e profili di runtime. Non è necessario creare un catalogo o impostare proprietà del catalogo.

Nell'immagine e nella versione di runtime 3.0 e precedenti, puoi attivare il catalogo di runtime Lakehouse predefinito impostando la seguente proprietà:

  • Workload batch, sessioni interattive e profili di runtime: dataproc.lakehouse.defaultCatalog=standard-lh-catalog-REGION
  • Cluster: dataproc:dataproc.lakehouse.defaultCatalog=standard-lh-catalog-REGION

Sostituisci REGION con la regione del workload, ad esempio us-central1.

Managed Service for Apache Spark risolve il catalogo predefinito come segue:

  1. Se imposti dataproc.lakehouse.defaultCatalog (per i cluster, dataproc:dataproc.lakehouse.defaultCatalog), Managed Service for Apache Spark utilizza il tuo valore e non lo modifica.

  2. In caso contrario, per la versione dell'immagine e del runtime 4.0 e successive, Managed Service for Apache Spark imposta dataproc.lakehouse.defaultCatalog sul catalogo iniziale regionale, standard-lh-catalog-REGION, dove REGION è la regione del workload. Se il catalogo iniziale non esiste, Managed Service for Apache Spark lo crea automaticamente nel progetto che esegue il workload. Non sono necessari ruoli IAM aggiuntivi per creare il catalogo iniziale.

  3. Per la versione dell'immagine e del runtime 3.0 e precedenti, Managed Service for Apache Spark non imposta un catalogo predefinito. Per attivare questa opzione, imposta dataproc.lakehouse.defaultCatalog=standard-lh-catalog-REGION esplicitamente, come descritto in precedenza in questa sezione.

Quando il catalogo predefinito è impostato, Spark lo registra con il nome del catalogo default_catalog e le seguenti proprietà risolte:

Proprietà Spark Valore
spark.sql.defaultCatalog default_catalog
spark.sql.catalog.default_catalog org.apache.iceberg.spark.SparkCatalog
spark.sql.catalog.default_catalog.type rest
spark.sql.catalog.default_catalog.warehouse bl://projects/PROJECT_ID/catalogs/CATALOG_ID

Di conseguenza, i nomi delle tabelle non qualificati come my_namespace.my_table vengono risolti in default_catalog.my_namespace.my_table nel catalogo di runtime Lakehouse.

Imposta il catalogo predefinito

Per utilizzare il catalogo di runtime Lakehouse come catalogo predefinito su un'immagine o una versione di runtime precedente o per utilizzare un catalogo diverso da quello iniziale, imposta la proprietà dataproc.lakehouse.defaultCatalog=CATALOG (per i cluster, dataproc:dataproc.lakehouse.defaultCatalog=CATALOG), dove CATALOG è uno dei seguenti:

  • standard-lh-catalog-REGION: il catalogo iniziale regionale nel progetto del workload.
  • projects/PROJECT_ID/catalogs/CATALOG_ID: un catalogo esistente, che può trovarsi in un altro progetto.

Ad esempio, il seguente comando invia un workload batch che utilizza un catalogo esistente come catalogo predefinito:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties=dataproc.lakehouse.defaultCatalog=projects/PROJECT_ID/catalogs/CATALOG_ID

Per configurare il catalogo predefinito nella console Google Cloud , consulta le istruzioni di configurazione del profilo di runtime e del cluster.

Disattiva il catalogo iniziale

Nella versione dell'immagine e del runtime 4.0 e successive, puoi disattivare il catalogo iniziale regionale impostando dataproc.lakehouse.defaultCatalog=CATALOG (per i cluster, dataproc:dataproc.lakehouse.defaultCatalog=CATALOG) sul nome completo della risorsa di un altro catalogo, ad esempio projects/PROJECT_ID/catalogs/CATALOG_ID. Managed Service for Apache Spark utilizza il tuo catalogo anziché quello iniziale e non esegue l'override della proprietà quando la imposti esplicitamente.

Verifica il catalogo predefinito

  1. Controlla le proprietà risolte:

    • Per le sessioni interattive, esegui questo comando:

      gcloud beta dataproc sessions describe SESSION_ID \
          --location=REGION \
          --format="yaml(runtimeConfig.properties)"
      
    • Per i cluster, controlla /etc/spark/conf/spark-defaults.conf sul nodo master.

  2. Nell'applicazione Spark, verifica che il catalogo predefinito sia attivo:

    print(spark.conf.get("spark.sql.defaultCatalog"))  # default_catalog
    

Configura Managed Service for Apache Spark e crea una sessione Spark

Configura un cluster, un workload batch o una sessione interattiva per utilizzare il catalogo REST Iceberg del catalogo di runtime Lakehouse. Tutti e tre supportano la proprietà di configurazione semplificata dataproc.lakehouse.catalog.CATALOG_NAME (consigliata), che consente a Managed Service for Apache Spark di leggere la definizione del catalogo e generare le proprietà Spark del catalogo REST Iceberg. Solo la forma del cluster accetta il prefisso dataproc:.

Sulla versione dell'immagine e del runtime 4.0 e successive, puoi saltare questa configurazione e utilizzare il catalogo di runtime Lakehouse predefinito. Utilizza le seguenti istruzioni per registrare i tuoi cataloghi o per configurare il catalogo di runtime Lakehouse nelle versioni precedenti.

Versioni di runtime e immagini supportate:

Sia la configurazione semplificata che quella manuale utilizzano l'autorizzazione Google per Iceberg (GoogleAuthManager), che richiede una delle seguenti versioni:

  • Cluster Managed Service for Apache Spark: versioni immagine 2.2 2.2.65 e successive, versioni immagine 2.3 2.3.11 e successive o versioni immagine 4.0 e successive.
  • Workload batch serverless e sessioni interattive di Managed Service for Apache Spark: runtime 2.2 2.2.60 e versioni successive, runtime 2.3 2.3.10 e versioni successive o runtime 3.0 e versioni successive.

Nella versione dell'immagine e del runtime 4.0 e successive, il catalogo di runtime Lakehouse è il catalogo predefinito.

Per i workload serverless batch e le sessioni interattive, i ruoli richiesti dipendono dalla versione di runtime. I runtime 3.0 e versioni successive utilizzano le credenziali dell'utente finale per impostazione predefinita. Per maggiori dettagli, consulta Ruoli richiesti.

Cluster

Crea un cluster Managed Service for Apache Spark con i componenti facoltativi Iceberg e Jupyter utilizzando le proprietà di configurazione semplificate (consigliato) o specificando manualmente le proprietà del catalogo nel notebook.

Configurazione semplificata tramite le proprietà (consigliata)

Crea il cluster con la proprietà del catalogo:

gcloud dataproc clusters create CLUSTER_NAME \
  --project=PROJECT_ID \
  --region=REGION \
  --image-version=IMAGE_VERSION \
  --optional-components=ICEBERG,JUPYTER \
  --enable-component-gateway \
  --properties='dataproc:dataproc.lineage.enabled=true,dataproc:dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID,spark:spark.sql.defaultCatalog=CATALOG_NAME'

Sostituisci quanto segue:

  • CLUSTER_NAME: un nome per il tuo cluster.
  • PROJECT_ID: il tuo ID progettoGoogle Cloud .
  • REGION: la regione Google Cloud del cluster, ad esempio us-central1.
  • IMAGE_VERSION: la versione immagine di Managed Service for Apache Spark, ad esempio 2.3-debian12. Consulta Versioni di immagini e runtime supportate.
  • CATALOG_NAME: un nome per il catalogo Spark locale, ad esempio iceberg_catalog. Può essere uguale a CATALOG_ID.
  • CATALOG_ID: l'ID del catalogo che hai creato in Prima di iniziare.

La proprietà dataproc:dataproc.lineage.enabled=true non è obbligatoria per il corretto funzionamento del catalogo REST Iceberg del catalogo di runtime di Lakehouse. Viene aggiunto per il monitoraggio della derivazione nell'esempio di derivazione dei dati.

Connettiti al cluster utilizzando un notebook Jupyter (un notebook Vertex AI Workbench o un notebook avviato sul cluster) e crea SparkSession senza specificare le configurazioni del catalogo:

from pyspark.sql import SparkSession

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

Sostituisci APP_NAME con il nome della tua applicazione Spark.

Configurazione manuale

Se non utilizzi la proprietà di configurazione semplificata, crea il cluster come descritto in precedenza senza dataproc:dataproc.lakehouse.catalog. nel flag --properties, connettiti a un blocco note Jupyter e configura SparkSession manualmente, come segue:

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

catalog_name = "CATALOG_NAME"

spark = SparkSession.builder.appName("APP_NAME") \
.config('spark.sql.defaultCatalog', catalog_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('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
.getOrCreate()

Sostituisci quanto segue:

  • CATALOG_NAME: un nome per il catalogo Spark locale, ad esempio iceberg_catalog.
  • APP_NAME: il nome della tua applicazione Spark.
  • WAREHOUSE_PATH: il percorso del tuo data warehouse. Per i cataloghi con più bucket (consigliato), utilizza bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Per i cataloghi con un singolo bucket, utilizza gs://CLOUD_STORAGE_BUCKET_NAME.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
Configura con la distribuzione delle credenziali

Per utilizzare la distribuzione delle credenziali, devi utilizzare un catalogo in modalità di distribuzione delle credenziali e aggiungere l'intestazione X-Iceberg-Access-Delegation alle richieste del catalogo REST Iceberg con un valore vended-credentials aggiungendo la riga seguente al builder SparkSession:

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

L'esempio seguente configura SparkSession con la distribuzione delle credenziali:

from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"

spark = SparkSession.builder.appName("APP_NAME") \
.config('spark.sql.defaultCatalog', catalog_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}.header.X-Iceberg-Access-Delegation', 'vended-credentials') \
.config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
.getOrCreate()

La configurazione semplificata aggiunge questa intestazione quando il catalogo utilizza la modalità di distribuzione delle credenziali. Per saperne di più, consulta la sezione Intestazioni in RESTCatalog della documentazione di Iceberg.

Configurazione della console

Per configurare il catalogo di runtime di Lakehouse quando crei un cluster nella consoleGoogle Cloud , completa i seguenti passaggi:

  1. Nella console Google Cloud , vai alla pagina Cluster di Managed Service for Apache Spark.

    Vai a Cluster

  2. Fai clic su Crea cluster, quindi su Crea nella riga Cluster su Compute Engine.

  3. Nel passaggio di configurazione del metastore, in Seleziona metastore e progetto, seleziona Catalogo di runtime Lakehouse.

  4. Configura l'ID progetto, il catalogo Endpoint REST Iceberg e il catalogo Endpoint Hive facoltativo, come descritto nella scheda Profilo di runtime.

  5. Completa le restanti impostazioni del cluster, quindi fai clic su Crea.

Serverless

Invia un workload batch PySpark a Managed Service for Apache Spark serverless utilizzando le proprietà di configurazione semplificate (consigliato) o specificando manualmente le proprietà del catalogo.

Configurazione semplificata tramite le proprietà (consigliata)

Passa la proprietà dataproc.lakehouse.catalog.CATALOG_NAME (senza il prefisso dataproc:) quando invii il workload batch:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
  --project=PROJECT_ID \
  --region=REGION \
  --version=RUNTIME_VERSION \
  --properties="spark.dataproc.lineage.enabled=true,dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID,spark.sql.defaultCatalog=CATALOG_NAME"

Sostituisci quanto segue:

  • PYSPARK_FILE: il percorso Cloud Storage gs:// del file dell'applicazione PySpark.
  • PROJECT_ID: il tuo ID progettoGoogle Cloud .
  • REGION: la regione del workload batch.
  • RUNTIME_VERSION: la versione del runtime serverless di Managed Service for Apache Spark, ad esempio 3.0. I ruoli richiesti dipendono dalla versione del runtime (consulta Versioni di immagini e runtime supportate).
  • CATALOG_NAME: un nome per il catalogo Spark locale, ad esempio iceberg_catalog. Può essere uguale a CATALOG_ID.
  • CATALOG_ID: l'ID del catalogo che hai creato in Prima di iniziare.

Nel file dell'applicazione PySpark, crea SparkSession senza specificare le configurazioni del catalogo:

from pyspark.sql import SparkSession

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

Configurazione manuale

Se non utilizzi la proprietà di configurazione semplificata, specifica le proprietà del catalogo nel flag --properties quando invii il workload batch:

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.header.x-goog-user-project=PROJECT_ID,\
spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

Sostituisci WAREHOUSE_PATH con il percorso del tuo warehouse. Per i cataloghi con più bucket (consigliato), utilizza bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Per i cataloghi con un singolo bucket, utilizza gs://CLOUD_STORAGE_BUCKET_NAME.

Configura con la distribuzione delle credenziali

Per utilizzare la distribuzione delle credenziali, devi utilizzare un catalogo in modalità di distribuzione delle credenziali e aggiungere l'intestazione X-Iceberg-Access-Delegation alle richieste del catalogo REST Iceberg con un valore vended-credentials aggiungendo la seguente proprietà al flag --properties:

spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials

L'esempio seguente invia un workload batch con distribuzione delle credenziali:

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.header.x-goog-user-project=PROJECT_ID,\
spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials,\
spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

La configurazione semplificata aggiunge questa intestazione quando il catalogo utilizza la modalità di distribuzione delle credenziali. Per saperne di più, consulta la sezione Intestazioni in RESTCatalog della documentazione di Iceberg.

Serverless

Crea una sessione interattiva serverless di Managed Service for Apache Spark da un notebook con l'API ManagedSparkSession, utilizzando proprietà di configurazione semplificate (consigliato) o specificando manualmente le proprietà del catalogo.

Configurazione semplificata tramite le proprietà (consigliata)

In un notebook in cui è installato il pacchetto google-cloud-spark-connect, ad esempio un notebook Google Cloud Data Agent Kit o un notebook Vertex AI Workbench, passa la proprietà dataproc.lakehouse.catalog.CATALOG_NAME (senza il prefisso dataproc:) quando crei la sessione:

from google.cloud.managed_spark_connect import ManagedSparkSession
from google.cloud.dataproc_v1 import Session

catalog_name = "CATALOG_NAME"

session_config = Session()
session_config.runtime_config.version = 'RUNTIME_VERSION'
session_config.runtime_config.properties["spark.dataproc.lineage.enabled"] = "true"

spark = ManagedSparkSession.builder.sessionId("SESSION_ID") \
  .sessionConfig(session_config) \
  .config(f'dataproc.lakehouse.catalog.{catalog_name}', 'projects/PROJECT_ID/catalogs/CATALOG_ID') \
  .config('spark.sql.defaultCatalog', catalog_name) \
  .getOrCreate()

Sostituisci quanto segue:

  • CATALOG_NAME: un nome per il catalogo Spark locale, ad esempio iceberg_catalog. Può essere uguale a CATALOG_ID.
  • RUNTIME_VERSION: la versione del runtime serverless di Managed Service for Apache Spark. google-cloud-spark-connect richiede il runtime 3.0 o versioni successive. I ruoli richiesti dipendono dalla versione di runtime (consulta Versioni di immagini e runtime supportate).
  • SESSION_ID: un ID personalizzato per la tua sessione Spark, ad esempio my-spark-session.
  • PROJECT_ID: il tuo ID progettoGoogle Cloud .
  • CATALOG_ID: l'ID del catalogo che hai creato in Prima di iniziare.

Puoi anche configurare un catalogo Lakehouse in un profilo di runtime. Per saperne di più, consulta la scheda Profilo di runtime.

Configurazione manuale

Se non utilizzi la proprietà di configurazione semplificata, specifica le proprietà del catalogo quando crei la sessione:

from google.cloud.managed_spark_connect import ManagedSparkSession
from google.cloud.dataproc_v1 import Session

catalog_name = "CATALOG_NAME"

session_config = Session()
session_config.runtime_config.version = 'RUNTIME_VERSION'
session_config.runtime_config.properties["spark.dataproc.lineage.enabled"] = "true"

spark = ManagedSparkSession.builder.sessionId("SESSION_ID") \
.sessionConfig(session_config) \
.config('spark.sql.defaultCatalog', catalog_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('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
.getOrCreate()

Sostituisci RUNTIME_VERSION come descritto nell'esempio di configurazione semplificata riportato in precedenza in questa scheda.

Sostituisci WAREHOUSE_PATH con il percorso del tuo warehouse. Per i cataloghi con più bucket (consigliato), utilizza bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Per i cataloghi con un singolo bucket, utilizza gs://CLOUD_STORAGE_BUCKET_NAME.

Configura con la distribuzione delle credenziali

Per utilizzare la distribuzione delle credenziali, devi utilizzare un catalogo in modalità di distribuzione delle credenziali e aggiungere l'intestazione X-Iceberg-Access-Delegation alle richieste del catalogo REST Iceberg con un valore vended-credentials aggiungendo la riga seguente al generatore di sessioni:

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

L'esempio seguente crea una sessione con distribuzione delle credenziali:

from google.cloud.managed_spark_connect import ManagedSparkSession
from google.cloud.dataproc_v1 import Session

catalog_name = "CATALOG_NAME"

session_config = Session()
session_config.runtime_config.version = 'RUNTIME_VERSION'
session_config.runtime_config.properties["spark.dataproc.lineage.enabled"] = "true"

spark = ManagedSparkSession.builder.sessionId("SESSION_ID") \
.sessionConfig(session_config) \
.config('spark.sql.defaultCatalog', catalog_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}.header.X-Iceberg-Access-Delegation', 'vended-credentials') \
.config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
.getOrCreate()

La configurazione semplificata aggiunge questa intestazione quando il catalogo utilizza la modalità di distribuzione delle credenziali. Per saperne di più, consulta la sezione Intestazioni in RESTCatalog della documentazione di Iceberg.

Serverless

Un profilo di runtime, chiamato modello di sessione in gcloud CLI e nell'API Dataproc, memorizza impostazioni serverless riutilizzabili, incluso il metastore. Le sessioni interattive create dal profilo di runtime utilizzano la configurazione del catalogo.

Configurazione della console

  1. Nella console Google Cloud , vai alla pagina Profili di runtime serverless.

    Vai a Profili di runtime serverless

  2. Fai clic su Crea o sul nome di un profilo di runtime esistente, quindi su Modifica.

  3. Espandi Configurazione aggiuntiva, quindi fai clic su Modifica accanto a Configurazione metastore.

  4. Seleziona Catalogo di runtime Lakehouse. Questa è la selezione predefinita.

  5. Configura il catalogo:

    • ID progetto: il progetto che contiene il catalogo. Il valore predefinito è il progetto corrente.
    • Endpoint REST Iceberg: selezionato per impostazione predefinita. Scegli una delle seguenti opzioni:
      • Definisci un nuovo catalogo per utilizzare il catalogo iniziale regionale, standard-lh-catalog-REGION.
      • Scegli un ID catalogo esistente.
    • (Facoltativo) Endpoint Hive: seleziona questa casella di controllo e specifica l'ID progetto, l'ID catalogo e il Nome catalogo di un catalogo Hive.
  6. Fai clic su Salva, quindi su Crea o Salva.

Configurazione gcloud

  1. Crea un file YAML che imposti il catalogo predefinito in runtimeConfig.properties:

    runtimeConfig:
    version: "RUNTIME_VERSION"
    properties:
      dataproc.lakehouse.defaultCatalog: projects/PROJECT_ID/catalogs/CATALOG_ID
      spark.dataproc.lineage.enabled: "true"
    sparkConnectSession: {}

    Nella versione runtime 4.0 e successive, puoi omettere dataproc.lakehouse.defaultCatalog per utilizzare il catalogo iniziale regionale.

  2. Importa il file per creare o aggiornare il profilo di runtime:

    gcloud beta dataproc session-templates import RUNTIME_PROFILE_ID \
      --location=REGION \
      --source=FILE_NAME.yaml
    

Sostituisci quanto segue:

  • RUNTIME_VERSION: la versione del runtime serverless di Managed Service for Apache Spark, ad esempio 4.0.
  • PROJECT_ID: il progetto che contiene il catalogo.
  • CATALOG_ID: l'ID del catalogo.
  • RUNTIME_PROFILE_ID: l'ID del profilo di runtime.
  • REGION: la regione del profilo di runtime.
  • FILE_NAME: il nome del file YAML.

Gestisci i dati con Spark SQL

Dopo aver configurato la sessione Spark, utilizza Spark SQL per eseguire operazioni di gestione dei dati.

Impostazione del catalogo: la proprietà dataproc.lakehouse.catalog. registra il catalogo con Spark, ma non lo rende il catalogo predefinito. Gli esempi nella sezione precedente impostano spark.sql.defaultCatalog (spark:spark.sql.defaultCatalog su un cluster) in modo da poter utilizzare nomi di tabelle non qualificati. Se ometti questa proprietà, qualifica i nomi delle tabelle con il nome del catalogo, ad esempio CATALOG_NAME.NAMESPACE_NAME.base_table. Nella versione dell'immagine e del runtime 4.0 e successive, se non imposti dataproc.lakehouse.defaultCatalog, i nomi delle tabelle non qualificati vengono risolti nel catalogo di runtime Lakehouse predefinito (default_catalog).

  1. Crea uno spazio dei nomi. Nel catalogo REST Iceberg del catalogo di runtime Lakehouse, uno spazio dei nomi corrisponde a un set di dati BigQuery.

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

    Sostituisci NAMESPACE_NAME con il nome del tuo namespace, ad esempio spark_lakehouse.

  2. Crea una tabella di base in formato Iceberg e inserisci i dati.

    spark.sql("DROP TABLE IF EXISTS base_table PURGE")
    spark.sql("CREATE TABLE base_table (id LONG) USING iceberg")
    spark.sql("INSERT INTO base_table VALUES 0, 1, 2, 3, 4")
    spark.sql("SELECT * FROM base_table").show()
    

    L'output è simile al seguente:

       +---+
       | id|
       +---+
       |  0|
       |  1|
       |  2|
       |  3|
       |  4|
       +---+
    
  3. Crea un'altra tabella per i nuovi dati.

    spark.sql("DROP TABLE IF EXISTS newdata PURGE")
    spark.sql("CREATE TABLE newdata(id LONG) USING iceberg")
    spark.sql("INSERT INTO newdata VALUES 3, 4, 5, 6")
    spark.sql("SELECT * FROM newdata").show()
    

    L'output è simile al seguente:

       +---+
       | id|
       +---+
       |  3|
       |  4|
       |  5|
       |  6|
       +---+
    
  4. Unisci i nuovi dati nella tabella di base.

    spark.sql("""MERGE INTO base_table USING newdata
               ON base_table.id = newdata.id
               WHEN MATCHED THEN
                 UPDATE SET base_table.id = newdata.id
               WHEN NOT MATCHED THEN INSERT * """)
    spark.sql("SELECT * FROM base_table").show()
    

    L'output è simile al seguente:

       +---+
       | id|
       +---+
       |  0|
       |  1|
       |  2|
       |  3|
       |  4|
       |  5|
       |  6|
       +---+
    
  5. Aggiorna i record nella tabella di base.

    spark.sql(
         "UPDATE base_table SET id = (id + 100) WHERE (id % 2 == 0)"
     )
    spark.sql("SELECT * FROM base_table").show()
    

    L'output è simile al seguente:

       +---+
       | id|
       +---+
       |  3|
       |104|
       |  5|
       |106|
       |100|
       |102|
       |  1|
       +---+
    
  6. Eliminare i record dalla tabella di base.

    spark.sql("DELETE FROM base_table WHERE (id % 2 == 0)")
    spark.sql("SELECT * FROM base_table").show()
    

    L'output è simile al seguente:

       +---+
       | id|
       +---+
       |  3|
       |  5|
       |  1|
       +---+
    

Esegui una query su uno snapshot storico

Recupera una versione precedente di una tabella eseguendo una query su un ID snapshot. Questa operazione è nota anche come viaggio nel tempo.

  1. Recupera l'ID snapshot della versione della tabella prima delle operazioni MERGE, UPDATE e DELETE.

    snapshot_ids = spark.sql(
         "SELECT snapshot_id FROM `NAMESPACE_NAME`.`base_table`.snapshots"
    ).collect()
    oldest_snapshot_id = snapshot_ids[1]["snapshot_id"]
    

    Sostituisci NAMESPACE_NAME con lo spazio dei nomi che hai creato.

  2. Esegui una query sulla tabella utilizzando l'ID snapshot recuperato.

    df = (
         spark.read.format("iceberg")
         .option("versionAsOf", oldest_snapshot_id)
         .load("base_table")
     )
    df.show()
    

    L'output mostra lo stato della tabella dopo l'operazione MERGE, ma prima delle operazioni UPDATE o DELETE.

       +---+
       | id|
       +---+
       |  0|
       |  1|
       |  2|
       |  3|
       |  4|
       |  5|
       |  6|
       +---+
    

Scopri la derivazione dei dati

Utilizzando Managed Service for Apache Spark 2.2 e versioni successive di immagini e runtime, puoi acquisire il movimento dei dati a livello di tabella e di colonna per le tabelle del catalogo REST Iceberg del catalogo di runtime Lakehouse e visualizzare i risultati nella derivazione dei dati di Knowledge Catalog.

Abilita l'acquisizione della derivazione per i workload Lakehouse

Per emettere eventi OpenLineage da Managed Service for Apache Spark all'API Data Lineage, verifica la seguente configurazione:

  1. Abilita l'API Data Lineage: assicurati che datalineage.googleapis.com sia abilitata nel tuo progetto.
  2. Verifica le autorizzazioni IAM: verifica che il account di servizio del workload o l'identità del nodo disponga di un ruolo che concede datalineage.events.create, ad esempio roles/dataproc.worker o roles/datalineage.producer (vedi Ruoli richiesti).
  3. Abilita il listener di derivazione Spark:
  4. Utilizza un runtime supportato per la derivazione a livello di colonna: la derivazione a livello di colonna richiede l'integrazione di OpenLineage Spark 1.34 o versioni successive. Consulta le versioni minime supportate di immagini e runtime.

Esempio di derivazione dei dati

  1. Esegui il seguente codice PySpark con la derivazione abilitata per creare tabelle Iceberg di origine e di destinazione e copiare i dati tra di loro:

    spark.sql("DROP TABLE IF EXISTS source_table PURGE")
    spark.sql("DROP TABLE IF EXISTS target_table PURGE")
    spark.sql("CREATE TABLE source_table (id LONG) USING iceberg")
    spark.sql("""CREATE TABLE target_table
      USING ICEBERG
      AS SELECT max(id) as top_id FROM source_table
      """)
    
  2. Nella console Google Cloud , vai alla pagina Knowledge Catalog Ricerca.

    Vai a Cerca

  3. Cerca target_table (o source_table), quindi fai clic sulla scheda Derivazione:

    Esempio di derivazione dei dati nella pagina Knowledge Catalog della console Google Cloud .
    Esempio di grafico della derivazione dei dati nella pagina Knowledge Catalog della console Google Cloud .

La modalità di visualizzazione delle tabelle nel grafico di derivazione dipende dal tipo di data warehouse del catalogo:

  • Cataloghi con più bucket (bl://): Knowledge Catalog registra i nodi delle tabelle logiche utilizzando il formato del nome completo biglake:table:{projectId}.{catalogId}.{namespaceId}.{tableId}.
  • Cataloghi con un singolo bucket (gs://): Knowledge Catalog riconosce sia l'entità logica biglake:table: sia la posizione fisica di Cloud Storage (gcs:{bucket}.{path}) quando OpenLineage genera i metadati del catalogo gcp_project_id; in caso contrario, registra i nodi fisici di Cloud Storage.

Per informazioni dettagliate sulla risoluzione dei facet e sull'esecuzione di query sui link biglake:table: in modo programmatico, consulta Mappatura di OpenLineage e Visualizza la derivazione dei dati.

Problemi noti relativi alla derivazione dei dati

In alcuni cluster Managed Service for Apache Spark, la derivazione dei dati completa potrebbe non essere generata a causa di un problema della libreria OpenLineage. Si tratta di una limitazione nota. Se influisce sui tuoi workload, contatta l'assistenza Google Cloud.

Passaggi successivi