Registrar uma tabela

O registro de uma tabela do Apache Iceberg integra os metadados dela 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 estrutura de tabela nova e vazia e o armazenamento associado a ela.

Antes de começar

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

  2. Ative a API BigLake.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter a permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com a função Proprietário (roles/owner). Caso contrário, você pode receber essa permissão com a função Administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin). Saiba como conceder funções.

    Ativar a API

  3. Configure o catálogo de 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:

  • Registrar uma tabela:
    • Administrador do BigLake (roles/biglake.admin) – seu projeto
    • Administrador do Storage (roles/storage.admin) – o bucket do Cloud Storage de destino

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 com papéis personalizados ou outros papéis predefinidos.

Registrar uma tabela

Registre uma tabela do Iceberg.

gcloud

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

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 Google Cloud ID do projeto.
  • 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) substitui a tabela se ela já existir.

REST

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

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 Google Cloud ID do projeto.
  • 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