O catálogo do ambiente de execução do Lakehouse permite alterar tabelas do Apache Iceberg para evoluir esquemas, como adicionar colunas, e configurar propriedades de tabela. Essas atualizações ajudam a armazenar metadados personalizados ou ativar recursos gerenciados pelo BigQuery (pré-lançamento), incluindo a linguagem de manipulação de dados (DML) do BigQuery e a manutenção automática de tabelas.
É possível alterar tabelas usando o console do Google Cloud , o Apache Spark, o Trino, o BigQuery (pré-lançamento) ou a API REST. Para atualizar as propriedades da tabela na linha de comando, use também a Google Cloud CLI.
Antes de começar
-
Verifique se o faturamento está ativado para o projeto do Google Cloud .
-
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. - 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 receber 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 de fornecimento sem credenciais:
- Editor do BigLake (
roles/biglake.editor): o projeto - Usuário de objetos do Storage (
roles/storage.objectUser): o bucket do Cloud Storage
- Editor do BigLake (
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 do ambiente de execução do Lakehouse, é útil entender os diferentes tipos de tabela e os recursos de ativação deles. Para saber mais sobre como usar as tabelas do Apache Iceberg, consulte Visão geral das tabelas do Apache Iceberg.
Tabelas do Iceberg compatíveis
Somente as tabelas Apache Iceberg V2 (GA) e V3 (pré-lançamento) são compatíveis. As tabelas do Iceberg V1 não são compatíveis. Para fazer upgrade das tabelas V1 atuais, consulte Fazer upgrade das tabelas do Iceberg V1 para V2.
Usar opções de tabela (pré-lançamento)
É possível ativar o uso de recursos gerenciados pelo BigQuery, como a linguagem de manipulação de dados (DML) do BigQuery e o gerenciamento automático de tabelas, configurando propriedades de tabela específicas. Esses recursos são ativados de maneiras diferentes, dependendo de onde a tabela é criada:
- Do 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, é preciso configurar explicitamente as propriedades da tabela. Para mais informações, consulte Configurar opções de tabela.
Consulte Configurar opções de tabela para instruções detalhadas.
Alterar uma tabela
Selecione uma das seguintes opções:
Console
No console do Google Cloud , acesse a página Lakehouse.
Selecione um catálogo ou crie um, se não tiver.
Selecione um namespace ou crie um, se não tiver.
Na página Detalhes do namespace, na guia Tabelas, clique no nome da tabela que você quer alterar. A página Detalhes da tabela é aberta.
Para adicionar colunas ao esquema da tabela, faça o seguinte:
- Clique na guia Esquema.
- Clique em Editar esquema.
- Na seção Novos campos, clique em Adicionar campo. Em Nome do campo, insira um nome de coluna e, na lista Tipo, selecione um tipo de dados. Para inserir campos como texto, clique no botão Editar como texto para ativar e insira JSON ou pares
name:typeseparados por vírgulas. - Clique em Salvar.
Para atualizar as propriedades da tabela, faça o seguinte:
- Clique na guia Detalhes.
- Clique em Editar detalhes.
Na seção Propriedades, atualize os valores das propriedades atuais. Para adicionar uma propriedade personalizada, clique em Adicionar propriedade e, nos campos Chave e Valor, insira a chave e o valor da propriedade.
Por exemplo, para ativar a DML do BigQuery ou a manutenção automática de tabelas, no campo Valor de
gcp.biglake.bigquery-dml.enabledougcp.biglake.table-management.enabled, insiratrue. Para mais informações, consulte Configurar opções de tabela.Clique em Atualizar.
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 a manutenção 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 a manutenção 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 tabela do Iceberg.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.KEY=VALUE,...: propriedades da tabela a serem adicionadas ou atualizadas.
BigQuery
Para atualizar as propriedades de uma tabela do Apache Iceberg no
catálogo do ambiente de execução do Lakehouse no BigQuery (como
ativar a DML do BigQuery ou a manutenção automática 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 em uma tabela do Apache Iceberg no
catálogo do ambiente 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 do Google Cloud.CATALOG_ID: o ID do catálogo do ambiente de execução do Lakehouse.NAMESPACE: o nome do namespace do Iceberg.TABLE_NAME: o nome da tabela do Iceberg.
REST
Para confirmar mudanças em uma tabela do Iceberg usando a API REST, faça uma solicitação POST
para o 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 um payload JSON CommitTableRequest do Iceberg válido que defina o requisito base 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 catálogo.NAMESPACE_NAME: o nome do namespace do catálogo.TABLE_NAME: o nome da tabela do Iceberg.
A seguir
- Saiba como excluir uma tabela.