Esta página se ha traducido con Cloud Translation API.

Usar BigLake Metastore con el catálogo REST de Iceberg

El catálogo REST de Apache Iceberg gestionado en BigLake Metastore crea interoperabilidad entre todos tus motores de consulta al ofrecer una única fuente fiable para todos tus datos de Iceberg. Permite que los motores de consultas, como Apache Spark, descubran, lean metadatos y gestionen tablas de Iceberg de forma coherente.

Las tablas de Iceberg que usas con el catálogo REST de Iceberg se denominan tablas de BigLake para Apache Iceberg (vista previa). Se trata de tablas Iceberg que creas a partir de motores de código abierto y que almacenas en Cloud Storage. Los pueden leer buscadores 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 empezar

Verify that billing is enabled for your Google Cloud project.
Consulta cómo comprobar 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: Pide a un administrador que configure la venta de credenciales por primera vez.
Opcional: consulta cómo funciona el metastore de BigLake y por qué deberías usarlo.

Roles obligatorios

Para obtener los permisos que necesitas para usar el catálogo REST de Iceberg en el metaalmacén de BigLake, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos:

Realizar tareas administrativas, como gestionar el acceso de los usuarios al catálogo y al almacenamiento, así como el modo de credenciales del catálogo:
- Administrador de BigLake (roles/biglake.admin) en el proyecto
- Administrador de Storage (roles/storage.admin) en el bucket de Cloud Storage
Leer datos de la tabla en el modo de venta de credenciales: Lector de BigLake (roles/biglake.viewer) en el proyecto
Escribir datos de tabla en el modo de venta de credenciales: Editor de BigLake (roles/biglake.editor) en el proyecto
Leer recursos de catálogo y datos de tablas en modo de venta sin credenciales:
- Lector de BigLake (roles/biglake.viewer) en el proyecto
- Lector de objetos de Storage (roles/storage.objectViewer) en el segmento de Cloud Storage
Gestionar recursos del catálogo y escribir datos de tabla en el modo de venta sin credenciales:
- Editor de BigLake (roles/biglake.editor) en el proyecto
- Usuario de objetos de almacenamiento (roles/storage.objectUser) en el cubo de Cloud Storage

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Configurar el modo de venta de credenciales

El modo de distribución de credenciales es un mecanismo de delegación de acceso al almacenamiento que permite a los administradores de metastore de BigLake controlar los permisos directamente en los recursos de metastore de BigLake, lo que elimina la necesidad de que los usuarios del catálogo tengan acceso directo a los segmentos de Cloud Storage. Permite que los administradores de BigLake concedan permisos a los usuarios en archivos de datos específicos.

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

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

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

Haz los cambios siguientes:

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

El resultado del comando curl es similar al siguiente. El valor de catalog prefix se encuentra 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 para darle 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"}'

Sustituye PREFIX por el campo prefix de la salida del comando anterior.

El resultado del comando curl contiene la cuenta de servicio, como se muestra a continuación:

{
  "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 has extraído en el paso anterior tiene los permisos necesarios para usar el modo de venta de credenciales, pide a tu administrador que le asigne el rol Usuario de objetos de almacenamiento (roles/storage.objectUser) en el segmento de almacenamiento.

Importante: Debe asignar este rol a la cuenta de servicio de BigLake que ha extraído en el paso anterior, no a su cuenta de usuario. Si no se asigna el rol a la entidad correcta, pueden producirse errores de permisos.

Limitaciones

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

No se admiten segmentos multirregionales, birregionales ni segmentos con una ubicación de región personalizada.
Cuando se usa el modo de venta de credenciales, debes asignar el valor org.apache.iceberg.gcp.gcs.GCSFileIO a la propiedad io-impl. El valor predeterminado, org.apache.iceberg.hadoop.HadoopFileIO, no se admite.

Configurar el catálogo REST de Iceberg

Clúster

Para usar Spark con el catálogo REST de Iceberg en Dataproc, primero debes crear 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

Haz los cambios siguientes:

CLUSTER_NAME: el nombre del clúster.
PROJECT_ID: tu ID de proyecto Google Cloud .
REGION: la región del clúster de Dataproc.
DATAPROC_VERSION: la versión de la imagen de Dataproc, por ejemplo, 2.2.

Una vez que hayas creado el clúster, configura tu sesión de Spark para que use el catálogo 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()

Haz los cambios siguientes:

CATALOG_NAME: nombre del catálogo de Iceberg REST.
APP_NAME: un nombre para tu sesión de Spark.
CLOUD_STORAGE_BUCKET_NAME: el nombre del segmento de Cloud Storage que almacena las tablas de Iceberg de BigLake.
PROJECT_ID: el proyecto al que se le factura el uso del catálogo REST de Iceberg, que puede ser diferente del proyecto propietario del segmento de Cloud Storage. Para obtener más información sobre la configuración de proyectos al usar una API REST, consulta Parámetros del sistema.

En este ejemplo no se usa la venta de credenciales. Para usar la venta de credenciales, debes añadir el encabezado X-Iceberg-Access-Delegation a las solicitudes del catálogo de REST de Iceberg con el valor vended-credentials. Para ello, añade 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 imagen de Dataproc en Compute Engine 2.2 2.2.65 y posteriores.
Versiones de imagen de Dataproc en Compute Engine 2.3 2.3.11 y posteriores.

Sin servidor

Envía una carga de trabajo por lotes de PySpark a Google Cloud Serverless 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/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"

Haz los cambios siguientes:

PYSPARK_FILE: la gs:// ruta de Cloud Storage a tu archivo de aplicación de PySpark.
PROJECT_ID: tu ID de proyecto Google Cloud .
REGION: la región de la carga de trabajo por lotes de Dataproc.
RUNTIME_VERSION: la versión del tiempo de ejecución de Serverless for Apache Spark, por ejemplo, 2.2.
CATALOG_NAME: nombre del catálogo de Iceberg REST.
CLOUD_STORAGE_BUCKET_NAME: el nombre del segmento de Cloud Storage que almacena las tablas de Iceberg de BigLake.

Para usar la venta de credenciales, debes añadir el encabezado X-Iceberg-Access-Delegation a las solicitudes del catálogo REST de Iceberg con el valor vended-credentials. Para ello, añade la siguiente línea a las configuraciones de Serverless 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/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 para Apache Spark admite flujos de autorización de Google para Iceberg en las siguientes versiones de tiempo de ejecución:

Serverless para Apache Spark 2.2 runtimes 2.2.60 y versiones posteriores
Sin servidor para Apache Spark 2.3 runtimes 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 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"

Haz los cambios siguientes:

CLUSTER_NAME: el nombre del clúster.
REGION: 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 red del clúster. Para obtener más información, consulta Configuración de red de clústeres de Dataproc.
CATALOG_NAME: nombre del catálogo de Trino que utiliza el catálogo REST de Iceberg.
CLOUD_STORAGE_BUCKET_NAME: el nombre del segmento de Cloud Storage que almacena las tablas de Iceberg de BigLake.
PROJECT_ID: el ID de tu proyecto Google Cloud que se usará en el metastore de BigLake.

Después de crear el clúster, usa SSH para conectarte a la instancia de VM principal y, a continuación, 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 posteriores
Versiones de tiempo de ejecución 2.3 de Dataproc en Compute Engine 2.3.11 y posteriores
Dataproc en Compute Engine 3.0 no es compatible.

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', '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()

Haz los cambios siguientes:

CATALOG_NAME: nombre del catálogo de Iceberg REST.
APP_NAME: un nombre para tu sesión de Spark.
CLOUD_STORAGE_BUCKET_NAME: el nombre del segmento de Cloud Storage que almacena las tablas de Iceberg de BigLake.
PROJECT_ID: el proyecto al que se le factura el uso del catálogo REST de Iceberg, que puede ser diferente del proyecto propietario del segmento de Cloud Storage. Para obtener más información sobre la configuración de proyectos al usar una API REST, consulta Parámetros del sistema.

En el ejemplo anterior no se usa la venta de credenciales. Para usar la venta de credenciales, debes añadir el encabezado X-Iceberg-Access-Delegation a las solicitudes del catálogo REST de Iceberg con el valor vended-credentials. Para ello, añade 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 las versiones de código abierto de Iceberg anteriores a la 1.10, puedes configurar la autenticación OAuth estándar 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()

Haz los cambios siguientes:

CATALOG_NAME: nombre del catálogo de Iceberg REST.
APP_NAME: un nombre para tu sesión de Spark.
CLOUD_STORAGE_BUCKET_NAME: el nombre del segmento de Cloud Storage que almacena las tablas de Iceberg de BigLake.
PROJECT_ID: el proyecto al que se le factura el uso del catálogo REST de Iceberg, que puede ser diferente del proyecto propietario del segmento de Cloud Storage. Para obtener más información sobre la configuración de proyectos al usar una API REST, consulta Parámetros del sistema.
TOKEN: tu token de autenticación, que tiene una validez de 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.

Crear un espacio de nombres

Spark

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

spark.sql("USE NAMESPACE_NAME;")

Sustituye NAMESPACE_NAME por el nombre del espacio de nombres.

Trino

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;

USE CATALOG_NAME.SCHEMA_NAME;

Haz los cambios siguientes:

CATALOG_NAME: nombre del catálogo de Trino que utiliza el catálogo REST de Iceberg.
SCHEMA_NAME: el nombre del esquema.

Crear una tabla

Spark

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

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

Haz los cambios siguientes:

NAMESPACE_NAME: el nombre de tu espacio de nombres
TABLE_NAME: un nombre para la tabla

Trino

CREATE TABLE TABLE_NAME (id int, data varchar);

DESCRIBE TABLE_NAME;

Sustituye TABLE_NAME por el nombre que quieras darle a la tabla.

Mostrar lista de tablas

Spark

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

Trino

SHOW TABLES;

Insertar 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 de BigQuery:

SELECT * FROM `CLOUD_STORAGE_BUCKET_NAME>NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`;

Haz los cambios siguientes:

CLOUD_STORAGE_BUCKET_NAME: el nombre del segmento de Cloud Storage de tu catálogo REST de Iceberg. Por ejemplo, si tu URI es gs://iceberg_bucket, usa iceberg_bucket.
NAMESPACE_OR_SCHEMA_NAME: 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: el nombre de la tabla.

Modificar un esquema de tabla

En el siguiente ejemplo se añade una columna a la tabla:

Spark

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

Haz los cambios siguientes:

NAMESPACE_NAME: el nombre de tu espacio de nombres
TABLE_NAME: un nombre para la tabla

Trino

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

Haz los cambios siguientes:

SCHEMA_NAME: el nombre de tu esquema
TABLE_NAME: un nombre para la tabla

Eliminar una tabla

En el siguiente ejemplo se elimina la tabla del espacio de nombres indicado:

Spark

spark.sql("DROP TABLE TABLE_NAME;")

Trino

DROP TABLE TABLE_NAME;

Precios

Para obtener información sobre los precios, consulta los precios de BigLake.

Siguientes pasos

Consulta más información sobre cómo gestionar recursos de Iceberg con BigLake Metastore.
Consulta información sobre las funciones adicionales del metastore de BigLake.