Registrar uma tabela

Ao registrar uma tabela do Apache Iceberg, os metadados dela são integrados ao catálogo de ambiente de execução do Lakehouse, disponibilizando os dados da tabela para consulta e gerenciamento em um namespace. Esse processo é diferente da criação de tabelas, que inicializa uma nova estrutura de tabela vazia e o armazenamento associado.

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 registrar uma tabela, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto e no bucket de armazenamento:

  • Registre uma tabela:
    • Administrador do BigLake (roles/biglake.admin): seu projeto
    • Administrador do Storage (roles/storage.admin): o bucket de destino 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.

Registrar uma tabela

Registre uma tabela do Iceberg.

gcloud

Para registrar uma tabela usando gcloud, execute o comando gcloud biglake iceberg tables register.

gcloud biglake iceberg tables register TABLE_NAME \
    --project="PROJECT_ID" \
    --catalog="CATALOG_ID" \
    --namespace="NAMESPACE_NAME" \
    --metadata-location="METADATA_LOCATION" \
    [--overwrite]

Substitua:

  • TABLE_NAME: o nome a ser atribuído à tabela registrada.
  • 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.
  • METADATA_LOCATION: o URI do Cloud Storage do arquivo JSON de metadados mais recente da tabela, por exemplo, gs://my-bucket/path/to/metadata/00001.metadata.json.
  • --overwrite: (opcional) substitua a tabela se ela já existir.

REST

Para registrar uma tabela do Iceberg usando a API REST, faça uma solicitação POST ao endpoint RegisterIcebergTable:

POST /iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/CATALOG_ID/namespaces/NAMESPACE_NAME/register

O corpo da solicitação precisa conter um payload JSON com a seguinte estrutura:

{
  "name": "TABLE_NAME",
  "metadata-location": "METADATA_LOCATION",
  "overwrite": OVERWRITE
}

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.
  • TABLE_NAME: o nome da tabela registrada.
  • METADATA_LOCATION: o URI do Cloud Storage do arquivo JSON de metadados mais recente da tabela.
  • OVERWRITE: true para substituir se a tabela existir, caso contrário, false.

A seguir