Utilizzare il metastore BigLake con il catalogo REST Iceberg

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/v1beta/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/v1beta/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.

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 un motore di query con 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/v1beta/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()

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

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

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

Crea uno spazio dei nomi

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.

Creare una tabella

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

Elenca tabelle

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

Inserire dati nella tabella

L'esempio seguente inserisce dati di esempio nella tabella:

spark.sql("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.sql("SELECT * FROM TABLE_NAME;").show()

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

SELECT * FROM `CLOUD_STORAGE_BUCKET_NAME>NAMESPACE_NAME.TABLE_NAME`;

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

Modificare uno schema della tabella

L'esempio seguente aggiunge una colonna alla tabella:

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

Eliminazione di una tabella

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

spark.sql("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.