Alterar uma visualização

Ao alterar uma visualização do Apache Iceberg, é possível evoluir o esquema e a definição de SQL da visualização ou definir e remover propriedades de visualização personalizadas, sem mudar a identidade da visualização no catálogo do ambiente de execução do Lakehouse.

Não é possível renomear uma visualização. Para renomear uma visualização, crie uma com o novo nome e exclua a original. O local de armazenamento de uma visualização também é imutável após a criação, e uma atualização que define um local diferente falha com um erro 400 Bad Request.

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 o endpoint do catálogo REST do Apache Iceberg.
  4. Analise as limitações das visualizações do Iceberg.
  5. Criar uma visualização.

Funções exigidas

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

  • Alterar 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 alterar 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 alterar uma 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
  • 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.

Substituir uma definição de visualização

Substitua o esquema e a lógica SQL de uma visualização atual. Quando você substitui uma visualização, o catálogo grava um novo arquivo metadata.json com controle de versão (por exemplo, 00001-UUID.metadata.json), anexa uma nova versão de visualização e um esquema aos metadados da visualização e preserva o view-uuid da visualização.

Spark

CREATE OR REPLACE VIEW my_ns.eng_employees (
  emp_id,
  emp_name,
  dept,
  salary,
  is_senior
)
COMMENT 'Updated Engineering view with seniority flag'
AS SELECT id, name, dept, salary, (salary >= 140000.0) AS is_senior
FROM my_ns.employees
WHERE dept = 'Engineering';

REST

Para atualizar uma visualização usando a API REST, faça uma solicitação POST ao endpoint UpdateIcebergView:

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

O corpo da solicitação precisa conter um payload JSON CommitViewRequest do Iceberg válido com o requirements e o updates a serem aplicados. O catálogo valida os requisitos de simultaneidade otimista e confirma as atualizações em um novo arquivo metadata.json.

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.
  • VIEW_NAME: o nome da visualização.

Definir e remover propriedades de visualização

Defina ou remova propriedades personalizadas em uma visualização sem mudar a definição dela.

Spark

Defina as propriedades:

ALTER VIEW my_ns.eng_employees
SET TBLPROPERTIES ('tier' = 'gold', 'reviewed' = 'true');

Cancele a definição de uma propriedade:

ALTER VIEW my_ns.eng_employees
UNSET TBLPROPERTIES IF EXISTS ('reviewed');

Para detalhes sobre como o catálogo lida com propriedades como write.metadata.compression-codec, consulte Ver propriedades.

REST

Envie um CommitViewRequest para o endpoint UpdateIcebergView com atualizações de set-properties ou remove-properties. Consulte Substituir uma definição de visualização para o caminho do endpoint.

A seguir