Crea una vista

La creazione di una vista Apache Iceberg consente di registrare una tabella logica non materializzata definita in SQL in uno spazio dei nomi del catalogo di runtime Lakehouse in modo che i motori compatibili con Iceberg, come Spark e Trino, possano eseguire query su di essa. Il catalogo scrive la definizione della vista in un file metadata.json con controllo delle versioni in Cloud Storage nella posizione della vista.

Poiché il catalogo convalida gli schemi delle tabelle di riferimento quando crei una visualizzazione, lo spazio dei nomi e ogni tabella a cui fa riferimento la visualizzazione devono già esistere. Per saperne di più, consulta Panoramica delle visualizzazioni Apache Iceberg.

Prima di iniziare

  1. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

  2. Abilita l'API BigLake, se non è già abilitata.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

  3. Configura il catalogo di runtime Lakehouse con un catalogo multi-bucket o un catalogo single-bucket. Le viste Iceberg non sono supportate nei cataloghi BigQuery o nei cataloghi federati.
  4. Esamina le limitazioni delle visualizzazioni Iceberg.
  5. Connetti il tuo motore open source all'endpoint del catalogo REST Apache Iceberg.

    • 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 risoluzione e il DDL della vista all'endpoint del catalogo REST Apache Iceberg.
    • Trino: utilizza Trino 482 o versioni successive e configura il connettore Trino Iceberg per utilizzare l'endpoint del catalogo REST Apache Iceberg. Per saperne di più, consulta Supporto di Trino.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare una visualizzazione, chiedi all'amministratore di concederti i seguenti ruoli IAM per il progetto e il bucket di archiviazione:

  • Creare una vista: BigLake Editor (roles/biglake.editor) - il tuo progetto
  • 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 una visualizzazione. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare una visualizzazione sono necessarie le seguenti autorizzazioni:

  • Crea una visualizzazione:
    • biglake.views.create sullo spazio dei nomi
    • biglake.tables.get su ogni tabella Iceberg a cui fa riferimento la vista
  • Scrivi i file di metadati della vista in modalità credenziali utente finale: storage.objects.create sul bucket Cloud Storage

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Per un elenco completo delle autorizzazioni di visualizzazione, consulta Ruoli e autorizzazioni richiesti.

Crea tabelle di base

Gli esempi in questo documento fanno riferimento al seguente spazio dei nomi e alle seguenti tabelle. Se non esistono già, creale:

CREATE NAMESPACE IF NOT EXISTS my_ns;
USE my_ns;

CREATE TABLE IF NOT EXISTS employees (
  id INT,
  name STRING,
  dept STRING,
  salary DOUBLE
) USING iceberg;

CREATE TABLE IF NOT EXISTS departments (
  dept_code STRING,
  dept_name STRING,
  building STRING
) USING iceberg;

(Facoltativo) Inserisci dati campionati per poter eseguire query sulle visualizzazioni che crei:

INSERT INTO my_ns.employees VALUES
  (1, 'Alice', 'Engineering', 150000.0),
  (2, 'Bob', 'Marketing', 120000.0),
  (3, 'Charlie', 'Engineering', 135000.0);

INSERT INTO my_ns.departments VALUES
  ('Engineering', 'Eng Org', 'Building A'),
  ('Marketing', 'Growth Org', 'Building B');

Crea una vista

Crea una vista Iceberg su una o più tabelle Iceberg.

Spark

Crea una vista con alias di colonna espliciti, commenti a livello di colonna, un commento a livello di vista e proprietà personalizzate. Il motore risolve i nomi delle tabelle non qualificati nella definizione della vista utilizzando default-catalog e default-namespace della vista:

CREATE VIEW eng_employees (
  emp_id COMMENT 'Unique employee ID',
  emp_name COMMENT 'Full name of employee',
  salary COMMENT 'Annual compensation'
)
COMMENT 'Curated view of Engineering department employees'
TBLPROPERTIES ('tier' = 'silver')
AS SELECT id, name, salary
FROM employees
WHERE dept = 'Engineering';

Per creare una vista solo se non esiste già, utilizza CREATE VIEW IF NOT EXISTS. Se la vista esiste, l'istruzione viene eseguita correttamente senza modificarla:

CREATE VIEW IF NOT EXISTS eng_employees AS
SELECT id, name, salary FROM employees;

Per impostazione predefinita, il catalogo scrive file di metadati compressi con gzip (.gz.metadata.json). Per scrivere file di metadati non compressi (.metadata.json), imposta la proprietà write.metadata.compression-codec su none:

CREATE VIEW uncompressed_eng_view
TBLPROPERTIES ('write.metadata.compression-codec' = 'none')
AS SELECT id, name FROM employees WHERE dept = 'Engineering';

REST

Per creare una vista Iceberg utilizzando l'API REST, invia una richiesta POST all'endpoint CreateIcebergView:

POST /iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/CATALOG_ID/namespaces/NAMESPACE_NAME/views

Il corpo della richiesta deve contenere un payload JSON Iceberg CreateViewRequest valido che definisce il nome della vista, lo schema, la versione della vista e le proprietà iniziali. Se imposti un location personalizzato, questo deve seguire le regole per la località di archiviazione delle visualizzazioni per il tipo di catalogo. La località è immutabile dopo la creazione.

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud.
  • CATALOG_ID: l'ID del tuo catalogo.
  • NAMESPACE_NAME: il nome dello spazio dei nomi del catalogo.

Crea visualizzazioni con join, aggregazioni e subquery

Una definizione di vista può includere join, aggregazioni, espressioni CASE, espressioni di tabella comuni (CTE), UNION ALL e subquery.

Crea una vista che unisce due tabelle:

CREATE VIEW employee_directory AS
SELECT e.id, e.name, d.dept_name, d.building
FROM my_ns.employees e
JOIN my_ns.departments d
  ON e.dept = d.dept_code;

Crea una vista che aggrega i dati e utilizza un'espressione CASE:

CREATE VIEW dept_summary AS
SELECT
  dept,
  CASE WHEN dept = 'Engineering' THEN 'TECH' ELSE 'NON-TECH' END AS category,
  COUNT(*) AS headcount,
  AVG(salary) AS avg_salary
FROM my_ns.employees
GROUP BY dept;

Crea una vista che utilizzi una CTE, UNION ALL e una subquery:

CREATE VIEW high_earners_cte AS
WITH eng AS (
  SELECT id, name, salary FROM my_ns.employees WHERE dept = 'Engineering'
)
SELECT id, name FROM eng WHERE salary >= 140000.0
UNION ALL
SELECT id, name FROM my_ns.employees
WHERE id IN (SELECT id FROM my_ns.employees WHERE dept = 'Marketing');

Crea una vista nidificata

Una vista può eseguire query su un'altra vista. Per eseguire query sulla vista esterna, è necessario disporre di biglake.views.get su entrambe le viste e dell'accesso in lettura a ogni tabella a cui fa riferimento una delle due viste.

CREATE VIEW top_eng_employees AS
SELECT emp_id, emp_name
FROM my_ns.eng_employees
WHERE salary >= 140000.0;

Crea una vista con l'itinerario temporale sulle tabelle sottostanti

Le viste non mantengono i propri snapshot dei dati, ma una definizione di vista può eseguire query su una tabella Iceberg sottostante in un timestamp o un ID snapshot specifico. Utilizza questo pattern per creare baseline storiche riproducibili per la conformità, la generazione di report o l'addestramento dei modelli.

  1. Inserisci un record per creare una nuova versione della tabella sottostante:

    INSERT INTO my_ns.employees VALUES (4, 'Diana', 'Engineering', 160000.0);
    
  2. Crea una vista bloccata allo stato della tabella prima dell'inserimento. Sostituisci il timestamp con un'ora precedente all'inserimento:

    CREATE VIEW eng_employees_baseline AS
    SELECT id, name, salary
    FROM my_ns.employees TIMESTAMP AS OF 'TIMESTAMP'
    WHERE dept = 'Engineering';
    

    In alternativa, blocca la visualizzazione su un ID snapshot della tabella specifico:

    CREATE VIEW eng_employees_snapshot_audit AS
    SELECT id, name, salary
    FROM my_ns.employees VERSION AS OF SNAPSHOT_ID
    WHERE dept = 'Engineering';
    
  3. Esegui una query sulla vista della cronologia. Il risultato esclude il record appena inserito:

    SELECT * FROM eng_employees_baseline;
    

Non puoi applicare TIMESTAMP AS OF o VERSION AS OF direttamente a un identificatore di visualizzazione. Esprimi il viaggio nel tempo all'interno della definizione della vista, rispetto alla tabella sottostante. Per saperne di più, consulta Risolvi i problemi relativi alle viste Iceberg.

Passaggi successivi