A partire dal 20 aprile 2026, BigLake si chiama ora Lakehouse. Il metastore BigLake ora si chiama catalogo runtime Lakehouse. Le API, le librerie client, i comandi CLI e i nomi IAM di Lakehouse rimangono invariati e fanno ancora riferimento a BigLake.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Configura il catalogo del runtime Lakehouse per Managed Service for Apache Spark utilizzando Apache Iceberg 1.9

Il catalogo Apache Iceberg personalizzato per BigQuery ti consente di connettere i motori Apache Spark e Apache Flink utilizzando Apache Iceberg 1.9 e versioni precedenti al catalogo di runtime Lakehouse. In Lakehouse senza confini, questa integrazione fornisce un singolo livello di metadati condiviso per gestire i formati di tabelle aperte tra i cluster Managed Service for Apache Spark e Managed Service for Apache Spark serverless.

Prima di iniziare

Abilita la fatturazione per il tuo progetto Google Cloud . Scopri come verificare se la fatturazione è abilitata per un progetto.
Abilita le API BigQuery e Dataproc.

Abilita le API
Scopri come funziona il catalogo di runtime Lakehouse.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare il catalogo di runtime di Lakehouse, chiedi all'amministratore di concederti i seguenti ruoli IAM:

Crea un cluster Managed Service for Apache Spark: Dataproc Worker (roles/dataproc.worker) sul account di servizio predefinito di Compute Engine nel progetto
Crea tabelle del catalogo di runtime Lakehouse:
- Dataproc Worker (roles/dataproc.worker) sul account di servizio VM di Managed Service for Apache Spark nel progetto
- Editor dati BigQuery (roles/bigquery.dataEditor) per l'account di servizio VM di Managed Service for Apache Spark nel progetto
- Storage Object User (roles/storage.objectUser) sul account di servizio della VM Managed Service for Apache Spark nel progetto
Esegui query sulle tabelle del catalogo di runtime Lakehouse:
- BigQuery Data Viewer (roles/bigquery.dataViewer) sul progetto
- Utente BigQuery (roles/bigquery.user) sul progetto
- Storage Object Viewer (roles/storage.objectViewer) sul progetto

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

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Configura il catalogo di runtime di Lakehouse con i cluster Managed Service for Apache Spark

Puoi configurare il catalogo di runtime di Lakehouse con i cluster Managed Service for Apache Spark utilizzando Apache Spark o Apache Flink:

Apache Spark

Configura un nuovo cluster. Per creare un nuovo cluster, esegui il seguente comando gcloud dataproc clusters create, che contiene le impostazioni necessarie per utilizzare il catalogo di runtime di Lakehouse:
```
gcloud dataproc clusters create CLUSTER_NAME \
    --project=PROJECT_ID \
    --region=LOCATION \
    --single-node
```
Sostituisci quanto segue:
- CLUSTER_NAME: un nome per il cluster.
- PROJECT_ID: l'ID del progetto Google Cloud in cui stai creando il cluster.
- LOCATION: la regione di Compute Engine in cui stai creando il cluster.
Invia un job Apache Spark utilizzando uno dei seguenti metodi:
Google Cloud CLI
gcloud dataproc jobs submit spark-sql \ --project=PROJECT_ID \ --cluster=CLUSTER_NAME \ --region=REGION \ --jars=https://storage-download.googleapis.com/maven-central/maven2/org/apache/iceberg/iceberg-spark-runtime-3.5_2.12/1.6.1/iceberg-spark-runtime-3.5_2.12-1.6.1.jar,BIGLAKE_ICEBERG_CATALOG_JAR \ --properties=spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\ spark.sql.catalog.CATALOG_NAME.catalog-impl=org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog,\ spark.sql.catalog.CATALOG_NAME.gcp_project=PROJECT_ID,\ spark.sql.catalog.CATALOG_NAME.gcp_location=LOCATION,\ spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_DIRECTORY \ --execute="SPARK_SQL_COMMAND"
Sostituisci quanto segue:
- PROJECT_ID: l'ID del progetto Google Cloud che contiene il cluster.
- CLUSTER_NAME: il nome del cluster che utilizzi per eseguire il job Apache Spark SQL.
- REGION: la regione di Compute Engine in cui si trova il cluster.
- BIGLAKE_ICEBERG_CATALOG_JAR: l'URI Cloud Storage del plug-in del catalogo personalizzato Apache Iceberg da utilizzare. A seconda del numero di versione di Apache Iceberg, seleziona una delle seguenti opzioni:
  
  Apache Iceberg 1.9.1: gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.9.1-1.0.1.jar
  
  Apache Iceberg 1.6.1: gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.6.1-1.0.2.jar
- LOCATION: la località delle risorse BigQuery.
- CATALOG_NAME: il nome del catalogo Apache Spark da utilizzare con il job SQL.
- WAREHOUSE_DIRECTORY: la cartella Cloud Storage che contiene il tuo data warehouse. Questo valore inizia con gs://.
- SPARK_SQL_COMMAND: la query SQL Apache Spark che vuoi eseguire. Questa query include i comandi per creare le risorse. Ad esempio, per creare uno spazio dei nomi e una tabella.
Interfaccia a riga di comando spark-sql
1. Nella console Google Cloud , vai alla pagina Istanze VM.
  
  Vai a Istanze VM
2. Per connetterti a un'istanza VM del cluster, fai clic su SSH nella riga che elenca il nome dell'istanza VM principale del cluster, ovvero il nome del cluster seguito da un suffisso -m. L'output è simile al seguente:
  
  Connected, host fingerprint: ssh-rsa ... Linux cluster-1-m 3.16.0-0.bpo.4-amd64 ... ... example-cluster@cluster-1-m:~$
3. Nel terminale, esegui questo comando di inizializzazione per il catalogo di runtime di Lakehouse:
  
  spark-sql \ --jars https://storage-download.googleapis.com/maven-central/maven2/org/apache/iceberg/iceberg-spark-runtime-3.5_2.12/1.6.1/iceberg-spark-runtime-3.5_2.12-1.6.1.jar,BIGLAKE_ICEBERG_CATALOG_JAR \ --conf spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog \ --conf spark.sql.catalog.CATALOG_NAME.catalog-impl=org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog \ --conf spark.sql.catalog.CATALOG_NAME.gcp_project=PROJECT_ID \ --conf spark.sql.catalog.CATALOG_NAME.gcp_location=LOCATION \ --conf spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_DIRECTORY
Sostituisci quanto segue:
- BIGLAKE_ICEBERG_CATALOG_JAR: l'URI Cloud Storage del plug-in del catalogo personalizzato Apache Iceberg da utilizzare. A seconda del numero di versione di Apache Iceberg, seleziona una delle seguenti opzioni:
  
  Apache Iceberg 1.9.1: gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.9.1-1.0.1.jar
  
  Apache Iceberg 1.6.1: gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.6.1-1.0.2.jar
- CATALOG_NAME: il nome del catalogo Apache Spark che utilizzi con il job SQL.
- PROJECT_ID: l'ID progetto Google Cloud per il catalogo di runtime Lakehouse a cui è collegato il catalogo Apache Spark.
- LOCATION: la località Google Cloud per il catalogo di runtime Lakehouse.
- WAREHOUSE_DIRECTORY: la cartella Cloud Storage che contiene il tuo data warehouse. Questo valore inizia con gs://.
Dopo aver eseguito la connessione al cluster, il terminale Apache Spark visualizza il prompt spark-sql, che puoi utilizzare per inviare job Apache Spark.
spark-sql (default)>

Apache Flink

Crea un cluster Managed Service for Apache Spark con il componente facoltativo Apache Flink abilitato e assicurati di utilizzare la versione immagine 2.2 o successiva.
Nella console Google Cloud , vai alla pagina Istanze VM.

Vai a Istanze VM
Nell'elenco delle istanze di macchine virtuali, fai clic su SSH per connetterti all'istanza VM principale del cluster, indicata con il nome del cluster seguito dal suffisso -m.

Configura il plug-in Catalogo Apache Iceberg personalizzato per BigQuery per il catalogo di runtime Lakehouse:

FLINK_VERSION=1.19
ICEBERG_VERSION=1.6.1

cd /usr/lib/flink

sudo wget -c https://repo.maven.apache.org/maven2/org/apache/iceberg/iceberg-flink-runtime-${FLINK_VERSION}/${ICEBERG_VERSION}/iceberg-flink-runtime-${FLINK_VERSION}-${ICEBERG_VERSION}.jar -P lib

sudo gcloud storage cp gs://spark-lib/bigquery/iceberg-bigquery-catalog-${ICEBERG_VERSION}-1.0.2.jar lib/

Avvia la sessione Apache Flink su YARN:

HADOOP_CLASSPATH=`hadoop classpath`

sudo bin/yarn-session.sh -nm flink-dataproc -d

sudo bin/sql-client.sh embedded \
-s yarn-session

Crea un catalogo in Apache Flink:
```
CREATE CATALOG CATALOG_NAME WITH (
'type'='iceberg',
'warehouse'='WAREHOUSE_DIRECTORY',
'catalog-impl'='org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog',
'gcp_project'='PROJECT_ID',
'gcp_location'='LOCATION'
);
```
Sostituisci quanto segue:
- CATALOG_NAME: l'identificatore del catalogo Apache Flink, collegato al catalogo di runtime Lakehouse.
- WAREHOUSE_DIRECTORY: il percorso di base della directory del warehouse (la cartella Cloud Storage in cui Apache Flink crea i file). Questo valore inizia con gs://.
- PROJECT_ID: l'ID progetto del catalogo di runtime Lakehouse a cui è collegato il catalogo Apache Flink.
- LOCATION: la località delle risorse BigQuery.

La sessione Apache Flink è ora connessa al catalogo di runtime Lakehouse e puoi eseguire i comandi SQL Apache Flink.

Gestisci le risorse del catalogo di runtime Lakehouse

Ora che hai eseguito la connessione al catalogo di runtime Lakehouse, puoi creare e visualizzare le risorse in base ai metadati archiviati nel catalogo di runtime Lakehouse.

Ad esempio, prova a eseguire i seguenti comandi nella sessione interattiva Apache Flink SQL per creare un database e una tabella Apache Iceberg.

Utilizza il catalogo Apache Iceberg personalizzato per BigQuery:
```
USE CATALOG CATALOG_NAME;
```
Sostituisci CATALOG_NAME con l'identificatore del catalogo Apache Flink.
Crea un database, che crea un set di dati in BigQuery:
```
CREATE DATABASE IF NOT EXISTS DATABASE_NAME;
```
Sostituisci DATABASE_NAME con il nome del nuovo database.
Utilizza il database che hai creato:
```
USE DATABASE_NAME;
```

Crea una tabella Apache Iceberg. Il seguente comando crea una tabella delle vendite di esempio:

CREATE TABLE IF NOT EXISTS ICEBERG_TABLE_NAME (
  order_number BIGINT,
  price        DECIMAL(32,2),
  buyer        ROW<first_name STRING, last_name STRING>,
  order_time   TIMESTAMP(3)
);

Sostituisci ICEBERG_TABLE_NAME con un nome per la nuova tabella.

Visualizza i metadati della tabella:
```
DESCRIBE EXTENDED ICEBERG_TABLE_NAME;
```
Elenca le tabelle nel database:
```
SHOW TABLES;
```

Importa i dati nella tabella

Dopo aver creato una tabella Apache Iceberg nella sezione precedente, puoi utilizzare Apache Flink DataGen come origine dati per importare dati in tempo reale nella tabella. I passaggi seguenti sono un esempio di questo flusso di lavoro:

Crea una tabella temporanea utilizzando DataGen:

CREATE TEMPORARY TABLE DATABASE_NAME.TEMP_TABLE_NAME
WITH (
  'connector' = 'datagen',
  'rows-per-second' = '10',
  'fields.order_number.kind' = 'sequence',
  'fields.order_number.start' = '1',
  'fields.order_number.end' = '1000000',
  'fields.price.min' = '0',
  'fields.price.max' = '10000',
  'fields.buyer.first_name.length' = '10',
  'fields.buyer.last_name.length' = '10'
)
LIKE DATABASE_NAME.ICEBERG_TABLE_NAME (EXCLUDING ALL);

Sostituisci quanto segue:

DATABASE_NAME: il nome del database in cui archiviare la tabella temporanea.
TEMP_TABLE_NAME: un nome per la tabella temporanea.
ICEBERG_TABLE_NAME: il nome della tabella Apache Iceberg creata nella sezione precedente.

Imposta il parallelismo su 1:
```
SET 'parallelism.default' = '1';
```

Imposta l'intervallo di checkpoint:

SET 'execution.checkpointing.interval' = '10second';

Imposta il checkpoint:

SET 'state.checkpoints.dir' = 'hdfs:///flink/checkpoints';

Avvia il job di streaming in tempo reale:

INSERT INTO ICEBERG_TABLE_NAME SELECT * FROM TEMP_TABLE_NAME;

L'output è simile al seguente:

[INFO] Submitting SQL update statement to the cluster...
[INFO] SQL update statement has been successfully submitted to the cluster:
Job ID: 0de23327237ad8a811d37748acd9c10b

Per controllare lo stato del job di streaming, segui questi passaggi:
1. Nella console Google Cloud , vai alla pagina Cluster.
  
  Vai a Cluster
2. Seleziona il tuo cluster.
3. Fai clic sulla scheda Interfacce web.
4. Fai clic sul link YARN ResourceManager.
5. Nell'interfaccia YARN ResourceManager, trova la tua sessione Apache Flink e fai clic sul link ApplicationMaster in UI di monitoraggio.
6. Nella colonna Stato, verifica che lo stato del job sia In esecuzione.

Esegui query sui dati in streaming nel client SQL Apache Flink:

SELECT * FROM ICEBERG_TABLE_NAME
/*+ OPTIONS('streaming'='true', 'monitor-interval'='3s')*/
ORDER BY order_time desc
LIMIT 20;

Esegui query sui dati in streaming in BigQuery:

SELECT * FROM `DATABASE_NAME.ICEBERG_TABLE_NAME`
ORDER BY order_time desc
LIMIT 20;

Termina il job di streaming nel client SQL Apache Flink:
```
STOP JOB 'JOB_ID';
```
Sostituisci JOB_ID con l'ID job visualizzato nell'output quando hai creato il job di flussi di dati.

Configura il catalogo di runtime di Lakehouse con Managed Service for Apache Spark serverless

Puoi configurare il catalogo di runtime Lakehouse con Managed Service for Apache Spark serverless utilizzando Apache Spark SQL o PySpark.

Apache Spark SQL

Crea un file SQL con i comandi Apache Spark SQL che vuoi eseguire nel catalogo di runtime di Lakehouse. Ad esempio, questo comando crea uno spazio dei nomi e una tabella:
```
CREATE NAMESPACE `CATALOG_NAME`.NAMESPACE_NAME;
CREATE TABLE `CATALOG_NAME`.NAMESPACE_NAME.TABLE_NAME (id int, data string) USING ICEBERG LOCATION 'WAREHOUSE_DIRECTORY';
```
Sostituisci quanto segue:
- CATALOG_NAME: il nome del catalogo che fa riferimento alla tabella Apache Spark.
- NAMESPACE_NAME: il nome dello spazio dei nomi che fa riferimento alla tabella Apache Spark.
- TABLE_NAME: un nome per la tabella Apache Spark.
- WAREHOUSE_DIRECTORY: l'URI della cartella Cloud Storage in cui è archiviato il tuo data warehouse.
Invia un job batch Apache Spark SQL eseguendo il seguente comando gcloud dataproc batches submit spark-sql:
```
gcloud dataproc batches submit spark-sql SQL_SCRIPT_PATH \
    --project=PROJECT_ID \
    --region=REGION \
    --subnet=projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME \
    --deps-bucket=BUCKET_PATH \
    --properties="spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog, \
    spark.sql.catalog.CATALOG_NAME.catalog-impl=org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog, \
    spark.sql.catalog.CATALOG_NAME.gcp_project=PROJECT_ID, \
    spark.sql.catalog.CATALOG_NAME.gcp_location=LOCATION, \
    spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_DIRECTORY"
```
Sostituisci quanto segue:
- SQL_SCRIPT_PATH: il percorso del file SQL utilizzato dal job batch.
- PROJECT_ID: l'ID del progetto Google Cloud in cui eseguire il job batch.
- REGION: la regione in cui viene eseguito il workload.
- SUBNET_NAME (facoltativo): il nome di una subnet VPC in REGION che soddisfa i requisiti della subnet della sessione.
- BUCKET_PATH: la località del bucket Cloud Storage in cui caricare le dipendenze del workload. WAREHOUSE_DIRECTORY si trova in questo bucket. Il prefisso URI gs:// del bucket non è obbligatorio. Puoi specificare il percorso o il nome del bucket, ad esempio mybucketname1.
- LOCATION: la località in cui eseguire il job batch.
Per saperne di più sull'invio di job batch Apache Spark, consulta Esegui un workload batch Apache Spark.

PySpark

Crea un file Python con i comandi PySpark che vuoi eseguire nel catalogo di runtime di Lakehouse.

Ad esempio, il seguente comando configura un ambiente Apache Spark per interagire con le tabelle Apache Iceberg archiviate nel catalogo di runtime Lakehouse. Il comando crea quindi un nuovo spazio dei nomi e una tabella Apache Iceberg al suo interno.
```
from pyspark.sql import SparkSession

spark = SparkSession.builder \
.appName("Lakehouse runtime catalog Iceberg") \
.config("spark.sql.catalog.CATALOG_NAME", "org.apache.iceberg.spark.SparkCatalog") \
.config("spark.sql.catalog.CATALOG_NAME.catalog-impl", "org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog") \
.config("spark.sql.catalog.CATALOG_NAME.gcp_project", "PROJECT_ID") \
.config("spark.sql.catalog.CATALOG_NAME.gcp_location", "LOCATION") \
.config("spark.sql.catalog.CATALOG_NAME.warehouse", "WAREHOUSE_DIRECTORY") \
.getOrCreate()

spark.sql("USE `CATALOG_NAME`;")
spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME;")
spark.sql("USE NAMESPACE_NAME;")
spark.sql("CREATE TABLE TABLE_NAME (id int, data string) USING ICEBERG LOCATION 'WAREHOUSE_DIRECTORY';")
```
Sostituisci quanto segue:
- PROJECT_ID: l'ID del progetto Google Cloud in cui eseguire il job batch.
- LOCATION: la località in cui si trovano le risorse BigQuery.
- CATALOG_NAME: il nome del catalogo che fa riferimento alla tabella Apache Spark.
- TABLE_NAME: un nome per la tabella Apache Spark.
- WAREHOUSE_DIRECTORY: l'URI della cartella Cloud Storage in cui è archiviato il tuo data warehouse.
- NAMESPACE_NAME: il nome dello spazio dei nomi che fa riferimento alla tabella Apache Spark.
Invia il job batch utilizzando il seguente comando gcloud dataproc batches submit pyspark:
```
gcloud dataproc batches submit pyspark PYTHON_SCRIPT_PATH \
    --version=2.2 \
    --project=PROJECT_ID \
    --region=REGION \
    --deps-bucket=BUCKET_PATH \
    --properties="spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,spark.sql.catalog.CATALOG_NAME.catalog-impl=org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog,spark.sql.catalog.CATALOG_NAME.gcp_project=PROJECT_ID,spark.sql.catalog.CATALOG_NAME.gcp_location=LOCATION,spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_DIRECTORY"
```
Sostituisci quanto segue:
- PYTHON_SCRIPT_PATH: il percorso dello script Python utilizzato dal job batch.
- PROJECT_ID: l'ID del progetto Google Cloud in cui eseguire il job batch.
- REGION: la regione in cui viene eseguito il workload.
- BUCKET_PATH: la località del bucket Cloud Storage in cui caricare le dipendenze del workload. Il prefisso URI gs:// del bucket non è obbligatorio. Puoi specificare il percorso o il nome del bucket, ad esempio mybucketname1.
Per saperne di più sull'invio di job batch PySpark, consulta il riferimento gcloud PySpark.

Passaggi successivi

Crea e gestisci le risorse.
Configura le funzionalità facoltative del catalogo di runtime Lakehouse.