Visão geral das visualizações do Apache Iceberg

As visualizações do Apache Iceberg permitem definir tabelas lógicas abertas e não materializadas com SQL e usá-las em mecanismos compatíveis com o Iceberg, como Apache Spark, Trino, Apache Flink, PyIceberg e dbt. É possível usar as visualizações do Iceberg para criar pipelines SQL modulares e expor projeções selecionadas de cópia zero em tabelas do Iceberg. As visualizações do Iceberg são gerenciadas pelo catálogo do ambiente de execução do Lakehouse pelo endpoint do catálogo REST do Apache Iceberg e seguem a especificação de visualização do Apache Iceberg e a especificação OpenAPI REST do Iceberg.

Neste documento, elas são chamadas de visualizações do Iceberg.

Ao contrário das visualizações autorizadas do BigQuery, as visualizações do Iceberg são avaliadas no lado do cliente pelo Compute Engine. As visualizações do Iceberg são objetos de catálogo que você cria, gerencia e consulta em mecanismos de código aberto.

Recursos

Os seguintes recursos são compatíveis:

  • Ciclo de vida completo da visualização: crie, substitua, altere propriedades, liste, inspecione e remova visualizações do Iceberg de mecanismos de código aberto compatíveis com o Iceberg, como Apache Spark e Trino.
  • Definições de visualização avançadas: defina visualizações com aliases de coluna, comentários no nível da coluna e da visualização, propriedades personalizadas, mesclagens, agregações, expressões de tabela comuns (CTEs), UNION ALL, subconsultas, visualizações aninhadas e viagem no tempo nas tabelas subjacentes.
  • Autenticação flexível: use credenciais de usuário final ou venda de credenciais com buckets padrão do Cloud Storage e buckets de namespace hierárquico.
  • Suporte a catálogos: crie visualizações em catálogos de vários buckets e de um único bucket.

Só é possível criar, gerenciar e consultar visualizações do Iceberg usando mecanismos de código aberto compatíveis com o Iceberg que se conectam ao endpoint do catálogo REST do Apache Iceberg. Saiba mais em Limitações.

Para o 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 da DDL e a resolução ao endpoint do catálogo REST do Apache Iceberg.

Para o Trino, use o Trino 482 ou mais recente. Para mais informações, consulte Suporte do Trino.

Como as visualizações do Iceberg funcionam

Uma visualização do Iceberg armazena a definição, o esquema e as propriedades do SQL em um arquivo metadata.json com controle de versão no Cloud Storage, em VIEW_LOCATION/metadata/. O catálogo do ambiente de execução do Lakehouse rastreia o local atual dos metadados de cada visualização e a expõe pelos endpoints de visualização do endpoint do catálogo REST do Apache Iceberg.

O Compute Engine avalia as visualizações do Iceberg no lado do cliente. Quando você executa SELECT * FROM my_view, o mecanismo carrega a definição da visualização do catálogo, resolve todas as tabelas e visualizações aninhadas referenciadas e, em seguida, executa a consulta nas tabelas subjacentes do Iceberg. O catálogo não executa a consulta em seu nome.

Sempre que você substitui uma visualização por CREATE OR REPLACE VIEW, o catálogo grava um novo arquivo metadata.json, anexa uma nova versão e um esquema aos metadados da visualização e preserva o view-uuid da visualização. A propriedade version.history.num-entries limita o número de versões retidas. Para mais informações, consulte Ver propriedades.

As tabelas e as visualizações compartilham o mesmo namespace de identificador em um namespace de catálogo. Não é possível criar uma visualização com o mesmo nome de uma tabela atual ou substituir uma tabela por uma visualização.

Papéis e permissões necessárias

Como o Compute Engine avalia as visualizações do lado do cliente, para consultar uma visualização, é preciso ter permissões nela e em todas as tabelas e visualizações aninhadas que ela referencia.

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

  • Criar, substituir, alterar e descartar visualizações: Editor do BigLake (roles/biglake.editor) - seu projeto
  • Listar e inspecionar definições de visualização: Leitor do BigLake (roles/biglake.viewer) - seu projeto
  • Consultar visualizações no modo de venda de credenciais: Leitor do BigLake (roles/biglake.viewer) - seu projeto
  • Consultar visualizações no modo de credenciais do usuário final:
    • Leitor do BigLake (roles/biglake.viewer): seu projeto
    • Leitor de objetos do Storage (roles/storage.objectViewer): o bucket do Cloud Storage
  • 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, gerenciar e consultar visualizações do Iceberg. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para criar, gerenciar e consultar visualizações do Iceberg:

  • Crie uma visualização:
    • biglake.views.create no namespace
    • biglake.tables.get em cada tabela do Iceberg referenciada pela visualização
  • Visualizações em lista: biglake.views.list no namespace
  • Receber detalhes da visualização: biglake.views.get na visualização
  • Alterar uma visualização:
    • biglake.views.update na visualização
    • biglake.tables.get em cada tabela do Iceberg referenciada pela nova definição de visualização
  • Para excluir uma visualização: biglake.views.delete nela
  • Consultar uma visualização:
    • biglake.views.get na visualização e em todas as visualizações aninhadas
    • biglake.tables.get em cada tabela do Iceberg referenciada pela visualização
  • Ler dados da tabela no modo de venda de credenciais: biglake.tables.getData em cada tabela do Iceberg referenciada pela visualização
  • Ler metadados de visualização e dados de tabela no modo de credenciais do usuário final: storage.objects.get no bucket do Cloud Storage
  • 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.

A tabela a seguir associa cada permissão de leitura às operações de endpoint do catálogo REST do Apache Iceberg que ela autoriza:

Permissão Recurso Operações de endpoint Incluído em papéis predefinidos
biglake.views.create Namespace CreateIcebergView roles/biglake.admin, roles/biglake.editor
biglake.views.get Ver GetIcebergView, CheckIcebergViewExists roles/biglake.admin, roles/biglake.editor, roles/biglake.viewer, roles/biglake.metadataViewer
biglake.views.update Ver UpdateIcebergView roles/biglake.admin, roles/biglake.editor
biglake.views.delete Ver DeleteIcebergView roles/biglake.admin, roles/biglake.editor
biglake.views.list Namespace ListIcebergViewIdentifiers roles/biglake.admin, roles/biglake.editor, roles/biglake.viewer, roles/biglake.metadataViewer

Para mais informações, consulte Papéis do IAM do Lakehouse.

Endpoints de visualização compatíveis

Quando um mecanismo inicializa uma sessão de catálogo com GET /v1/config?warehouse=WAREHOUSE_URI, o endpoint do catálogo REST do Apache Iceberg anuncia os seguintes endpoints de visualização na lista endpoints. Na tabela a seguir, {prefix} é projects/PROJECT_ID/catalogs/CATALOG_ID.

Método e caminho Operação Descrição Permissão necessária
GET /v1/{prefix}/namespaces/{namespace}/views ListIcebergViewIdentifiers Lista os identificadores de visualização em lista no namespace. É compatível com pageToken e pageSize. Não inclui tabelas. biglake.views.list no namespace
POST /v1/{prefix}/namespaces/{namespace}/views CreateIcebergView Cria uma visualização, grava o arquivo 00000-UUID.metadata.json inicial no Cloud Storage e registra a visualização. biglake.views.create no namespace
GET /v1/{prefix}/namespaces/{namespace}/views/{view} GetIcebergView Carrega os metadados da visualização atual e o local dos metadados. biglake.views.get na visualização
POST /v1/{prefix}/namespaces/{namespace}/views/{view} UpdateIcebergView Valida os requisitos de simultaneidade otimista e confirma as atualizações em um novo arquivo metadata.json. biglake.views.update na visualização
DELETE /v1/{prefix}/namespaces/{namespace}/views/{view} DeleteIcebergView Remove a visualização do catálogo e limpa a política do Identity and Access Management (IAM) no nível da visualização. biglake.views.delete na visualização
HEAD /v1/{prefix}/namespaces/{namespace}/views/{view} CheckIcebergViewExists Verifica se uma visualização existe. biglake.views.get na visualização

Ações de gerenciamento

É possível realizar as seguintes ações de gerenciamento nas visualizações do Iceberg:

  • Criar uma visualização: defina uma visualização em uma ou mais tabelas do Iceberg usando o Spark ou o endpoint do catálogo REST do Apache Iceberg (CreateIcebergView).
  • Visualizações em lista: liste os identificadores de visualização em um namespace usando o Spark ou o endpoint do catálogo REST do Apache Iceberg (ListIcebergViewIdentifiers).
  • Ver detalhes da visualização: inspecione o esquema, a definição de SQL e as propriedades de uma visualização usando o Spark ou o endpoint do catálogo REST do Apache Iceberg (GetIcebergView).
  • Consultar uma visualização: execute consultas em uma visualização de um mecanismo de código aberto compatível com o Iceberg, como o Spark.
  • Alterar uma visualização: substitua a definição da visualização ou atualize as propriedades dela usando o Spark ou o endpoint do catálogo REST do Apache Iceberg (UpdateIcebergView).
  • Excluir uma visualização: remova uma visualização do catálogo usando o Spark ou o endpoint do catálogo REST do Apache Iceberg (DeleteIcebergView).

Limitações

As visualizações do Iceberg têm as seguintes limitações:

  • Somente mecanismos de código aberto. É possível criar, gerenciar e consultar visualizações do Iceberg apenas em mecanismos de código aberto compatíveis com o Iceberg usando o endpoint do catálogo REST do Apache Iceberg. O SQL do BigQuery, a ferramenta de linha de comando bq, o Google Cloud console, a CLI gcloud e o Terraform não são compatíveis com as visualizações do Iceberg.
  • Tipos de catálogo compatíveis. As visualizações do Iceberg são compatíveis apenas com catálogos de vários buckets e de um único bucket. O catálogo rejeita operações de visualização em catálogos do BigQuery e catálogos federados com um erro 400 Bad Request (FAILED_PRECONDITION).
  • Operações de visualização REST não compatíveis.
    • Não é possível renomear uma visualização (POST /v1/{prefix}/views/rename ou ALTER VIEW ... RENAME TO). Para renomear uma visualização, crie uma com o novo nome e, em seguida, descarte a original.
    • Não é possível registrar um arquivo de visualização metadata.json (registerView) existente.
    • Não há suporte para visualizações materializadas. Somente visualizações lógicas do Iceberg são compatíveis.
  • Viagem no tempo em visualizações. Não é possível aplicar TIMESTAMP AS OF ou VERSION AS OF a um identificador de visualização. Uma definição de visualização pode aplicar a viagem no tempo às tabelas subjacentes que ela consulta. Para mais informações, consulte Criar uma visualização com viagem no tempo em tabelas subjacentes.
  • Ver o local de armazenamento.
    • Em catálogos de bucket único, não é possível usar locais de visualização personalizados. O local da visualização precisa corresponder ao caminho padrão NAMESPACE_LOCATION/VIEW_NAME.
    • Em catálogos de vários buckets, um local de visualização personalizado precisa estar dentro do prefixo do URI de armazenamento do namespace e dos locais de armazenamento permitidos do catálogo.
    • Depois que você cria uma visualização, o local de armazenamento dela é imutável. A tentativa de definir um local diferente falha com um erro 400 Bad Request.

Ver propriedades

As visualizações do Iceberg são compatíveis com as propriedades de visualização definidas pelo Apache Iceberg. A tabela a seguir descreve como o catálogo processa essas propriedades:

Propriedade Valor padrão Comportamento
write.metadata.compression-codec gzip Por padrão, o catálogo grava arquivos .gz.metadata.json compactados com gzip. Defina como none para gravar arquivos .metadata.json não compactados. O valor diferencia maiúsculas de minúsculas. É possível definir essa propriedade no momento da criação ou com ALTER VIEW ... SET TBLPROPERTIES.
write.metadata.path VIEW_LOCATION/metadata Ignorado para visualizações. O catálogo sempre grava arquivos de metadados de visualização em VIEW_LOCATION/metadata/VERSION-UUID.metadata.json.
version.history.num-entries 10 Precisa ser um número inteiro positivo. Limita o número de entradas que o catálogo retém na lista versions e no version-log da visualização. Quando um commit excede esse limite, o catálogo remove as entradas mais antigas e sempre mantém a versão atual e as versões adicionadas pelo commit. O registro de versões é destinado à auditoria e à reversão administrativa. Os Compute Engines não são compatíveis com a consulta de versões de visualização histórica com SQL.

A seguir