A partire dal 20 aprile 2026, BigLake si chiama ora Lakehouse per Apache Iceberg. BigLake Metastore 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 Spark e Hive con il catalogo runtime Lakehouse

Questo documento spiega come configurare Apache Spark e Apache Hive per utilizzare il catalogo runtime Lakehouse. Scopri come creare un catalogo Apache Hive, configurare le sessioni Spark per connettersi al metastore ed eseguire carichi di lavoro per creare tabelle su cui puoi eseguire query direttamente in BigQuery.

Prima di iniziare

Leggi l'articolo Informazioni sui cataloghi Hive nel catalogo runtime Lakehouse per capire come Spark si connette al catalogo runtime Lakehouse.
Consulta Formati di archiviazione e tipi di dati supportati.
Consulta la sezione Limitazioni e considerazioni.

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei carichi di lavoro.

Verify that billing is enabled for your Google Cloud project.

Enable the Lakehouse for Apache Iceberg, Dataproc API APIs.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Lakehouse for Apache Iceberg, Dataproc API APIs.

Roles required to enable APIs

Enable the APIs

Ruoli obbligatori

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

Crea un cluster Managed Service for Apache Spark: Editor Dataproc (roles/dataproc.editor)
Account di servizio del cluster:
- Dataproc Worker (roles/dataproc.worker)
- Storage Object User (roles/storage.objectUser)
- BigLake Editor (roles/biglake.editor)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
Accesso in scrittura a tutte le risorse del catalogo runtime Lakehouse: BigLake Editor (roles/biglake.editor)
Accesso di sola lettura a tutte le risorse del catalogo runtime Lakehouse: BigLake Viewer (roles/biglake.viewer)

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.

Per istruzioni, vedi Concedere un singolo ruolo.

Flusso di lavoro generale

Per utilizzare il catalogo runtime Lakehouse con Spark e Hive, segui questo flusso di lavoro generale:

Crea un catalogo Hive di Lakehouse for Apache Iceberg.
Configura la sessione Spark utilizzando lo strumento che preferisci (ad esempio Managed Service for Apache Spark o BigQuery Studio).
Esegui operazioni su database e tabelle all'interno della sessione Spark.
Invia workload batch a Managed Service for Apache Spark ed esegui query sulle tabelle risultanti direttamente da BigQuery.

Crea un catalogo Hive Lakehouse

Per utilizzare il catalogo runtime Lakehouse con Spark e Hive, devi prima creare un catalogo Hive.

Un catalogo Hive Lakehouse è una raccolta di database Hive. Prima di eseguire i job Spark, crea un catalogo per registrarlo con Lakehouse Metastore. Il catalogo ha un nome e una posizione Cloud Storage in cui risiedono i dati Hive.

Console

Nella console Google Cloud , apri la pagina Lakehouse.

Vai a Lakehouse
Fai clic su Crea catalogo.
Seleziona Catalogo runtime Lakehouse.
Per Tipo di catalogo, seleziona Hive Metastore.
Nel campo Seleziona un bucket Cloud Storage, inserisci il nome del bucket Cloud Storage da utilizzare con il catalogo. In alternativa, fai clic su Sfoglia per scegliere un bucket esistente o crearne uno nuovo.
In ID catalogo, assegna un nome al catalogo Hive Lakehouse.
In Località principale, specifica la stessa regione del bucket.
Fai clic su Crea.

gcloud

Per creare un catalogo Hive, esegui questo comando:

gcloud beta biglake hive catalogs create LAKEHOUSE_CATALOG_ID \
    --project=PROJECT_ID \
    --location-uri="gs://GCS_WAREHOUSE_PATH" \
    --primary-location=REGION \
    --description="DESCRIPTION"

Sostituisci quanto segue:

LAKEHOUSE_CATALOG_ID: il nome del catalogo Hive.
GCS_WAREHOUSE_PATH: il percorso Cloud Storage che archivia il warehouse Hive.
PROJECT_ID: il tuo Google Cloud ID progetto.
REGION: la regione principale del metastore. Per i bucket a una sola regione, deve corrispondere alla regione del bucket. Per i bucket a due regioni o multiregionali, deve essere una delle regioni costituenti e in cui è prevista la replica principale del metastore. L'altra regione diventa la replica secondaria.
DESCRIPTION: una descrizione del catalogo.

curl

Per creare un catalogo Hive, esegui questo comando:

curl -X POST -s -i -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-d '{"locationUri": "gs://GCS_WAREHOUSE_PATH", "description": "DESCRIPTION"}' \
-H "Content-Type:application/json" \ "https://biglake.googleapis.com/hive/v1beta/projects/PROJECT_ID/catalogs?hiveCatalogId=LAKEHOUSE_CATALOG_ID&primary_location=REGION"

Sostituisci quanto segue:

LAKEHOUSE_CATALOG_ID: il nome del catalogo Hive.
GCS_WAREHOUSE_PATH: il percorso Cloud Storage che archivia il warehouse Hive.
PROJECT_ID: il tuo ID progetto Google Cloud .
REGION: la regione principale del metastore. Per i bucket a una sola regione, deve corrispondere alla regione del bucket. Per i bucket a due regioni o multiregionali, deve essere una delle regioni costituenti e in cui è prevista la replica principale del metastore. L'altra regione diventa la replica secondaria.
DESCRIPTION: una descrizione del catalogo.

Configurare e utilizzare Spark e Hive

Per utilizzare il catalogo runtime Lakehouse, devi configurare la sessione Spark con proprietà specifiche. Puoi impostare queste proprietà quando crei un cluster Managed Service for Apache Spark o specificarle ogni volta che crei una sessione.

Queste proprietà includono dettagli come la fabbrica client, Google Cloud l'ID progetto, il catalogo predefinito e la directory del warehouse. Dopo aver stabilito la sessione, puoi eseguire operazioni fondamentali come elencare i database esistenti, creare nuovi database, definire tabelle e inserire dati.

spark-sql

Utilizza SSH per connetterti al nodo primario del cluster Managed Service for Apache Spark.

Esegui spark-sql nella riga di comando con le seguenti proprietà per avviare una sessione Spark SQL interattiva:

spark-sql \
    --conf spark.hive.metastore.client.factory.class=com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory \
    --conf spark.hive.metastore.blms.project.id=PROJECT_ID \
    --conf spark.hive.metastore.blms.catalog.default=LAKEHOUSE_CATALOG_ID \
    --conf spark.hive.metastore.warehouse.dir=gs://GCS_WAREHOUSE_PATH

Dopo l'avvio della sessione, Spark si connette al catalogo del runtime Lakehouse.

Esegui questi comandi per creare ed eseguire query sulle risorse:


-- Show all the databases in the current project.
SHOW DATABASES;

-- Create a database.
CREATE DATABASE spark_blms_database;

-- Create a Parquet datasource table.
CREATE TABLE spark_blms_database.parquet_quick_start (id INT, name STRING) USING PARQUET;

-- Insert data into the table.
INSERT INTO TABLE spark_blms_database.parquet_quick_start VALUES (1, 'my-first-user');

Sostituisci quanto segue:

PROJECT_ID: il tuo Google Cloud ID progetto.
LAKEHOUSE_CATALOG_ID: il nome del catalogo Hive.
GCS_WAREHOUSE_PATH: il percorso Cloud Storage che archivia il warehouse Hive.

Jupyter Notebook

Completa le istruzioni per eseguire un notebook Jupyter su un cluster Managed Service for Apache Spark.
Accedi all'interfaccia web di Jupyter dalla scheda Interfacce web della pagina dei dettagli del cluster nella console Google Cloud .

In un nuovo notebook, crea una sessione Spark ed esegui le seguenti query:

from pyspark.sql import SparkSession

# If a Spark session exists, stop it first by running spark.stop()
spark = SparkSession.builder\
    .master("local")\
    .appName("Lakehouse runtime catalog tutorial")\
    .config("spark.hive.metastore.client.factory.class", "com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory")\
    .config("spark.hive.metastore.blms.project.id", "PROJECT_ID")\
    .config("spark.hive.metastore.warehouse.dir", "gs://GCS_WAREHOUSE_PATH")\
    .config("spark.hive.metastore.blms.catalog.default", "LAKEHOUSE_CATALOG_ID")\
    .getOrCreate()

# Show all the databases.
df = spark.sql("SHOW DATABASES;")
df.show()

# Create a database.
spark.sql("CREATE DATABASE jupyter_blms_db")

# Create a Parquet datasource table.
spark.sql("CREATE TABLE jupyter_blms_db.parquet_table(id INT, name STRING) USING PARQUET")

# Insert data into the table.
spark.sql("INSERT INTO TABLE jupyter_blms_db.parquet_table VALUES (1, 'my-first-user');")

# Query from table.
spark.sql("SELECT * FROM jupyter_blms_db.parquet_table;").show()

Sostituisci quanto segue:

PROJECT_ID: il tuo Google Cloud ID progetto.
GCS_WAREHOUSE_PATH: il percorso Cloud Storage che archivia il warehouse Hive.
LAKEHOUSE_CATALOG_ID: il nome del catalogo Hive.

Notebook BigQuery

Nella console Google Cloud , vai a BigQuery.

Vai a BigQuery
Nel riquadro Explorer, fai clic su + AGGIUNGI e poi su Blocco note Python.

In una cella di codice, configura la sessione di Managed Service for Apache Spark e le proprietà del catalogo del runtime Lakehouse:

from google.cloud.dataproc_spark_connect import DataprocSparkSession
from google.cloud.dataproc_v1 import Session
import os

os.environ['DATAPROC_SPARK_CONNECT_DEFAULT_DATASOURCE'] = ""

session = Session()
session.environment_config.execution_config.ttl = {"seconds": 864000}
session.runtime_config.version = "2.3"
session.runtime_config.properties = {
 "spark.hive.metastore.blms.project.id": "PROJECT_ID",
 "spark.hive.metastore.blms.catalog.default": "LAKEHOUSE_CATALOG_ID",
 "spark.hive.metastore.warehouse.dir": "gs://GCS_WAREHOUSE_PATH",
 "spark.hive.metastore.client.factory.class": "com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory",
 "spark.sql.catalogImplementation": "hive"
}

spark = DataprocSparkSession.builder.dataprocSessionConfig(session).getOrCreate()
print("Spark session created successfully")

In un'altra cella di codice, crea un database e una tabella:

# Create a database
spark.sql("CREATE DATABASE bq_spark_blms_database;")

# Create a parquet datasource table
spark.sql("CREATE TABLE bq_spark_blms_database.parquet_quick_start (id INT, name STRING) USING PARQUET;")

# Insert data into the table
spark.sql("INSERT INTO TABLE bq_spark_blms_database.parquet_quick_start VALUES (1, 'my-first-user');")

# Query from table
spark.sql("select * from bq_spark_blms_database.parquet_quick_start;").show()

Sostituisci quanto segue:

PROJECT_ID: il tuo Google Cloud ID progetto.
GCS_WAREHOUSE_PATH: il percorso Cloud Storage che archivia il warehouse Hive.
LAKEHOUSE_CATALOG_ID: il nome del catalogo Hive.

Interfaccia a riga di comando Hive

Per utilizzare la CLI Hive, devi configurarla per connettersi al metastore. Puoi farlo in due modi:

Opzione 1: configurazione permanente. Aggiorna il file /etc/hive/conf/hive-site.xml sul nodo principale.
Opzione 2: configurazione temporanea.Fornisci i flag di configurazione quando avvii la CLI.

Per configurare la CLI ed eseguire la sessione di query:

Utilizza SSH per connetterti al nodo primario del cluster Managed Service for Apache Spark.

A seconda del metodo di configurazione, esegui una delle seguenti operazioni:

Per configurare in modo permanente (opzione 1):

Apri /etc/hive/conf/hive-site.xml sul nodo principale e aggiungi le seguenti proprietà:

<property>
    <name>hive.metastore.blms.project.id</name>
    <value>PROJECT_ID</value>
    <description></description>
</property>

<property>
    <name>hive.metastore.client.factory.class</name>
    <value>com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory</value>
    <description></description>
</property>
<property>
    <name>hive.metastore.blms.catalog.default</name>
    <value>LAKEHOUSE_CATALOG_ID</value>
    <description></description>
</property>
<property>
    <name>hive.metastore.warehouse.dir</name>
    <value>gs://GCS_WAREHOUSE_PATH</value>
    <description></description>
</property>

Avvia l'interfaccia a riga di comando Hive:
```
hive
```

Per configurare temporaneamente all'avvio (opzione 2): avvia l'interfaccia a riga di comando di Hive con i flag di configurazione:

hive \
--hiveconf hive.metastore.blms.project.id="PROJECT_ID" \
--hiveconf hive.metastore.blms.catalog.default="LAKEHOUSE_CATALOG_ID" \
--hiveconf hive.metastore.client.factory.class=com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory \
--hiveconf hive.metastore.warehouse.dir="gs://GCS_WAREHOUSE_PATH"

Poi, esegui questi comandi nella sessione di Hive CLI:
```
show databases;
create database hive_query_test;
create table hive_query_test.parquet_table (id INT, name STRING) stored as PARQUET;
select * from hive_query_test.parquet_table;
```
Sostituisci quanto segue:
- PROJECT_ID: il tuo Google Cloud ID progetto.
- LAKEHOUSE_CATALOG_ID: il nome del catalogo Hive.
- GCS_WAREHOUSE_PATH: il percorso Cloud Storage che archivia il warehouse Hive.

Invia un job batch Managed Service for Apache Spark

Puoi inviare un workload batch PySpark a Managed Service for Apache Spark che utilizza il catalogo del runtime Lakehouse.

Questo snippet PySpark inizializza una sessione Spark configurata per connettersi al catalogo del runtime Lakehouse. Imposta proprietà essenziali come la fabbrica di client Lakehouse, l'ID progetto, il catalogo predefinito e la directory del warehouse. Google Cloud Dopo aver stabilito la sessione, il codice mostra come elencare i database esistenti, creare un nuovo database e definire una tabella in formato Parquet all'interno di questo database utilizzando i comandi Spark SQL.

Crea un file Python con un job PySpark:

from pyspark.sql import SparkSession

spark = (
    SparkSession.builder.appName("Lakehouse runtime catalog tutorial")
    .config(
       "spark.hive.metastore.client.factory.class",
"com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory")
    .config("spark.hive.metastore.blms.project.id", "PROJECT_ID")
    .config("spark.hive.metastore.blms.catalog.default", "LAKEHOUSE_CATALOG_ID")
    .config(
        "spark.hive.metastore.warehouse.dir",
        "gs://GCS_WAREHOUSE_PATH",
    )
    .enableHiveSupport()
    .getOrCreate()
)

# Show all the databases.
spark.sql("SHOW DATABASES;").show()

# Create a database.
spark.sql("CREATE DATABASE dp_serverless_test")

# Create a Parquet datasource table.
spark.sql(
        "CREATE TABLE dp_serverless_test.parquet_table(id INT, name STRING) USING"
        " PARQUET"
    )

# Query from table.
spark.sql("SELECT * from  dp_serverless_test.parquet_table").show()

Sostituisci quanto segue:

PROJECT_ID: il tuo ID progetto Google Cloud .
LAKEHOUSE_CATALOG_ID: il nome del catalogo Hive.
GCS_WAREHOUSE_PATH: il percorso Cloud Storage che archivia il warehouse Hive.

Invia il job batch:
```
gcloud dataproc batches submit pyspark PYTHON_SCRIPT_FILE \
    --version=2.2 \
    --project=PROJECT_ID \
    --region=REGION \
    --deps-bucket=gs://CLOUD_STORAGE_BUCKET
```
Sostituisci quanto segue:
- PYTHON_SCRIPT_FILE: il percorso del file dell'applicazione PySpark. Può essere un percorso locale o il percorso dell'oggetto Cloud Storage.
- PROJECT_ID: il tuo ID progetto.
- REGION: la regione in cui eseguire il job batch.
- CLOUD_STORAGE_BUCKET: il nome del bucket Cloud Storage utilizzato per organizzare le dipendenze di qualsiasi workload.

Esegui query sulla tabella da BigQuery

Dopo aver creato risorse da Spark nel catalogo runtime Lakehouse, puoi eseguire query su queste risorse da BigQuery Studio.

Nella Google Cloud console, vai a BigQuery.

Vai a BigQuery
Nell'editor di query, inserisci la seguente istruzione:
```
SELECT * FROM `PROJECT_ID.LAKEHOUSE_CATALOG_ID.DATABASE_NAME.TABLE_NAME`;
```
Sostituisci quanto segue:
- PROJECT_ID: il tuo ID progetto.
- LAKEHOUSE_CATALOG_ID: il nome del catalogo Hive.
- DATABASE_NAME: il nome del database.
- TABLE_NAME: il nome della tabella.

Configura Spark e Hive con il catalogo runtime Lakehouse Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Ruoli obbligatori

Flusso di lavoro generale

Crea un catalogo Hive Lakehouse

Console

gcloud

curl

Configurare e utilizzare Spark e Hive

spark-sql

Jupyter Notebook

Notebook BigQuery

Interfaccia a riga di comando Hive

Invia un job batch Managed Service for Apache Spark

Esegui query sulla tabella da BigQuery

Configura Spark e Hive con il catalogo runtime Lakehouse