Registra una tabla

Registrar una tabla de Apache Iceberg existente integra sus metadatos en el catálogo de entornos de ejecución de Lakehouse, lo que hace que los datos de la tabla estén disponibles para su consulta y administración dentro de un espacio de nombres. Este proceso difiere de la creación de tablas, que inicializa una nueva estructura de tabla vacía y su almacenamiento asociado.

Antes de comenzar

  1. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

  2. Habilita la API de BigLake si aún no lo hiciste.

    Roles necesarios para habilitar las APIs

    Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

    Habilitar la API

  3. Configura el catálogo de entornos de ejecución de Lakehouse con el extremo del catálogo de REST de Apache Iceberg.

Roles obligatorios

Para obtener los permisos que necesitas para registrar una tabla, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto y bucket de almacenamiento:

  • Registra una tabla:
    • Administrador de BigLake (roles/biglake.admin): Tu proyecto
    • Administrador de almacenamiento (roles/storage.admin): Es el bucket de Cloud Storage de destino.

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Registra una tabla

Registra una tabla de Iceberg existente.

gcloud

Para registrar una tabla con gcloud, ejecuta el 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]

Reemplaza lo siguiente:

  • TABLE_NAME: Es el nombre que se asignará a la tabla registrada.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • CATALOG_ID: Es el ID del catálogo.
  • NAMESPACE_NAME: Es el nombre del espacio de nombres del catálogo.
  • METADATA_LOCATION: Es el URI de Cloud Storage del archivo JSON de metadatos más reciente de la tabla, por ejemplo, gs://my-bucket/path/to/metadata/00001.metadata.json.
  • --overwrite: (Opcional) Reemplaza la tabla si ya existe.

REST

Para registrar una tabla de Iceberg con la API de REST, realiza una solicitud POST al extremo RegisterIcebergTable:

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

El cuerpo de la solicitud debe contener una carga útil de JSON con la siguiente estructura:

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

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • CATALOG_ID: Es el ID del catálogo.
  • NAMESPACE_NAME: Es el nombre del espacio de nombres del catálogo.
  • TABLE_NAME: Es el nombre de la tabla registrada.
  • METADATA_LOCATION: Es el URI de Cloud Storage del archivo JSON de metadatos más reciente de la tabla.
  • OVERWRITE: true para reemplazar si la tabla existe; de lo contrario, false.

¿Qué sigue?