Concetti relativi all'endpoint del catalogo REST di Apache Iceberg

Il catalogo runtime lakehouse fornisce una gestione centralizzata dei metadati per Google Cloud Lakehouse. Questo documento descrive i concetti di base del catalogo del runtime Lakehouse, concentrandosi sull'endpoint del catalogo REST Apache Iceberg, sulla sua 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 generale di queste risorse:

Risorsa Descrizione
Catalogo Il contenitore di primo livello, un catalogo, ti 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 cataloghi supportati

Quando configuri il client, specifichi una posizione del magazzino. Questa scelta determina il funzionamento e l'integrazione del catalogo con altri serviziGoogle Cloud . 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 unico bucket Cloud Storage; per i dati condivisi in più bucket, sono necessari più cataloghi.

Dettagli del warehouse

Consigliato

  • Warehouse dei bucket Cloud Storage (gs://): questo è l'approccio standard in cui il catalogo gestisce direttamente i metadati e i file di dati Apache Iceberg in un bucket Cloud Storage specificato. Questa opzione ti offre il controllo diretto sul layout dei dati e supporta la distribuzione delle credenziali per controllo dell'accesso dell'accesso granulare. In questo modo puoi creare e gestire tabelle del catalogo REST 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 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.lakehouse-catalog-id.quickstart_namespace.quickstart_table.

Alternative

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

Regioni del bucket e del catalogo

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 a quella 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 due regioni.

  • Bucket multiregionali: il sistema seleziona le località regionali per il catalogo all'interno del dominio geografico della multiregione. Per impostazione predefinita, queste posizioni potrebbero non corrispondere a quelle comuni di BigQuery, come US e EU. Si tratta invece di 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 in questi cataloghi, BigQuery indirizza la query alla regione nella regione principale del catalogo. Se esegui una query in una regione virtuale specifica (ad esempio US o EU) e i metadati del catalogo non sono presenti in quella località, la query potrebbe non riuscire.

Specifica le regioni principali per le multiregioni USA e 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.

  • Multi-regione EU di Cloud Storage: specifica EU o europe-west4.
  • Multi-regione Cloud Storage USA: specifica US o us-central1.

Il sistema seleziona la replica principale di un catalogo quando lo crei, ma puoi aggiornarla dinamicamente chiamando FailoverCatalog. Per saperne di più sulla definizione delle posizioni principali, consulta Utilizzare l'endpoint del catalogo REST di Apache Iceberg.

Esecuzione di query sui cataloghi

Quando esegui query sulle tabelle del catalogo del runtime Lakehouse da BigQuery, utilizzi una struttura di denominazione in quattro parti, spesso denominata P.C.N.T:

  • Progetto: l'ID progetto Google Cloud proprietario del catalogo.
  • Catalogo: il nome del catalogo runtime lakehouse.
  • Namespace: lo spazio dei nomi 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 catalogo; possono essere utilizzati in qualsiasi progetto in cui è abilitata l'API BigQuery. In questo modo potrai:

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 negli esempi di configurazione del client in Utilizza 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 formato bq://projects/PROJECT_ID/locations/LOCATION.

Passaggi successivi