Se usó la API de Cloud Translation para traducir esta página.

Usa BigLake Metastore con el catálogo de REST de Iceberg

El catálogo REST de Apache Iceberg administrado en BigLake Metastore crea interoperabilidad entre todos 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.

Las tablas de Iceberg que usas con el catálogo de REST de Iceberg se denominan tablas de BigLake para Apache Iceberg (versión preliminar). Son tablas de Iceberg que creas a partir de motores de código abierto y almacenas en Cloud Storage. Los pueden leer los motores de código abierto o BigQuery. Las escrituras solo se admiten desde motores de código abierto. En este documento, nos referimos a estas tablas como tablas de BigLake Iceberg.

Antes de comenzar

Verify that billing is enabled for your Google Cloud project.
Obtén información para verificar si la facturación está habilitada en un proyecto.
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
Opcional: Pídele a un administrador que configure la venta de credenciales por primera vez.
Opcional: Comprende cómo funciona BigLake Metastore y por qué deberías usarlo.

Roles requeridos

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:

Realizar tareas administrativas, como administrar el acceso de los usuarios al catálogo, el acceso al almacenamiento y el modo de credenciales del catálogo:
- Administrador de BigLake (roles/biglake.admin) en el proyecto
- Administrador de almacenamiento (roles/storage.admin) en el bucket de Cloud Storage
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: BigLake Editor (roles/biglake.editor) en el proyecto
Leer recursos del catálogo y datos de tablas en el modo de no venta de credenciales:
- Visualizador de BigLake (roles/biglake.viewer) en el proyecto
- Visualizador de objetos de almacenamiento (roles/storage.objectViewer) en el bucket de Cloud Storage
Administra los recursos del catálogo y escribe datos de la tabla en el modo que no es de venta de credenciales:
- Editor de BigLake (roles/biglake.editor) en el proyecto
- Usuario de objetos de almacenamiento (roles/storage.objectUser) en el bucket de Cloud Storage

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

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

Cómo configurar el modo de venta de credenciales

El modo de 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.

Un administrador del catálogo habilita la venta de credenciales en el cliente del catálogo de Iceberg REST.

Como usuario del catálogo, puedes indicarle al catálogo de Iceberg REST que devuelva credenciales de almacenamiento de alcance reducido especificando la delegación de acceso, que forma parte de la especificación de la API del catálogo de Iceberg REST. Para obtener más información, consulta Configura un motor de consultas con el catálogo de Iceberg REST.

Para inicializar el catálogo y habilitar el modo de venta de credenciales, sigue estos pasos.

Inicializa el catálogo con el siguiente comando:

curl -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/v1/config?warehouse=gs://CLOUD_STORAGE_BUCKET_NAME

Reemplaza lo siguiente:

PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
CLOUD_STORAGE_BUCKET_NAME: Es el nombre del bucket de Cloud Storage que almacena la tabla de Iceberg.

El resultado del comando curl es similar al siguiente: El valor del prefijo del catálogo se puede encontrar en el campo overrides.prefix de la respuesta:

{
  "overrides": {
    "catalog_credential_mode": "CREDENTIAL_MODE_END_USER",
    "prefix": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME"
  },
  "endpoints": [
    "GET /v1/{prefix}/namespaces",
    "POST /v1/{prefix}/namespaces",
    "GET /v1/{prefix}/namespaces/{namespace}",
    "HEAD /v1/{prefix}/namespaces/{namespace}",
    "DELETE /v1/{prefix}/namespaces/{namespace}",
    "POST /v1/{prefix}/namespaces/{namespace}/properties",
    "GET /v1/{prefix}/namespaces/{namespace}/tables",
    "POST /v1/{prefix}/namespaces/{namespace}/tables",
    "GET /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "POST /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}"
  ]
}

Habilita el modo de venta de credenciales y extrae la cuenta de servicio a la que se le otorgarán permisos con el siguiente comando:

curl -X PATCH -H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/PREFIX?update_mask=credential_mode -d '{"credential_mode":"CREDENTIAL_MODE_VENDED_CREDENTIALS"}'

Reemplaza PREFIX por el campo prefix del resultado del comando anterior.

El resultado del comando curl contiene la cuenta de servicio, similar a lo siguiente:

{
  "name": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME",
  "credential_mode": "CREDENTIAL_MODE_VENDED_CREDENTIALS",
  "biglake-service-account": "BIGLAKE_SERVICE_ACCOUNT"
}

Para asegurarte de que la cuenta de servicio de BigLake que extrajiste en el paso anterior tenga los permisos necesarios para usar el modo de venta de credenciales, pídele a tu administrador que le otorgue el rol de usuario de objetos de almacenamiento (roles/storage.objectUser) en el bucket de almacenamiento.

Importante: Debes otorgar este rol a la cuenta de servicio de BigLake que extrajiste en el paso anterior, no a tu cuenta de usuario. Si no se otorga el rol al principal correcto, es posible que se produzcan errores de permisos.

Limitaciones

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

No se admiten los buckets multirregionales, los buckets birregionales ni los buckets con ubicación de región personalizada.
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.

Configura el catálogo de REST de Iceberg

Clúster

Para usar Spark con el catálogo de REST de Iceberg en Dataproc, primero crea un clúster con 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: El ID de tu proyecto 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', '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}.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.
CLOUD_STORAGE_BUCKET_NAME: Es el nombre del bucket de Cloud Storage que almacena las tablas de BigLake Iceberg.
PROJECT_ID: Es el proyecto al que se le factura el uso del catálogo de 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.

En este ejemplo, no se usa la venta de credenciales. Para usar la venta de credenciales, debes agregar el encabezado X-Iceberg-Access-Delegation a las solicitudes del 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(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 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=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"

Reemplaza lo siguiente:

PYSPARK_FILE: Es la ruta de acceso de Cloud Storage gs:// a tu archivo de aplicación de PySpark.
PROJECT_ID: El ID de tu proyecto 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.
CLOUD_STORAGE_BUCKET_NAME: Es el nombre del bucket de Cloud Storage que almacena las tablas de BigLake Iceberg.

Para usar la venta de credenciales, debes agregar el encabezado X-Iceberg-Access-Delegation a las solicitudes del catálogo de Iceberg REST 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:

Entornos 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 de 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=gs://CLOUD_STORAGE_BUCKET_NAME,\
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: 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 un nombre para tu catálogo de Trino que usa el catálogo de REST de Iceberg.
CLOUD_STORAGE_BUCKET_NAME: Es el nombre del bucket de Cloud Storage que almacena las tablas de BigLake Iceberg.
PROJECT_ID: El ID de tu proyecto de Google Cloud que se usará para BigLake Metastore.

Después de crear el clúster, usa SSH para conectarte a la instancia de VM principal y, luego, usa la CLI de Trino de la siguiente manera:

trino

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.

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 de Iceberg de BigLake Metastore REST.

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}.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.
CLOUD_STORAGE_BUCKET_NAME: Es el nombre del bucket de Cloud Storage que almacena las tablas de BigLake Iceberg.
PROJECT_ID: Es el proyecto al que se le factura el uso del catálogo de Iceberg REST, 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.

En el ejemplo anterior, no se usa la venta de credenciales. Para usar la venta de credenciales, debes agregar el encabezado X-Iceberg-Access-Delegation a las solicitudes del 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(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 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/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}.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.
CLOUD_STORAGE_BUCKET_NAME: Es el nombre del bucket de Cloud Storage que almacena las tablas de BigLake Iceberg.
PROJECT_ID: Es el proyecto al que se le factura el uso del catálogo de Iceberg REST, 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.

.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.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', '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

Spark

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

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;

USE CATALOG_NAME.SCHEMA_NAME;

Reemplaza lo siguiente:

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

Crea una tabla

Spark

spark.sql("CREATE TABLE TABLE_NAME (id int, data string) USING ICEBERG;")

spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

Reemplaza lo siguiente:

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

Trino

CREATE TABLE TABLE_NAME (id int, data varchar);

DESCRIBE TABLE_NAME;

Reemplaza TABLE_NAME por un nombre para tu tabla.

Enumerar tablas

Spark

spark.sql("SHOW TABLES").show()

Trino

SHOW TABLES;

Inserta datos en la tabla

En el siguiente ejemplo, se insertan datos de muestra en la tabla:

Spark

spark.sql("INSERT INTO TABLE_NAME VALUES (1, \"first row\"), (2, \"second row\"), (3, \"third row\");")

Trino

INSERT INTO TABLE_NAME VALUES (1, 'first row'), (2, 'second row'), (3, 'third row');

Consultar una tabla

En el siguiente ejemplo, se seleccionan todos los datos de la tabla:

Spark

spark.sql("SELECT * FROM TABLE_NAME;").show()

Trino

SELECT * FROM TABLE_NAME;

En el siguiente ejemplo, se consulta la misma tabla desde BigQuery:

SELECT * FROM `CLOUD_STORAGE_BUCKET_NAME>NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`;

Reemplaza lo siguiente:

CLOUD_STORAGE_BUCKET_NAME: Es el nombre del bucket de Cloud Storage para tu catálogo de REST de Iceberg. Por ejemplo, si tu URI es gs://iceberg_bucket, usa iceberg_bucket.
NAMESPACE_OR_SCHEMA_NAME: Es el espacio de nombres de la tabla si se usa Spark o el nombre del esquema de la tabla si se usa Trino.
TABLE_NAME: Es el nombre de tu tabla.

Cómo modificar un esquema de tabla

En el siguiente ejemplo, se agrega una columna a la tabla:

Spark

spark.sql("ALTER TABLE TABLE_NAME ADD COLUMNS ( desc string);")
spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

Reemplaza lo siguiente:

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

Trino

ALTER TABLE TABLE_NAME ADD COLUMN desc varchar;
DESCRIBE SCHEMA_NAME.TABLE_NAME;

Reemplaza lo siguiente:

SCHEMA_NAME: El nombre de tu esquema
TABLE_NAME: Un nombre para tu tabla

Borra una tabla

En el siguiente ejemplo, se borra la tabla del espacio de nombres determinado:

Spark

spark.sql("DROP TABLE TABLE_NAME;")

Trino

DROP TABLE TABLE_NAME;

Precios

Para obtener detalles sobre los precios, consulta Precios de BigLake.

¿Qué sigue?

Obtén más información para administrar recursos de Iceberg con BigLake Metastore.
Obtén más información sobre las funciones adicionales de BigLake Metastore.