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.
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
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that you have the permissions required to complete this guide.
-
Verify that billing is enabled for your Google Cloud project.
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.enablepermission. 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.- Crea un bucket Cloud Storage per archiviare i dati Iceberg.
- 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.0e successive se utilizzi il catalogo iniziale predefinito, che viene creato automaticamente. - (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:
- Dataproc Editor (
roles/dataproc.editor) sul progetto - Utente dell'account di servizio (
roles/iam.serviceAccountUser) nel service account predefinito di Compute Engine o in un service account personalizzato
- Dataproc Editor (
-
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
- BigLake Editor (
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:
- Dataproc Serverless Node (
roles/dataproc.serverlessNode) sul progetto - Dataproc Resource Manager Node Service Agent (
roles/dataprocrm.nodeServiceAgent) sul progetto
- Dataproc Serverless Node (
-
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
- BigLake Editor (
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:
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.In caso contrario, per la versione dell'immagine e del runtime
4.0e successive, Managed Service for Apache Spark impostadataproc.lakehouse.defaultCatalogsul catalogo iniziale regionale,standard-lh-catalog-REGION, doveREGIONè 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.Per la versione dell'immagine e del runtime
3.0e precedenti, Managed Service for Apache Spark non imposta un catalogo predefinito. Per attivare questa opzione, impostadataproc.lakehouse.defaultCatalog=standard-lh-catalog-REGIONesplicitamente, 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
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.confsul nodo master.
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.22.2.65e successive, versioni immagine2.32.3.11e successive o versioni immagine4.0e successive. - Workload batch serverless e sessioni interattive di Managed Service for Apache Spark: runtime
2.22.2.60e versioni successive, runtime2.32.3.10e versioni successive o runtime3.0e 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 esempious-central1.IMAGE_VERSION: la versione immagine di Managed Service for Apache Spark, ad esempio2.3-debian12. Consulta Versioni di immagini e runtime supportate.CATALOG_NAME: un nome per il catalogo Spark locale, ad esempioiceberg_catalog. Può essere uguale aCATALOG_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 esempioiceberg_catalog.APP_NAME: il nome della tua applicazione Spark.WAREHOUSE_PATH: il percorso del tuo data warehouse. Per i cataloghi con più bucket (consigliato), utilizzabl://projects/PROJECT_ID/catalogs/CATALOG_ID. Per i cataloghi con un singolo bucket, utilizzags://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:
Nella console Google Cloud , vai alla pagina Cluster di Managed Service for Apache Spark.
Fai clic su Crea cluster, quindi su Crea nella riga Cluster su Compute Engine.
Nel passaggio di configurazione del metastore, in Seleziona metastore e progetto, seleziona Catalogo di runtime Lakehouse.
Configura l'ID progetto, il catalogo Endpoint REST Iceberg e il catalogo Endpoint Hive facoltativo, come descritto nella scheda Profilo di runtime.
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 Storagegs://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 esempio3.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 esempioiceberg_catalog. Può essere uguale aCATALOG_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 esempioiceberg_catalog. Può essere uguale aCATALOG_ID.RUNTIME_VERSION: la versione del runtime serverless di Managed Service for Apache Spark.google-cloud-spark-connectrichiede il runtime3.0o 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 esempiomy-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
Nella console Google Cloud , vai alla pagina Profili di runtime serverless.
Fai clic su Crea o sul nome di un profilo di runtime esistente, quindi su Modifica.
Espandi Configurazione aggiuntiva, quindi fai clic su Modifica accanto a Configurazione metastore.
Seleziona Catalogo di runtime Lakehouse. Questa è la selezione predefinita.
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.
- Definisci un nuovo catalogo per utilizzare il catalogo iniziale regionale,
- (Facoltativo) Endpoint Hive: seleziona questa casella di controllo e specifica l'ID progetto, l'ID catalogo e il Nome catalogo di un catalogo Hive.
Fai clic su Salva, quindi su Crea o Salva.
Configurazione gcloud
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.0e successive, puoi ometteredataproc.lakehouse.defaultCatalogper utilizzare il catalogo iniziale regionale.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 esempio4.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).
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_NAMEcon il nome del tuo namespace, ad esempiospark_lakehouse.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| +---+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| +---+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| +---+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| +---+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.
Recupera l'ID snapshot della versione della tabella prima delle operazioni
MERGE,UPDATEeDELETE.snapshot_ids = spark.sql( "SELECT snapshot_id FROM `NAMESPACE_NAME`.`base_table`.snapshots" ).collect() oldest_snapshot_id = snapshot_ids[1]["snapshot_id"]Sostituisci
NAMESPACE_NAMEcon lo spazio dei nomi che hai creato.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 operazioniUPDATEoDELETE.+---+ | 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:
- Abilita l'API Data Lineage: assicurati che
datalineage.googleapis.comsia abilitata nel tuo progetto. - 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 esempioroles/dataproc.workeroroles/datalineage.producer(vedi Ruoli richiesti). - Abilita il listener di derivazione Spark:
- Cluster: passa
--properties='dataproc:dataproc.lineage.enabled=true'quando crei il cluster o impostaDATAPROC_LINEAGE_ENABLED=truenei metadati del progetto (consulta Utilizza la derivazione dei dati di Spark sui cluster). - Workload batch serverless, sessioni interattive e profili di runtime: imposta
spark.dataproc.lineage.enabled=truenelle proprietà di configurazione del runtime (consulta Utilizza la derivazione dei dati con i workload serverless). Le impostazioni dei metadati del progetto (DATAPROC_LINEAGE_ENABLED) non si applicano ai runtime serverless3.0e versioni successive, quindi imposta la proprietà Spark in modo esplicito (consulta Abilita la derivazione dei dati a livello di progetto).
- Cluster: passa
- Utilizza un runtime supportato per la derivazione a livello di colonna: la derivazione a livello di colonna richiede l'integrazione di OpenLineage Spark
1.34o versioni successive. Consulta le versioni minime supportate di immagini e runtime.
Esempio di derivazione dei dati
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 """)Nella console Google Cloud , vai alla pagina Knowledge Catalog Ricerca.
Cerca
target_table(osource_table), quindi fai clic sulla scheda Derivazione:
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 completobiglake:table:{projectId}.{catalogId}.{namespaceId}.{tableId}. - Cataloghi con un singolo bucket (
gs://): Knowledge Catalog riconosce sia l'entità logicabiglake:table:sia la posizione fisica di Cloud Storage (gcs:{bucket}.{path}) quando OpenLineage genera i metadati del catalogogcp_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
- Scopri di più sul catalogo REST Iceberg del catalogo di runtime Lakehouse.
- Esegui query sui cataloghi federati con Spark.
- Esplora le funzionalità di Apache Iceberg.
- Scopri come eseguire query sui dati Iceberg dal catalogo di runtime Lakehouse.
- Scopri di più sulla provenienza dei dati e su Managed Service for Apache Spark.