Utilizza il catalogo REST Lakehouse Iceberg

Per i nuovi flussi di lavoro, ti consigliamo di utilizzare l'endpoint del catalogo REST di Apache Iceberg all'interno del catalogo di runtime Lakehouse.

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

Questo approccio è una buona scelta se utilizzi motori open source 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, familiarizza con il catalogo runtime Lakehouse e con la panoramica dell'endpoint del catalogo REST Iceberg.

  1. Verifica che la fatturazione sia abilitata 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 di 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:
  • Leggi i dati della tabella in modalità di distribuzione delle credenziali: Visualizzatore BigLake (roles/biglake.viewer) sul progetto
  • Scrivi i dati della tabella in modalità di distribuzione delle credenziali: Editor BigLake (roles/biglake.editor) sul progetto
  • 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:
  • Esegui operazioni DML (Data Manipulation Language) con la federazione del catalogo BigQuery:
    • Editor dati BigQuery (roles/bigquery.dataEditor) sul progetto
    • Amministratore Storage (roles/storage.admin) sul bucket Cloud Storage. Se utilizzi motori di query come Managed Service for Apache Spark per eseguire operazioni DML, concedi questi ruoli all'account di servizio che utilizzi per eseguire i job in quel motore.

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 Apache Iceberg è soggetto alle seguenti limitazioni:

Limitazioni generali

  • Trino è supportato solo con la federazione del catalogo BigQuery quando si utilizzano le versioni 2.3.16 e successive delle immagini Managed Service for Apache Spark su Compute Engine 2.3.
  • Quando utilizzi la modalità di distribuzione delle credenziali, devi impostare la proprietà io-impl su org.apache.iceberg.gcp.gcs.GCSFileIO. Il valore predefinito, org.apache.iceberg.hadoop.HadoopFileIO, non è supportato.

Limitazioni delle tabelle

  • Le tabelle gestite tramite l'endpoint del catalogo REST Apache Iceberg non supportano il controllo dell'accesso granulare (FGAC), ad esempio la sicurezza a livello di riga e di colonna.

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 degli Account Google.

Limitazioni delle query

  • Non è possibile creare visualizzazioni sulle tabelle Apache Iceberg gestite dall'endpoint del catalogo REST Apache Iceberg in BigQuery.
  • 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 di Apache Iceberg nel catalogo del runtime Lakehouse:

  1. In base alla Panoramica dell'endpoint del catalogo REST Iceberg, scegli la posizione del data warehouse del catalogo (Cloud Storage o BigQuery).
  2. Se utilizzi un warehouse Cloud Storage gs://, crea un catalogo che rimandi alla posizione del warehouse.
  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.

Crea un catalogo

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

  • Con le credenziali utente finale, il catalogo trasmette l'identità dell'utente finale che vi accede a Cloud Storage per i controlli di autorizzazione.

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

Credenziali utente finale

Console

  1. Apri la pagina Lakehouse nella console Google Cloud .

    Vai a Google Cloud Lakehouse

  2. Fai clic su Crea catalogo.

  3. 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. Puoi avere un solo catalogo per bucket Cloud Storage.

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

  5. Fai clic su Crea.

gcloud

Utilizza il comando gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user \
    [--primary-location LOCATION]

Sostituisci quanto segue:

  • CATALOG_NAME: un nome per il catalogo. Per le tabelle del catalogo REST di Lakehouse gestito per Apache Iceberg, questo nome spesso corrisponde all'ID bucket Cloud Storage utilizzato con il catalogo REST. Ad esempio, se il bucket è gs://bucket-id, il nome del catalogo potrebbe essere bucket-id. Questo nome viene utilizzato anche come identificatore del catalogo quando si eseguono query su queste tabelle da BigQuery.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • LOCATION: (facoltativo) la regione principale per il catalogo. Per i bucket multiregionali Cloud Storage USA o UE, specifica US o EU per assicurarti che il catalogo sia accessibile dalle regioni BigQuery corrispondenti. Per saperne di più, consulta Regioni del catalogo.

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 dell'accesso quando configuri l'endpoint del catalogo REST di Apache Iceberg.

Console

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

    Vai a Google Cloud Lakehouse

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

  3. Per 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 da un elenco di bucket esistenti o per crearne uno nuovo. Puoi avere un solo catalogo per bucket Cloud Storage.

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

  5. Fai clic su Crea.

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

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

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

    In questo modo viene verificato che il account di servizio del catalogo disponga del ruolo Utente oggetti Storage sul bucket di archiviazione.

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

Per utilizzare Spark con l'endpoint del catalogo REST di Apache Iceberg su Managed Service for Apache Spark, crea prima un cluster che includa il componente Apache Iceberg:

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION

Sostituisci quanto segue:

  • CLUSTER_NAME: un nome per il cluster.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • REGION: la regione per il cluster Managed Service for Apache Spark.
  • DATAPROC_VERSION: la versione dell'immagine di Managed Service for Apache Spark, ad esempio 2.2.

Dopo aver creato il cluster, configura la sessione 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: il nome dell'endpoint del catalogo REST Apache Iceberg.
  • APP_NAME: un nome per la sessione Spark.
  • REST_API_VERSION: impostato su v1 per la versione stabile dell'API. Imposta questo valore su v1beta se devi aggirare un problema noto con la generazione della derivazione dei dati.
  • WAREHOUSE_PATH: il percorso del tuo warehouse. Utilizza gs://CLOUD_STORAGE_BUCKET_NAME. Per utilizzare BigQuery catalog federation, 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

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 di 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', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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.

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 con la seguente configurazione:

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.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    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.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

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.2.
  • CATALOG_NAME: il nome dell'endpoint del catalogo REST Apache Iceberg.
  • REST_API_VERSION: impostato su v1 per la versione stabile dell'API. Imposta questo valore su v1beta se devi aggirare un problema noto con la generazione della derivazione dei dati.
  • WAREHOUSE_PATH: il percorso del tuo warehouse. Utilizza gs://CLOUD_STORAGE_BUCKET_NAME. Per utilizzare BigQuery catalog federation, consulta Utilizzare la federazione del catalogo con BigQuery.

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=gs://CLOUD_STORAGE_BUCKET_NAME,\
    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.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
    spark.sql.catalog.CATALOG_NAME.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token, \
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

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 Managed Service for Apache Spark 2.2 2.2.60 e versioni successive
  • 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 utilizzando l'endpoint del catalogo REST Apache Iceberg.
  • REST_API_VERSION: impostato su v1 per la versione stabile dell'API. Imposta questo valore su v1beta se devi aggirare un problema noto con la generazione della derivazione dei dati.
  • WAREHOUSE_PATH: il percorso del tuo warehouse. Utilizza gs://CLOUD_STORAGE_BUCKET_NAME.
  • PROJECT_ID: il tuo ID progetto Google Cloud da utilizzare per il catalogo di runtime di 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 non è supportata su Managed Service for Apache Spark Trino.

Apache Iceberg 1.10 o versioni successive

Apache Iceberg 1.10 e le versioni successive open source 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 runtime Lakehouse del catalogo REST 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: il nome dell'endpoint del catalogo REST Apache Iceberg.
  • APP_NAME: un nome per la sessione Spark.
  • REST_API_VERSION: impostato su v1 per la versione stabile dell'API. Imposta questo valore su v1beta se devi aggirare un problema noto con la generazione della derivazione dei dati.
  • WAREHOUSE_PATH: il percorso del tuo warehouse. Utilizza gs://CLOUD_STORAGE_BUCKET_NAME. Per utilizzare BigQuery catalog federation, 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', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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: il nome dell'endpoint del catalogo REST Apache Iceberg.
  • APP_NAME: un nome per la sessione Spark.
  • REST_API_VERSION: impostato su v1 per la versione stabile dell'API. Imposta questo valore su v1beta se devi aggirare un problema noto con la generazione della derivazione dei dati.
  • WAREHOUSE_PATH: il percorso del tuo warehouse. Utilizza gs://CLOUD_STORAGE_BUCKET_NAME. Per utilizzare BigQuery catalog federation, 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', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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.

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 utilizzando l'endpoint del catalogo REST Apache Iceberg.
  • SCHEMA_NAME: un nome per lo schema.

Esegui query sulle tabelle in BigQuery

Il modo in cui esegui query sulle tabelle create tramite l'endpoint del catalogo REST Apache Iceberg in BigQuery dipende dal fatto che utilizzi un warehouse di bucket Cloud Storage o la federazione BigQuery.

  • Warehouse dei bucket Cloud Storage: se hai configurato il client con un percorso del warehouse gs://, esegui query sulle tabelle da BigQuery utilizzando il nome in quattro parti (P.C.N.T) project.catalog.namespace.table. Per saperne di più sulla struttura di P.C.N.T., consulta Concetti del catalogo Iceberg REST. Il componente catalog è il nome della risorsa del catalogo del runtime Lakehouse. Per ulteriori informazioni sull'esecuzione di query sulle tabelle, vedi Eseguire una query su una tabella.

  • Federazione BigQuery: se hai configurato il client con un percorso del data warehouse bq://, le tabelle che crei sono visibili in BigQuery e possono essere sottoposte a query direttamente utilizzando BigQuery SQL standard:

    SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

    Sostituisci quanto segue:

    • NAMESPACE_NAME: il nome del tuo spazio dei nomi.
    • TABLE_NAME: il nome della tabella.

Utilizzare la federazione del catalogo con BigQuery

Per informazioni sulla federazione dei cataloghi, consulta Concetti del catalogo REST Iceberg. Per abilitare la federazione, configura il client con il formato bq://projects/PROJECT_ID del warehouse nel campo WAREHOUSE_PATH degli esempi di configurazione del client in Configura l'applicazione client. Puoi anche scegliere di includere una località BigQuery per limitare le richieste future a una singola località utilizzando il formato bq://projects/PROJECT_ID/locations/LOCATION.

Poiché queste risorse sono gestite da BigQuery, devi disporre delle autorizzazioni richieste applicabili.

Dopo aver configurato il client per la federazione, puoi creare uno spazio dei nomi per le tabelle federate.

Spark

Per utilizzare la federazione del catalogo BigQuery, includi le clausole LOCATION e DBPROPERTIES:

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME LOCATION 'gs://BUCKET_NAME/NAMESPACE_NAME' WITH DBPROPERTIES ('gcp-region' = 'LOCATION');")
spark.sql("USE NAMESPACE_NAME;")

Sostituisci quanto segue:

  • NAMESPACE_NAME: un nome per lo spazio dei nomi.
  • BUCKET_NAME: il bucket Cloud Storage che utilizzi con il catalogo.
  • LOCATION: una posizione BigQuery. Il valore predefinito è la multi-regione US.

Trino

Per utilizzare la federazione del catalogo BigQuery, includi le proprietà LOCATION e gcp-region:

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME WITH ( LOCATION = 'gs://BUCKET_NAME/SCHEMA_NAME', "gcp-region" = 'LOCATION');
USE CATALOG_NAME.SCHEMA_NAME;

Sostituisci quanto segue:

  • CATALOG_NAME: il nome del catalogo Trino utilizzando l'endpoint del catalogo REST Apache Iceberg.
  • SCHEMA_NAME: un nome per lo schema.
  • BUCKET_NAME: il bucket Cloud Storage che utilizzi con il catalogo.
  • LOCATION: una posizione BigQuery. Il valore predefinito è la multi-regione US.

Prezzi

Per i dettagli sui prezzi, consulta la pagina Prezzi di Google Cloud Lakehouse.

Passaggi successivi