Consultar una tabla

Cuando se consulta una tabla, se leen los datos de los archivos subyacentes de Cloud Storage con los metadatos que administra el catálogo de tiempo de ejecución de Lakehouse.

Puedes ejecutar consultas desde motores de código abierto, como Spark y Trino, o directamente desde BigQuery con una sintaxis de nombre de tabla de cuatro partes (sintaxis de P.C.N.T).

Antes de comenzar

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

  2. Habilita la API de BigLake si aún no lo hiciste.

    Roles necesarios para habilitar las APIs

    Para habilitar 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 obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

    Habilitar la API

  3. Configura el catálogo de entornos de ejecución de Lakehouse con el extremo del catálogo de REST de Apache Iceberg.

Roles obligatorios

Para obtener los permisos que necesitas para consultar una tabla, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto y bucket de almacenamiento:

  • Leer datos de la tabla en el modo de venta de credenciales: Visualizador de BigLake (roles/biglake.viewer): el proyecto
  • Lee datos de tablas en el modo de no venta de credenciales:
    • Visualizador de BigLake (roles/biglake.viewer): El proyecto
    • Visualizador de objetos de Storage (roles/storage.objectViewer): 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.

Funciones y asistencia de tablas

Cuando se usan tablas en el catálogo del tiempo de ejecución de Lakehouse, es útil comprender los diferentes tipos de tablas y sus capacidades de habilitación. Para obtener más información sobre el uso específico de las tablas de Apache Iceberg, consulta Descripción general de las tablas de Apache Iceberg.

Tablas de Iceberg compatibles

Solo se admiten las tablas de Apache Iceberg V2 (GA) y V3 (versión preliminar). No se admiten las tablas de Iceberg V1. Para actualizar las tablas de la versión 1 existentes, consulta Actualiza las tablas de Iceberg de la versión 1 a la versión 2.

Usar opciones de tabla (vista previa)

Puedes habilitar el uso de las capacidades administradas de BigQuery, como el lenguaje de manipulación de datos (DML) de BigQuery y la administración automática de tablas, configurando propiedades específicas de la tabla. Estas funciones se habilitan de diferentes maneras según dónde se cree la tabla:

  • Desde BigQuery: El DML de BigQuery y la administración automática de tablas están habilitados de forma predeterminada.
  • Desde motores de código abierto: Para habilitar la opción, debes configurar explícitamente las propiedades de la tabla. Consulta Cómo configurar opciones de tablas para obtener más información.

Cuando consultas tablas desde BigQuery, puedes acceder a las tablas estándar de Iceberg, así como a las tablas habilitadas para las capacidades administradas de BigQuery. Consulta Cómo configurar opciones de tablas para obtener instrucciones detalladas.

Consultar una tabla

Selecciona todos los datos de la tabla:

Spark 

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

Trino 

SELECT * FROM TABLE_NAME;

BigQuery

Para consultar tablas de Apache Iceberg en el catálogo del entorno de ejecución de Lakehouse desde BigQuery, usa el nombre de tabla de cuatro partes en tu consulta con el siguiente formato: PROJECT_NAME.CATALOG_ID.NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME.

SELECT * FROM `PROJECT_NAME.CATALOG_ID.NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`;

Reemplaza los siguientes valores:

  • PROJECT_NAME: Es elGoogle Cloud proyecto que posee el catálogo en el catálogo del entorno de ejecución de Lakehouse. Se factura la consulta al proyectoGoogle Cloud seleccionado en la consola de Google Cloud .

  • CATALOG_ID: Es el ID del catálogo de entorno de ejecución de Lakehouse especificado cuando se creó el catálogo. Este identificador se usa como nombre del catálogo en las consultas de BigQuery.

    Este identificador también es el nombre de tu bucket de Cloud Storage.

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

  • 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.

Consulta con la función de viaje en el tiempo

Puedes consultar los datos históricos de tus tablas administradas de Apache Iceberg con la función de viaje en el tiempo. Puedes viajar en el tiempo desde BigQuery con la cláusula FOR SYSTEM_TIME AS OF o desde motores de código abierto, como Spark, con IDs de instantáneas, marcas de tiempo, etiquetas o ramas.

Consulta por marca de tiempo

Para consultar datos a partir de una marca de tiempo específica, haz lo siguiente:

Spark 

SELECT * FROM NAMESPACE.TABLE_NAME TIMESTAMP AS OF '2026-02-26 01:21:00';

BigQuery 

SELECT * FROM `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME` FOR SYSTEM_TIME AS OF '2026-02-26 01:21:00';

Consulta por ID de instantánea

Para consultar datos a partir de un ID de instantánea específico, haz lo siguiente:

Spark 

SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 10963874102873;

Consultar por etiqueta

Para crear una etiqueta y consultar los datos a partir de esa etiqueta, sigue estos pasos:

Spark 

-- Create tag 'historical-snapshot'
ALTER TABLE NAMESPACE.TABLE_NAME CREATE TAG 'historical-snapshot' AS OF VERSION 123456789012345;

-- Query by tag
SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 'historical-snapshot';

Consulta por rama

Para crear una rama y consultar datos a partir de ella, haz lo siguiente:

Spark 

-- Create branch 'audit-branch'
ALTER TABLE NAMESPACE.TABLE_NAME CREATE BRANCH 'audit-branch' AS OF VERSION 123456789012345;

-- Query by branch
SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 'audit-branch';

¿Qué sigue?