Configura l'endpoint del catalogo REST Lakehouse Iceberg

Per i nuovi cataloghi, ti consigliamo di utilizzare l'endpoint del catalogo REST Apache Iceberg nel catalogo runtime Lakehouse. Questo endpoint fornisce un'interfaccia standardizzata e completamente gestita basata sull'API REST del catalogo Apache Iceberg open source.

Questo endpoint funge da unica fonte attendibile, consentendo un'interoperabilità senza problemi tra i motori di query. Consente a motori come Apache Spark di scoprire, leggere e gestire le tabelle di Google Cloud Lakehouse.

Questo approccio è una buona scelta se utilizzi motori OSS o di terze parti compatibili per accedere ai dati in Cloud Storage e hai bisogno dell'interoperabilità con altri motori, incluso BigQuery. Supporta funzionalità come la distribuzione delle credenziali per controllo dell'accesso granulare e la replica tra regioni e il ripristino di emergenza.

Al contrario, l'endpoint Custom Apache Iceberg catalog for BigQuery è un'integrazione precedente. Anche se i flussi di lavoro esistenti possono continuare a utilizzarlo, il catalogo REST offre un'esperienza più standardizzata e ricca di funzionalità.

Prima di iniziare

Prima di continuare, acquisisci familiarità con il catalogo runtime Lakehouse e con la panoramica dell'endpoint del catalogo REST Iceberg.

Se hai tabelle Apache Iceberg versione 1 (V1) esistenti, devi eseguirne l'upgrade prima di utilizzarle con l'endpoint del catalogo REST di Apache Iceberg. Per ulteriori informazioni, vedi Eseguire l'upgrade delle tabelle Iceberg V1 alla versione V2.

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

  2. Abilita l'API BigLake.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilitare l'API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per utilizzare l'endpoint del catalogo REST Apache Iceberg nel catalogo del runtime Lakehouse, chiedi all'amministratore di concederti i seguenti ruoli IAM:

  • Eseguire attività amministrative, come la gestione dell'accesso utente al catalogo, dell'accesso allo spazio di archiviazione e della modalità di distribuzione delle credenziali del catalogo:
  • Registra le tabelle in un catalogo BigLake: BigLake Admin (roles/biglake.admin) sul progetto.
  • Leggi i dati della tabella in modalità di distribuzione delle credenziali: Visualizzatore BigLake (roles/biglake.viewer) sul progetto. Se utilizzi motori di query come Managed Service for Apache Spark, Managed Service for Apache Spark o Dataflow per leggere i dati delle tabelle, concedi questo ruolo al account di servizio che utilizzi per eseguire i job in quel motore.
  • Scrivi i dati della tabella in modalità di distribuzione delle credenziali: Editor BigLake (roles/biglake.editor) sul progetto. Se utilizzi motori di query come Managed Service for Apache Spark, Managed Service for Apache Spark o Dataflow per scrivere dati delle tabelle, concedi questo ruolo al account di servizio che utilizzi per eseguire i job in quel motore.
  • Utilizza il account di servizio del catalogo del runtime Lakehouse di cui è stato eseguito il provisioning automatico in modalità di distribuzione delle credenziali: Storage Object User (roles/storage.objectUser) su tutti i bucket Cloud Storage associati. Dopo aver creato il catalogo, concedi esplicitamente il ruolo Storage Object User (roles/storage.objectUser) su tutti i bucket di archiviazione associati al account di servizio del catalogo di runtime Lakehouse con provisioning automatico.
  • Leggi le risorse del catalogo e i dati delle tabelle in modalità non di distribuzione delle credenziali:
  • Gestisci le risorse del catalogo e scrivi i dati delle tabelle in modalità non di distribuzione delle credenziali:

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.

Limitazioni

L'endpoint del catalogo REST di Apache Iceberg è soggetto alle seguenti limitazioni:

Limitazioni generali

  • Sono supportate le tabelle Apache Iceberg V2 (GA) e V3 (anteprima). Le tabelle Iceberg V1 non sono supportate. Prima di utilizzare le tabelle V1 esistenti con l'endpoint del catalogo REST Apache Iceberg, devi eseguire l'upgrade a una versione supportata.
  • Trino è supportato solo con la federazione del catalogo BigQuery quando utilizzi Managed Service for Apache Spark su Compute Engine 2.3 con versioni dell'immagine 2.3.16 e successive.
  • Quando utilizzi la modalità di distribuzione delle credenziali, se il motore di query ti consente di impostare la proprietà io-impl per una connessione al catalogo, devi impostarla su org.apache.iceberg.gcp.gcs.GCSFileIO.
  • I bucket spazi dei nomi gerarchici non sono attualmente supportati nella modalità di distribuzione delle credenziali.

Limitazioni delle tabelle

  • Non puoi creare o modificare tabelle nell'endpoint del catalogo REST di Apache Iceberg utilizzando le istruzioni Data Definition Language (DDL) o Data Manipulation Language (DML) di BigQuery. Puoi modificare queste tabelle utilizzando l'API BigQuery (con lo strumento a riga di comando bq o le librerie client), ma in questo modo rischi di apportare modifiche incompatibili con il motore esterno.
  • Le tabelle gestite tramite l'endpoint del catalogo REST di Apache Iceberg non supportano il controllo dell'accesso granulare (FGAC), ad esempio la sicurezza a livello di riga e di colonna.
  • L'impostazione delle proprietà della tabella Iceberg write.data.path o write.metadata.path su valori diversi da quelli predefiniti è vietata.
  • I percorsi delle tabelle devono essere nidificati all'interno del percorso dello spazio dei nomi padre (ad esempio, gs://{namespace_path}/.../{table_name}). Per evitare conflitti e migliorare la sicurezza, al percorso risultante viene aggiunto automaticamente un suffisso di stringa casuale (ad esempio, gs://{namespace_path}/{table_name}/{random_suffix}).

Limitazioni per i dati

  • Sono supportati solo i file Parquet. Per maggiori dettagli su come BigQuery gestisce i file Parquet, consulta Caricamento di dati Parquet da Cloud Storage.
  • La dimensione massima del file Iceberg metadata.json è 1 MB. Per richiedere un aumento di questo limite, contatta il team dedicato al tuo Account Google.

Limitazioni delle query

  • Non è possibile eseguire query sulle tabelle di metadati Apache Iceberg (ad esempio .snapshots o .files) in BigQuery utilizzando identificatori di nomi in cinque parti. Puoi eseguire query su queste tabelle utilizzando Spark.

Configura l'endpoint del catalogo REST Iceberg

Prima di configurare il catalogo, ti consigliamo di leggere la panoramica dell'endpoint del catalogo REST di Apache Iceberg per comprendere la gerarchia delle risorse, i tipi di catalogo e la struttura di denominazione.

Di seguito sono riportati i passaggi generali da seguire quando utilizzi l'endpoint del catalogo REST Apache Iceberg nel catalogo runtime Lakehouse:

  1. In base alla panoramica dell'endpoint del catalogo REST Iceberg, scegli il tipo di catalogo. Puoi configurare un catalogo multi-bucket (bl://) (opzione consigliata) o un catalogo single-bucket (gs://).
  2. Crea un catalogo che rimandi alla posizione del magazzino.
  3. Configura l'applicazione client per utilizzare l'endpoint del catalogo REST di Apache Iceberg.
  4. Crea uno spazio dei nomi o uno schema per organizzare le tabelle.
  5. Crea ed esegui query sulle tabelle utilizzando il client configurato.

Considerazioni

Valuta le seguenti opzioni per la modalità delle credenziali e la configurazione dello spazio di archiviazione.

Modalità delle credenziali (ambito)

Puoi creare un catalogo che utilizza le credenziali dell'utente finale o la modalità di distribuzione delle credenziali.

  • Credenziali utente finale: il catalogo trasmette l'identità dell'utente finale che vi accede a Cloud Storage per i controlli di autorizzazione.

  • Modalità di distribuzione delle credenziali:un meccanismo di delega dell'accesso allo spazio di archiviazione che consente agli amministratori del catalogo di runtime Lakehouse di controllare le autorizzazioni direttamente sulle risorse del catalogo di runtime Lakehouse, eliminando la necessità che gli utenti del catalogo abbiano accesso diretto ai bucket Cloud Storage. Consente agli amministratori di Lakehouse di Google Cloud di concedere agli utenti autorizzazioni su file di dati specifici.

Tipo di bucket

Puoi scegliere di creare un catalogo con un solo bucket o con più bucket.

  • Più bucket (bl://) (consigliato): questa configurazione consente al catalogo di associare più bucket e di assegnare un nome al catalogo indipendentemente dal nome del bucket. I cataloghi multi-bucket non sono supportati nella console Google Cloud .
  • Bucket singolo (gs://): questa configurazione limita il catalogo a un singolo bucket e blocca il nome del catalogo sul nome del bucket. È sconsigliato per i nuovi progetti.

Località

Familiarizza con i requisiti relativi alla località prima di creare un catalogo.

  • Quando crei uno spazio dei nomi, questo utilizza automaticamente la stessa regione del catalogo.

  • Se il tuo catalogo utilizza un bucket multiregionale e vuoi utilizzarlo con le multi-regioni BigQuery (US o EU), devi eliminare e ricreare il catalogo per specificare la località principale.

Crea un catalogo

Segui questi passaggi per creare un catalogo in base alla modalità di credenziali e al tipo di bucket che preferisci.

Credenziali utente finale

Console

  1. Apri la pagina Lakehouse nella console Google Cloud .

    Vai a Lakehouse

  2. Fai clic su Crea catalogo.

  3. Per Tipo di catalogo, seleziona Bucket Cloud Storage.

  4. Inserisci o cerca il bucket Cloud Storage da utilizzare con il catalogo (per un catalogo a bucket singolo (gs://), puoi avere un solo catalogo per bucket e il nome del catalogo corrisponde al nome del bucket).

  5. In Authentication method (Metodo di autenticazione), seleziona End-user credentials (Credenziali utente finale).

  6. Fai clic su Crea.

gcloud

Creare un catalogo multibrand (bl://) (consigliato)

Questa configurazione consente al catalogo di associare più bucket e di assegnare un nome al catalogo indipendentemente dal nome di qualsiasi bucket.

Per creare un catalogo multibracket (bl://), consigliato, esegui il comando gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    --credential-mode end-user \
    [--primary-location LOCATION]

Crea un catalogo a un solo bucket (gs://)

Per creare un catalogo a un solo bucket (gs://), esegui questo comando:

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user

Sostituisci quanto segue:

  • CATALOG_NAME: un nome per il catalogo. Per i cataloghi multi-bucket (bl://) (consigliati), questo è il nome del catalogo personalizzato. Per i cataloghi a bucket singolo (gs://), questo valore corrisponde all'ID bucket Cloud Storage utilizzato con il catalogo REST. Questo nome viene utilizzato anche come identificatore del catalogo quando esegui query su queste tabelle da BigQuery.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • DEFAULT_LOCATION: specifica la posizione di archiviazione predefinita per il catalogo. Puoi specificare un bucket (gs://my-bucket) o un percorso secondario (gs://my-bucket/path). Tutti gli spazi dei nomi e le tabelle del catalogo devono trovarsi nel percorso specificato. Ad esempio, se specifichi gs://my-bucket/path, non puoi creare spazi dei nomi o tabelle in gs://my-bucket/another/path.
  • RESTRICTED_LOCATIONS: (facoltativo) elenco separato da virgole di posizioni di archiviazione consentite aggiuntive, nel formato gs://my-bucket-1/...,gs://my-bucket-2/.... Se specifichi un percorso (ad esempio gs://my-bucket/path), tutti gli spazi dei nomi o le tabelle all'interno di quel bucket devono trovarsi in quel percorso. Tutte le località di spazio di archiviazione sul cloud configurate nella località predefinita e nelle località con limitazioni devono trovarsi nello stesso gruppo di regioni geografiche o nella stessa giurisdizione (ad esempio Stati Uniti, Europa, Canada o Asia). Ad esempio, non puoi combinare un bucket negli Stati Uniti con un bucket in Europa. Per un elenco delle località supportate, consulta Località Lakehouse. Avviso di sicurezza:evita di configurare percorsi sovrapposti con altri cataloghi per impedire l'esposizione non autorizzata delle credenziali. Per saperne di più, vedi Archiviazione in più bucket.
  • LOCATION: (facoltativo) la regione principale per il catalogo per garantire l'interoperabilità con BigQuery. Per i bucket Cloud Storage nella regione Stati Uniti (ad esempio US o us-central1) o nella regione UE (ad esempio EU o europe-west4), specifica US o EU rispettivamente per assicurarti che il catalogo sia accessibile e disponibile per le query dalle multiregioni BigQuery corrispondenti. Per saperne di più, consulta Regioni dei bucket e dei cataloghi.

Modalità di distribuzione delle credenziali

Un amministratore del catalogo attiva la distribuzione delle credenziali quando crea o aggiorna un catalogo. In qualità di utente del catalogo, puoi quindi indicare all'endpoint del catalogo REST di Apache Iceberg di restituire credenziali di archiviazione con ambito ridotto specificando la delega di accesso quando configuri l'endpoint del catalogo REST di Apache Iceberg.

Il account di servizio del catalogo del runtime Lakehouse di cui è stato eseguito il provisioning automatico richiede il ruolo Storage Object User (roles/storage.objectUser) esplicito su tutti i bucket Cloud Storage associati. Per impostazione predefinita, non ha alcun accesso. Senza questo ruolo, le credenziali vendute non avranno un ambito sufficiente per eseguire scritture di archiviazione. Se utilizzi strumenti come gcloud o Terraform, devi concedere questo ruolo manualmente.

Console

  1. Nella console Google Cloud , apri la pagina Lakehouse.

    Vai a Lakehouse

  2. Fai clic su Crea catalogo. Viene visualizzata la pagina Crea catalogo.

  3. Per Tipo di catalogo, seleziona Bucket Cloud Storage.

  4. Inserisci o cerca il bucket Cloud Storage da utilizzare con il catalogo (per un catalogo a bucket singolo (gs://), puoi avere un solo catalogo per bucket e il nome del catalogo corrisponde al nome del bucket).

  5. In Authentication method (Metodo di autenticazione), seleziona Credential vending mode (Modalità di distribuzione delle credenziali).

  6. Fai clic su Crea.

    Il catalogo viene creato e si apre la pagina Dettagli catalogo.

  7. Nella sezione Metodo di autenticazione, fai clic su Imposta autorizzazioni bucket.

  8. Nella finestra di dialogo, fai clic su Conferma.

    In questo modo viene verificato che il account di servizio del catalogo disponga del ruolo Storage Object User su tutti i bucket di archiviazione associati.

gcloud

Creare un catalogo multibrand (bl://) (consigliato)

Questa configurazione consente al catalogo di associare più bucket e di assegnare un nome al catalogo indipendentemente dal nome di qualsiasi bucket.

Per creare un catalogo multibracket (bl://), consigliato, esegui il comando gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    --credential-mode vended-credentials \
    [--primary-location LOCATION]

Crea un catalogo a un solo bucket (gs://)

Per creare un catalogo a un solo bucket (gs://), esegui questo comando:

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode vended-credentials

Sostituisci quanto segue:

  • CATALOG_NAME: un nome per il catalogo. Per i cataloghi multi-bucket (bl://) (consigliati), questo è il nome del catalogo personalizzato. Per i cataloghi a bucket singolo (gs://), questo valore corrisponde all'ID bucket Cloud Storage utilizzato con il catalogo REST. Questo nome viene utilizzato anche come identificatore del catalogo quando esegui query su queste tabelle da BigQuery.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • DEFAULT_LOCATION: specifica la posizione di archiviazione predefinita per il catalogo. Puoi specificare un bucket (gs://my-bucket) o un percorso secondario (gs://my-bucket/path). Tutti gli spazi dei nomi e le tabelle del catalogo devono trovarsi nel percorso specificato. Ad esempio, se specifichi gs://my-bucket/path, non puoi creare spazi dei nomi o tabelle in gs://my-bucket/another/path.
  • RESTRICTED_LOCATIONS: (facoltativo) elenco separato da virgole di posizioni di archiviazione consentite aggiuntive, nel formato gs://my-bucket-1/...,gs://my-bucket-2/.... Se specifichi un percorso (ad esempio gs://my-bucket/path), tutti gli spazi dei nomi o le tabelle all'interno di quel bucket devono trovarsi in quel percorso. Tutte le località di spazio di archiviazione sul cloud configurate nella località predefinita e nelle località con limitazioni devono trovarsi nello stesso gruppo di regioni geografiche o nella stessa giurisdizione (ad esempio Stati Uniti, Europa, Canada o Asia). Ad esempio, non puoi combinare un bucket negli Stati Uniti con un bucket in Europa. Per un elenco delle località supportate, consulta Località Lakehouse. Avviso di sicurezza:evita di configurare percorsi sovrapposti con altri cataloghi per impedire l'esposizione non autorizzata delle credenziali. Per saperne di più, vedi Archiviazione in più bucket.

  • LOCATION: (facoltativo) la regione principale per il catalogo per garantire l'interoperabilità con BigQuery. Per i bucket Cloud Storage nella regione Stati Uniti (ad esempio US o us-central1) o nella regione UE (ad esempio EU o europe-west4), specifica US o EU rispettivamente per assicurarti che il catalogo sia accessibile e disponibile per le query dalle multiregioni BigQuery corrispondenti. Per saperne di più, consulta Regioni dei bucket e dei cataloghi.

    Dopo aver creato il catalogo, concedi esplicitamente il ruolo Storage Object User (roles/storage.objectUser) su tutti i bucket di archiviazione associati al account di servizio del catalogo runtime Lakehouse di cui è stato eseguito il provisioning automatico.

Configura l'applicazione client

Dopo aver creato un catalogo, configura l'applicazione client per utilizzarlo. Questi esempi mostrano come configurare con o senza la distribuzione delle credenziali.

Cluster

Crea un cluster Managed Service for Apache Spark su Compute Engine utilizzando proprietà di configurazione semplificate (consigliato) o specificando le proprietà manualmente.

Crea un cluster con la proprietà catalogo:

gcloud dataproc clusters create CLUSTER_NAME \
  --enable-component-gateway \
  --project=PROJECT_ID \
  --region=REGION \
  --optional-components=ICEBERG \
  --image-version=DATAPROC_VERSION \
  --properties="dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Sostituisci quanto segue:

  • CLUSTER_NAME: un nome per il cluster.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • REGION: la regione del cluster Managed Service for Apache Spark.
  • DATAPROC_VERSION: la versione dell'immagine Managed Service for Apache Spark, ad esempio 2.3.
  • CATALOG_NAME: un nome per il catalogo Spark locale (ad esempio my_catalog). Può essere uguale a CATALOG_ID.
  • CATALOG_ID: l'ID del catalogo che hai creato.

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, crea un cluster come descritto in precedenza, ma senza il flag --properties. A questo punto, configura manualmente SparkSession:

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/REST_API_VERSION/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 esempio my_catalog).
  • APP_NAME: un nome per la sessione Spark.
  • REST_API_VERSION: impostato su v1 per la versione stabile dell'API.
  • WAREHOUSE_PATH: il percorso del tuo warehouse. Per i cataloghi BigLake, utilizza bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Per i cataloghi dei bucket Cloud Storage, utilizza gs://CLOUD_STORAGE_BUCKET_NAME. Per utilizzare la federazione del catalogo BigQuery, consulta Utilizzare la federazione del catalogo con BigQuery.
  • PROJECT_ID: il progetto a cui viene addebitato l'utilizzo dell'endpoint del catalogo REST Apache Iceberg, che potrebbe essere diverso dal progetto proprietario del bucket Cloud Storage. Per informazioni dettagliate sulla configurazione del progetto quando utilizzi un'API REST, vedi Parametri di sistema.

Configurare 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 di vended-credentials aggiungendo la seguente riga al builder SparkSession: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Esempio con distribuzione delle credenziali

Il seguente esempio configura il motore di query con la distribuzione delle credenziali:

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/REST_API_VERSION/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()

Per saperne di più, consulta la sezione Intestazioni in RESTCatalog della documentazione di Apache Iceberg.

I cluster Managed Service for Apache Spark supportano i flussi di autorizzazione Google per Apache Iceberg nelle seguenti release:

  • Versioni immagine 2.2 di Managed Service for Apache Spark su Compute Engine 2.2.65 e successive.
  • Versioni dell'immagine Managed Service for Apache Spark su Compute Engine 2.3 2.3.11 e successive.

Serverless

Invia un workload batch PySpark a Managed Service for Apache Spark utilizzando proprietà di configurazione semplificate (consigliato) o specificando le proprietà manualmente.

Invia un job batch con la proprietà del catalogo:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Sostituisci quanto segue:

  • PYSPARK_FILE: il percorso Cloud Storage gs:// del file dell'applicazione PySpark.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • REGION: la regione per il workload batch Managed Service for Apache Spark.
  • RUNTIME_VERSION: la versione del runtime di Managed Service for Apache Spark, ad esempio 2.3.
  • CATALOG_NAME: un nome per il catalogo Spark locale (ad esempio my_catalog). Può essere uguale a CATALOG_ID.
  • CATALOG_ID: l'ID del catalogo che hai creato.

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, devi specificare manualmente le configurazioni del catalogo:

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/REST_API_VERSION/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 quanto segue:

  • PYSPARK_FILE: il percorso Cloud Storage gs:// del file dell'applicazione PySpark.
  • REGION: la regione per il workload batch Managed Service for Apache Spark.
  • RUNTIME_VERSION: la versione del runtime di Managed Service for Apache Spark, ad esempio 2.3.
  • CATALOG_NAME: un nome per il catalogo Spark locale (ad esempio my_catalog).
  • REST_API_VERSION: impostato su v1 per la versione stabile dell'API.
  • WAREHOUSE_PATH: il percorso del tuo warehouse. Per i cataloghi BigLake, utilizza bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Per i cataloghi dei bucket Cloud Storage, utilizza gs://CLOUD_STORAGE_BUCKET_NAME. Per utilizzare la federazione del catalogo BigQuery, consulta Utilizzare la federazione del catalogo con BigQuery.
  • PROJECT_ID: il progetto a cui viene addebitato l'utilizzo dell'endpoint del catalogo REST Apache Iceberg, che potrebbe essere diverso dal progetto proprietario del bucket Cloud Storage. Per informazioni dettagliate sulla configurazione del progetto quando utilizzi un'API REST, vedi Parametri di sistema.

Configurare 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 dell'endpoint del catalogo REST di Apache Iceberg con un valore di vended-credentials aggiungendo la seguente riga alle configurazioni di Managed Service for Apache Spark: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Esempio con distribuzione delle credenziali

Il seguente esempio configura il motore di query con la 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/REST_API_VERSION/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

Per saperne di più, consulta la sezione Intestazioni in RESTCatalog della documentazione di Apache Iceberg.

Managed Service for Apache Spark supporta i flussi di autorizzazione Google per Apache Iceberg nelle seguenti versioni del runtime:

  • Runtime 2.2.60 e versioni successive di Managed Service for Apache Spark 2.2
  • Runtime Managed Service for Apache Spark 2.3 2.3.10 e versioni successive

Trino

Per utilizzare Trino con l'endpoint del catalogo REST di Apache Iceberg, crea un cluster Managed Service for Apache Spark con il componente Trino e configura le proprietà del catalogo utilizzando il flag gcloud dataproc clusters create --properties. L'esempio seguente crea un catalogo Trino denominato CATALOG_NAME:

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=REGION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=WAREHOUSE_PATH,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.biglake.project-id=PROJECT_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager"

Sostituisci quanto segue:

  • CLUSTER_NAME: un nome per il cluster.
  • REGION: la regione del cluster Managed Service for Apache Spark.
  • DATAPROC_VERSION: la versione dell'immagine di Managed Service for Apache Spark, ad esempio 2.2.
  • NETWORK_ID: ID rete cluster. Per maggiori informazioni, vedi Configurazione di rete del cluster Managed Service for Apache Spark.
  • CATALOG_NAME: il nome del catalogo Trino che utilizza l'endpoint del catalogo REST Apache Iceberg.
  • REST_API_VERSION: impostato su v1 per la versione stabile dell'API.
  • WAREHOUSE_PATH: il percorso del tuo warehouse. Per i cataloghi BigLake, utilizza bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Per i cataloghi dei bucket Cloud Storage, utilizza gs://CLOUD_STORAGE_BUCKET_NAME.
  • PROJECT_ID: il tuo ID progetto Google Cloud da utilizzare per il catalogo runtime Lakehouse.

Dopo la creazione del cluster, connettiti all'istanza VM principale e utilizza la CLI Trino:

trino --catalog=CATALOG_NAME

Managed Service for Apache Spark Trino supporta i flussi di autorizzazione Google per Apache Iceberg nelle seguenti release:

  • Versioni del runtime di Managed Service for Apache Spark su Compute Engine 2.2 2.2.65 e successive
  • Versioni del runtime di Managed Service for Apache Spark su Compute Engine 2.3 2.3.11 e successive
  • Managed Service for Apache Spark su Compute Engine 3.0 non è supportato.

Configurare con la distribuzione delle credenziali

La distribuzione delle credenziali è supportata solo su Trino versione 481 e successive.

Apache Iceberg 1.10 o versioni successive

Le versioni open source di Apache Iceberg 1.10 e successive hanno il supporto integrato per i flussi di autorizzazione Google in GoogleAuthManager. Di seguito è riportato un esempio di come configurare Spark per utilizzare l'endpoint del catalogo REST di Apache Iceberg.

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_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/REST_API_VERSION/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') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Sostituisci quanto segue:

  • CATALOG_NAME: un nome per il catalogo Spark locale (ad esempio my_catalog).
  • APP_NAME: un nome per la sessione Spark.
  • REST_API_VERSION: impostato su v1 per la versione stabile dell'API.
  • WAREHOUSE_PATH: il percorso del tuo warehouse. Per i cataloghi BigLake, utilizza bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Per i cataloghi dei bucket Cloud Storage, utilizza gs://CLOUD_STORAGE_BUCKET_NAME. Per utilizzare la federazione del catalogo BigQuery, consulta Utilizzare la federazione del catalogo con BigQuery.
  • PROJECT_ID: il progetto a cui viene addebitato l'utilizzo dell'endpoint del catalogo REST di Apache Iceberg, che potrebbe essere diverso dal progetto proprietario del bucket Cloud Storage. Per informazioni dettagliate sulla configurazione del progetto quando utilizzi un'API REST, vedi Parametri di sistema.

Configurare con la distribuzione delle credenziali

L'esempio precedente non utilizza 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 dell'endpoint del catalogo REST di Apache Iceberg con un valore di vended-credentials aggiungendo la seguente riga al builder SparkSession: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Esempio con distribuzione delle credenziali

Il seguente esempio configura il motore di query con la distribuzione delle credenziali:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_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/REST_API_VERSION/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') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Per saperne di più, consulta la sezione Intestazioni in RESTCatalog della documentazione di Apache Iceberg.

Versioni precedenti di Apache Iceberg

Per le release open source di Apache Iceberg precedenti alla 1.10, puoi configurare l'autenticazione OAuth standard configurando una sessione con quanto 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.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.9.1,org.apache.iceberg:iceberg-gcp-bundle:1.9.1') \
  .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/REST_API_VERSION/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}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .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') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Sostituisci quanto segue:

  • CATALOG_NAME: un nome per il catalogo Spark locale (ad esempio my_catalog).
  • APP_NAME: un nome per la sessione Spark.
  • REST_API_VERSION: impostato su v1 per la versione stabile dell'API.
  • WAREHOUSE_PATH: il percorso del tuo warehouse. Per i cataloghi BigLake, utilizza bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Per i cataloghi dei bucket Cloud Storage, utilizza gs://CLOUD_STORAGE_BUCKET_NAME. Per utilizzare la federazione del catalogo BigQuery, consulta Utilizzare la federazione del catalogo con BigQuery.
  • PROJECT_ID: il progetto a cui viene addebitato l'utilizzo dell'endpoint del catalogo REST di Apache Iceberg, che potrebbe essere diverso dal progetto proprietario del bucket Cloud Storage. Per informazioni dettagliate sulla configurazione del progetto quando utilizzi un'API REST, vedi Parametri di sistema.
  • TOKEN: il token di autenticazione, valido per un'ora, ad esempio un token generato utilizzando gcloud auth application-default print-access-token.

Configurare con la distribuzione delle credenziali

L'esempio precedente non utilizza 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 dell'endpoint del catalogo REST di Apache Iceberg con un valore di vended-credentials aggiungendo la seguente riga al builder SparkSession: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Esempio con distribuzione delle credenziali

Il seguente esempio configura il motore di query con la distribuzione delle credenziali:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_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/REST_API_VERSION/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}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .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') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Per saperne di più, consulta la sezione Intestazioni in RESTCatalog della documentazione di Apache Iceberg.

Creare uno spazio dei nomi o uno schema

Dopo aver configurato il client, crea uno spazio dei nomi o uno schema per organizzare le tabelle. La sintassi per creare uno spazio dei nomi o uno schema varia a seconda del motore di query. Gli esempi riportati di seguito mostrano come crearli utilizzando Spark e Trino.

Console

  1. Nella console Google Cloud , vai a Lakehouse.

    Vai a Lakehouse

  2. Seleziona un catalogo esistente o creane uno se non ne hai.

  3. Nella barra dei menu, fai clic su + Crea spazio dei nomi.

  4. In Nome spazio dei nomi, inserisci un nome univoco per lo spazio dei nomi.

  5. In Posizione, specifica il percorso da associare al tuo spazio dei nomi:

    • Multi-bucket (bl://) (consigliato): puoi impostare qualsiasi località personalizzata, purché si trovi in una località consentita dal catalogo (default_location o restricted_locations). Se non specifichi una località, lo spazio dei nomi viene creato nella località predefinita del catalogo (ad esempio, gs://{path-to-default-location}/{namespace_name}). Tieni presente che i cataloghi multi-bucket (bl://) (consigliati) non possono essere gestiti nella console.
    • Bucket singolo (gs://): la posizione dello spazio dei nomi viene ereditata automaticamente dal bucket singolo del catalogo.

  6. Fai clic su Crea.

Spark

Warehouse Cloud Storage

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME;")
spark.sql("USE NAMESPACE_NAME;")

Sostituisci NAMESPACE_NAME con un nome per lo spazio dei nomi.

Trino

Warehouse Cloud Storage

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;
USE CATALOG_NAME.SCHEMA_NAME;

Sostituisci quanto segue:

  • CATALOG_NAME: il nome del catalogo Trino che utilizza l'endpoint del catalogo REST Apache Iceberg.
  • SCHEMA_NAME: un nome per lo schema.

Eseguire l'upgrade di un catalogo

Se hai un catalogo esistente con un solo bucket (gs://), puoi eseguire l'upgrade a un tipo di catalogo con più bucket (bl://), che è consigliato. L'upgrade ti consente di associare più bucket e configurare posizioni con limitazioni mantenendo il nome originale del catalogo.

Per eseguire l'upgrade del catalogo, vedi Aggiornare un catalogo.

Passaggi successivi