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
- Leitor do BigLake (
-
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.createno namespace -
biglake.tables.getem cada tabela do Iceberg referenciada pela visualização
-
-
Visualizações em lista:
biglake.views.listno namespace -
Receber detalhes da visualização:
biglake.views.getna visualização -
Alterar uma visualização:
-
biglake.views.updatena visualização -
biglake.tables.getem cada tabela do Iceberg referenciada pela nova definição de visualização
-
-
Para excluir uma visualização:
biglake.views.deletenela -
Consultar uma visualização:
-
biglake.views.getna visualização e em todas as visualizações aninhadas -
biglake.tables.getem cada tabela do Iceberg referenciada pela visualização
-
-
Ler dados da tabela no modo de venda de credenciais:
biglake.tables.getDataem 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.getno bucket do Cloud Storage -
Gravar arquivos de metadados de visualização no modo de credenciais do usuário final:
storage.objects.createno 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/renameouALTER 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.
- Não é possível renomear uma visualização (
- Viagem no tempo em visualizações. Não é possível aplicar
TIMESTAMP AS OFouVERSION AS OFa 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.
- 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
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
- Saiba como criar uma visualização.
- Saiba como consultar uma visualização.
- Saiba como resolver problemas de visualizações do Iceberg.