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

  1. 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.
  2. Instala Google Cloud CLI.

  3. Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

  4. Para inicializar gcloud CLI, ejecuta el siguiente comando:

    gcloud init
  5. 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 permiso resourcemanager.projects.create. Obtén más información para otorgar roles.
    • Crea un proyecto de Google Cloud :

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por 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_ID por el nombre de tu proyecto de Google Cloud .

  6. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

  7. 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
  8. 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.jobUser

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    Reemplaza lo siguiente:

    • PROJECT_ID: ID del proyecto
    • USER_IDENTIFIER: Es el identificador de tu cuenta de usuario . Por ejemplo, myemail@example.com. cuenta de
    • ROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.
  9. Instala Google Cloud CLI.

  10. Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

  11. Para inicializar gcloud CLI, ejecuta el siguiente comando:

    gcloud init
  12. 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 permiso resourcemanager.projects.create. Obtén más información para otorgar roles.
    • Crea un proyecto de Google Cloud :

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por 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_ID por el nombre de tu proyecto de Google Cloud .

  13. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

  14. 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
  15. 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.jobUser

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    Reemplaza lo siguiente:

    • PROJECT_ID: ID del proyecto
    • USER_IDENTIFIER: Es el identificador de tu cuenta de usuario . Por ejemplo, myemail@example.com. cuenta de
    • ROLE: 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:

  1. En la consola de Google Cloud , haz clic en Activar Cloud Shell.

    Activa Cloud Shell

  2. Haz clic en Autorizar cuando se te solicite.

  3. 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"
  4. 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.

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

  1. 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')
    """)
    EOF

    Esta secuencia de comandos inicia una sesión de Spark, crea un espacio de nombres llamado quickstart_namespace y una tabla de Iceberg llamada quickstart_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-location de tu catálogo (gs://${BUCKET_NAME}).

  2. Copia quickstart.py en 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:

  1. 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=rest y IcebergSparkSessionExtensions), estas propiedades configuran la conexión del catálogo de tiempo de ejecución de Lakehouse:

    • uri y warehouse (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.type y header.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-impl y gcs.oauth2.refresh-credentials-endpoint: Solicita credenciales temporales de Cloud Storage vendidas del catálogo y configura el cliente GCSFileIO de 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):

  1. 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:

  1. 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 \
        --quiet
  2. Borra el espacio de nombres de tu catálogo:

    gcloud biglake iceberg namespaces delete quickstart_namespace \
        --project=${PROJECT_ID} \
        --catalog=${LAKEHOUSE_CATALOG_ID} \
        --quiet
  3. Borra tu catálogo:

    gcloud biglake iceberg catalogs delete ${LAKEHOUSE_CATALOG_ID} \
        --project=${PROJECT_ID} --quiet
  4. Borra el bucket de Cloud Storage y todo su contenido:

    gcloud storage rm -r gs://${BUCKET_NAME}

¿Qué sigue?