Configura el extremo del catálogo REST de Lakehouse para Iceberg

Para los catálogos nuevos, recomendamos usar el extremo del catálogo de REST de Apache Iceberg en el catálogo de entorno de ejecución de Lakehouse. Este extremo proporciona una interfaz estandarizada y completamente administrada basada en la API de REST del catálogo de Apache Iceberg de código abierto.

Este extremo actúa como una única fuente de información, lo que permite una interoperabilidad perfecta en todos tus motores de consultas. Permite que motores como Apache Spark descubran, lean y administren tus tablas de Google Cloud Lakehouse.

Este enfoque es una buena opción si usas motores de OSS o de terceros compatibles para acceder a los datos en Cloud Storage y necesitas interoperabilidad con otros motores, incluido BigQuery. Admite funciones como la venta de credenciales para el control de acceso detallado y la replicación entre regiones y la recuperación ante desastres.

En cambio, el extremo Catálogo personalizado de Apache Iceberg para BigQuery es una integración anterior. Si bien los flujos de trabajo existentes pueden seguir usándolo, el catálogo de REST ofrece una experiencia más estandarizada y con más funciones.

Antes de comenzar

Antes de continuar, familiarízate con el catálogo de entorno de ejecución de Lakehouse y el resumen del extremo del catálogo de REST de Iceberg.

Si tienes tablas de Apache Iceberg existentes de la versión 1 (V1), debes actualizarlas antes de usarlas con el extremo del catálogo REST de Apache Iceberg. Para obtener más información, consulta Actualiza las tablas de Iceberg V1 a V2.

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

  2. Habilita la API de BigLake.

    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

Roles obligatorios

Para obtener los permisos que necesitas para usar el extremo del catálogo REST 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:

  • Realizar tareas administrativas, como administrar el acceso de los usuarios al catálogo, el acceso al almacenamiento y el modo de venta de credenciales del catálogo:
  • Registrar tablas en un catálogo de Lakehouse: Administrador de BigLake (roles/biglake.admin) en el proyecto
  • Leer datos de la tabla en modo de venta de credenciales: Visualizador de BigLake (roles/biglake.viewer) en el proyecto Si usas motores de consultas, como Managed Service para Apache Spark, Managed Service para Apache Spark o Dataflow, para leer datos de tablas, otorga este rol a la cuenta de servicio que usas para ejecutar trabajos en ese motor.
  • Escribir datos de la tabla en modo de venta de credenciales: Editor de BigLake (roles/biglake.editor) en el proyecto Si usas motores de consultas, como Managed Service para Apache Spark, Managed Service para Apache Spark o Dataflow, para escribir datos de tablas, otorga este rol a la cuenta de servicio que usas para ejecutar trabajos en ese motor.
  • Usa la cuenta de servicio del catálogo del entorno de ejecución de Lakehouse aprovisionada automáticamente en el modo de venta de credenciales: Usuario de objetos de almacenamiento (roles/storage.objectUser) en todos los buckets de Cloud Storage asociados. Después de crear el catálogo, otorga de forma explícita el rol de usuario de objetos de almacenamiento (roles/storage.objectUser) en todos los buckets de almacenamiento asociados a la cuenta de servicio del catálogo de Lakehouse aprovisionado automáticamente.
  • Leer recursos del catálogo y datos de tablas en el modo de no venta de credenciales:
  • Administra los recursos del catálogo y escribe datos de la tabla en el modo de no venta de credenciales:

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 mediante roles personalizados o cualquier otro rol predefinido.

Limitaciones

El extremo del catálogo de REST de Apache Iceberg está sujeto a las siguientes limitaciones:

Limitaciones generales

  • Se admiten las tablas de Apache Iceberg V2 (GA) y V3 (versión preliminar). No se admiten las tablas de Iceberg V1. Antes de usar tablas existentes de la versión 1 con el extremo del catálogo de REST de Apache Iceberg, debes actualizarlas a una versión compatible.
  • Cuando se usa el modo de venta de credenciales, si el motor de consultas te permite establecer la propiedad io-impl para una conexión de catálogo, debes establecerla en org.apache.iceberg.gcp.gcs.GCSFileIO.
  • Actualmente, no se admiten los buckets con espacios de nombres jerárquicos en el modo de venta de credenciales.

Limitaciones de las tablas

  • No puedes crear ni modificar tablas en el extremo del catálogo de Apache Iceberg REST con sentencias del lenguaje de definición de datos (DDL) o del lenguaje de manipulación de datos (DML) de BigQuery. Puedes modificar estas tablas con la API de BigQuery (con la herramienta de línea de comandos de bq o las bibliotecas cliente), pero si lo haces, corres el riesgo de realizar cambios que sean incompatibles con el motor externo.
  • Las tablas administradas a través del extremo del catálogo REST de Apache Iceberg no admiten el control de acceso detallado (FGAC), como la seguridad a nivel de fila y columna.
  • Está prohibido establecer las propiedades de la tabla de Iceberg write.data.path o write.metadata.path en valores distintos de los predeterminados.
  • Las rutas de acceso a las tablas deben estar anidadas dentro de la ruta de acceso del espacio de nombres principal (por ejemplo, gs://{namespace_path}/.../{table_name}). Para evitar conflictos y mejorar la seguridad, se agrega automáticamente un sufijo de cadena aleatoria a la ubicación resultante (por ejemplo, gs://{namespace_path}/{table_name}/{random_suffix}).

Limitaciones de datos

  • Solo se admiten archivos Parquet. Para obtener más detalles sobre cómo BigQuery controla los archivos Parquet, consulta Carga datos Parquet desde Cloud Storage.
  • El tamaño del archivo de Iceberg metadata.json está limitado a 1 MB. Para solicitar un aumento de este límite, comunícate con tu equipo de Cuentas de Google.

Limitaciones de las consultas

  • Las tablas de metadatos de Apache Iceberg (como .snapshots o .files) no se pueden consultar en BigQuery con identificadores de nombres de cinco partes. Puedes consultar estas tablas con Spark.

Consideraciones

Ten en cuenta los siguientes parámetros de configuración cuando crees un catálogo.

Tipo de bucket

Puedes crear un catálogo de un solo bucket o de varios buckets.

  • Catálogo de varios buckets (bl://) (recomendado): Esta configuración permite que tu catálogo asocie varios buckets y que le asignes un nombre independiente de cualquier nombre de bucket.
  • Un solo bucket (gs://): Esta configuración restringe tu catálogo a un solo bucket y bloquea el nombre del catálogo con el nombre del bucket. No se recomienda para proyectos nuevos.

Modo de credencial (alcance)

Puedes crear un catálogo que use credenciales de usuario final o el modo de venta de credenciales.

  • Credenciales de usuario final: El catálogo pasa la identidad del usuario final que accede a él a Cloud Storage para las verificaciones de autorización.

  • Modo de venta de credenciales: Es un mecanismo de delegación de acceso al almacenamiento que permite a los administradores del catálogo del entorno de ejecución de Lakehouse controlar los permisos directamente en los recursos del catálogo del entorno de ejecución de Lakehouse, lo que elimina la necesidad de que los usuarios del catálogo tengan acceso directo a los buckets de Cloud Storage. Permite que los administradores de Lakehouse de Google Cloud otorguen permisos a los usuarios sobre archivos de datos específicos.

    La cuenta de servicio del catálogo del entorno de ejecución de Lakehouse aprovisionada automáticamente requiere el rol explícito de Usuario de objetos de almacenamiento (roles/storage.objectUser) en todos los buckets de Cloud Storage asociados. De forma predeterminada, no tiene acceso de ningún tipo. Sin este rol, las credenciales vendidas no tendrán el alcance suficiente para realizar escrituras de almacenamiento. Si usas herramientas como gcloud o Terraform, debes otorgar este rol de forma manual.

    La creación de la cuenta de servicio del catálogo aprovisionada automáticamente tiene coherencia eventual. Esto significa que la cuenta de servicio tarda en propagarse por el sistema. Si intentas otorgar roles a la cuenta de servicio inmediatamente después de su creación, es posible que la solicitud falle. Para saber cuánto tiempo tardan, en promedio, en propagarse los cambios de acceso, consulta Propagación de cambios de acceso.

Ubicación

Familiarízate con los requisitos de ubicación antes de crear un catálogo.

  • Cuando creas un espacio de nombres, este usa automáticamente la misma región que tu catálogo.

  • Si tu catálogo usa un bucket multirregional y deseas usarlo con las multirregiones de BigQuery (US o EU), debes borrar y volver a crear el catálogo para especificar la ubicación principal.

Configura el extremo del catálogo de REST de Iceberg

Antes de configurar tu catálogo, te recomendamos que leas la descripción general del extremo del catálogo REST de Apache Iceberg para comprender su jerarquía de recursos, los tipos de catálogos y la estructura de nomenclatura.

A continuación, se indican los pasos generales que debes seguir cuando uses el extremo del catálogo de REST de Apache Iceberg en el catálogo del entorno de ejecución de Lakehouse:

  1. Elige el tipo de catálogo: un catálogo de varios buckets (bl://) (recomendado) o un catálogo de un solo bucket (gs://).
  2. Crea un catálogo que apunte a la ubicación de tu almacén.
  3. Configura tu aplicación cliente para que use el extremo del catálogo REST de Apache Iceberg.
  4. Crea un espacio de nombres o un esquema para organizar tus tablas.
  5. Crea tablas y consulta datos en ellas con el cliente configurado.

Crea un catálogo

Sigue estos pasos para crear un catálogo según el modo de credenciales y el tipo de bucket que prefieras.

Console

Crea un catálogo de varios bucket (bl://) (recomendado)

Esta configuración permite que tu catálogo asocie varios buckets y que le asignes un nombre independientemente del nombre de cualquier bucket.

  1. Abre la página Lakehouse en la consola de Google Cloud .

    Ir a Lakehouse

  2. Haz clic en Crear catálogo.

  3. En Tipo de catálogo, selecciona Catálogo de REST de Iceberg.

  4. En Opciones de bucket para el catálogo de Lakehouse, selecciona Catálogo de varios buckets.

  5. En Ruta de acceso predeterminada de Cloud Storage para el catálogo, ingresa o busca la ruta de acceso de Cloud Storage que se usará con tu catálogo.

  6. En ID de catálogo, ingresa un nombre personalizado para tu catálogo.

  7. En Ubicación principal, selecciona una ubicación. La ubicación debe estar cerca de las regiones del bucket principal.

  8. Haz clic en Continuar.

  9. En el paso Rutas de datos, agrega rutas de Cloud Storage adicionales si es necesario.

  10. Haz clic en Continuar.

  11. En Método de autenticación, selecciona Credenciales de usuario final o Modo de venta de credenciales.

  12. Haz clic en Crear.

    Se creará tu catálogo y se abrirá la página Detalles del catálogo.

  13. Si seleccionaste Modo de venta de credenciales, sigue estos pasos adicionales:

    1. En Método de autenticación, haz clic en Establecer permisos del bucket.
    2. En el diálogo, haz clic en Confirmar.

Crea un catálogo de un solo bucket (gs://)

  1. En Tipo de catálogo, selecciona Catálogo de REST de Iceberg.
  2. En Opciones de bucket para el catálogo de Lakehouse, selecciona Catálogo de bucket único.
  3. En Ruta de acceso predeterminada de Cloud Storage para el catálogo, ingresa o busca la ruta de acceso de Cloud Storage que se usará con tu catálogo. (En el caso de un catálogo de un solo bucket (gs://), solo puedes tener un catálogo por bucket, y el nombre del catálogo debe coincidir con el nombre del bucket).
  4. Haz clic en Continuar.
  5. En Método de autenticación, selecciona Credenciales de usuario final o Modo de venta de credenciales.
  6. Haz clic en Crear.
  7. Si seleccionaste Modo de venta de credenciales, realiza los siguientes pasos adicionales:
    1. En Método de autenticación, haz clic en Establecer permisos del bucket.
    2. En el diálogo, haz clic en Confirmar.

gcloud

Crea un catálogo de varios bucket (bl://) (recomendado)

Esta configuración permite que tu catálogo asocie varios buckets y que le asignes un nombre independientemente del nombre de cualquier bucket.

Para crear un catálogo de varios bucket (bl://), que es el método recomendado, ejecuta el comando gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    --credential-mode CREDENTIAL_MODE \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    [--primary-location LOCATION]

Reemplaza lo siguiente:

  • CATALOG_NAME: Un nombre para tu catálogo. En el caso de los catálogos de varios bucket (bl://) (recomendado), este es el nombre de tu catálogo personalizado. En el caso de los catálogos de un solo bucket (gs://), este valor coincide con el ID de bucket de Cloud Storage que se usa con el catálogo de REST.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud.
  • DEFAULT_LOCATION: Especifica la ubicación de almacenamiento predeterminada para el catálogo. Puedes especificar un bucket (gs://my-bucket) o una subruta de acceso (gs://my-bucket/path). Todos los espacios de nombres y las tablas del catálogo deben residir en la ruta de acceso especificada. Por ejemplo, si especificas gs://my-bucket/path, no puedes crear espacios de nombres ni tablas en gs://my-bucket/another/path.

  • CREDENTIAL_MODE: Es el método de autenticación. Usa end-user para Credenciales de usuario final o vended-credentials para Modo de venta de credenciales.

    Nota: Si usas el modo de venta de credenciales, debes otorgar de forma explícita el rol de usuario de objetos de almacenamiento (roles/storage.objectUser) en todos los buckets de almacenamiento asociados a la cuenta de servicio del catálogo de entorno de ejecución de Lakehouse aprovisionado automáticamente de tu catálogo.

  • RESTRICTED_LOCATIONS: (Opcional) Lista separada por comas de ubicaciones de almacenamiento permitidas adicionales, en el formato gs://my-bucket-1/...,gs://my-bucket-2/.... Si especificas una ruta de acceso (como gs://my-bucket/path), todos los espacios de nombres o las tablas dentro de ese bucket deben estar en esa ruta de acceso. Todas las ubicaciones de almacenamiento en la nube configuradas en la ubicación predeterminada y las ubicaciones restringidas deben estar en el mismo grupo de regiones geográficas o jurisdicción (como Estados Unidos, Europa, Canadá o Asia). Por ejemplo, no puedes combinar un bucket en EE.UU. con uno en Europa. Para obtener una lista de las ubicaciones compatibles, consulta Ubicaciones de Lakehouse.

    Advertencia: Evita configurar rutas superpuestas con otros catálogos para impedir la exposición no autorizada de credenciales. Para obtener más información, consulta Almacenamiento en varios buckets.

  • LOCATION: (Opcional) Es la región principal del catálogo para garantizar la interoperabilidad con BigQuery. En el caso de los buckets de Cloud Storage en la región de EE.UU. (por ejemplo, US o us-central1) o la región de la UE (por ejemplo, EU o europe-west4), especifica US o EU, respectivamente, para garantizar que se pueda acceder al catálogo y que esté disponible para realizar consultas desde las multirregiones de BigQuery correspondientes. Para obtener más información, consulta Regiones de buckets y catálogos.

Crea un catálogo de un solo bucket (gs://)

Para crear un catálogo de un solo bucket (gs://), ejecuta el siguiente comando:

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode CREDENTIAL_MODE

Reemplaza lo siguiente:

  • CATALOG_NAME: Un nombre para tu catálogo. En el caso de los catálogos de varios bucket (bl://) (recomendado), este es el nombre de tu catálogo personalizado. En el caso de los catálogos de un solo bucket (gs://), este valor coincide con el ID de bucket de Cloud Storage que se usa con el catálogo de REST.
  • PROJECT_ID: ID del proyecto de Google Cloud.
  • CREDENTIAL_MODE: Es el método de autenticación. Usa end-user para Credenciales de usuario final o vended-credentials para Modo de venta de credenciales.

Configura la aplicación cliente

Después de crear un catálogo, configura tu aplicación cliente para que lo use. En estos ejemplos, se muestra cómo configurar la autenticación con o sin venta de credenciales.

Clúster

Crea un clúster de Managed Service para Apache Spark en Compute Engine con propiedades de configuración simplificadas (recomendado) o especificando propiedades de forma manual.

Crea un clúster con la propiedad del catálogo:

gcloud dataproc clusters create CLUSTER_NAME \
  --enable-component-gateway \
  --project=PROJECT_ID \
  --region=REGION \
  --optional-components=ICEBERG \
  --image-version=DATAPROC_VERSION \
  --properties="dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Reemplaza lo siguiente:

  • CLUSTER_NAME: Es un nombre para tu clúster.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • REGION: Es la región del clúster de Managed Service para Apache Spark.
  • DATAPROC_VERSION: Es la versión de la imagen de Managed Service para Apache Spark, por ejemplo, 2.3.
  • CATALOG_NAME: Es un nombre para el catálogo local de Spark (por ejemplo, my_catalog). Puede ser el mismo que CATALOG_ID.
  • CATALOG_ID: Es el ID del catálogo que creaste.

En el archivo de la aplicación de PySpark, crea el SparkSession sin especificar la configuración del catálogo:

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

Configuración manual

Si no usas la propiedad de configuración simplificada, crea un clúster como se describió anteriormente, pero sin la marca --properties. Luego, configura tu SparkSession de forma manual:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .getOrCreate()

Reemplaza lo siguiente:

  • CATALOG_NAME: Es un nombre para el catálogo local de Spark (por ejemplo, my_catalog).
  • APP_NAME: Es un nombre para tu sesión de Spark.
  • REST_API_VERSION: Se establece en v1 para la versión estable de la API.
  • WAREHOUSE_PATH: Es la ruta de acceso a tu almacén. Para los catálogos de BigLake, usa bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Usa gs://CLOUD_STORAGE_BUCKET_NAME para los catálogos de bucket de Cloud Storage.
  • PROJECT_ID: Es el proyecto al que se le factura el uso del extremo del catálogo de REST de Apache Iceberg, que puede ser diferente del proyecto propietario del bucket de Cloud Storage. Para obtener detalles sobre la configuración del proyecto cuando se usa una API de REST, consulta Parámetros del sistema.

Configura la venta de credenciales

Para usar la venta de credenciales, debes usar un catálogo en modo de venta de credenciales y agregar el encabezado X-Iceberg-Access-Delegation a las solicitudes de catálogo de REST de Iceberg con un valor de vended-credentials. Para ello, agrega la siguiente línea al compilador SparkSession: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Ejemplo con venta de credenciales

En el siguiente ejemplo, se configura el motor de consultas con la venta de credenciales:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .getOrCreate()

Para obtener más información, consulta la sección Encabezados en RESTCatalog de la documentación de Apache Iceberg.

Los clústeres de Managed Service para Apache Spark admiten flujos de autorización de Google para Apache Iceberg en las siguientes versiones:

  • Versiones de imagen 2.2.65 y posteriores de Managed Service para Apache Spark en Compute Engine
  • Versiones de imagen 2.3.11 y posteriores de Managed Service para Apache Spark en Compute Engine

Sin servidores

Envía una carga de trabajo por lotes de PySpark a Managed Service para Apache Spark con propiedades de configuración simplificadas (recomendado) o especificando propiedades de forma manual.

Envía un trabajo por lotes con la propiedad del catálogo:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Reemplaza lo siguiente:

  • PYSPARK_FILE: Es la ruta de acceso de Cloud Storage gs:// a tu archivo de aplicación de PySpark.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • REGION: Es la región de la carga de trabajo por lotes de Managed Service para Apache Spark.
  • RUNTIME_VERSION: Es la versión del entorno de ejecución de Managed Service para Apache Spark, por ejemplo, 2.3.
  • CATALOG_NAME: Es un nombre para el catálogo local de Spark (por ejemplo, my_catalog). Puede ser el mismo que CATALOG_ID.
  • CATALOG_ID: Es el ID del catálogo que creaste.

En el archivo de la aplicación de PySpark, crea el SparkSession sin especificar la configuración del catálogo:

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

Configuración manual

Si no usas la propiedad de configuración simplificada, debes especificar manualmente los parámetros de configuración del catálogo:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

Reemplaza lo siguiente:

  • PYSPARK_FILE: Es la ruta de acceso de Cloud Storage gs:// a tu archivo de aplicación de PySpark.
  • REGION: Es la región de la carga de trabajo por lotes de Managed Service para Apache Spark.
  • RUNTIME_VERSION: Es la versión del entorno de ejecución de Managed Service para Apache Spark, por ejemplo, 2.3.
  • CATALOG_NAME: Es un nombre para el catálogo local de Spark (por ejemplo, my_catalog).
  • REST_API_VERSION: Se establece en v1 para la versión estable de la API.
  • WAREHOUSE_PATH: Es la ruta de acceso a tu almacén. Para los catálogos de BigLake, usa bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Usa gs://CLOUD_STORAGE_BUCKET_NAME para los catálogos de bucket de Cloud Storage.
  • PROJECT_ID: Es el proyecto al que se le factura el uso del extremo del catálogo de REST de Apache Iceberg, que puede ser diferente del proyecto propietario del bucket de Cloud Storage. Para obtener detalles sobre la configuración del proyecto cuando se usa una API de REST, consulta Parámetros del sistema.

Configura la venta de credenciales

Para usar la venta de credenciales, debes usar un catálogo en modo de venta de credenciales y agregar el encabezado X-Iceberg-Access-Delegation a las solicitudes de extremo del catálogo de REST de Apache Iceberg con un valor de vended-credentials. Para ello, agrega la siguiente línea a las configuraciones de Managed Service para Apache Spark: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Ejemplo con venta de credenciales

En el siguiente ejemplo, se configura el motor de consultas con la venta de credenciales:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials,\"
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions

Para obtener más información, consulta la sección Encabezados en RESTCatalog de la documentación de Apache Iceberg.

Managed Service para Apache Spark admite flujos de autorización de Google para Apache Iceberg en las siguientes versiones del entorno de ejecución:

  • Tiempos de ejecución 2.2.60 y versiones posteriores de Managed Service para Apache Spark
  • Tiempos de ejecución de Managed Service para Apache Spark 2.3.10 y versiones posteriores

Trino

Para usar Trino con el extremo del catálogo REST de Apache Iceberg, crea un clúster de Managed Service para Apache Spark con el componente de Trino y configura las propiedades del catálogo con la marca gcloud dataproc clusters create --properties. En el siguiente ejemplo, se crea un catálogo de Trino llamado CATALOG_NAME:

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=REGION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=WAREHOUSE_PATH,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.biglake.project-id=PROJECT_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager"

Reemplaza lo siguiente:

  • CLUSTER_NAME: Es un nombre para tu clúster.
  • REGION: Es la región del clúster de Managed Service para Apache Spark.
  • DATAPROC_VERSION: Es la versión de la imagen de Managed Service para Apache Spark, por ejemplo, 2.2.
  • NETWORK_ID: ID de la red del clúster. Para obtener más información, consulta Configuración de red del clúster de Managed Service para Apache Spark.
  • CATALOG_NAME: Es el nombre de tu catálogo de Trino que usa el extremo del catálogo de REST de Apache Iceberg.
  • REST_API_VERSION: Se establece en v1 para la versión estable de la API.
  • WAREHOUSE_PATH: Es la ruta de acceso a tu almacén. Para los catálogos de BigLake, usa bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Usa gs://CLOUD_STORAGE_BUCKET_NAME para los catálogos de bucket de Cloud Storage.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud que se usará para el catálogo del entorno de ejecución de Lakehouse.

Después de crear el clúster, conéctate a la instancia de VM principal y usa la CLI de Trino:

trino --catalog=CATALOG_NAME

Managed Service para Apache Spark Trino admite flujos de autorización de Google para Apache Iceberg en las siguientes versiones:

  • Versiones del entorno de ejecución 2.2 de Managed Service para Apache Spark en Compute Engine: 2.2.65 y versiones posteriores
  • Versiones del entorno de ejecución 2.3 de Managed Service para Apache Spark en Compute Engine: 2.3.11 y versiones posteriores
  • No se admite Managed Service para Apache Spark en Compute Engine 3.0.

Configura la venta de credenciales

La venta de credenciales solo es compatible con la versión 481 y versiones posteriores de Trino.

Apache Iceberg 1.10 o versiones posteriores

Las versiones 1.10 y posteriores de Apache Iceberg de código abierto tienen compatibilidad integrada con los flujos de autorización de Google en GoogleAuthManager. A continuación, se muestra un ejemplo de cómo configurar Spark para usar el extremo del catálogo de REST de Apache Iceberg.

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Reemplaza lo siguiente:

  • CATALOG_NAME: Es un nombre para el catálogo local de Spark (por ejemplo, my_catalog).
  • APP_NAME: Es un nombre para tu sesión de Spark.
  • REST_API_VERSION: Se establece en v1 para la versión estable de la API.
  • WAREHOUSE_PATH: Es la ruta de acceso a tu almacén. Para los catálogos de BigLake, usa bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Usa gs://CLOUD_STORAGE_BUCKET_NAME para los catálogos de bucket de Cloud Storage.
  • PROJECT_ID: Es el proyecto al que se le factura el uso del extremo del catálogo de REST de Apache Iceberg, que puede ser diferente del proyecto propietario del bucket de Cloud Storage. Para obtener detalles sobre la configuración del proyecto cuando se usa una API de REST, consulta Parámetros del sistema.

Configura la venta de credenciales

En el ejemplo anterior, no se usa la venta de credenciales. Para usar la venta de credenciales, debes usar un catálogo en modo de venta de credenciales y agregar el encabezado X-Iceberg-Access-Delegation a las solicitudes de extremo del catálogo de REST de Apache Iceberg con un valor de vended-credentials agregando la siguiente línea al compilador SparkSession: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Ejemplo con venta de credenciales

En el siguiente ejemplo, se configura el motor de consultas con la venta de credenciales:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Para obtener más información, consulta la sección Encabezados en RESTCatalog de la documentación de Apache Iceberg.

Versiones anteriores de Apache Iceberg

En el caso de las versiones de Apache Iceberg de código abierto anteriores a la 1.10, puedes configurar la autenticación estándar de OAuth configurando una sesión con lo siguiente:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.9.1,org.apache.iceberg:iceberg-gcp-bundle:1.9.1') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Reemplaza lo siguiente:

  • CATALOG_NAME: Es un nombre para el catálogo local de Spark (por ejemplo, my_catalog).
  • APP_NAME: Es un nombre para tu sesión de Spark.
  • REST_API_VERSION: Se establece en v1 para la versión estable de la API.
  • WAREHOUSE_PATH: Es la ruta de acceso a tu almacén. Para los catálogos de BigLake, usa bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Usa gs://CLOUD_STORAGE_BUCKET_NAME para los catálogos de bucket de Cloud Storage.
  • PROJECT_ID: Es el proyecto al que se le factura el uso del extremo del catálogo de REST de Apache Iceberg, que puede ser diferente del proyecto propietario del bucket de Cloud Storage. Para obtener detalles sobre la configuración del proyecto cuando se usa una API de REST, consulta Parámetros del sistema.
  • TOKEN: Tu token de autenticación, que es válido por una hora, por ejemplo, un token generado con gcloud auth application-default print-access-token.

Configura la venta de credenciales

En el ejemplo anterior, no se usa la venta de credenciales. Para usar la venta de credenciales, debes usar un catálogo en modo de venta de credenciales y agregar el encabezado X-Iceberg-Access-Delegation a las solicitudes de extremo del catálogo de REST de Apache Iceberg con un valor de vended-credentials agregando la siguiente línea al compilador SparkSession: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Ejemplo con venta de credenciales

En el siguiente ejemplo, se configura el motor de consultas con la venta de credenciales:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Para obtener más información, consulta la sección Encabezados en RESTCatalog de la documentación de Apache Iceberg.

Crea un espacio de nombres o un esquema

Después de configurar tu cliente, crea un espacio de nombres o un esquema para organizar tus tablas. La sintaxis para crear un espacio de nombres o un esquema varía según el motor de consultas. En los siguientes ejemplos, se muestra cómo crearlos con Spark y Trino.

Console

  1. En la consola de Google Cloud , ve a Lakehouse.

    Ir a Lakehouse

  2. Selecciona un catálogo existente o crea uno si no tienes.

  3. En la barra de menú, haz clic en + Crear espacio de nombres.

  4. En Nombre del espacio de nombres, ingresa un nombre único para tu espacio de nombres.

  5. En Ubicación, especifica la ruta de acceso que se asociará con tu espacio de nombres:

    • Varios bucket (bl://) (recomendado): Puedes establecer cualquier ubicación personalizada, siempre y cuando se encuentre en una ubicación permitida por el catálogo (default_location o restricted_locations). Si no especificas una ubicación, el espacio de nombres se crea en la ubicación predeterminada del catálogo (por ejemplo, gs://{path-to-default-location}/{namespace_name}).
    • Un solo bucket (gs://): La ubicación del espacio de nombres se hereda automáticamente del único bucket del catálogo.

  6. Haz clic en Crear.

Spark

Almacén de Cloud Storage

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME;")
spark.sql("USE NAMESPACE_NAME;")

Reemplaza NAMESPACE_NAME por un nombre para el espacio de nombres.

Trino

Almacén de Cloud Storage

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;
USE CATALOG_NAME.SCHEMA_NAME;

Reemplaza lo siguiente:

  • CATALOG_NAME: Es el nombre de tu catálogo de Trino que usa el extremo del catálogo de REST de Apache Iceberg.
  • SCHEMA_NAME: Un nombre para tu esquema.

Actualiza un catálogo

Si tienes un catálogo existente de un solo bucket (gs://), puedes actualizarlo a un tipo de catálogo de varios buckets (bl://), que es el recomendado. La actualización te permite asociar varios buckets y configurar ubicaciones restringidas, y conservar el nombre del catálogo original.

Para actualizar tu catálogo, consulta Cómo actualizar un catálogo.

¿Qué sigue?