A partire dal 20 aprile 2026, BigLake si chiama ora Lakehouse. Il metastore BigLake ora si chiama catalogo runtime Lakehouse. Le API, le librerie client, i comandi CLI e i nomi IAM di Lakehouse rimangono invariati e fanno ancora riferimento a BigLake.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Informazioni sull'endpoint del catalogo REST di Apache Iceberg

Borderless Lakehouse 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 e i comportamenti di routing regionali.

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 eseguire 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 In che modo Lakehouse implementa l'API del catalogo REST Apache Iceberg.

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 catalogo, il container di primo livello, consente di organizzare spazi dei nomi e tabelle in gruppi logici dividendoli in cataloghi diversi. Ogni catalogo è supportato da posizioni di archiviazione del magazzino designate (ad esempio uno o più bucket Cloud Storage) che archiviano 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 posizioni 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 (opzione consigliata) o un catalogo con un solo bucket.

Entrambe le opzioni supportano la distribuzione delle credenziali.

Quando configuri i motori di query client (come Spark o Trino) per connetterti all'endpoint del catalogo REST Apache Iceberg, devi specificare il percorso del magazzino in base al tipo di catalogo:

Catalogo con più bucket: imposta il percorso del magazzino su bl://projects/PROJECT_ID/catalogs/CATALOG_ID.
Catalogo con un solo bucket: imposta il percorso del magazzino su gs://CLOUD_STORAGE_BUCKET_NAME.

Catalogo con più bucket (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:

Configurazione del magazzino client (bl://): quando configuri un client Iceberg per connetterti a un catalogo con più bucket, specifica il percorso del magazzino utilizzando il formato URI bl://: bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Il formato bl:// viene utilizzato esclusivamente durante la configurazione del client per identificare il catalogo. Quando crei o configuri il catalogo stesso in Google Cloud, le posizioni di archiviazione (default_location e restricted_locations) vengono sempre specificate come percorsi Cloud Storage (gs://).
Numero massimo di bucket: puoi specificare un massimo di 15 bucket per catalogo.
Località predefinita: fornisci un percorso a un bucket (default_location) o a un sottopercorso (ad esempio gs://my-bucket/path) da utilizzare come posizione 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 posizione specificata, viene utilizzata default_location.
Posizioni limitate: puoi anche fornire una configurazione restricted_locations facoltativa per bucket o percorsi aggiuntivi in cui è possibile creare spazi dei nomi e tabelle. Se specifichi un sottopercorso (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 tra progetti e regioni diversi e avere configurazioni diverse (ad esempio, a regione singola, a due regioni o multiregionale), tutte le posizioni Cloud Storage nella località predefinita e nelle posizioni 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 allo stesso bucket (ad esempio, utilizzando posizioni predefinite o posizioni 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: consentono di specificare posizioni degli spazi dei nomi personalizzate, a condizione che si trovino in un percorso configurato nelle posizioni 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.

Catalogo con un solo bucket

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 (gs://) che specifichi. Nell'API sottostante, questa opzione corrisponde alla CATALOG_TYPE_GCS_BUCKET configurazione.

Per i cataloghi con un solo bucket, il nome del catalogo è impostato sul nome del bucket.

Ad esempio, se assegni al bucket il nome iceberg-bucket, sia il catalogo sia il bucket condividono questo nome. Utilizza questo nome 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.

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 tra progetti non sono supportati).
- Regione: derivata rigorosamente dalla località del bucket e non può essere personalizzata.
- Archiviazione: limita il catalogo a un singolo bucket (nessuna posizione limitata).
Configurazione del magazzino client (gs://): quando configuri un client Iceberg per un catalogo con un solo bucket, specifica il percorso del bucket Cloud Storage (gs://CLOUD_STORAGE_BUCKET_NAME) come posizione del magazzino.
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 un catalogo con più bucket (opzione consigliata): puoi eseguire l'upgrade di un catalogo con un solo bucket esistente a un catalogo con più bucket (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 posizioni 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:

Catalogo con più bucket: (opzione consigliata): la regione del catalogo è derivata dal bucket configurato in default_location.
Catalogo con un solo bucket: 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).
Multiregione: la regione del catalogo è impostata su una località regionale specifica all'interno del dominio geografico della multiregione. Per impostazione predefinita, questa potrebbe non essere allineata alle multiregioni BigQuery comuni come US ed EU (ad esempio, un bucket multiregionale US viene mappato su us-central1 o us-east4).

Quando BigQuery esegue una query sulle tabelle in questi cataloghi, la indirizza alla regione principale del catalogo. Se esegui 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 multiregioni

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

Puoi specificare una multiregione (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 multiregioni (ad esempio us-central1 o europe-west4).
Un bucket a due regioni o a due regioni personalizzata 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

Configurare l'endpoint del catalogo REST Apache Iceberg

Informazioni sull'endpoint del catalogo REST di Apache Iceberg Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.