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 rigida. 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 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 saperne di più, consulta Esegui l'upgrade delle tabelle Iceberg V1 alla versione V2.

Conformità delle API e operazioni REST

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

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 queste risorse:

Risorsa	Descrizione
Catalogo	Il container di primo livello, un catalogo, ti consente di organizzare gli spazi dei nomi e le tabelle in gruppi logici suddividendoli in cataloghi diversi. Ogni catalogo è supportato da posizioni di archiviazione del warehouse designate (ad esempio uno o più bucket Cloud Storage) che archiviano i file di metadati e dati sottostanti.
Spazio dei nomi	Un gruppo logico utilizzato per organizzare le tabelle all'interno di un catalogo, che 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 modo in cui opera e si integra con i servizi Google Cloud. Puoi configurare un catalogo con più bucket (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, specifichi 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 assegnare un nome al catalogo indipendentemente dal nome del bucket e di configurare più bucket per un singolo catalogo. Nell'API sottostante, questo corrisponde alla configurazione CATALOG_TYPE_BIGLAKE.

Considerazioni:

Configurazione del warehouse client (bl://): quando configuri un client Iceberg per la connessione 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 località di archiviazione (default_location e restricted_locations) vengono sempre specificate come percorsi Cloud Storage (gs://).
Bucket massimi: puoi specificare un massimo di 128 bucket per catalogo.
Posizione predefinita: fornisci un percorso a un bucket (default_location) o un sottopercorso (ad esempio gs://my-bucket/path) che funga da 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à 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 percorso secondario (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: anche se i bucket possono essere tra progetti, tra regioni e avere configurazioni diverse (ad esempio singola regione, a due regioni o multiregionale), tutte le località di 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 degli Stati Uniti con un bucket in Europa o in Canada.
Più cataloghi per bucket: puoi fare in modo che più cataloghi puntino allo stesso bucket (ad esempio, utilizzando località predefinite o località limitate diverse). Tuttavia, questa configurazione è 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, purché 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 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

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://) specificato da te. Nell'API sottostante, questo corrisponde alla configurazione CATALOG_TYPE_GCS_BUCKET.

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

Ad esempio, se assegni al bucket il nome iceberg-bucket, sia il catalogo che 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 dei tipi di catalogo legacy. L'utilizzo della configurazione legacy con un singolo bucket è 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: deriva rigorosamente dalla località del bucket e non può essere personalizzata.
- Spazio di archiviazione: limita il catalogo a un singolo bucket (nessuna località limitata).
Configurazione del warehouse client (gs://): quando configuri un client Iceberg per un catalogo con un singolo bucket, 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 con più bucket (consigliato): puoi eseguire l'upgrade di un catalogo con un singolo bucket esistente a un catalogo con più bucket (consigliato). Il catalogo di cui è stato eseguito l'upgrade mantiene il nome del bucket originale. In seguito, puoi associare più bucket al catalogo e configurare le località limitate.

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 viene ricavata dal bucket configurato in default_location.
Catalogo con bucket singolo: la regione del catalogo deriva 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:

Singola regione: la regione del catalogo corrisponde esattamente alla regione del bucket.
A due regioni: la regione del catalogo corrisponde alla doppia regione del bucket (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, questo potrebbe non essere in linea con le regioni multiple 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, indirizza la query alla regione principale del catalogo. Se esegui query su 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 va a buon fine.

Regioni principali per multiregione

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 località 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 multi-regioni (ad esempio us-central1 o europe-west4).
Un bucket a due regioni o a due regioni personalizzate 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 saperne di più, consulta Crea un catalogo.

Per instradare le richieste direttamente a una regione specifica per i requisiti di residenza dei dati e sovranità, 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 indicata come P.C.N.T:

Project: l'ID progetto Google Cloud 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.