Usa el catálogo de REST de Lakehouse Iceberg

Para los flujos de trabajo nuevos, recomendamos usar el extremo del catálogo REST de Apache Iceberg en el catálogo del entorno de ejecución de Lakehouse.

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

Este enfoque es una buena opción si usas motores de código abierto 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 del entorno de ejecución de Lakehouse y la descripción general del extremo del catálogo REST de Iceberg.

  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 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 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 usuarios al catálogo, el acceso al almacenamiento y el modo de venta de credenciales del catálogo:
  • Leer datos de la tabla en el modo de venta de credenciales: Visualizador de BigLake (roles/biglake.viewer) en el proyecto
  • Escribir datos de la tabla en el modo de venta de credenciales: Editor de BigLake (roles/biglake.editor) en el proyecto
  • 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:
  • Realiza operaciones del lenguaje de manipulación de datos (DML) con la federación del catálogo de BigQuery:
    • Editor de datos de BigQuery (roles/bigquery.dataEditor) en el proyecto
    • Administrador de almacenamiento (roles/storage.admin) en el bucket de Cloud Storage Si usas motores de consultas, como Managed Service para Apache Spark, para realizar operaciones de DML, otorga estos roles a la cuenta de servicio que usas para ejecutar trabajos en ese motor.

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

  • Trino solo es compatible con la federación de catálogos de BigQuery cuando se usan las versiones de imagen 2.3.16 y posteriores de Managed Service para Apache Spark en Compute Engine.
  • Cuando usas el modo de venta de credenciales, debes establecer la propiedad io-impl en org.apache.iceberg.gcp.gcs.GCSFileIO. No se admite el valor predeterminado, org.apache.iceberg.hadoop.HadoopFileIO.

Limitaciones de tablas

  • Las tablas administradas a través del extremo del catálogo de REST de Apache Iceberg no admiten el control de acceso detallado (FGAC), como la seguridad a nivel de fila y columna.

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

  • En BigQuery, no se pueden crear vistas sobre tablas de Apache Iceberg administradas por el extremo del catálogo de REST de Apache Iceberg.
  • 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.

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 usas el extremo del catálogo de REST de Apache Iceberg en el catálogo del entorno de ejecución de Lakehouse:

  1. Según el Resumen del extremo del catálogo REST de Iceberg, elige la ubicación de tu almacén de catálogo (Cloud Storage o BigQuery).
  2. Si usas un almacén de datos gs:// de Cloud Storage, crea un catálogo que apunte a la ubicación de tu almacén de datos.
  3. Configura tu aplicación cliente para que use el extremo del catálogo de REST de Apache Iceberg.
  4. Crea un espacio de nombres o un esquema para organizar tus tablas.
  5. Crea y consulta tablas con el cliente configurado.

Crea un catálogo

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

  • Con las 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.

  • La 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 Google Cloud Lakehouse otorguen permisos a los usuarios sobre archivos de datos específicos.

Credenciales del usuario final

Console

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

    Ir a Google Cloud Lakehouse

  2. Haz clic en Crear catálogo.

  3. En el campo Selecciona un bucket de Cloud Storage, ingresa el nombre del bucket de Cloud Storage que deseas usar con tu catálogo. También puedes hacer clic en Explorar para elegir un bucket existente o crear uno nuevo. Solo puedes tener un catálogo por bucket de Cloud Storage.

  4. En Método de autenticación, selecciona Credenciales de usuario final.

  5. Haz clic en Crear.

gcloud

Usa el comando gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user \
    [--primary-location LOCATION]

Reemplaza lo siguiente:

  • CATALOG_NAME: Es un nombre para tu catálogo. En el caso de las tablas del catálogo REST administrado de Lakehouse para Apache Iceberg, este nombre suele coincidir con el ID de bucket de Cloud Storage que se usa con el catálogo REST. Por ejemplo, si tu bucket es gs://bucket-id, el nombre del catálogo podría ser bucket-id. Este nombre también se usa como identificador del catálogo cuando se consultan estas tablas desde BigQuery.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: (Opcional) Es la región principal del catálogo. Para los buckets multirregionales de Cloud Storage de EE.UU. o la UE, especifica US o EU para garantizar que se pueda acceder al catálogo desde las regiones de BigQuery correspondientes. Para obtener más información, consulta Regiones del catálogo.

Modo de venta de credenciales

Un administrador del catálogo habilita la venta de credenciales cuando crea o actualiza un catálogo. Como usuario del catálogo, puedes indicarle al extremo del catálogo REST de Apache Iceberg que devuelva credenciales de almacenamiento con alcance reducido especificando la delegación de acceso cuando configures el extremo del catálogo REST de Apache Iceberg.

Console

  1. En la consola de Google Cloud , abre la página Lakehouse.

    Ir a Google Cloud Lakehouse

  2. Haz clic en Crear catálogo. Se abrirá la página Crear catálogo.

  3. En Selecciona un bucket de Cloud Storage, ingresa el nombre del bucket de Cloud Storage que deseas usar con tu catálogo. También puedes hacer clic en Explorar para elegir entre una lista de buckets existentes o crear uno nuevo. Solo puedes tener un catálogo por bucket de Cloud Storage.

  4. En Método de autenticación, selecciona Modo de venta de credenciales.

  5. Haz clic en Crear.

    Se crea tu catálogo y se abre la página Detalles del catálogo.

  6. En Método de autenticación, haz clic en Establecer permisos del bucket.

  7. En el diálogo, haz clic en Confirmar.

    Esto verifica que la cuenta de servicio de tu catálogo tenga el rol de usuario de objetos de almacenamiento en tu bucket de almacenamiento.

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

Para usar Spark con el extremo del catálogo REST de Apache Iceberg en Managed Service para Apache Spark, primero crea un clúster que incluya el componente de Apache Iceberg:

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION

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.2.

Después de crear el clúster, configura tu sesión de Spark para usar el extremo del catálogo 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 el nombre del extremo del catálogo de REST de Apache Iceberg.
  • 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. Se establece en v1beta si necesitas solucionar un problema conocido con la generación del linaje de datos.
  • WAREHOUSE_PATH: Es la ruta de acceso a tu almacén. Usa gs://CLOUD_STORAGE_BUCKET_NAME. Para usar la federación de catálogos de BigQuery, consulta Usa la federación de catálogos con BigQuery.
  • PROJECT_ID: Es el proyecto al que se le factura el uso del extremo del catálogo 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 del catálogo 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(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', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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 la sección 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 de Managed Service para Apache Spark en Compute Engine: 2.2.65 y versiones posteriores.
  • 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 la siguiente configuración:

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.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    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.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.
  • 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.2.
  • CATALOG_NAME: Es el nombre del extremo del catálogo de REST de Apache Iceberg.
  • REST_API_VERSION: Se establece en v1 para la versión estable de la API. Se establece en v1beta si necesitas solucionar un problema conocido con la generación del linaje de datos.
  • WAREHOUSE_PATH: Es la ruta de acceso a tu almacén. Usa gs://CLOUD_STORAGE_BUCKET_NAME. Para usar la federación de catálogos de BigQuery, consulta Usa la federación de catálogos con BigQuery.

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=gs://CLOUD_STORAGE_BUCKET_NAME,\
    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.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
    spark.sql.catalog.CATALOG_NAME.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token, \
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

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:

  • Entornos de ejecución 2.2.60 y versiones posteriores de Managed Service para Apache Spark 2.2
  • Entornos 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: 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. Se establece en v1beta si necesitas solucionar un problema conocido con la generación del linaje de datos.
  • WAREHOUSE_PATH: Es la ruta de acceso a tu almacén. Usa gs://CLOUD_STORAGE_BUCKET_NAME.
  • 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 no se admite en Trino de Managed Service para Apache Spark.

Apache Iceberg 1.10 o versiones posteriores

Las versiones de código abierto de Apache Iceberg 1.10 y posteriores 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 tiempo de ejecución de Lakehouse 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 el nombre del extremo del catálogo de REST de Apache Iceberg.
  • 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. Se establece en v1beta si necesitas solucionar un problema conocido con la generación del linaje de datos.
  • WAREHOUSE_PATH: Es la ruta de acceso a tu almacén. Usa gs://CLOUD_STORAGE_BUCKET_NAME. Para usar la federación de catálogos de BigQuery, consulta Usa la federación de catálogos con BigQuery.
  • PROJECT_ID: Es el proyecto al que se le factura el uso del extremo del catálogo 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', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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 el nombre del extremo del catálogo de REST de Apache Iceberg.
  • 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. Se establece en v1beta si necesitas solucionar un problema conocido con la generación del linaje de datos.
  • WAREHOUSE_PATH: Es la ruta de acceso a tu almacén. Usa gs://CLOUD_STORAGE_BUCKET_NAME. Para usar la federación de catálogos de BigQuery, consulta Usa la federación de catálogos con BigQuery.
  • PROJECT_ID: Es el proyecto al que se le factura el uso del extremo del catálogo 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', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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.

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.

Consulta tablas en BigQuery

La forma en que consultas las tablas que creas a través del extremo del catálogo de REST de Apache Iceberg en BigQuery depende de si usas un almacén de buckets de Cloud Storage o la federación de BigQuery.

  • Almacén de buckets de Cloud Storage: Si configuraste tu cliente con una ruta de acceso al almacén gs://, consulta las tablas de BigQuery con el nombre de cuatro partes (P.C.N.T) project.catalog.namespace.table. Para obtener más información sobre la estructura de P.C.N.T., consulta Conceptos del catálogo de Iceberg REST. El componente catalog es el nombre del recurso del catálogo del catálogo del entorno de ejecución de Lakehouse. Si deseas obtener más información para consultar tablas, consulta Consulta una tabla.

  • Federación de BigQuery: Si configuraste tu cliente con una ruta de acceso de bq://, las tablas que crees serán visibles en BigQuery y se podrán consultar directamente con el SQL estándar de BigQuery:

    SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

    Reemplaza lo siguiente:

    • NAMESPACE_NAME: Es el nombre de tu espacio de nombres.
    • TABLE_NAME: Es el nombre de tu tabla.

Usa la federación de catálogos con BigQuery

Para obtener información sobre la federación de catálogos, consulta Conceptos del catálogo de REST de Iceberg. Para habilitar la federación, configura tu cliente con el formato de almacén bq://projects/PROJECT_ID en el campo WAREHOUSE_PATH de los ejemplos de configuración del cliente en Configura la aplicación cliente. También puedes incluir una ubicación de BigQuery para restringir las solicitudes futuras a una sola ubicación con el formato bq://projects/PROJECT_ID/locations/LOCATION.

Como BigQuery administra estos recursos, debes tener los permisos necesarios aplicables.

Después de configurar tu cliente para la federación, puedes crear un espacio de nombres para tus tablas federadas.

Spark

Para usar la federación del catálogo de BigQuery, incluye las cláusulas LOCATION y DBPROPERTIES:

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME LOCATION 'gs://BUCKET_NAME/NAMESPACE_NAME' WITH DBPROPERTIES ('gcp-region' = 'LOCATION');")
spark.sql("USE NAMESPACE_NAME;")

Reemplaza lo siguiente:

  • NAMESPACE_NAME: Un nombre para tu espacio de nombres.
  • BUCKET_NAME: Es el bucket de Cloud Storage que usas con tu catálogo.
  • LOCATION: Una ubicación de BigQuery El valor predeterminado es la multirregión US.

Trino

Para usar la federación del catálogo de BigQuery, incluye las propiedades LOCATION y gcp-region:

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME WITH ( LOCATION = 'gs://BUCKET_NAME/SCHEMA_NAME', "gcp-region" = 'LOCATION');
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.
  • BUCKET_NAME: Es el bucket de Cloud Storage que usas con tu catálogo.
  • LOCATION: Una ubicación de BigQuery El valor predeterminado es la multirregión US.

Precios

Para obtener detalles sobre los precios, consulta Precios de Google Cloud Lakehouse.

¿Qué sigue?