Usa el catálogo REST de Iceberg de BigLake Metastore

El catálogo REST de Apache Iceberg en BigLake Metastore es la forma recomendada de usar BigLake Metastore para flujos de trabajo nuevos. Crea interoperabilidad entre tus motores de consultas, ya que ofrece una sola fuente de verdad para todos tus datos de Iceberg. Permite que los motores de consultas, como Apache Spark, descubran, lean metadatos y administren tablas de Iceberg de manera coherente.

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 catálogo de Iceberg personalizado para BigQuery es una integración anterior. Si bien los flujos de trabajo existentes pueden seguir usándola, 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 BigLake Metastore.

  1. Verify that billing is enabled for your Google Cloud project.

  2. Enable the BigLake API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

Roles obligatorios

Para obtener los permisos que necesitas para usar el catálogo de REST de Iceberg en el metastore de BigLake, pídele a tu administrador que te otorgue los siguientes roles de IAM:

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 catálogo de REST de Iceberg está sujeto a las siguientes limitaciones:

  • 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.
  • Trino solo se admite con la federación de catálogos de BigQuery cuando se usan versiones de imagen 2.3 de Dataproc en Compute Engine 2.3.16 y versiones posteriores.

Recursos del catálogo

El catálogo REST de Apache Iceberg en BigLake Metastore usa una jerarquía de recursos para organizar tus datos.

Recursos del catálogo REST de Apache Iceberg

En la siguiente tabla, se proporciona una descripción general de los recursos que usa el catálogo REST de Apache Iceberg en BigLake Metastore.

Recurso Descripción
Catálogo Un catálogo es un contenedor de nivel superior que te permite organizar los espacios de nombres y las tablas en grupos lógicos dividiéndolos en diferentes catálogos.
Espacio de nombres Es una agrupación lógica que se usa para organizar tablas dentro de un catálogo. Funciona como bases de datos, esquemas o directorios.
Tabla Las tablas contienen definiciones de filas y columnas que se pueden consultar.

Catálogos admitidos

Cuando configuras tu cliente, especificas una ubicación de almacén. Esta elección determina cómo opera tu catálogo y cómo se integra con otros servicios de Google Cloud.

Tipo de catálogo Descripción
Bucket de Cloud Storage Todos los datos de un catálogo se almacenan en un solo bucket de Cloud Storage. Para los datos que se comparten en varios buckets, se requieren varios catálogos.
Federación de BigQuery Te permite usar el catálogo REST de Iceberg para administrar y consultar tablas que son visibles para BigQuery. Para obtener más información, consulta Usa la federación de catálogos con BigQuery.

Detalles del almacén del catálogo

Recomendado

  • Almacén de buckets de Cloud Storage (gs://): Este es el enfoque estándar en el que el catálogo administra directamente los metadatos y los archivos de datos de Iceberg en un bucket de Cloud Storage que especificas. Esta opción te brinda control directo sobre el diseño de tus datos y admite la venta de credenciales para un control de acceso detallado. Esto te permite crear y administrar tablas de BigLake para Apache Iceberg.

    Por ejemplo, si creaste tu bucket para almacenar tu catálogo y lo llamaste iceberg-bucket, tanto el nombre del catálogo como el del bucket serán iceberg-bucket. Esto se usará más adelante cuando consultes tu catálogo en BigQuery con la sintaxis de P.C.N.T. Por ejemplo my-project.biglake-catalog-id.quickstart_namespace.quickstart_table.

Heredado

  • Federación de BigQuery (bq://): Este enfoque te permite usar el catálogo de REST de Iceberg para administrar y consultar tablas que son visibles para BigQuery, sin necesidad de crear un recurso de catálogo. Para obtener más información, consulta Usa la federación de catálogos con BigQuery.

Estructura de nomenclatura de P.C.N.T.

Cuando consultas tablas de BigLake Metastore desde BigQuery, usas una estructura de nombres de cuatro partes, a menudo denominada P.C.N.T:

  • Proyecto: Es el ID del proyecto Google Cloud que posee el catálogo.
  • Catálogo: Es el nombre del catálogo de BigLake Metastore.
  • Namespace: Es el espacio de nombres de Iceberg (equivalente a un conjunto de datos de BigQuery).
  • Tabla: Es el nombre de la tabla.

Por ejemplo, my-project.biglake-catalog-id.my-namespace.my-table.

Configura el catálogo de REST de Iceberg

A continuación, se indican los pasos generales que debes seguir cuando usas el catálogo REST de Apache Iceberg en BigLake Metastore:

  1. Comprende y elige la ubicación de tu almacén de catálogos, ya sea 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 usar el catálogo REST de 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 que configuraste.

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 de BigLake Metastore controlar los permisos directamente en los recursos de BigLake Metastore, 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 BigLake otorguen permisos a los usuarios sobre archivos de datos específicos.

Credenciales del usuario final

Console

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

    Ir a BigLake

  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 beta biglake iceberg catalogs create

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

Reemplaza lo siguiente:

  • CATALOG_NAME: Un nombre para tu catálogo. En el caso de las tablas de BigLake administradas para Apache Iceberg, este nombre suele coincidir con el ID de bucket de Cloud Storage que se usa con el catálogo de 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 .

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 catálogo REST de Iceberg que muestre credenciales de almacenamiento con alcance reducido especificando la delegación de acceso cuando configures el catálogo REST de Iceberg.

Console

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

    Ir a BigLake

  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 usarlo. En estos ejemplos, se muestra cómo realizar la configuración con o sin la venta de credenciales.

Clúster

Para usar Spark con el catálogo de REST de Iceberg en Dataproc, primero crea un clúster que incluya el componente de 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 Dataproc.
  • DATAPROC_VERSION: La versión de la imagen de Dataproc, por ejemplo, 2.2.

Después de crear el clúster, configura tu sesión de Spark para usar el catálogo de REST de 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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .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 de tu catálogo de Iceberg REST.
  • APP_NAME: Es un nombre para tu sesión de Spark.
  • 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 catálogo REST de 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 con 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .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 Iceberg.

Los clústeres de Dataproc admiten los flujos de autorización de Google para Iceberg en las siguientes versiones:

  • Versiones de imágenes 2.2.65 y posteriores de Dataproc en Compute Engine
  • Versiones de imágenes 2.3.11 y posteriores de Dataproc en Compute Engine 2.3

Sin servidores

Envía una carga de trabajo por lotes de PySpark a Google Cloud Serverless for 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/v1/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,\
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false"

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 Dataproc.
  • RUNTIME_VERSION: Es la versión del entorno de ejecución de Serverless for Apache Spark, por ejemplo, 2.2.
  • CATALOG_NAME: Es el nombre de tu catálogo de Iceberg REST.
  • 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 con 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 a las configuraciones de Serverless for 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/v1/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.rest-metrics-reporting-enabled=false,
    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 Iceberg.

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

  • Tiempos de ejecución de Serverless for Apache Spark 2.2.60 y versiones posteriores
  • Entornos de ejecución de Serverless for Apache Spark 2.3.10 y versiones posteriores

Trino

Para usar Trino con el catálogo REST de Iceberg, crea un clúster de Dataproc 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/v1/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 Dataproc.
  • DATAPROC_VERSION: Versión de la imagen de Dataproc, por ejemplo, 2.2.
  • NETWORK_ID: Es el ID de la red del clúster. Para obtener más información, consulta Configuración de la red de un clúster de Dataproc.
  • CATALOG_NAME: Es el nombre de tu catálogo de Trino que usa el catálogo REST de Iceberg.
  • 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 BigLake Metastore.

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

Dataproc Trino admite flujos de autorización de Google para Iceberg en las siguientes versiones:

  • Versiones de tiempo de ejecución 2.2 de Dataproc en Compute Engine: 2.2.65 y versiones posteriores
  • Versiones del entorno de ejecución 2.3 de Dataproc en Compute Engine: 2.3.11 y versiones posteriores
  • No se admite Dataproc en Compute Engine 3.0.

Configura con la venta de credenciales

La venta de credenciales no se admite en Dataproc Trino.

Iceberg 1.10 o versiones posteriores

Las versiones de código abierto de 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 Apache Spark para usar el catálogo REST de Iceberg de BigLake Metastore.

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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .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 de tu catálogo de Iceberg REST.
  • APP_NAME: Es un nombre para tu sesión de Spark.
  • 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 catálogo REST de 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 con 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 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .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 Iceberg.

Versiones anteriores de Iceberg

En el caso de las versiones de código abierto de Iceberg 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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .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 de tu catálogo de Iceberg REST.
  • APP_NAME: Es un nombre para tu sesión de Spark.
  • 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 catálogo REST de 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 con 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 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .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 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 catálogo REST de 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 catálogo de REST de 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. El componente catalog es el nombre del recurso del catálogo de metastore de BigLake. Para obtener más información, consulta Cómo consultar una tabla.

  • Federación de BigQuery: Si configuraste tu cliente con una ruta de acceso de almacén de datos 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

Puedes usar la interfaz del catálogo REST de Iceberg para administrar y consultar tablas que son visibles para BigQuery. Los catálogos de federación de BigQuery no requieren que crees un recurso de catálogo, sino que se pueden usar en cualquier proyecto que tenga habilitada la API de BigQuery. Esto te permite hacer lo siguiente:

Como BigQuery administra estos recursos, debes tener los permisos requeridos correspondientes. La venta de credenciales no es compatible con los catálogos federados.

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 Usa el catálogo de REST de Iceberg. 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.

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 catálogo REST de 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 BigLake.

¿Qué sigue?