Alterar uma tabela

Alterar uma tabela permite evoluir o esquema (como adicionar colunas) e atualizar as propriedades de metadados da tabela.

As modificações são gerenciadas pelo catálogo de ambientes de execução do Lakehouse.

Antes de começar

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

2. Ative a API BigLake, se ela ainda não estiver ativada.

   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 com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o 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.

Funções exigidas

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

• Alterar tabela no modo de venda de credenciais: Editor do BigLake (roles/biglake.editor): o projeto
• Alterar tabela no modo sem fornecimento de credenciais:
  • Editor do BigLake (roles/biglake.editor): o projeto
  • 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.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Recursos e suporte de tabelas

Ao usar tabelas no catálogo de tempo de execução do Lakehouse, é útil entender os diferentes tipos de tabelas e os recursos de ativação. Para saber mais sobre o uso específico de tabelas do Apache Iceberg, consulte Visão geral das tabelas do Apache Iceberg.

Tabelas do Iceberg compatíveis

Somente tabelas do Apache Iceberg V2 (GA) e V3 (pré-lançamento) são compatíveis. Não há suporte para tabelas do Iceberg V1. Para fazer upgrade das tabelas V1 atuais, consulte Fazer upgrade das tabelas Iceberg V1 para V2.

Usar opções de tabela (prévia)

É possível ativar o uso de recursos gerenciados do BigQuery, como a linguagem de manipulação de dados (DML) do BigQuery e o gerenciamento automático de tabelas, configurando propriedades específicas da tabela. Esses recursos são ativados de maneiras diferentes, dependendo de onde a tabela é criada:

• No BigQuery:a DML do BigQuery e o gerenciamento automático de tabelas são ativados por padrão.
• De mecanismos de código aberto:para ativar, configure explicitamente as propriedades da tabela. Consulte Configurar opções de tabela para mais informações.

Consulte Configurar opções de tabela para instruções detalhadas.

Alterar uma tabela

Adicione uma coluna à tabela:

Console

1. No console Google Cloud , acesse Lakehouse.

   Acessar o Lakehouse

2. Selecione um catálogo ou crie um se você não tiver.

3. Na tabela Detalhes do namespace, selecione uma tabela e expanda as opções do menu.

4. Clique em Editar.

5. Atualize os valores da tabela na caixa de diálogo. Na seção Propriedades, é possível adicionar ou modificar propriedades como gcp.biglake.bigquery-dml.enabled e gcp.biglake.table-management.enabled para ativar ou desativar a DML do BigQuery ou o gerenciamento automático de tabelas.

   Por exemplo, é possível definir esses valores como true para ativar esses recursos. Para mais informações, consulte Configurar opções de tabela.

6. Clique em Salvar.

Spark

spark.sql("ALTER TABLE TABLE_NAME ADD COLUMNS ( desc string);")
spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

Para ativar a interoperabilidade de leitura/gravação e o gerenciamento de tabelas, defina as propriedades usando a cláusula SET TBLPROPERTIES:

SET TBLPROPERTIES (
  'gcp.biglake.bigquery-dml.enabled' = true,
  'gcp.biglake.table-management.enabled' = true
)

Trino

ALTER TABLE TABLE_NAME ADD COLUMN desc varchar;
DESCRIBE SCHEMA_NAME.TABLE_NAME;

Para ativar a interoperabilidade de leitura/gravação e o gerenciamento de tabelas, configure as seguintes propriedades de tabela:

• 'gcp.biglake.bigquery-dml.enabled' = true
• 'gcp.biglake.table-management.enabled' = true

gcloud

Para atualizar as propriedades da tabela usando gcloud, execute o comando gcloud biglake iceberg tables update.

gcloud biglake iceberg tables update TABLE_NAME \
    --project="PROJECT_ID" \
    --catalog="CATALOG_ID" \
    --namespace="NAMESPACE_NAME" \
    --update-properties="KEY=VALUE,..."

Substitua:

• TABLE_NAME: o nome da sua tabela Iceberg.
• PROJECT_ID: o ID do projeto Google Cloud .
• CATALOG_ID: o ID do seu catálogo.
• NAMESPACE_NAME: o nome do namespace do catálogo.
• KEY=VALUE,...: propriedades da tabela a serem adicionadas ou atualizadas.

BigQuery

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para atualizar as propriedades de uma tabela do Apache Iceberg no catálogo de tempo de execução do Lakehouse do BigQuery (como ativar a DML do BigQuery ou o gerenciamento automático de tabelas), use a seguinte instrução ALTER TABLE do GoogleSQL:

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "enabled");

Para atualizar o esquema e adicionar uma coluna a uma tabela do Apache Iceberg no catálogo de tempo de execução do Lakehouse do BigQuery, use a seguinte instrução ALTER TABLE do GoogleSQL:

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
ADD COLUMN new_column STRING;

Substitua:

• PROJECT_ID: o ID do projeto Google Cloud .
• CATALOG_ID: o ID do catálogo de ambientes de execução do Lakehouse.
• NAMESPACE: o nome do namespace do Iceberg.
• TABLE_NAME: o nome da sua tabela Iceberg.

REST

Para confirmar mudanças em uma tabela do Iceberg usando a API REST, faça uma solicitação POST ao endpoint UpdateIcebergTable (CommitTable):

POST /iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/CATALOG_ID/namespaces/NAMESPACE_NAME/tables/TABLE_NAME

O corpo da solicitação precisa conter uma carga útil JSON CommitTableRequest do Iceberg válida que define o requisito básico e a lista de atualizações de metadados a serem aplicadas.

Substitua:

• PROJECT_ID: o ID do projeto Google Cloud .
• CATALOG_ID: o ID do seu catálogo.
• NAMESPACE_NAME: o nome do namespace do catálogo.
• TABLE_NAME: o nome da sua tabela Iceberg.

A seguir

• Saiba como excluir uma tabela.