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 il metastore BigLake e la panoramica del catalogo REST di Iceberg prima di continuare.

  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 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:
  • 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 al 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

Il catalogo Iceberg REST è 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 di Managed Service for Apache Spark su Compute Engine.
  • 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 il catalogo REST 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 ulteriori 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

  • Le viste sulle tabelle Iceberg gestite dal catalogo REST non possono essere create in BigQuery.
  • Non è possibile eseguire query sulle tabelle di metadati Iceberg (ad esempio .snapshots o .files) in BigQuery utilizzando identificatori di nomi in cinque parti; puoi eseguire query su queste tabelle utilizzando Spark.

Configura il catalogo REST Iceberg

Prima di configurare il catalogo, ti consigliamo di leggere la panoramica del catalogo Iceberg REST 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 il catalogo REST di Apache Iceberg in BigLake Metastore:

  1. In base alla Panoramica 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 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 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 metastore BigLake di controllare le autorizzazioni direttamente sulle risorse del metastore BigLake, 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 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 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 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 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.

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 il catalogo REST di Iceberg su Managed Service per Apache Spark, 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 per il cluster Managed Service per Apache Spark.
  • DATAPROC_VERSION: la versione dell'immagine di Managed Service per Apache Spark, 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 BigQuery catalog federation, consulta Utilizzare la federazione del catalogo con BigQuery.
  • PROJECT_ID: il progetto a cui viene fatturato l'utilizzo del catalogo REST 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 Managed Service per Apache Spark supportano i flussi di autorizzazione Google per Iceberg nelle seguenti release:

  • Managed Service per Apache Spark sulle versioni 2.2 delle immagini Compute Engine 2.2.65 e successive.
  • Managed Service per Apache Spark sulle versioni dell'immagine Compute Engine 2.3 2.3.11 e successive.

Serverless

Invia un workload batch PySpark a Managed Service 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 workload batch di Managed Service per Apache Spark.
  • RUNTIME_VERSION: la versione del runtime di Managed Service 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 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 del catalogo REST di 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/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.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token, \
    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.

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

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

Trino

Per utilizzare Trino con il catalogo REST di 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/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 Managed Service per Apache Spark.
  • DATAPROC_VERSION: versione dell'immagine di Managed Service per Apache Spark, ad esempio 2.2.
  • NETWORK_ID: ID rete cluster. Per maggiori informazioni, vedi Configurazione di rete del cluster Managed Service per Apache Spark.
  • 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

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

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

Configurare con la distribuzione delle credenziali

La distribuzione delle credenziali non è supportata su Managed Service per Apache Spark 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 BigQuery catalog federation, consulta Utilizzare la federazione del catalogo con BigQuery.
  • PROJECT_ID: il progetto a cui viene fatturato l'utilizzo del catalogo REST 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 BigQuery catalog federation, consulta Utilizzare la federazione del catalogo con BigQuery.
  • PROJECT_ID: il progetto a cui viene fatturato l'utilizzo del catalogo REST 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.

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. Per saperne di più sulla struttura di P.C.N.T., consulta Concetti del catalogo Iceberg REST. Il componente catalog è il nome della risorsa catalogo BigLake Metastore. 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 magazzino nel campo WAREHOUSE_PATH negli 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 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