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.

Crea una tabella Iceberg ed esegui query su di essa in Lakehouse utilizzando Google Cloud CLI

In questa guida rapida, scoprirai come Lakehouse senza confini ti consente di condividere le tabelle Apache Iceberg tra motori open source e Google Cloud gestendo i metadati delle tabelle, inclusi schemi, snapshot e posizioni di archiviazione, nel catalogo runtime Lakehouse.

Per completare questa guida rapida, segui questi passaggi:

Crea un catalogo: crea un catalogo con più bucket nel catalogo di runtime Lakehouse supportato da Cloud Storage.
Crea una tabella Iceberg con Spark: esegui uno script PySpark su Managed Service for Apache Spark per provare un workload open source senza configurare il tuo cluster. Spark si connette tramite l'endpoint del catalogo REST Apache Iceberg, che funziona anche con qualsiasi motore compatibile con Iceberg, come Spark autogestito, Trino o Apache Flink.
Esegui query sulla tabella in BigQuery: esegui query sulla stessa tabella in BigQuery utilizzando la sintassi P.C.N.T (Project.Catalog.Namespace.Table) in quattro parti, senza necessità di ETL o registrazione manuale della tabella.

Prima di iniziare

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.

Installa Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea o seleziona un Google Cloud progetto.

Ruoli richiesti per selezionare o creare un progetto

Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere ruoli.

Crea un progetto Google Cloud :
```
gcloud projects create PROJECT_ID
```
Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.
Seleziona il progetto Google Cloud che hai creato:
```
gcloud config set project PROJECT_ID
```
Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

Abilita le API BigLake, Managed Service for Apache Spark, Cloud Storage, BigQuery e Compute Engine, se non sono già abilitate:

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

gcloud services enable biglake.googleapis.com dataproc.googleapis.com storage.googleapis.com bigquery.googleapis.com compute.googleapis.com

Concedi ruoli al tuo account utente. Esegui il seguente comando una volta per ciascuno dei seguenti ruoli IAM: roles/biglake.admin, roles/storage.admin, roles/dataproc.editor, roles/resourcemanager.projectIamAdmin, roles/bigquery.jobUser

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Sostituisci quanto segue:

PROJECT_ID: il tuo ID progetto.
USER_IDENTIFIER: l'identificatore del tuo account utente . Ad esempio: myemail@example.com.
ROLE: il ruolo IAM che concedi al tuo account utente.

Installa Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Crea o seleziona un Google Cloud progetto.

Ruoli richiesti per selezionare o creare un progetto

Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere ruoli.

Crea un progetto Google Cloud :
```
gcloud projects create PROJECT_ID
```
Sostituisci PROJECT_ID con un nome per il progetto Google Cloud che stai creando.
Seleziona il progetto Google Cloud che hai creato:
```
gcloud config set project PROJECT_ID
```
Sostituisci PROJECT_ID con il nome del progetto Google Cloud .

Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

Abilita le API BigLake, Managed Service for Apache Spark, Cloud Storage, BigQuery e Compute Engine, se non sono già abilitate:

Ruoli richiesti per abilitare le API

gcloud services enable biglake.googleapis.com dataproc.googleapis.com storage.googleapis.com bigquery.googleapis.com compute.googleapis.com

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Sostituisci quanto segue:

PROJECT_ID: il tuo ID progetto.
USER_IDENTIFIER: l'identificatore del tuo account utente . Ad esempio: myemail@example.com.
ROLE: il ruolo IAM che concedi al tuo account utente.

Configura l'ambiente e crea un bucket

Apri Cloud Shell e crea un bucket Cloud Storage per contenere uno script PySpark e i dati della tabella Iceberg:

Nella console Google Cloud , fai clic su Attiva Cloud Shell.

Attiva Cloud Shell
Fai clic su Autorizza, se richiesto.

Imposta le variabili di ambiente per il progetto, la regione, il bucket e il nome del catalogo in modo da poterle riutilizzare in questa guida rapida:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"
export BUCKET_NAME="${PROJECT_ID}-lakehouse-quickstart"
export LAKEHOUSE_CATALOG_ID="quickstart_catalog"

Crea un bucket Cloud Storage nella regione selezionata:

gcloud storage buckets create gs://${BUCKET_NAME} \
    --project=${PROJECT_ID} \
    --location=${REGION}

Concedi le autorizzazioni al account di servizio Spark

Per impostazione predefinita, Managed Service for Apache Spark esegue i job batch utilizzando l'account di servizio predefinito di Compute Engine del tuo progetto. Concedi a questo account di servizio i seguenti ruoli IAM in modo che possa leggere lo script PySpark da Cloud Storage e interagire con il catalogo di runtime di Lakehouse e BigQuery:

Ruolo	Risorsa	Finalità
Dataproc Worker (`roles/dataproc.worker`)	Progetto	Esegui i workload batch Managed Service for Apache Spark.
Service Usage Consumer (`roles/serviceusage.serviceUsageConsumer`)	Progetto	Utilizza le API e la quota del progetto.
BigLake Editor (`roles/biglake.editor`)	Progetto	Crea risorse del catalogo e richiedi le credenziali di archiviazione vendute.
Editor dati BigQuery (`roles/bigquery.dataEditor`)	Progetto	Gestisci i metadati BigQuery per le tue tabelle.
Storage Object Viewer (`roles/storage.objectViewer`)	Bucket	Leggi lo script PySpark dal bucket Cloud Storage.

Tieni presente che il account di servizio Spark ha bisogno solo del ruolo Storage Object Viewer (roles/storage.objectViewer) per leggere lo script PySpark. Non ha bisogno dell'accesso in scrittura diretto al bucket perché il catalogo di runtime Lakehouse fornisce credenziali di scrittura temporanee e con ambito tabella quando viene eseguito il job.

In Cloud Shell, esegui questo script per concedere questi ruoli:

PROJECT_NUMBER=$(gcloud projects describe ${PROJECT_ID} \
    --format='value(projectNumber)')
SPARK_SA="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"

for ROLE in \
    "roles/dataproc.worker" \
    "roles/serviceusage.serviceUsageConsumer" \
    "roles/biglake.editor" \
    "roles/bigquery.dataEditor"; do
  gcloud projects add-iam-policy-binding ${PROJECT_ID} \
      --member="serviceAccount:${SPARK_SA}" \
      --role="${ROLE}"
done

gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
    --member="serviceAccount:${SPARK_SA}" \
    --role="roles/storage.objectViewer"

Crea un catalogo nel catalogo di runtime Lakehouse

Crea un catalogo nel catalogo di runtime Lakehouse per le tue tabelle Apache Iceberg.

In Cloud Shell, crea un catalogo multicloud. Un catalogo multibucket consente di denominare il catalogo indipendentemente da qualsiasi nome di bucket e di associare più bucket Cloud Storage a un unico catalogo. Attiva la modalità di distribuzione delle credenziali in modo che il catalogo di runtime Lakehouse possa emettere in modo sicuro credenziali di archiviazione temporanee per Spark per tuo conto.
```
gcloud biglake iceberg catalogs create ${LAKEHOUSE_CATALOG_ID} \
    --project=${PROJECT_ID} \
    --catalog-type=biglake \
    --default-location=gs://${BUCKET_NAME} \
    --credential-mode=vended-credentials
```

Concedi al catalogo l'accesso al tuo bucket:

Con la distribuzione delle credenziali, il account di servizio di cui è stato eseguito il provisioning automatico del catalogo deve disporre del ruolo Storage Object User (roles/storage.objectUser) nel tuo bucket per poter generare token di accesso temporanei per i motori client.

# Retrieve the auto-provisioned catalog service account email
CATALOG_SA=$(gcloud biglake iceberg catalogs describe ${LAKEHOUSE_CATALOG_ID} \
    --project=${PROJECT_ID} \
    --format='value(biglake-service-account)')

# Grant the Storage Object User role to the catalog service account on your bucket
gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
    --member="serviceAccount:${CATALOG_SA}" \
    --role="roles/storage.objectUser"

Crea una tabella Iceberg con un job PySpark

Con il catalogo e le autorizzazioni pronti, puoi eseguire un job PySpark su Managed Service for Apache Spark per creare una tabella Iceberg e inserire alcuni dati campionati.

Creare e caricare uno script PySpark

In Cloud Shell, crea un file denominato quickstart.py:

cat << 'EOF' > quickstart.py
from pyspark.sql import SparkSession

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

# Create a namespace
spark.sql("CREATE NAMESPACE IF NOT EXISTS `quickstart_catalog`.quickstart_namespace")

# Create the table
spark.sql("""
    CREATE OR REPLACE TABLE `quickstart_catalog`.quickstart_namespace.quickstart_table (
        id INT,
        name STRING
    )
    USING iceberg
""")

# Insert data into the table
spark.sql("""
    INSERT INTO `quickstart_catalog`.quickstart_namespace.quickstart_table
    VALUES (1, 'one'), (2, 'two'), (3, 'three')
""")
EOF

Questo script avvia una sessione Spark, crea uno spazio dei nomi denominato quickstart_namespace e una tabella Iceberg denominata quickstart_table e inserisce tre righe di dati campionati. Poiché le istruzioni SQL non specificano un percorso del bucket (LOCATION), il catalogo di runtime Lakehouse archivia automaticamente lo spazio dei nomi e i file delle tabelle nel bucket --default-location del catalogo (gs://${BUCKET_NAME}).

Copia quickstart.py nel bucket Cloud Storage in modo che Managed Service for Apache Spark possa accedervi:
```
gcloud storage cp quickstart.py gs://${BUCKET_NAME}/quickstart.py
```

Esegui lo script PySpark

Invia lo script PySpark come job batch Managed Service for Apache Spark, che esegue il codice con le librerie Iceberg preinstallate senza la necessità di eseguire il provisioning di un cluster.

Il flag --properties configura Spark per la connessione al catalogo nel catalogo di runtime Lakehouse utilizzando l'endpoint del catalogo REST di Apache Iceberg:

In Cloud Shell, invia il job batch:

gcloud dataproc batches submit pyspark gs://${BUCKET_NAME}/quickstart.py \
    --project=${PROJECT_ID} \
    --region=${REGION} \
    --version=2.2 \
    --properties="spark.sql.catalog.quickstart_catalog=org.apache.iceberg.spark.SparkCatalog,\
spark.sql.catalog.quickstart_catalog.type=rest,\
spark.sql.catalog.quickstart_catalog.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
spark.sql.catalog.quickstart_catalog.warehouse=bl://projects/${PROJECT_ID}/catalogs/${LAKEHOUSE_CATALOG_ID},\
spark.sql.catalog.quickstart_catalog.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
spark.sql.catalog.quickstart_catalog.header.x-goog-user-project=${PROJECT_ID},\
spark.sql.catalog.quickstart_catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
spark.sql.catalog.quickstart_catalog.header.X-Iceberg-Access-Delegation=vended-credentials,\
spark.sql.catalog.quickstart_catalog.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token"

Oltre alle impostazioni Iceberg standard (SparkCatalog, type=rest e IcebergSparkSessionExtensions), queste proprietà configurano la connessione al catalogo di runtime Lakehouse:

uri e warehouse (bl://...): connetti Spark all'endpoint del catalogo REST di Apache Iceberg del catalogo di runtime Lakehouse e indirizza le richieste al catalogo multi-bucket.
rest.auth.type e header.x-goog-user-project: autentica le richieste REST utilizzando le credenziali del account di servizio Spark e addebita la quota API al tuo progetto.
header.X-Iceberg-Access-Delegation, io-impl e gcs.oauth2.refresh-credentials-endpoint: richiedi credenziali temporanee di Cloud Storage dal catalogo e configura il client GCSFileIO di Iceberg per scrivere file di dati utilizzando questi token.

Per saperne di più su queste impostazioni, consulta Configura l'applicazione client e la documentazione sulla configurazione di Apache Iceberg Spark.

Al termine del job, l'output è simile al seguente:

Batch [cb9d84e9489d408baca4f9e7ab4c64ff] finished.
metadata:
  '@type': type.googleapis.com/google.cloud.dataproc.v1.BatchOperationMetadata
  batch: projects/PROJECT_ID/locations/us-central1/batches/cb9d84e9489d408baca4f9e7ab4c64ff
  batchUuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9
  createTime: '2026-01-24T00:10:50.224097Z'
  description: Batch
  labels:
    goog-dataproc-batch-id: cb9d84e9489d408baca4f9e7ab4c64ff
    goog-dataproc-batch-uuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9
    goog-dataproc-drz-resource-uuid: batch-54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9
    goog-dataproc-location: us-central1
  operationType: BATCH
  name: projects/PROJECT_ID/regions/us-central1/operations/32287926-5f61-3572-b54a-fbad8940d6ef

Esegui query sulla tabella da BigQuery

Ora che Spark ha scritto la tabella Iceberg, puoi eseguirne immediatamente una query in BigQuery utilizzando la sintassi P.C.N.T (Project.Catalog.Namespace.Table) in quattro parti:

In Cloud Shell, esegui questo comando bq query:

bq query --project_id=${PROJECT_ID} --location=${REGION} --use_legacy_sql=false \
    "SELECT * FROM \`${PROJECT_ID}.${LAKEHOUSE_CATALOG_ID}.quickstart_namespace.quickstart_table\`"

L'output mostra le tre righe che hai inserito con il job PySpark:

+----+-------+
| id | name  |
+----+-------+
|  1 | one   |
|  2 | two   |
|  3 | three |
+----+-------+

Poiché il catalogo di runtime Lakehouse tiene traccia dei metadati Iceberg e gestisce l'accesso allo spazio di archiviazione, BigQuery legge i file sottostanti in Cloud Storage non appena Spark esegue il commit dello snapshot.

Nello stesso punto, puoi anche leggere o scrivere in quickstart_table utilizzando qualsiasi altro motore compatibile con Iceberg, come Trino, Flink o un cluster Managed Spark autogestito. Poiché la distribuzione delle credenziali è abilitata nel catalogo, un motore esterno ha bisogno solo del ruolo Visualizzatore BigLake (roles/biglake.viewer) nel tuo progetto per leggere la tabella o del ruolo Editor BigLake (roles/biglake.editor) per scrivere anche i dati e eseguire il commit di nuove istantanee. Per scoprire come connettere altri motori, consulta Configura l'endpoint del catalogo REST Apache Iceberg.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi inutili, elimina le risorse che hai creato in questa guida rapida. L'eliminazione della tabella, dello spazio dei nomi e del catalogo rimuove la registrazione dei metadati dal catalogo di runtime Lakehouse, mentre l'eliminazione del bucket rimuove i file di dati Parquet e di metadati Iceberg sottostanti archiviati in Cloud Storage:

In Cloud Shell, elimina la tabella dal catalogo:

gcloud biglake iceberg tables delete quickstart_table \
    --project=${PROJECT_ID} \
    --catalog=${LAKEHOUSE_CATALOG_ID} \
    --namespace=quickstart_namespace \
    --quiet

Elimina lo spazio dei nomi dal catalogo:

gcloud biglake iceberg namespaces delete quickstart_namespace \
    --project=${PROJECT_ID} \
    --catalog=${LAKEHOUSE_CATALOG_ID} \
    --quiet

Elimina il catalogo:

gcloud biglake iceberg catalogs delete ${LAKEHOUSE_CATALOG_ID} \
    --project=${PROJECT_ID} --quiet

Elimina il bucket Cloud Storage e tutti i relativi contenuti:
```
gcloud storage rm -r gs://${BUCKET_NAME}
```

Passaggi successivi

Prova la guida rapida Crea ed esegui query su una tabella Iceberg utilizzando la console Google Cloud per creare spazi dei nomi e tabelle Iceberg nella UI e modificare i dati utilizzando data manipulation language (DML) di BigQuery.
Prova il codelab Configurare l'accesso ai dati cross-cloud per eseguire query sui dati in Amazon Web Services (AWS), AlloyDB per PostgreSQL e Cloud Storage senza ETL.
Scopri di più sui cataloghi multibucket e sull'endpoint del catalogo REST Apache Iceberg.
Scopri come gestire i cataloghi nel catalogo di runtime Lakehouse.
Scopri di più sulle tabelle Apache Iceberg gestite da Lakehouse.