Le viste Apache Iceberg ti consentono di definire tabelle logiche aperte e non materializzate con SQL e di utilizzarle da motori compatibili con Iceberg come Apache Spark, Trino, Apache Flink, PyIceberg e dbt. Puoi utilizzare le viste Iceberg per creare pipeline SQL modulari ed esporre proiezioni curate e senza copia sulle tabelle Iceberg. Le viste Iceberg sono gestite dal catalogo di runtime Lakehouse tramite l'endpoint del catalogo REST Apache Iceberg e seguono la specifica della vista Apache Iceberg e la specifica OpenAPI REST Iceberg.
Questo documento fa riferimento a queste visualizzazioni come visualizzazioni Iceberg.
A differenza delle viste autorizzate di BigQuery, le viste Iceberg vengono valutate lato client dal tuo motore di computing. Le viste Iceberg sono oggetti del catalogo che crei, gestisci e interroghi da motori open source.
Funzionalità
Sono supportate le seguenti funzionalità:
- Ciclo di vita completo delle viste: crea, sostituisci, modifica le proprietà, elenca, ispeziona ed elimina le viste Iceberg da motori open source compatibili con Iceberg come Apache Spark e Trino.
- Definizioni di visualizzazioni avanzate: definisci le visualizzazioni con alias di colonna, commenti a livello di colonna e di visualizzazione, proprietà personalizzate, join, aggregazioni, espressioni di tabella comuni (CTE),
UNION ALL, subquery, visualizzazioni nidificate e cronologia dei dati sulle tabelle sottostanti. - Autenticazione flessibile: utilizza le credenziali dell'utente finale o la distribuzione delle credenziali con i bucket Cloud Storage standard e i bucket con spazio dei nomi gerarchico.
- Supporto dei cataloghi: crea visualizzazioni in cataloghi con più bucket e cataloghi con un solo bucket.
Puoi creare, gestire ed eseguire query sulle viste Iceberg solo tramite motori open source compatibili con Iceberg che si connettono all'endpoint del catalogo REST di Apache Iceberg. Per ulteriori informazioni, vedi Limiti.
Per Spark, utilizza Spark 3.5 o versioni successive con il runtime Iceberg 1.6.0 o versioni successive. Utilizza il runtime Iceberg 1.10.0 o versioni successive in modo che Spark rilevi gli endpoint di visualizzazione supportati tramite la risposta GET /v1/config del catalogo. Imposta spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions in modo che Spark deleghi la DDL e la risoluzione della visualizzazione all'endpoint del catalogo REST Apache Iceberg.
Per Trino, utilizza Trino 482 o versioni successive. Per ulteriori informazioni, consulta Supporto di Trino.
Come funzionano le viste Iceberg
Una vista Iceberg archivia la definizione, lo schema e le proprietà SQL in un file metadata.json con controllo delle versioni in Cloud Storage, in VIEW_LOCATION/metadata/. Il catalogo di runtime di Lakehouse tiene traccia della posizione corrente dei metadati per ogni vista ed espone la vista tramite gli endpoint della vista dell'endpoint del catalogo REST Apache Iceberg.
Il tuo motore di computing valuta le viste Iceberg lato client. Quando esegui SELECT * FROM my_view, il motore carica la definizione della vista dal catalogo, risolve ogni tabella e vista nidificata di riferimento, quindi esegue la query sulle tabelle Iceberg sottostanti. Il catalogo non esegue la query per tuo conto.
Ogni volta che sostituisci una vista con CREATE OR REPLACE VIEW, il catalogo scrive un nuovo file metadata.json, aggiunge una nuova versione e uno schema ai metadati della vista e conserva il view-uuid della vista. La proprietà version.history.num-entries limita il numero di versioni conservate.
Per saperne di più, consulta Visualizza le proprietà.
Le tabelle e le viste condividono lo stesso spazio dei nomi dell'identificatore all'interno di uno spazio dei nomi del catalogo. Non puoi creare una vista con lo stesso nome di una tabella esistente o sostituire una tabella con una vista.
Ruoli e autorizzazioni richiesti
Poiché Compute Engine valuta le viste lato client, l'esecuzione di query su una vista richiede autorizzazioni sulla vista e su ogni tabella e vista nidificata a cui fa riferimento.
Per ottenere le autorizzazioni necessarie per creare, gestire ed eseguire query sulle viste Iceberg, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto e nel bucket di archiviazione:
-
Creare, sostituire, modificare ed eliminare viste:
BigLake Editor (
roles/biglake.editor) - il tuo progetto -
Elencare ed esaminare le definizioni delle viste:
BigLake Viewer (
roles/biglake.viewer) - il tuo progetto -
Esegui query sulle viste in modalità di distribuzione delle credenziali:
BigLake Viewer (
roles/biglake.viewer) - il tuo progetto -
Esegui query sulle viste in modalità Credenziali utente finale:
- BigLake Viewer (
roles/biglake.viewer) - il tuo progetto - Storage Object Viewer (
roles/storage.objectViewer): il bucket Cloud Storage
- BigLake Viewer (
-
Scrivi i file dei metadati della vista in modalità credenziali dell'utente finale:
Storage Object User (
roles/storage.objectUser) - il bucket Cloud Storage
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Questi ruoli predefiniti contengono le autorizzazioni necessarie per creare, gestire ed eseguire query sulle visualizzazioni Iceberg. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
Per creare, gestire ed eseguire query sulle viste Iceberg sono necessarie le seguenti autorizzazioni:
-
Crea una visualizzazione:
-
biglake.views.createsullo spazio dei nomi -
biglake.tables.getsu ogni tabella Iceberg a cui fa riferimento la vista
-
-
Visualizzazioni elenco:
biglake.views.listnello spazio dei nomi -
Recupera i dettagli della visualizzazione:
biglake.views.getsulla visualizzazione -
Modifica una vista:
-
biglake.views.updatenella vista -
biglake.tables.getsu ogni tabella Iceberg a cui fa riferimento la nuova definizione della vista
-
-
Elimina una visualizzazione:
biglake.views.deletesulla visualizzazione -
Esegui una query su una vista:
-
biglake.views.getsulla vista e su eventuali viste nidificate -
biglake.tables.getsu ogni tabella Iceberg a cui fa riferimento la vista
-
-
Leggi i dati della tabella in modalità di distribuzione delle credenziali:
biglake.tables.getDatasu ogni tabella Iceberg a cui fa riferimento la vista -
Leggi i metadati della vista e i dati della tabella in modalità credenziali dell'utente finale:
storage.objects.getsul bucket Cloud Storage -
Scrivi i file di metadati della vista in modalità credenziali utente finale:
storage.objects.createsul bucket Cloud Storage
Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.
La tabella seguente mappa ogni autorizzazione di visualizzazione alle operazioni degli endpoint del catalogo REST Apache Iceberg che autorizza:
| Autorizzazione | Risorsa | Operazioni sugli endpoint | Incluso nei ruoli predefiniti |
|---|---|---|---|
biglake.views.create |
Spazio dei nomi | CreateIcebergView |
roles/biglake.admin, roles/biglake.editor |
biglake.views.get |
Visualizza | GetIcebergView, CheckIcebergViewExists |
roles/biglake.admin, roles/biglake.editor,
roles/biglake.viewer,
roles/biglake.metadataViewer |
biglake.views.update |
Visualizza | UpdateIcebergView |
roles/biglake.admin, roles/biglake.editor |
biglake.views.delete |
Visualizza | DeleteIcebergView |
roles/biglake.admin, roles/biglake.editor |
biglake.views.list |
Spazio dei nomi | ListIcebergViewIdentifiers |
roles/biglake.admin, roles/biglake.editor,
roles/biglake.viewer,
roles/biglake.metadataViewer |
Per saperne di più, consulta Ruoli IAM di Lakehouse.
Endpoint di visualizzazione supportati
Quando un motore inizializza una sessione del catalogo con GET /v1/config?warehouse=WAREHOUSE_URI, l'endpoint del catalogo REST Apache Iceberg annuncia i seguenti endpoint di visualizzazione nell'elenco endpoints. Nella tabella seguente, {prefix} è
projects/PROJECT_ID/catalogs/CATALOG_ID.
| Metodo e percorso | Operazione | Descrizione | Autorizzazione obbligatoria |
|---|---|---|---|
GET /v1/{prefix}/namespaces/{namespace}/views |
ListIcebergViewIdentifiers |
Elenca gli identificatori delle visualizzazioni nello spazio dei nomi. Supporta pageToken
e pageSize. Non include tabelle. |
biglake.views.list nello spazio dei nomi |
POST /v1/{prefix}/namespaces/{namespace}/views |
CreateIcebergView |
Crea una visualizzazione, scrive il file 00000-UUID.metadata.json iniziale in Cloud Storage e registra la visualizzazione. |
biglake.views.create nello spazio dei nomi |
GET /v1/{prefix}/namespaces/{namespace}/views/{view} |
GetIcebergView |
Carica i metadati della visualizzazione corrente e la posizione dei metadati. | biglake.views.get nella visualizzazione |
POST /v1/{prefix}/namespaces/{namespace}/views/{view} |
UpdateIcebergView |
Convalida i requisiti di contemporaneità ottimistica ed esegue il commit degli aggiornamenti in un nuovo file metadata.json. |
biglake.views.update nella visualizzazione |
DELETE /v1/{prefix}/namespaces/{namespace}/views/{view} |
DeleteIcebergView |
Rimuove la vista dal catalogo ed elimina la policy IAM (Identity and Access Management) a livello di vista. | biglake.views.delete nella visualizzazione |
HEAD /v1/{prefix}/namespaces/{namespace}/views/{view} |
CheckIcebergViewExists |
Controlla se esiste una vista. | biglake.views.get nella visualizzazione |
Azioni di gestione
Puoi eseguire le seguenti azioni di gestione sulle visualizzazioni Iceberg:
- Crea una vista: definisci una vista su una o più tabelle Iceberg utilizzando Spark o l'endpoint del catalogo REST Apache Iceberg (
CreateIcebergView). - Visualizzazioni elenco: elenca gli identificatori delle visualizzazioni in uno spazio dei nomi utilizzando Spark o l'endpoint del catalogo REST Apache Iceberg (
ListIcebergViewIdentifiers). - Visualizza i dettagli della vista: esamina lo schema, la definizione SQL e le proprietà di una vista utilizzando Spark o l'endpoint del catalogo REST Apache Iceberg (
GetIcebergView). - Esegui query su una vista: esegui query su una vista da un motore open source compatibile con Iceberg, ad esempio Spark.
- Modifica una vista: sostituisci la definizione della vista o aggiorna le proprietà della vista utilizzando Spark o l'endpoint del catalogo REST Apache Iceberg (
UpdateIcebergView). - Elimina una vista: elimina una vista dal catalogo utilizzando Spark o l'endpoint del catalogo REST Apache Iceberg (
DeleteIcebergView).
Limitazioni
Le viste Iceberg presentano le seguenti limitazioni:
- Solo motori open source. Puoi creare, gestire ed eseguire query sulle visualizzazioni Iceberg solo da motori open source compatibili con Iceberg tramite l'endpoint del catalogo REST Apache Iceberg. BigQuery SQL, lo strumento a riga di comando bq, la console Google Cloud , gcloud CLI e Terraform non supportano le visualizzazioni Iceberg.
- Tipi di catalogo supportati. Le visualizzazioni Iceberg sono supportate solo nei cataloghi multi-bucket e nei cataloghi single-bucket. Il catalogo rifiuta le operazioni di visualizzazione sui cataloghi BigQuery e sui cataloghi federati con un errore
400 Bad Request(FAILED_PRECONDITION). - Operazioni di visualizzazione REST non supportate.
- La ridenominazione di una vista (
POST /v1/{prefix}/views/renameoALTER VIEW ... RENAME TO) non è supportata. Per rinominare una vista, creane una con il nuovo nome, quindi elimina la vista originale. - La registrazione di un file di visualizzazione
metadata.jsonesistente (registerView) non è supportata. - Le viste materializzate non sono supportate. Sono supportate solo le viste logiche Iceberg.
- La ridenominazione di una vista (
- Viaggio nel tempo sulle visualizzazioni. Non puoi applicare
TIMESTAMP AS OFoVERSION AS OFa un identificatore di visualizzazione. Una definizione di vista può applicare il viaggio nel tempo alle tabelle sottostanti su cui esegue query. Per saperne di più, consulta Crea una vista con l'analisi cronologica sulle tabelle sottostanti. - Visualizza la località di archiviazione.
- Nei cataloghi con un singolo bucket, le località delle visualizzazioni personalizzate non sono supportate. La località della vista deve corrispondere al percorso predefinito
NAMESPACE_LOCATION/VIEW_NAME. - Nei cataloghi con più bucket, la posizione di una vista personalizzata deve rientrare nel prefisso dell'URI di archiviazione dello spazio dei nomi e nelle posizioni di archiviazione consentite del catalogo.
- Dopo aver creato una visualizzazione, la relativa località di archiviazione è immutabile.
Il tentativo di impostare una località diversa non va a buon fine e viene visualizzato un errore
400 Bad Request.
- Nei cataloghi con un singolo bucket, le località delle visualizzazioni personalizzate non sono supportate. La località della vista deve corrispondere al percorso predefinito
Visualizza proprietà
Le viste Iceberg supportano le proprietà delle viste definite da Apache Iceberg. La tabella seguente descrive in che modo il catalogo gestisce queste proprietà:
| Proprietà | Valore predefinito | Comportamento |
|---|---|---|
write.metadata.compression-codec |
gzip |
Per impostazione predefinita, il catalogo scrive file .gz.metadata.json compressi con gzip. Imposta su none per scrivere file .metadata.json non compressi. Il valore è sensibile alle maiuscole. Puoi impostare questa proprietà al momento della creazione o con
ALTER VIEW ... SET TBLPROPERTIES. |
write.metadata.path |
VIEW_LOCATION/metadata |
Ignorato per le visualizzazioni. Il catalogo scrive sempre i file dei metadati della visualizzazione in VIEW_LOCATION/metadata/VERSION-UUID.metadata.json. |
version.history.num-entries |
10 |
Deve essere un numero intero positivo. Limita il numero di voci che il catalogo conserva nell'elenco versions e in version-log della visualizzazione. Quando un commit supera questo limite, il catalogo rimuove le voci meno recenti e conserva sempre la versione corrente e le versioni aggiunte dal commit. Il log delle versioni è destinato all'audit e al rollback amministrativo; i motori di Compute Engine non supportano l'esecuzione di query sulle versioni delle visualizzazioni storiche con SQL. |
Passaggi successivi
- Scopri come creare una visualizzazione.
- Scopri come eseguire query su una vista.
- Scopri come risolvere i problemi relativi alle viste Iceberg.