Concetti relativi all'endpoint del catalogo REST di Apache Iceberg

Lakehouse for Apache Iceberg gestisce i metadati tramite il catalogo runtime Lakehouse. Quando utilizzi l'endpoint del catalogo REST Apache Iceberg, il sistema organizza i dati in una gerarchia di risorse rigorosa. La configurazione del catalogo determina i tipi di archiviazione supportati, i comportamenti di routing regionali e le opzioni di federazione delle query.

Funzionalità e conformità

Il catalogo runtime Lakehouse è progettato per integrarsi con i motori di query conformi a Iceberg supportando i formati di tabella standard e rispettando le API aperte.

Formati di tabella supportati

Sono supportate le tabelle Apache Iceberg V2 (GA) e V3 (anteprima). Le tabelle Iceberg V1 non sono supportate. Prima di utilizzare le tabelle V1 esistenti con l'endpoint del catalogo REST Apache Iceberg, devi eseguirne l'upgrade a una versione supportata. Per ulteriori informazioni, vedi Eseguire l'upgrade delle tabelle Iceberg V1 a V2.

Conformità API e operazioni REST

Il catalogo runtime Lakehouse implementa l'API del catalogo REST Apache Iceberg standard aperto. I motori di query client interagiscono con il catalogo utilizzando le API del catalogo REST standard. Per ulteriori informazioni, vedi Iceberg Conformità dell'API del catalogo REST.

Gerarchia delle risorse

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

Risorsa Descrizione
Catalogo Un container di primo livello, un catalogo ti consente di organizzare spazi dei nomi e tabelle in gruppi logici dividendoli in cataloghi diversi. Ogni catalogo è supportato da una località di archiviazione del magazzino designata (ad esempio un bucket Cloud Storage o un proxy di federazione BigQuery) che archivia i file di dati e metadati sottostanti.
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.

Cataloghi e località di archiviazione

La configurazione di un catalogo determina il suo funzionamento e la sua integrazione con i servizi Google Cloud. Puoi configurare un catalogo con più bucket (bl://) (opzione consigliata) o un catalogo con un solo bucket (gs://).

Entrambe le opzioni supportano la distribuzione delle credenziali per un controllo dell'accesso granulare.

Più bucket (bl://) (opzione consigliata)

Questo approccio ti consente di assegnare un nome al catalogo indipendentemente dal nome del bucket e di configurare più bucket per un singolo catalogo. Nell'API sottostante, questa opzione corrisponde alla CATALOG_TYPE_BIGLAKE configurazione.

Considerazioni:

  • Località predefinita: fornisci un percorso a un bucket (default_location) o un sottopath (ad esempio gs://my-bucket/path) da utilizzare come località di archiviazione predefinita. Tutte le risorse del catalogo (spazi dei nomi e tabelle) devono trovarsi nel percorso specificato. Ad esempio, se specifichi gs://my-bucket/path, non puoi ospitare spazi dei nomi o tabelle in gs://my-bucket/another/path. Per gli spazi dei nomi creati senza una località specificata, viene utilizzata default_location.
  • Località limitate: puoi anche fornire una configurazione facoltativa restricted_locations per bucket o percorsi aggiuntivi in cui è possibile creare spazi dei nomi e tabelle. Se specifichi un sottopath (ad esempio gs://my-bucket/path), tutte le risorse create utilizzando questa configurazione devono trovarsi in quel percorso (ad esempio, gs://my-bucket/another/path non può ospitare spazi dei nomi o tabelle).
  • Requisiti del gruppo di regioni geografiche: sebbene i bucket possano essere cross-project, cross-region e avere configurazioni diverse (ad esempio a regione singola, a due regioni o multiregionale), tutte le località Cloud Storage nella località predefinita e nelle località limitate devono trovarsi nello stesso gruppo di regioni geografiche (ad esempio Stati Uniti, Europa, Canada o Asia). Ad esempio, non puoi configurare un bucket multiregionale statunitense con un bucket in Europa o in Canada.
  • Più cataloghi per bucket: puoi avere più cataloghi che puntano a uno stesso bucket (ad esempio utilizzando località predefinite o località limitate diverse). Tuttavia, questa configurazione è fortemente sconsigliata perché può causare conflitti di metadati, sovrascritture accidentali dei dati o problemi di sicurezza come la perdita di autorizzazioni.
  • Spazi dei nomi: consente di specificare località di spazi dei nomi personalizzate, a condizione che si trovino in un percorso configurato nelle località predefinite o limitate. Tieni presente che alle tabelle create in questi cataloghi verrà aggiunto automaticamente un suffisso di stringa casuale ai relativi percorsi fisici per evitare conflitti (ad esempio, gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}). Per ulteriori informazioni, vedi Regole di gestione e sicurezza delle tabelle.

Bucket singolo (gs://)

Questo è l'approccio legacy in cui il catalogo gestisce direttamente i metadati e i file di dati Apache Iceberg in un singolo bucket Cloud Storage che specifichi. Nell'API sottostante, questa opzione corrisponde alla CATALOG_TYPE_GCS_BUCKETconfigurazione.

Per i cataloghi di bucket Cloud Storage, il nome del catalogo è impostato sul nome del bucket.

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.

Considerazioni:

  • Limitazioni del tipo di catalogo legacy. L'utilizzo della configurazione legacy con un solo bucket è fortemente sconsigliato per i nuovi progetti. Questa configurazione presenta diverse limitazioni critiche:

    • Nome del catalogo: bloccato sul nome del bucket Cloud Storage sottostante.
    • Progetto: bloccato sul progetto del bucket (i cataloghi cross-project non sono supportati).
    • Regione: derivata rigorosamente dalla località del bucket e non può essere personalizzata.
    • Archiviazione: limita il catalogo a un singolo bucket (nessuna località limitata).

  • Limitazione di un catalogo per bucket: per questo tipo di catalogo legacy, puoi avere un solo catalogo per bucket e il nome del catalogo deve corrispondere al nome del bucket.

  • Eseguire l'upgrade a più bucket (bl://) (opzione consigliata): puoi eseguire l'upgrade di un catalogo con un solo bucket (gs://) esistente a un catalogo con più bucket (bl://) (opzione consigliata). Il catalogo di cui è stato eseguito l'upgrade conserva il nome del bucket originale. Dopodiché, puoi associare più bucket al catalogo e configurare le località limitate.

Regioni di bucket e cataloghi

La regione di un endpoint del catalogo nel catalogo runtime Lakehouse è determinata dalla regione del bucket Cloud Storage sottostante:

  • Più bucket (bl://) (opzione consigliata): la regione del catalogo è derivata dal bucket configurato in default_location.
  • Bucket singolo (gs://): la regione del catalogo è derivata rigorosamente dal bucket associato al catalogo e non può essere personalizzata.

La regione del catalogo mappata varia a seconda del tipo di regione del bucket:

  • Regione singola: la regione del catalogo corrisponde esattamente alla regione del bucket.
  • A due regioni: la regione del catalogo corrisponde al bucket a due regioni (ad esempio ASIA1 o NAM4).
  • Più regioni: la regione del catalogo è impostata su una località regionale specifica all'interno del dominio geografico della regione multiregionale. Per impostazione predefinita, questa potrebbe non essere allineata alle regioni multiregionali BigQuery comuni come US ed EU (ad esempio, un bucket multiregionale US viene mappato a us-central1 o us-east4).

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

Regioni principali per le regioni multiregionali

Per consentire a BigQuery di eseguire query sulle tabelle del catalogo dalla regione multiregionale US o EU, specifica US o EU come regione principale quando crei il catalogo.

Puoi specificare una regione multiregionale (US o EU) come regione principale nelle seguenti configurazioni:

Se il bucket default_location è:

  • Un bucket multiregionale US o EU.
  • Un bucket a regione singola all'interno di queste regioni multiregionali (ad esempio us-central1 o europe-west4).
  • Un bucket a due regioni o a due regioni personalizzato all'interno di queste aree (ad esempio NAM4 o EUR4).

La replica principale viene definita quando crei il catalogo, ma puoi eseguire dinamicamente un failover chiamando FailoverCatalog. Per ulteriori informazioni, vedi Creare un catalogo.

Eseguire query sui cataloghi da BigQuery

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

  • Project: l'ID progetto proprietario del catalogo. Google Cloud
  • Catalog: il nome del catalogo runtime Lakehouse.
  • Namespace: lo spazio dei nomi Apache Iceberg (equivalente a un set di dati BigQuery).
  • Table: il nome della tabella.

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

Passaggi successivi