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 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 connetterti al metastore ed eseguire carichi di lavoro per creare tabelle su cui puoi eseguire query direttamente in BigQuery.

Prima di iniziare

Leggi Informazioni sui cataloghi Hive nel catalogo runtime Lakehouse per capire come Spark si connette al catalogo runtime Lakehouse.
Esamina i formati di archiviazione e i tipi di dati supportati.
Esamina le limitazioni e le considerazioni.

Accedi al tuo Google Cloud account. 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, Managed Service for Apache Spark 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, Managed Service for Apache Spark APIs.

Roles required to enable APIs

Enable the APIs

Ruoli obbligatori

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

Crea un cluster Managed Service for Apache Spark: Editor Dataproc (roles/dataproc.editor)
Account di servizio del cluster:
- Worker Dataproc (roles/dataproc.worker)
- Utente oggetti Storage (roles/storage.objectUser)
- Editor BigLake (roles/biglake.editor)
- Consumer utilizzo servizi (roles/serviceusage.serviceUsageConsumer)
Accesso in scrittura a tutte le risorse del catalogo runtime Lakehouse: Editor BigLake (roles/biglake.editor)
Accesso di sola lettura a tutte le risorse del catalogo runtime Lakehouse: Visualizzatore BigLake (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 le istruzioni, consulta 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 Lakehouse.
Configura la sessione Spark utilizzando lo strumento che preferisci (ad esempio Managed Service for Apache Spark o BigQuery Studio).
Esegui operazioni di database e tabelle all'interno della sessione Spark.
Invia carichi di lavoro 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 località Cloud Storage in cui risiedono i dati Hive.

Console

Nella Google Cloud console, apri la pagina Lakehouse.

Vai a Lakehouse
Fai clic su Crea catalogo.
Seleziona Catalogo runtime Lakehouse.
In Tipo di catalogo, seleziona Metastore Hive.
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 il comando seguente:

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 in cui è archiviato il warehouse Hive.
PROJECT_ID: il tuo Google Cloud ID progetto.
REGION: la regione principale del metastore. Per i bucket a regione singola, 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 il comando seguente:

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 in cui è archiviato il warehouse Hive.
PROJECT_ID: il tuo Google Cloud ID progetto.
REGION: la regione principale del metastore. Per i bucket a regione singola, 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.

Configura e utilizza 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 factory 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 principale 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 runtime Lakehouse.

Esegui i seguenti 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 progetto ID.
LAKEHOUSE_CATALOG_ID: il nome del catalogo Hive.
GCS_WAREHOUSE_PATH: il percorso Cloud Storage in cui è archiviato il warehouse Hive.

Blocco note Jupyter

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

In un nuovo blocco note, 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 progetto ID.
GCS_WAREHOUSE_PATH: il percorso Cloud Storage in cui è archiviato il warehouse Hive.
LAKEHOUSE_CATALOG_ID: il nome del catalogo Hive.

Blocco note BigQuery

Nella Google Cloud console, 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 le proprietà della sessione Managed Service for Apache Spark e del catalogo 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 progetto ID.
GCS_WAREHOUSE_PATH: il percorso Cloud Storage in cui è archiviato il warehouse Hive.
LAKEHOUSE_CATALOG_ID: il nome del catalogo Hive.

Interfaccia a riga di comando Hive

Per utilizzare l'interfaccia a riga di comando Hive, devi configurarla in modo che si connetta 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 l'interfaccia a riga di comando.

Per configurare l'interfaccia a riga di comando ed eseguire la sessione di query:

Utilizza SSH per connetterti al nodo principale 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 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"

Quindi, esegui i seguenti comandi nella sessione dell'interfaccia a riga di comando Hive:
```
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 progetto ID.
- LAKEHOUSE_CATALOG_ID: il nome del catalogo Hive.
- GCS_WAREHOUSE_PATH: il percorso Cloud Storage in cui è archiviato il warehouse Hive.

Invia un job batch Managed Service for Apache Spark

Puoi inviare un carico di lavoro batch PySpark a Managed Service for Apache Spark che utilizza il catalogo runtime Lakehouse.

Questo snippet PySpark inizializza una sessione Spark configurata per la connessione al catalogo runtime Lakehouse. Imposta le proprietà essenziali come la factory client Lakehouse, Google Cloud l'ID progetto, il catalogo predefinito e la directory del warehouse. 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 Google Cloud ID progetto.
LAKEHOUSE_CATALOG_ID: il nome del catalogo Hive.
GCS_WAREHOUSE_PATH: il percorso Cloud Storage in cui è archiviato 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 dello script Python. 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 eseguire lo staging delle dipendenze di qualsiasi carico di lavoro.

Esegui query sulla tabella da BigQuery

Dopo aver creato le risorse da Spark nel catalogo runtime Lakehouse, puoi eseguire query su di esse 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

Configura e utilizza Spark e Hive

spark-sql

Blocco note Jupyter

Blocco note 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