Utilizza il metastore BigLake con il catalogo REST Iceberg

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Nota: per richiedere feedback o assistenza per questa funzionalità, invia un'email all'indirizzo [e-mail].

Il catalogo REST Apache Iceberg gestito in BigLake Metastore crea l'interoperabilità tra tutti i motori di query offrendo un'unica fonte di verità 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.

Le tabelle Iceberg che utilizzi con il catalogo REST Iceberg sono chiamate tabelle BigLake per Apache Iceberg (anteprima). Si tratta di tabelle Iceberg che crei da motori open source e archivi in Cloud Storage. Possono essere letti da motori open source o BigQuery. Le scritture sono supportate solo dai motori open source. In questo documento, ci riferiamo a queste tabelle come tabelle BigLake Iceberg.

Prima di iniziare

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

   Scopri come verificare se la fatturazione è abilitata per un progetto.

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

3. (Facoltativo) Chiedi a un amministratore di configurare la distribuzione delle credenziali per la prima volta.
4. (Facoltativo) Scopri come funziona il metastore BigLake e perché dovresti utilizzarlo.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per utilizzare il catalogo Iceberg REST in BigLake Metastore, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Eseguire attività amministrative, come la gestione dell'accesso degli utenti al catalogo, l'accesso allo spazio di archiviazione e la modalità 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) nel bucket Cloud Storage

Per ulteriori informazioni 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.

Configurare la modalità di distribuzione delle credenziali

La modalità di 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 di BigLake di concedere agli utenti autorizzazioni su file di dati specifici.

Un amministratore del catalogo attiva la distribuzione delle credenziali sul client del catalogo Iceberg REST.

In qualità di utente del catalogo, puoi quindi indicare al catalogo Iceberg REST di restituire le credenziali di archiviazione con ambito ridotto specificando la delega di accesso, che fa parte della specifica dell'API Iceberg REST Catalog. Per saperne di più, consulta Configurare un motore di query con il catalogo Iceberg REST.

Per inizializzare il catalogo e attivare la modalità di distribuzione delle credenziali, segui questi passaggi.

1. Inizializza il catalogo con il seguente comando:

   curl -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/v1/config?warehouse=gs://CLOUD_STORAGE_BUCKET_NAME

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID del tuo Google Cloud progetto.
   • CLOUD_STORAGE_BUCKET_NAME: il nome del bucket Cloud Storage che archivia la tabella Iceberg.

   L'output del comando curl è simile al seguente. Il valore del prefisso del catalogo si trova nel campo overrides.prefix della risposta:

   {
     "overrides": {
       "catalog_credential_mode": "CREDENTIAL_MODE_END_USER",
       "prefix": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME"
     },
     "endpoints": [
       "GET /v1/{prefix}/namespaces",
       "POST /v1/{prefix}/namespaces",
       "GET /v1/{prefix}/namespaces/{namespace}",
       "HEAD /v1/{prefix}/namespaces/{namespace}",
       "DELETE /v1/{prefix}/namespaces/{namespace}",
       "POST /v1/{prefix}/namespaces/{namespace}/properties",
       "GET /v1/{prefix}/namespaces/{namespace}/tables",
       "POST /v1/{prefix}/namespaces/{namespace}/tables",
       "GET /v1/{prefix}/namespaces/{namespace}/tables/{table}",
       "HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table}",
       "POST /v1/{prefix}/namespaces/{namespace}/tables/{table}",
       "DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}"
     ]
   }
   

2. Attiva la modalità di distribuzione delle credenziali ed estrai il account di servizio a cui concedere le autorizzazioni con il seguente comando:

   curl -X PATCH -H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/PREFIX?update_mask=credential_mode -d '{"credential_mode":"CREDENTIAL_MODE_VENDED_CREDENTIALS"}'

   Sostituisci PREFIX con il campo prefix dell'output del comando precedente.

   L'output comando curl contiene l'account di servizio, simile al seguente:

   {
     "name": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME",
     "credential_mode": "CREDENTIAL_MODE_VENDED_CREDENTIALS",
     "biglake-service-account": "BIGLAKE_SERVICE_ACCOUNT"
   }
   

3. Per assicurarti che il account di servizio BigLake estratto nel passaggio precedente disponga delle autorizzazioni necessarie per utilizzare la modalità di distribuzione delle credenziali, chiedi all'amministratore di concedergli il ruolo Utente oggetti Storage (roles/storage.objectUser) sul bucket di archiviazione.

   Importante: devi concedere questo ruolo al service account BigLake che hai estratto nel passaggio precedente, non al tuo account utente. La mancata concessione del ruolo all'entità corretta potrebbe comportare errori di autorizzazione.

Limitazioni

Il catalogo Iceberg REST è soggetto alle seguenti limitazioni:

• Non sono supportati i bucket multiregionali, i bucket a due regioni e i bucket con posizionamento personalizzato delle regioni.
• 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.

Configura il catalogo REST Iceberg

Cluster

Per utilizzare Spark con il catalogo Iceberg REST su Dataproc, crea innanzitutto un cluster con 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 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', '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}.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: un nome per il catalogo Iceberg REST.
• APP_NAME: un nome per la sessione Spark.
• CLOUD_STORAGE_BUCKET_NAME: il nome del bucket Cloud Storage che archivia le tabelle BigLake Iceberg.
• PROJECT_ID: il progetto a cui viene fatturato l'utilizzo del catalogo Iceberg REST, 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.

Questo esempio non utilizza la distribuzione delle credenziali. Per utilizzare la distribuzione delle credenziali, devi aggiungere l'intestazione X-Iceberg-Access-Delegation alle richieste del catalogo REST Iceberg con un valore di vended-credentials, aggiungendo la seguente riga al builder SparkSession:

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

Esempio con distribuzione delle credenziali

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

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

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(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 sulle versioni dell'immagine Compute Engine 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=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"

Sostituisci quanto segue:

• PYSPARK_FILE: il percorso gs:// Cloud Storage 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: un nome per il catalogo Iceberg REST.
• CLOUD_STORAGE_BUCKET_NAME: il nome del bucket Cloud Storage che archivia le tabelle BigLake Iceberg.

Per utilizzare la distribuzione delle credenziali, devi aggiungere l'intestazione X-Iceberg-Access-Delegation alle richieste del catalogo REST 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 di Serverless per Apache Spark 2.2 2.2.60 e versioni successive
• Runtime Serverless per Apache Spark 2.3 2.3.10 e versioni successive

Trino

Per utilizzare Trino con il catalogo REST 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=gs://CLOUD_STORAGE_BUCKET_NAME,\
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: ID rete cluster. Per saperne di più, consulta Configurazione di rete del cluster Dataproc.
• CATALOG_NAME: un nome per il catalogo Trino utilizzando il catalogo REST Iceberg.
• CLOUD_STORAGE_BUCKET_NAME: il nome del bucket Cloud Storage che archivia le tabelle BigLake Iceberg.
• PROJECT_ID: il tuo ID progetto Google Cloud da utilizzare per il metastore BigLake.

Dopo la creazione del cluster, utilizza SSH per connetterti all'istanza VM principale, quindi utilizza la CLI Trino nel seguente modo:

trino

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.

Importante: 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 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', '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}.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: un nome per il catalogo Iceberg REST.
• APP_NAME: un nome per la sessione Spark.
• CLOUD_STORAGE_BUCKET_NAME: il nome del bucket Cloud Storage che archivia le tabelle BigLake Iceberg.
• PROJECT_ID: il progetto a cui viene fatturato l'utilizzo del catalogo Iceberg REST, 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.

L'esempio precedente non utilizza la distribuzione delle credenziali. Per utilizzare la distribuzione delle credenziali, devi aggiungere l'intestazione X-Iceberg-Access-Delegation alle richieste del catalogo REST Iceberg con un valore di vended-credentials, aggiungendo la seguente riga al builder SparkSession:

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

Esempio con distribuzione delle credenziali

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

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

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(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 release 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', '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}.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: un nome per il catalogo Iceberg REST.
• APP_NAME: un nome per la sessione Spark.
• CLOUD_STORAGE_BUCKET_NAME: il nome del bucket Cloud Storage che archivia le tabelle BigLake Iceberg.
• PROJECT_ID: il progetto a cui viene fatturato l'utilizzo del catalogo Iceberg REST, 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.

L'esempio precedente non utilizza la distribuzione delle credenziali. Per utilizzare la distribuzione delle credenziali, devi aggiungere l'intestazione X-Iceberg-Access-Delegation alle richieste del catalogo REST Iceberg con un valore di vended-credentials, aggiungendo la seguente riga al builder SparkSession:

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

Esempio con distribuzione delle credenziali

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

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

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.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', '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.

Crea uno spazio dei nomi

Spark

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

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;

USE CATALOG_NAME.SCHEMA_NAME;

Sostituisci quanto segue:

• CATALOG_NAME: un nome per il catalogo Trino utilizzando il catalogo REST Iceberg.
• SCHEMA_NAME: un nome per lo schema.

Creare una tabella

Spark

spark.sql("CREATE TABLE TABLE_NAME (id int, data string) USING ICEBERG;")

spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

Sostituisci quanto segue:

• NAMESPACE_NAME: il nome del tuo spazio dei nomi
• TABLE_NAME: un nome per la tabella

Trino

CREATE TABLE TABLE_NAME (id int, data varchar);

DESCRIBE TABLE_NAME;

Sostituisci TABLE_NAME con un nome per la tabella.

Elenca tabelle

Spark

spark.sql("SHOW TABLES").show()

Trino

SHOW TABLES;

Inserire dati nella tabella

L'esempio seguente inserisce dati di esempio nella tabella:

Spark

spark.sql("INSERT INTO TABLE_NAME VALUES (1, \"first row\"), (2, \"second row\"), (3, \"third row\");")

Trino

INSERT INTO TABLE_NAME VALUES (1, 'first row'), (2, 'second row'), (3, 'third row');

Eseguire una query su una tabella.

L'esempio seguente seleziona tutti i dati della tabella:

Spark

spark.sql("SELECT * FROM TABLE_NAME;").show()

Trino

SELECT * FROM TABLE_NAME;

La seguente query di esempio esegue una query sulla stessa tabella di BigQuery:

SELECT * FROM `CLOUD_STORAGE_BUCKET_NAME>NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`;

Sostituisci quanto segue:

• CLOUD_STORAGE_BUCKET_NAME: il nome del bucket Cloud Storage per il catalogo Iceberg REST. Ad esempio, se il tuo URI è gs://iceberg_bucket, utilizza iceberg_bucket.

• NAMESPACE_OR_SCHEMA_NAME: lo spazio dei nomi della tabella se utilizzi Spark o il nome dello schema della tabella se utilizzi Trino.

• TABLE_NAME: il nome della tabella.

Modificare uno schema della tabella

L'esempio seguente aggiunge una colonna alla tabella:

Spark

spark.sql("ALTER TABLE TABLE_NAME ADD COLUMNS ( desc string);")
spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

Sostituisci quanto segue:

• NAMESPACE_NAME: il nome del tuo spazio dei nomi
• TABLE_NAME: un nome per la tabella

Trino

ALTER TABLE TABLE_NAME ADD COLUMN desc varchar;
DESCRIBE SCHEMA_NAME.TABLE_NAME;

Sostituisci quanto segue:

• SCHEMA_NAME: il nome dello schema
• TABLE_NAME: un nome per la tabella

Eliminazione di una tabella

L'esempio seguente elimina la tabella dallo spazio dei nomi specificato:

Spark

spark.sql("DROP TABLE TABLE_NAME;")

Trino

DROP TABLE TABLE_NAME;

Prezzi

Per i dettagli sui prezzi, consulta Prezzi di BigLake.

Passaggi successivi

• Scopri di più sulla gestione delle risorse Iceberg con BigLake Metastore.
• Scopri di più sulle funzionalità aggiuntive del metastore BigLake.