Concetti relativi all'endpoint del catalogo REST di Apache Iceberg

Il catalogo di runtime Lakehouse fornisce una gestione centralizzata dei metadati per Google Cloud Lakehouse. Questo documento descrive i concetti di base del catalogo di runtime Lakehouse, concentrandosi sull'endpoint endpoint del catalogo REST di Apache Iceberg, sulla relativa gerarchia delle risorse e su altri tipi di catalogo supportati.

Gerarchia delle risorse

L'endpoint del catalogo REST di Apache Iceberg utilizza una gerarchia di risorse per organizzare i dati. La tabella seguente fornisce una panoramica di alto livello di queste risorse:

Risorsa Descrizione
Catalogo Un container 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.

Tipi di catalogo supportati

Quando configuri il client, devi specificare una posizione del warehouse. Questa scelta determina il funzionamento del catalogo e la sua integrazione con altri Google Cloud servizi. La tabella seguente descrive i tipi di catalogo supportati:

Tipo di catalogo Descrizione
Bucket Cloud Storage Tutti i dati di un catalogo vengono archiviati in un singolo bucket Cloud Storage; per i dati condivisi tra più bucket, sono necessari più cataloghi.
Federazione del catalogo BigQuery Consente di utilizzare l'endpoint del catalogo REST di Apache Iceberg per gestire ed eseguire query sulle tabelle visibili a BigQuery. Per ulteriori informazioni, vedi Federazione del catalogo con BigQuery.

Dettagli del warehouse

Consigliato

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

    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 viene utilizzato in un secondo momento quando esegui una query sul catalogo in BigQuery, utilizzando la sintassi P.C.N.T. Ad esempio my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table.

Alternative

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

Regioni dei bucket e dei cataloghi

Per i warehouse dei bucket Cloud Storage nel catalogo di runtime Lakehouse, il sistema seleziona la regione del catalogo in modo che corrisponda alla regione del bucket sottostante:

  • Bucket a regione singola: la regione del catalogo corrisponde esattamente alla regione del bucket.

  • Bucket a due regioni: include regioni a due regioni predefinite e definite dall'utente, come ASIA1 e NAM4. La regione del catalogo corrisponde alle regioni doppie.

  • Bucket multiregionali: il sistema seleziona le località regionali per il catalogo all'interno del dominio geografico della regione multipla. Per impostazione predefinita, queste località potrebbero non corrispondere alle località BigQuery comuni come US ed EU. Al contrario, sono località regionali all'interno del dominio geografico (ad esempio, us-central1 e us-east4 per un bucket multiregionale US).

Quando BigQuery esegue una query sulle tabelle di questi cataloghi, la indirizza alla regione principale del catalogo. Se esegui una query in una regione virtuale specifica (come US o EU) e i metadati del catalogo non sono presenti in quella località, la query potrebbe non riuscire.

Specificare le regioni principali per le regioni multiple USA ed UE

Per i cataloghi che utilizzano un bucket multiregionale US o EU, puoi specificare la regione principale quando crei il catalogo per assicurarti che BigQuery possa accedervi dalle regioni corrispondenti.

  • Regione multipla UE di Cloud Storage: specifica EU o europe-west4.
  • Regione multipla USA di Cloud Storage: specifica US o us-central1.

Il sistema seleziona una replica principale del catalogo quando la crei, ma puoi aggiornarla dinamicamente chiamando FailoverCatalog. Per ulteriori informazioni sulla definizione delle località principali, vedi Utilizzare l'endpoint del catalogo REST di Apache Iceberg.

Eseguire query sui cataloghi

Quando esegui query sulle tabelle del catalogo di runtime Lakehouse 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 di runtime Lakehouse.
  • Namespace: lo spazio dei nomi di Apache Iceberg (equivalente a un set di dati BigQuery).
  • Tabella: il nome della tabella.

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

Federazione del catalogo con BigQuery

Puoi utilizzare l'interfaccia dell'endpoint del catalogo REST di Apache Iceberg per gestire ed eseguire query sulle tabelle visibili a BigQuery.

I cataloghi di federazione del catalogo BigQuery non richiedono la creazione di una risorsa del catalogo; possono essere utilizzati in qualsiasi progetto in cui è abilitata l'API BigQuery. In questo modo puoi:

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

Per abilitare la federazione, configura il client con il bq://projects/PROJECT_ID formato del warehouse in il campo WAREHOUSE_PATH negli esempi di configurazione del client in Utilizzare l'endpoint del catalogo REST di Apache Iceberg. Puoi anche scegliere di includere una località BigQuery per limitare le richieste future a una singola località utilizzando il bq://projects/PROJECT_ID/locations/LOCATION formato.

Passaggi successivi