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 di 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 di runtime Lakehouse è progettato per integrarsi con motori di query conformi a Iceberg supportando formati di tabelle 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 Esegui l'upgrade delle tabelle Iceberg V1 alla V2.

Conformità delle API e operazioni REST

Il catalogo di runtime Lakehouse implementa l'API standard aperta Apache Iceberg REST Catalog. I motori di query client interagiscono con il catalogo utilizzando le API REST Catalog standard. Per saperne di più, consulta Come Lakehouse implementa l'API REST Catalog di Apache Iceberg.

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, consente di organizzare gli spazi dei nomi e le tabelle in gruppi logici dividendoli in cataloghi diversi. Ogni catalogo è supportato da posizioni di archiviazione warehouse 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 multibucket (consigliato) 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, specifica il percorso del warehouse in base al tipo di catalogo:

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

Catalogo con più bucket (consigliato)

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

Considerazioni:

Configurazione del warehouse client (bl://): quando configuri un client Iceberg per connettersi a un catalogo con più bucket, specifica il percorso del warehouse 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 in Google Cloud, le posizioni di archiviazione (default_location e restricted_locations) vengono sempre specificate come percorsi Cloud Storage (gs://).
Bucket massimi: puoi specificare un massimo di 15 bucket per catalogo.
Località predefinita: fornisci un percorso a un bucket (default_location) o un percorso secondario (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 località specificata, viene utilizzato default_location.
Località con limitazioni: puoi anche fornire una configurazione restricted_locations facoltativa per bucket o percorsi aggiuntivi in cui possono essere creati spazi dei nomi e tabelle. Se specifichi un percorso secondario (ad esempio gs://my-bucket/path), tutte le risorse create utilizzando questa configurazione devono trovarsi in questo percorso (ad esempio, gs://my-bucket/another/path non può ospitare spazi dei nomi o tabelle).
Requisiti per il gruppo di regioni geografiche: sebbene i bucket possano essere interprogetto, interregionali e avere configurazioni diverse (ad esempio a singola regione, a due regioni o multiregionale), tutte le località Cloud Storage nella località predefinita e nelle località con limitazioni devono trovarsi nello stesso gruppo di regioni geografiche (ad esempio Stati Uniti, Europa, Canada o Asia). Ad esempio, non puoi configurare un bucket multiregionale degli Stati Uniti con un bucket in Europa o in Canada.
Più cataloghi per bucket: puoi avere più cataloghi che puntano allo stesso bucket (ad esempio, utilizzando località predefinite diverse o località con limitazioni). 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 personalizzate per gli spazi dei nomi, a condizione che si trovino in un percorso configurato nelle posizioni predefinite o con limitazioni. 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 saperne di più, consulta Regole di gestione e sicurezza delle tabelle.

Catalogo con bucket singolo

Si tratta dell'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 impostazione corrisponde alla configurazione CATALOG_TYPE_GCS_BUCKET.

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 precedente. L'utilizzo della configurazione legacy con un singolo bucket è fortemente sconsigliato per i nuovi progetti. Questa configurazione presenta diverse limitazioni critiche:
- Nome 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 posizione del bucket e non può essere personalizzata.
- Spazio di archiviazione: limita il catalogo a un singolo bucket (nessuna località con limitazioni).
Configurazione del warehouse client (gs://): quando configuri un client Iceberg per un catalogo a bucket singolo, specifica il percorso del bucket Cloud Storage (gs://CLOUD_STORAGE_BUCKET_NAME) come posizione del warehouse.
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.
Esegui l'upgrade al catalogo multicluster (opzione consigliata): puoi eseguire l'upgrade di un catalogo a un solo bucket esistente a un catalogo multicluster (opzione consigliata). Il catalogo di cui è stato eseguito l'upgrade mantiene il nome del bucket originale. Dopodiché, puoi associare più bucket al catalogo e configurare le località con limitazioni.

Regioni dei bucket e dei cataloghi

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

Catalogo con più bucket (consigliato): la regione del catalogo deriva dal bucket configurato in default_location.
Catalogo con bucket singolo: 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 a quella 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 posizione regionale specifica all'interno del dominio geografico della multiregione. Per impostazione predefinita, questo potrebbe non essere in linea con le multi-regioni BigQuery comuni come US e EU (ad esempio, un bucket multiregionale US viene mappato a us-central1 o us-east4).

Quando BigQuery esegue una query sulle tabelle di 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 posizione, la query non va a buon fine.

Regioni principali per le multi-regioni

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

Puoi specificare una multi-regione (US o EU) come regione primaria nelle seguenti configurazioni:

Se il bucket default_location è:

Un bucket multiregionale US o EU.
Un bucket in una singola regione all'interno di queste più regioni (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 primaria viene definita quando crei il catalogo, ma puoi eseguire dinamicamente un failover chiamando FailoverCatalog. Per ulteriori informazioni, vedi Creare un catalogo.

Per indirizzare le richieste direttamente a una regione specifica per i requisiti di residenza e sovranità dei dati, puoi utilizzare gli endpoint regionali (biglake.LOCATION.rep.googleapis.com). Per saperne di più, consulta Endpoint regionali di Lakehouse.

Esecuzione di query sui cataloghi da BigQuery

Quando esegui query sulle tabelle del catalogo di runtime Lakehouse da BigQuery, utilizzi una struttura di denominazione in quattro parti, spesso definita 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 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.

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.