Crea y consulta una tabla de Iceberg en Lakehouse con Google Cloud CLI
Borderless Lakehouse te permite compartir tablas de Apache Iceberg en Google Cloud y motores de código abierto, como Apache Spark, Trino y Apache Flink. El catálogo de tiempo de ejecución de Lakehouse hace un seguimiento de los metadatos, incluidos los esquemas, las instantáneas y las ubicaciones de Cloud Storage, a través del extremo del catálogo de REST de Apache Iceberg.
En esta guía de inicio rápido, usarás Google Cloud CLI para configurar un catálogo de varios bucket y ejecutar un trabajo de PySpark en Managed Service para Apache Spark. Después de que el trabajo crea una tabla de Iceberg, la consultas directamente en BigQuery con la sintaxis de 4 partes P.C.N.T (Project.Catalog.Namespace.Table) sin mover ni registrar datos.
Antes de comenzar
- Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
-
Instala Google Cloud CLI.
-
Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.
-
Para inicializar gcloud CLI, ejecuta el siguiente comando:
gcloud init -
Crea o selecciona un proyecto de Google Cloud .
Roles necesarios para seleccionar o crear un proyecto
- Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
-
Crea un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos
(
roles/resourcemanager.projectCreator), que contiene el permisoresourcemanager.projects.create. Obtén más información para otorgar roles.
-
Crea un proyecto de Google Cloud :
gcloud projects create PROJECT_ID
Reemplaza
PROJECT_IDpor un nombre para el proyecto de Google Cloud que estás creando. -
Selecciona el proyecto de Google Cloud que creaste:
gcloud config set project PROJECT_ID
Reemplaza
PROJECT_IDpor el nombre de tu proyecto de Google Cloud .
-
Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .
Habilita las APIs de BigLake, Managed Service para Apache Spark, Cloud Storage, BigQuery y API de Compute Engine, si aún no están habilitadas:
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el permiso
serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.gcloud services enable biglake.googleapis.com
dataproc.googleapis.com storage.googleapis.com bigquery.googleapis.com compute.googleapis.com -
Otorga roles a tu cuenta de usuario. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM:
roles/biglake.admin, roles/storage.admin, roles/dataproc.editor, roles/resourcemanager.projectIamAdmin, roles/bigquery.jobUsergcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Reemplaza lo siguiente:
PROJECT_ID: ID del proyectoUSER_IDENTIFIER: Es el identificador de tu cuenta de usuario . Por ejemplo,myemail@example.com. cuenta deROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.
-
Instala Google Cloud CLI.
-
Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.
-
Para inicializar gcloud CLI, ejecuta el siguiente comando:
gcloud init -
Crea o selecciona un proyecto de Google Cloud .
Roles necesarios para seleccionar o crear un proyecto
- Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
-
Crea un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos
(
roles/resourcemanager.projectCreator), que contiene el permisoresourcemanager.projects.create. Obtén más información para otorgar roles.
-
Crea un proyecto de Google Cloud :
gcloud projects create PROJECT_ID
Reemplaza
PROJECT_IDpor un nombre para el proyecto de Google Cloud que estás creando. -
Selecciona el proyecto de Google Cloud que creaste:
gcloud config set project PROJECT_ID
Reemplaza
PROJECT_IDpor el nombre de tu proyecto de Google Cloud .
-
Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .
Habilita las APIs de BigLake, Managed Service para Apache Spark, Cloud Storage, BigQuery y API de Compute Engine, si aún no están habilitadas:
Roles necesarios para habilitar las APIs
Para habilitar las APIs, necesitas el permiso
serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.gcloud services enable biglake.googleapis.com
dataproc.googleapis.com storage.googleapis.com bigquery.googleapis.com compute.googleapis.com -
Otorga roles a tu cuenta de usuario. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM:
roles/biglake.admin, roles/storage.admin, roles/dataproc.editor, roles/resourcemanager.projectIamAdmin, roles/bigquery.jobUsergcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Reemplaza lo siguiente:
PROJECT_ID: ID del proyectoUSER_IDENTIFIER: Es el identificador de tu cuenta de usuario . Por ejemplo,myemail@example.com. cuenta deROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.
Configura tu entorno y crea un bucket
Abre Cloud Shell y crea un bucket de Cloud Storage para almacenar una secuencia de comandos de PySpark y datos de la tabla de Iceberg:
En la consola de Google Cloud , haz clic en Activar Cloud Shell.
Haz clic en Autorizar cuando se te solicite.
Configura las variables de entorno para el nombre del proyecto, la región, el bucket y el catálogo, de modo que puedas reutilizarlas en esta guía de inicio rápido:
export PROJECT_ID=$(gcloud config get-value project) export REGION="us-central1" export BUCKET_NAME="${PROJECT_ID}-lakehouse-quickstart" export LAKEHOUSE_CATALOG_ID="quickstart_catalog"Crea un bucket de Cloud Storage en la región que seleccionaste:
gcloud storage buckets create gs://${BUCKET_NAME} \ --project=${PROJECT_ID} \ --location=${REGION}
Otorga permisos a la cuenta de servicio de Spark
De forma predeterminada, Managed Service para Apache Spark ejecuta trabajos por lotes con la cuenta de servicio predeterminada de Compute Engine de tu proyecto. Otorga a esta cuenta de servicio los siguientes roles de IAM para que pueda leer tu secuencia de comandos de PySpark desde Cloud Storage y pueda interactuar con el catálogo de tiempo de ejecución de Lakehouse y BigQuery:
| Rol | Recurso | Objetivo |
|---|---|---|
| Trabajador de Dataproc ( roles/dataproc.worker) |
Proyecto | Ejecuta cargas de trabajo por lotes de Managed Service para Apache Spark. |
| Consumidor de Service Usage ( roles/serviceusage.serviceUsageConsumer) |
Proyecto | Usar las APIs y la cuota del proyecto |
| Editor de BigLake ( roles/biglake.editor) |
Proyecto | Crear recursos de catálogo y solicitar credenciales de almacenamiento vendidas |
| Editor de datos de BigQuery ( roles/bigquery.dataEditor) |
Proyecto | Administra los metadatos de BigQuery para tus tablas. |
| Visualizador de objetos de almacenamiento ( roles/storage.objectViewer) |
Bucket | Lee tu secuencia de comandos de PySpark desde tu bucket de Cloud Storage. |
Ten en cuenta que la cuenta de servicio de Spark solo necesita el rol de visualizador de objetos de Storage (roles/storage.objectViewer) para leer tu secuencia de comandos de PySpark. No necesita
acceso de escritura directo a tu bucket porque el
catálogo de tiempo de ejecución de Lakehouse vende credenciales de escritura temporales con alcance de tabla
cuando se ejecuta el trabajo.
En Cloud Shell, ejecuta la siguiente secuencia de comandos para otorgar estos roles:
PROJECT_NUMBER=$(gcloud projects describe ${PROJECT_ID} \
--format='value(projectNumber)')
SPARK_SA="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
for ROLE in \
"roles/dataproc.worker" \
"roles/serviceusage.serviceUsageConsumer" \
"roles/biglake.editor" \
"roles/bigquery.dataEditor"; do
gcloud projects add-iam-policy-binding ${PROJECT_ID} \
--member="serviceAccount:${SPARK_SA}" \
--role="${ROLE}"
done
gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \
--member="serviceAccount:${SPARK_SA}" \
--role="roles/storage.objectViewer"Crea un catálogo en el catálogo de tiempo de ejecución de Lakehouse
Crea un catálogo en el catálogo de tiempo de ejecución de Lakehouse para tus tablas de Apache Iceberg.
En Cloud Shell, crea un catálogo de varios bucket. Un catálogo de varios buckets te permite nombrar tu catálogo de forma independiente de cualquier nombre de bucket y asociar varios buckets de Cloud Storage con un solo catálogo. Habilita el modo de venta de credenciales para que el catálogo de entorno de ejecución de Lakehouse pueda emitir de forma segura credenciales de almacenamiento temporales para Spark en tu nombre.
gcloud biglake iceberg catalogs create ${LAKEHOUSE_CATALOG_ID} \ --project=${PROJECT_ID} \ --catalog-type=biglake \ --default-location=gs://${BUCKET_NAME} \ --credential-mode=vended-credentials
Otorga acceso al catálogo a tu bucket:
Con la venta de credenciales, la cuenta de servicio aprovisionada automáticamente del catálogo necesita el rol de usuario de objetos de almacenamiento (
roles/storage.objectUser) en tu bucket para que pueda generar tokens de acceso temporales para los motores de cliente.# Retrieve the auto-provisioned catalog service account email CATALOG_SA=$(gcloud biglake iceberg catalogs describe ${LAKEHOUSE_CATALOG_ID} \ --project=${PROJECT_ID} \ --format='value(biglake-service-account)') # Grant the Storage Object User role to the catalog service account on your bucket gcloud storage buckets add-iam-policy-binding gs://${BUCKET_NAME} \ --member="serviceAccount:${CATALOG_SA}" \ --role="roles/storage.objectUser"
Crea una tabla de Iceberg con un trabajo de PySpark
Con el catálogo y los permisos listos, puedes ejecutar un trabajo de PySpark en Managed Service para Apache Spark para crear una tabla de Iceberg y, luego, insertar algunos datos de muestra.
Crea y sube una secuencia de comandos de PySpark
En Cloud Shell, crea un archivo llamado
quickstart.py:cat << 'EOF' > quickstart.py from pyspark.sql import SparkSession spark = SparkSession.builder.appName("quickstart").getOrCreate() # Create a namespace spark.sql("CREATE NAMESPACE IF NOT EXISTS `quickstart_catalog`.quickstart_namespace") # Create the table spark.sql(""" CREATE OR REPLACE TABLE `quickstart_catalog`.quickstart_namespace.quickstart_table ( id INT, name STRING ) USING iceberg """) # Insert data into the table spark.sql(""" INSERT INTO `quickstart_catalog`.quickstart_namespace.quickstart_table VALUES (1, 'one'), (2, 'two'), (3, 'three') """) EOFEsta secuencia de comandos inicia una sesión de Spark, crea un espacio de nombres llamado
quickstart_namespacey una tabla de Iceberg llamadaquickstart_table, y, luego, inserta tres filas de datos de muestra. Debido a que las sentencias de SQL no especifican una ruta de acceso del bucket (LOCATION), el catálogo de tiempo de ejecución de Lakehouse almacena automáticamente los archivos de espacio de nombres y de tabla en el bucket--default-locationde tu catálogo (gs://${BUCKET_NAME}).Copia
quickstart.pyen tu bucket de Cloud Storage para que Managed Service para Apache Spark pueda acceder a él:gcloud storage cp quickstart.py gs://${BUCKET_NAME}/quickstart.py
Ejecuta la secuencia de comandos de PySpark
Envía tu secuencia de comandos de PySpark como un trabajo por lotes de Managed Service para Apache Spark, que ejecuta tu código con bibliotecas de Iceberg preinstaladas sin necesidad de aprovisionar un clúster.
La marca --properties configura Spark para que se conecte a tu catálogo en el
catálogo de entorno de ejecución de Lakehouse con el extremo del catálogo de REST de Apache Iceberg:
En Cloud Shell, envía el trabajo por lotes:
gcloud dataproc batches submit pyspark gs://${BUCKET_NAME}/quickstart.py \ --project=${PROJECT_ID} \ --region=${REGION} \ --version=2.2 \ --properties="spark.sql.catalog.quickstart_catalog=org.apache.iceberg.spark.SparkCatalog,\ spark.sql.catalog.quickstart_catalog.type=rest,\ spark.sql.catalog.quickstart_catalog.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\ spark.sql.catalog.quickstart_catalog.warehouse=bl://projects/${PROJECT_ID}/catalogs/${LAKEHOUSE_CATALOG_ID},\ spark.sql.catalog.quickstart_catalog.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\ spark.sql.catalog.quickstart_catalog.header.x-goog-user-project=${PROJECT_ID},\ spark.sql.catalog.quickstart_catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\ spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\ spark.sql.catalog.quickstart_catalog.header.X-Iceberg-Access-Delegation=vended-credentials,\ spark.sql.catalog.quickstart_catalog.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token"
Además de la configuración estándar de Iceberg (
SparkCatalog,type=restyIcebergSparkSessionExtensions), estas propiedades configuran la conexión del catálogo de tiempo de ejecución de Lakehouse:uriywarehouse(bl://...): Conecta Spark al extremo del catálogo de REST de Apache Iceberg del catálogo de entorno de ejecución de Lakehouse y enruta las solicitudes a tu catálogo de varios bucket.rest.auth.typeyheader.x-goog-user-project: Autentica las solicitudes de REST con las credenciales de la cuenta de servicio de Spark y factura la cuota de la API a tu proyecto.header.X-Iceberg-Access-Delegation,io-implygcs.oauth2.refresh-credentials-endpoint: Solicita credenciales temporales de Cloud Storage vendidas del catálogo y configura el clienteGCSFileIOde Iceberg para escribir archivos de datos con esos tokens.
Para obtener más información sobre estos parámetros de configuración, consulta Configura la aplicación cliente y la documentación de configuración de Apache Iceberg Spark.
Cuando finaliza el trabajo, el resultado es similar al siguiente:
Batch [cb9d84e9489d408baca4f9e7ab4c64ff] finished. metadata: '@type': type.googleapis.com/google.cloud.dataproc.v1.BatchOperationMetadata batch: projects/PROJECT_ID/locations/us-central1/batches/cb9d84e9489d408baca4f9e7ab4c64ff batchUuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9 createTime: '2026-01-24T00:10:50.224097Z' description: Batch labels: goog-dataproc-batch-id: cb9d84e9489d408baca4f9e7ab4c64ff goog-dataproc-batch-uuid: 54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9 goog-dataproc-drz-resource-uuid: batch-54b0b9d2-f0a1-4fdf-ae44-eead3f8e60e9 goog-dataproc-location: us-central1 operationType: BATCH name: projects/PROJECT_ID/regions/us-central1/operations/32287926-5f61-3572-b54a-fbad8940d6ef
Consulta la tabla desde BigQuery
Ahora que Spark escribió tu tabla de Iceberg, puedes consultarla de inmediato en BigQuery con la sintaxis de 4 partes P.C.N.T (Project.Catalog.Namespace.Table):
En Cloud Shell, ejecuta el siguiente comando de
bq query:bq query --project_id=${PROJECT_ID} --location=${REGION} --use_legacy_sql=false \ "SELECT * FROM \`${PROJECT_ID}.${LAKEHOUSE_CATALOG_ID}.quickstart_namespace.quickstart_table\`"En el resultado, se muestran las tres filas que insertaste con tu trabajo de PySpark:
+----+-------+ | id | name | +----+-------+ | 1 | one | | 2 | two | | 3 | three | +----+-------+
Como el catálogo del entorno de ejecución de Lakehouse hace un seguimiento de los metadatos de Iceberg y controla el acceso al almacenamiento, BigQuery lee los archivos subyacentes en Cloud Storage en cuanto Spark confirma la instantánea.
En este mismo punto, también puedes leer o escribir en quickstart_table con
cualquier otro motor compatible con Iceberg, como Trino,
Flink o un clúster de Spark autoadministrado. Debido a que
la venta de credenciales está habilitada en tu catálogo, un motor externo solo necesita
el rol de visualizador de BigLake (roles/biglake.viewer) en tu proyecto para leer
la tabla o el rol de editor de BigLake (roles/biglake.editor) para también
escribir datos y confirmar instantáneas nuevas. Para obtener información sobre cómo conectar otros motores, consulta
Configura el extremo del catálogo de REST de Apache Iceberg.
Realiza una limpieza
Para evitar que se apliquen cargos innecesarios a tu cuenta de Google Cloud , borra los recursos que creaste en esta guía de inicio rápido. Si borras la tabla, el espacio de nombres y el catálogo, se quitará el registro de metadatos del catálogo de tiempo de ejecución de Lakehouse, mientras que, si borras el bucket, se quitarán los datos de Parquet y los archivos de metadatos de Iceberg subyacentes almacenados en Cloud Storage:
En Cloud Shell, borra la tabla de tu catálogo:
gcloud biglake iceberg tables delete quickstart_table \ --project=${PROJECT_ID} \ --catalog=${LAKEHOUSE_CATALOG_ID} \ --namespace=quickstart_namespace \ --quietBorra el espacio de nombres de tu catálogo:
gcloud biglake iceberg namespaces delete quickstart_namespace \ --project=${PROJECT_ID} \ --catalog=${LAKEHOUSE_CATALOG_ID} \ --quietBorra tu catálogo:
gcloud biglake iceberg catalogs delete ${LAKEHOUSE_CATALOG_ID} \ --project=${PROJECT_ID} --quietBorra el bucket de Cloud Storage y todo su contenido:
gcloud storage rm -r gs://${BUCKET_NAME}
¿Qué sigue?
- Prueba la guía de inicio rápido Crea y consulta una tabla de Iceberg con la consola de Google Cloud para crear espacios de nombres y tablas de Iceberg en la IU y modificar datos con el lenguaje de manipulación de datos (DML) de BigQuery.
- Prueba el codelab Configura el acceso a los datos multinube para consultar datos en Amazon Web Services (AWS), AlloyDB para PostgreSQL y Cloud Storage sin ETL.
- Obtén más información sobre los catálogos de bucket buckets y el extremo del catálogo de REST de Apache Iceberg.
- Obtén más información para administrar catálogos en el catálogo de entorno de ejecución de Lakehouse.
- Obtén más información sobre las tablas de Apache Iceberg administradas por Lakehouse.