Crea y administra recursos en el catálogo del entorno de ejecución de Lakehouse

Lakehouse para Apache Iceberg admite la administración de recursos a través del catálogo de entornos de ejecución de Lakehouse.

Este catálogo compartido elimina el requisito de mantener varios catálogos para las cargas de trabajo de código abierto en diferentes motores de procesamiento de datos. Las operaciones admitidas incluyen la creación, visualización, modificación y eliminación de recursos, como espacios de nombres y tablas.

Antes de comenzar

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

  2. Habilita las APIs de BigQuery, BigQuery Storage y Managed Service para Apache Spark.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

    Habilitar las API

Roles obligatorios

Para obtener los permisos que necesitas para administrar los recursos de Apache Iceberg en el catálogo del entorno de ejecución de Lakehouse, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

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.

Crea recursos de catálogo

En las siguientes secciones, se describe cómo crear recursos en el catálogo del entorno de ejecución de Lakehouse.

Crea espacios de nombres

Selecciona una de las siguientes opciones:

API

Usa el método datasets.insert y especifica el campo ExternalCatalogDatasetOptions en el recurso del conjunto de datos que pasas.

{
  "datasetReference": {
    "projectId": "PROJECT_ID",
    "datasetId": "DATASET_ID"
  },
  "externalCatalogDatasetOptions": {
    "defaultStorageLocationUri": "URI",
    "parameters": {
      ...
    }
  },
  "location": "LOCATION"
}

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto que contiene tu conjunto de datos de destino.
  • DATASET_ID: Es el ID de tu conjunto de datos de destino.
  • URI: Es el URI de Cloud Storage de todas las tablas del conjunto de datos.
  • LOCATION: La ubicación de BigQuery en la que deseas crear el conjunto de datos.

SQL de Apache Spark 

CREATE NAMESPACE SPARK_CATALOG.NAMESPACE;

Reemplaza lo siguiente:

  • SPARK_CATALOG: Es el nombre de tu catálogo de Apache Spark.
  • NAMESPACE: Es el nombre de tu nuevo espacio de nombres.

Terraform 

provider "google" {
  project = "PROJECT_ID"
}

resource "google_bigquery_dataset" "default" {
  dataset_id = "DATASET_ID"
  location   = "LOCATION"

  external_catalog_dataset_options {
    default_storage_location_uri = "URI"
    parameters = {
      ...
    }
  }
}

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto que contiene tu conjunto de datos de destino.
  • DATASET_ID: Es el ID de tu conjunto de datos de destino.
  • LOCATION: La ubicación de BigQuery en la que deseas crear el conjunto de datos.
  • URI: Es el URI de Cloud Storage de todas las tablas del conjunto de datos.

Crea tablas de Apache Iceberg

Selecciona una de las siguientes opciones:

API

Usa el método tables.insert y especifica el campo ExternalCatalogTableOptions en el recurso de tabla que pasas.

{
  "tableReference": {
    "projectId": "PROJECT_ID",
    "datasetId": "DATASET_ID",
    "tableId": "TABLE_ID"
  },
  "externalCatalogTableOptions": {
    "parameters": {
      "table_type": "iceberg",
      "metadata_location": "METADATA_URI"
    },
    "connection_id": "CONNECTION_ID"
  }
}

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto que contiene tu tabla de destino.
  • DATASET_ID: Es el ID del conjunto de datos que contiene tu tabla de destino.
  • TABLE_ID: Es el ID de la tabla de destino.
  • METADATA_URI: Es el URI de Cloud Storage del archivo de metadatos de Apache Iceberg más reciente. Por ejemplo, gs://mybucket/mytable/metadata/1234.metadata.json.
  • CONNECTION_ID: Es el ID de tu conexión a Cloud Storage.

SQL de Apache Spark 

CREATE TABLE SPARK_CATALOG.NAMESPACE.TABLE
  (id bigint, data string) USING iceberg;

Reemplaza lo siguiente:

  • SPARK_CATALOG: Es el nombre de tu catálogo de Apache Spark.
  • NAMESPACE: Es el nombre de tu espacio de nombres.
  • TABLE: Es el nombre de tu tabla nueva.

Terraform 

resource "google_bigquery_table" "default" {
  deletion_protection = false
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "TABLE"

  external_catalog_table_options {
    storage_descriptor {
      location_uri  = "STORAGE_URI"
      input_format  = "org.apache.hadoop.mapred.FileInputFormat"
      output_format = "org.apache.hadoop.mapred.FileOutputFormat"
    }
    parameters = {
      "table_type"        = "iceberg"
      "metadata_location" = "METADATA_URI"
      "write.parquet.compression-codec" : "zstd"
      "EXTERNAL" : "TRUE"
    }
  }
}

Reemplaza lo siguiente:

  • TABLE: Es el nombre de la tabla de destino.
  • STORAGE_URI: Es el URI de Cloud Storage en el que se almacenan los datos de la tabla, que comienza con gs://.
  • METADATA_URI: Es el URI de Cloud Storage del archivo de metadatos de Apache Iceberg más reciente. Por ejemplo, gs://mybucket/mytable/metadata/1234.metadata.json.

Visualiza recursos del catálogo

En las siguientes secciones, se describe cómo ver los recursos en el catálogo del entorno de ejecución de Lakehouse.

Cómo ver los espacios de nombres

Selecciona una de las siguientes opciones:

API

Usa el método datasets.list para ver todos los espacios de nombres o el método datasets.get para ver información sobre un espacio de nombres definido.

SQL de Apache Spark

Para ver todos los espacios de nombres en un catálogo, usa la siguiente instrucción:

SHOW { DATABASES | NAMESPACES } IN SPARK_CATALOG;

Reemplaza SPARK_CATALOG por el nombre de tu catálogo de Apache Spark.

Para ver información sobre un espacio de nombres definido, usa la siguiente instrucción:

DESCRIBE { DATABASE | NAMESPACE } [EXTENDED]
SPARK_CATALOG.NAMESPACE;

Reemplaza lo siguiente:

  • SPARK_CATALOG: Es el nombre de tu catálogo de Apache Spark.
  • NAMESPACE: Es el nombre de tu espacio de nombres.

Ver tablas

Selecciona una de las siguientes opciones:

API

Usa el método tables.list para ver todas las tablas en un espacio de nombres o el método tables.get para ver información sobre una tabla definida.

SQL de Apache Spark

Para ver todas las tablas en un espacio de nombres, usa la siguiente instrucción:

SHOW TABLES IN SPARK_CATALOG.NAMESPACE;

Reemplaza lo siguiente:

  • SPARK_CATALOG: Es el nombre de tu catálogo de Apache Spark.
  • NAMESPACE: Es el nombre de tu espacio de nombres.

Para ver información sobre una tabla definida, usa la siguiente instrucción:

DESCRIBE TABLE [EXTENDED]
SPARK_CATALOG.NAMESPACE.TABLE;

Reemplaza lo siguiente:

  • SPARK_CATALOG: Es el nombre de tu catálogo de Apache Spark.
  • NAMESPACE: Es el nombre de tu espacio de nombres.
  • TABLE: Es el nombre de tu tabla.

Modifica los recursos del catálogo

En las siguientes secciones, se describe cómo modificar los recursos en el catálogo del entorno de ejecución de Lakehouse.

Actualiza los espacios de nombres

Selecciona una de las siguientes opciones:

API

Usa el método datasets.patch y actualiza el campo ExternalCatalogDatasetOptions en el recurso del conjunto de datos. No se recomienda el método datasets.update porque reemplaza todo el recurso del conjunto de datos.

SQL de Apache Spark

Usa la sentencia ALTER DATABASE.

Actualiza tablas de Apache Iceberg

Selecciona una de las siguientes opciones:

API

Usa el método tables.patch y actualiza el campo ExternalCatalogTableOptions en el recurso de tabla. No se recomienda el método tables.update porque reemplaza todo el recurso de tabla.

Para actualizar el esquema o el archivo de metadatos, usa el método tables.patch y establece la propiedad autodetect_schema como verdadera:

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID?autodetect_schema=true

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto que contiene la tabla que deseas actualizar.
  • DATASET_ID: Es el ID del conjunto de datos que contiene la tabla que deseas actualizar.
  • TABLE_ID: Es el ID de la tabla que deseas actualizar.

En el cuerpo de la solicitud, especifica el valor actualizado para cada campo. Por ejemplo, para actualizar la ubicación de los metadatos de la tabla de Apache Iceberg, especifica el valor actualizado para el campo metadata_location:

{
  "externalCatalogTableOptions": {
    "parameters": {"metadata_location": "METADATA_URI"}
  },
  "schema": null
}'

Reemplaza METADATA_URI por el URI de Cloud Storage del archivo de metadatos de Apache Iceberg más reciente. Por ejemplo, gs://mybucket/mytable/metadata/1234.metadata.json.

SQL de Apache Spark

Usa la sentencia ALTER TABLE.

Borra recursos del catálogo

En las siguientes secciones, se describe cómo borrar recursos en el catálogo del entorno de ejecución de Lakehouse.

Borra espacios de nombres

Selecciona una de las siguientes opciones:

API

Usa el método datasets.delete. Establece el parámetro deleteContents en verdadero para borrar las tablas de tu espacio de nombres.

SQL de Apache Spark 

DROP NAMESPACE SPARK_CATALOG.NAMESPACE;

Reemplaza lo siguiente:

  • SPARK_CATALOG: Es el nombre de tu catálogo de Apache Spark.
  • NAMESPACE: Es el nombre de tu espacio de nombres.

Borra las tablas

Selecciona una de las siguientes opciones:

API

Usa el método tables.delete y especifica el nombre de la tabla. Con este método, no se borran los archivos asociados en Cloud Storage.

SQL de Apache Spark

Para descartar la tabla, usa la siguiente instrucción:

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE;

Reemplaza lo siguiente:

  • SPARK_CATALOG: Es el nombre de tu catálogo de Apache Spark.
  • NAMESPACE: Es el nombre de tu espacio de nombres.
  • TABLE: Es el nombre de la tabla que se descartará.

Para descartar la tabla y borrar los archivos asociados en Cloud Storage, usa la siguiente instrucción:

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE PURGE;

Reemplaza lo siguiente:

  • SPARK_CATALOG: Es el nombre de tu catálogo de Apache Spark.
  • NAMESPACE: Es el nombre de tu espacio de nombres.
  • TABLE: Es el nombre de la tabla que se borrará.

¿Qué sigue?