Criar uma visualização

Ao criar uma visualização do Apache Iceberg, é possível registrar uma tabela lógica não materializada definida por SQL em um namespace do catálogo do ambiente de execução do Lakehouse para que mecanismos compatíveis com o Iceberg, como Spark e Trino, possam consultá-la. O catálogo grava a definição da visualização em um arquivo metadata.json com controle de versão no Cloud Storage, no local da visualização.

Como o catálogo valida os esquemas das tabelas referenciadas quando você cria uma visualização, o namespace e todas as tabelas referenciadas pela visualização já precisam existir. Para mais informações, consulte Visão geral das visualizações do Apache Iceberg.

Antes de começar

  1. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  2. Ative a API BigLake, se ainda não tiver feito isso.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

  3. Configure o catálogo do ambiente de execução do Lakehouse com um catálogo de vários buckets ou de um único bucket. As visualizações do Iceberg não são compatíveis com catálogos do BigQuery ou catálogos federados.
  4. Analise as limitações das visualizações do Iceberg.
  5. Conecte seu mecanismo de código aberto ao endpoint do catálogo REST do Apache Iceberg.

    • Spark: use o Spark 3.5 ou mais recente com o ambiente de execução do Iceberg 1.6.0 ou mais recente. Use o ambiente de execução do Iceberg 1.10.0 ou mais recente para que o Spark descubra os endpoints de visualização compatíveis pela resposta GET /v1/config do catálogo. Defina spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions para que o Spark delegue a visualização de DDL e a resolução ao endpoint do catálogo REST do Apache Iceberg.
    • Trino: use o Trino 482 ou mais recente e configure o conector do Trino Iceberg para usar o endpoint do catálogo REST do Apache Iceberg. Para mais informações, consulte Suporte do Trino.

Funções exigidas

Para receber as permissões necessárias para criar uma visualização, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto e no bucket de armazenamento:

  • Criar uma visualização: Editor do BigLake (roles/biglake.editor) - seu projeto
  • Gravar arquivos de metadados de visualização no modo de credenciais do usuário final: Usuário de objetos do Storage (roles/storage.objectUser): o bucket do Cloud Storage

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para criar uma visualização. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar uma visualização:

  • Crie uma visualização:
    • biglake.views.create no namespace
    • biglake.tables.get em cada tabela do Iceberg referenciada pela visualização
  • Gravar arquivos de metadados de visualização no modo de credenciais do usuário final: storage.objects.create no bucket do Cloud Storage

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Para uma lista completa de permissões de leitura, consulte Papéis e permissões necessários.

Criar tabelas base

Os exemplos neste documento fazem referência ao namespace e às tabelas a seguir. Se eles ainda não existirem, crie-os:

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;

Opcional: insira dados de amostra para consultar as visualizações criadas:

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');

Criar uma visualização

Crie uma visualização do Iceberg em uma ou mais tabelas do Iceberg.

Spark

Crie uma visualização com aliases de coluna explícitos, comentários no nível da coluna, um comentário no nível da visualização e propriedades personalizadas. O mecanismo resolve nomes de tabela não qualificados na definição da visualização usando o default-catalog e o default-namespace da visualização:

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';

Para criar uma visualização somente se ela ainda não existir, use CREATE VIEW IF NOT EXISTS. Se a visualização existir, a instrução será bem-sucedida sem modificá-la:

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

Por padrão, o catálogo grava arquivos de metadados compactados com gzip (.gz.metadata.json). Para gravar arquivos de metadados não compactados (.metadata.json), defina a propriedade write.metadata.compression-codec como none:

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

REST

Para criar uma visualização do Iceberg usando a API REST, faça uma solicitação POST ao endpoint CreateIcebergView:

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

O corpo da solicitação precisa conter um payload JSON CreateViewRequest do Iceberg válido que defina o nome, o esquema, a versão e as propriedades iniciais da visualização. Se você definir um location personalizado, ele precisará seguir as regras de local de armazenamento de visualização para seu tipo de catálogo. O local é imutável após a criação.

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud.
  • CATALOG_ID: o ID do catálogo.
  • NAMESPACE_NAME: o nome do namespace do catálogo.

Criar visualizações com mesclagens, agregações e subconsultas

Uma definição de visualização pode incluir mesclagens, agregações, expressões CASE, expressões de tabela comuns (CTEs), UNION ALL e subconsultas.

Crie uma visualização que mescle duas tabelas:

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;

Crie uma visualização que agregue dados e use uma expressão 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;

Crie uma visualização que use uma CTE, UNION ALL e uma subconsulta:

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');

Criar uma visualização aninhada

Uma visualização pode consultar outra. A consulta da visualização externa requer biglake.views.get em ambas as visualizações e acesso de leitura a todas as tabelas que qualquer uma das visualizações referencia.

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

Criar uma visualização com viagem no tempo em tabelas subjacentes

As visualizações não mantêm os próprios snapshots de dados, mas uma definição de visualização pode consultar uma tabela do Iceberg subjacente em um carimbo de data/hora ou ID de snapshot específico. Use esse padrão para criar linhas de base históricas reproduzíveis para compliance, relatórios ou treinamento de modelo.

  1. Insira um registro para criar uma nova versão da tabela:

    INSERT INTO my_ns.employees VALUES (4, 'Diana', 'Engineering', 160000.0);
    
  2. Crie uma visualização fixada ao estado da tabela antes da inserção. Substitua o carimbo de data/hora por um horário anterior à inserção:

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

    Como alternativa, fixe a visualização em um ID de snapshot de tabela específico:

    CREATE VIEW eng_employees_snapshot_audit AS
    SELECT id, name, salary
    FROM my_ns.employees VERSION AS OF SNAPSHOT_ID
    WHERE dept = 'Engineering';
    
  3. Consulte a visualização histórica. O resultado exclui o registro recém-inserido:

    SELECT * FROM eng_employees_baseline;
    

Não é possível aplicar TIMESTAMP AS OF ou VERSION AS OF diretamente a um identificador de visualização. Expressar a viagem no tempo dentro da definição da visualização, em relação à tabela subjacente. Para mais informações, consulte Resolver problemas de visualizações do Iceberg.

A seguir