Utilizza il catalogo REST di Iceberg del metastore BigLake

Il catalogo REST di Apache Iceberg in BigLake Metastore è il modo consigliato per utilizzare BigLake Metastore per i nuovi flussi di lavoro. Crea interoperabilità tra i motori di query offrendo un'unica fonte attendibile per tutti i dati Iceberg. Consente ai motori di query, come Apache Spark, di rilevare, leggere i metadati e gestire le tabelle Iceberg in modo coerente.

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, tra cui 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, il catalogo Iceberg personalizzato per 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

Acquisisci familiarità con BigLake Metastore prima di continuare.

1. Verify that billing is enabled for your Google Cloud project.

2. Enable the BigLake API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per utilizzare il catalogo REST Iceberg in BigLake Metastore, 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:
  • BigLake Admin (roles/biglake.admin) sul progetto
  • Amministratore Storage (roles/storage.admin) sul bucket Cloud Storage
• 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:
  • BigLake Viewer (roles/biglake.viewer) sul progetto
  • Visualizzatore oggetti Storage (roles/storage.objectViewer) sul bucket Cloud Storage
• Gestisci le risorse del catalogo e scrivi i dati delle tabelle in modalità non di distribuzione delle credenziali:
  • BigLake Editor (roles/biglake.editor) sul progetto
  • Storage Object User (roles/storage.objectUser) sul bucket Cloud Storage

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

Il catalogo Iceberg REST è soggetto alle seguenti limitazioni:

• 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.
• Trino è supportato solo con la federazione del catalogo BigQuery quando si utilizzano le versioni 2.3.16 e successive delle immagini Dataproc su Compute Engine.

Risorse del catalogo

Il catalogo REST di Apache Iceberg in BigLake Metastore utilizza una gerarchia di risorse per organizzare i dati.

Risorse del catalogo REST di Apache Iceberg

La seguente tabella fornisce una panoramica generale delle risorse utilizzate dal catalogo REST di Apache Iceberg in BigLake Metastore.

Risorsa	Descrizione
Catalogo	Il contenitore di primo livello, un catalogo, consente di organizzare spazi dei nomi e tabelle in gruppi logici dividendoli in cataloghi diversi.
Spazio dei nomi	Un raggruppamento logico utilizzato per organizzare le tabelle all'interno di un catalogo, questo funziona come database, schemi o directory.
Tabella	Le tabelle contengono definizioni di righe e colonne su cui è possibile eseguire query.

Cataloghi supportati

Quando configuri il client, specifichi una posizione del magazzino. Questa scelta determina il funzionamento del catalogo e la sua integrazione con altri Google Cloud servizi.

Tipo di catalogo	Descrizione
Bucket Cloud Storage	Tutti i dati di un catalogo vengono archiviati in un unico bucket Cloud Storage; per i dati condivisi in più bucket, sono necessari più cataloghi.
Federazione BigQuery	Consente di utilizzare il catalogo REST di Iceberg per gestire ed eseguire query sulle tabelle visibili a BigQuery. Per ulteriori informazioni, vedi Utilizzare la federazione dei cataloghi con BigQuery.

Dettagli del warehouse del catalogo

Consigliato

• Warehouse dei bucket Cloud Storage (gs://): questo è l'approccio standard in cui il catalogo gestisce direttamente i metadati e i file di dati Iceberg in un bucket Cloud Storage specificato. Questa opzione ti offre il controllo diretto sul layout dei dati e supporta la distribuzione delle credenziali percontrollo dell'accessoso granulare. In questo modo puoi creare e gestire tabelle BigLake per Apache Iceberg.

  Importante: per i cataloghi che utilizzano un bucket Cloud Storage come warehouse, il nome del catalogo è anche l'identificatore della risorsa catalogo.

  Ad esempio, se hai creato il bucket per archiviare il catalogo e l'hai chiamato iceberg-bucket, sia il nome del catalogo sia il nome del bucket sono iceberg-bucket. Questo valore viene utilizzato in un secondo momento quando esegui query sul catalogo in BigQuery, utilizzando la sintassi P.C.N.T. Ad esempio my-project.biglake-catalog-id.quickstart_namespace.quickstart_table.

Legacy

• Federazione BigQuery (bq://): questo approccio ti consente di utilizzare il catalogo REST Iceberg per gestire ed eseguire query sulle tabelle visibili a BigQuery, senza dover creare una risorsa catalogo. Per ulteriori informazioni, vedi Utilizzare la federazione del catalogo con BigQuery.

Struttura di denominazione P.C.N.T

Quando esegui query sulle tabelle del metastore BigLake da BigQuery, utilizzi una struttura di denominazione in quattro parti, spesso chiamata P.C.N.T:

• Progetto: l' Google Cloud ID progetto proprietario del catalogo.
• Catalogo: il nome del catalogo metastore BigLake.
• Namespace: lo spazio dei nomi Iceberg (equivalente a un set di dati BigQuery).
• Tabella: il nome della tabella.

Ad esempio, my-project.biglake-catalog-id.my-namespace.my-table.

Configura il catalogo REST di Iceberg

Di seguito sono riportati i passaggi generali da seguire quando utilizzi il catalogo REST di Apache Iceberg in BigLake metastore:

1. Comprendere e scegliere la posizione del magazzino 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 in modo che utilizzi il catalogo REST di 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 dell'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 di BigLake Metastore di controllare le autorizzazioni direttamente sulle risorse BigLake Metastore, eliminando la necessità che gli utenti del catalogo abbiano accesso diretto ai bucket Cloud Storage. Consente agli amministratori BigLake di concedere agli utenti autorizzazioni su file di dati specifici.

Credenziali utente finale

Console

1. Apri la pagina BigLake nella console Google Cloud .

   Vai a BigLake

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 beta biglake iceberg catalogs create.

gcloud beta 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 le tabelle BigLake gestite per Apache Iceberg, questo nome spesso corrisponde all'ID bucket Cloud Storage utilizzato con il catalogo REST. Ad esempio, se il tuo bucket è gs://bucket-id, il nome del catalogo potrebbe essere bucket-id. 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 .

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 al catalogo REST di Iceberg di restituire le credenziali di archiviazione con ambito ridotto specificando la delega dell'accesso quando configuri il catalogo REST di Iceberg.

Console

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

   Vai a BigLake

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.

Configurare 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 il catalogo REST di Iceberg su Dataproc, crea prima un cluster che includa il componente 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 del cluster Dataproc.
• DATAPROC_VERSION: la versione dell'immagine Dataproc, ad esempio 2.2.

Dopo aver creato il cluster, configura la sessione Spark per utilizzare il catalogo REST di 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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Sostituisci quanto segue:

• CATALOG_NAME: il nome del catalogo Iceberg REST.
• APP_NAME: un nome per la sessione Spark.
• WAREHOUSE_PATH: il percorso del tuo warehouse. 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 fatturato l'utilizzo del catalogo REST di 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .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 Iceberg.

I cluster Dataproc supportano i flussi di autorizzazione Google per Iceberg nelle seguenti release:

• Dataproc sulle versioni dell'immagine Compute Engine 2.2 2.2.65 e successive.
• Dataproc su Compute Engine versioni immagine 2.3 2.3.11 e successive.

Serverless

Invia un workload batch PySpark a Google Cloud Serverless per 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/v1/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,\
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false"

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 carico di lavoro batch Dataproc.
• RUNTIME_VERSION: la versione del runtime di Serverless per Apache Spark, ad esempio 2.2.
• CATALOG_NAME: il nome del catalogo Iceberg REST.
• WAREHOUSE_PATH: il percorso del tuo warehouse. Utilizza gs://CLOUD_STORAGE_BUCKET_NAME. Per utilizzare la federazione del catalogo BigQuery, 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 del catalogo REST di Iceberg con un valore di vended-credentials aggiungendo la seguente riga alle configurazioni di Serverless per 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/v1/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.rest-metrics-reporting-enabled=false,
    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 Iceberg.

Serverless per Apache Spark supporta i flussi di autorizzazione Google per Iceberg nelle seguenti versioni di runtime:

• Runtime Serverless per Apache Spark 2.2 2.2.60 e versioni successive
• Runtime 2.3.10 e versioni successive di Serverless per Apache Spark 2.3

Trino

Per utilizzare Trino con il catalogo REST di Iceberg, crea un cluster Dataproc 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/v1/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 Dataproc.
• DATAPROC_VERSION: versione immagine Dataproc, ad esempio 2.2.
• NETWORK_ID: l'ID rete del cluster. Per saperne di più, consulta Configurazione di rete del cluster Dataproc.
• CATALOG_NAME: il nome del catalogo Trino che utilizza il catalogo REST di Iceberg.
• WAREHOUSE_PATH: il percorso del tuo warehouse. Utilizza gs://CLOUD_STORAGE_BUCKET_NAME.
• PROJECT_ID: il tuo ID progetto Google Cloud da utilizzare per BigLake Metastore.

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

trino --catalog=CATALOG_NAME

Dataproc Trino supporta i flussi di autorizzazione Google per Iceberg nelle seguenti release:

• Versioni runtime di Dataproc su Compute Engine 2.2 2.2.65 e successive
• Versioni runtime di Dataproc su Compute Engine 2.3 2.3.11 e successive
• Dataproc su Compute Engine 3.0 non è supportato.

Configurare con la distribuzione delle credenziali

La distribuzione delle credenziali non è supportata su Dataproc Trino.

Iceberg 1.10 o versioni successive

Le versioni open source di 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 Apache Spark per utilizzare il catalogo REST di Iceberg di BigLake Metastore.

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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Sostituisci quanto segue:

• CATALOG_NAME: il nome del catalogo Iceberg REST.
• APP_NAME: un nome per la sessione Spark.
• WAREHOUSE_PATH: il percorso del tuo warehouse. 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 fatturato l'utilizzo del catalogo REST di 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 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .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 Iceberg.

Versioni precedenti di Iceberg

Per le versioni open source di 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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Sostituisci quanto segue:

• CATALOG_NAME: il nome del catalogo Iceberg REST.
• APP_NAME: un nome per la sessione Spark.
• WAREHOUSE_PATH: il percorso del tuo warehouse. 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 fatturato l'utilizzo del catalogo REST di 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 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .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 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.

Attenzione: se utilizzi la distribuzione delle credenziali, non creare spazi dei nomi o schemi all'interno di altri spazi dei nomi o schemi, perché in questo modo puoi concedere agli utenti l'accesso a risorse non previste.

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 il catalogo REST di Iceberg.
• SCHEMA_NAME: un nome per lo schema.

Esegui query sulle tabelle in BigQuery

Il modo in cui esegui query sulle tabelle create tramite il catalogo Iceberg REST 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. Il componente catalog è il nome della risorsa catalogo metastore BigLake. Per ulteriori informazioni, 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 SQL BigQuery 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

Puoi utilizzare l'interfaccia del catalogo REST di Iceberg per gestire ed eseguire query sulle tabelle visibili a BigQuery. I cataloghi di federazione BigQuery non richiedono la creazione di una risorsa catalogo; possono essere utilizzati in qualsiasi progetto in cui è abilitata l'API BigQuery. In questo modo potrai:

• Crea e gestisci tabelle Iceberg esterne in BigQuery.
• Esegui query sulle tabelle BigLake per Apache Iceberg in BigQuery con il catalogo REST Iceberg.

Poiché queste risorse sono gestite da BigQuery, devi disporre delle autorizzazioni richieste applicabili. La distribuzione delle credenziali non è supportata per i cataloghi federati.

Per abilitare la federazione, configura il client con il formato del warehouse bq://projects/PROJECT_ID nel campo WAREHOUSE_PATH degli esempi di configurazione del client in Utilizzare il catalogo REST di Iceberg. 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.

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 che utilizza il catalogo REST di 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 Prezzi di BigLake.

Passaggi successivi

• Scopri come gestire i cataloghi nella console Google Cloud .

• Scopri di più sulle tabelle BigLake per Apache Iceberg.