A partir del 20 de abril de 2026, BigLake se llama Lakehouse. El metastore de BigLake ahora se llama catálogo de entorno de ejecución de Lakehouse. Los nombres de IAM, los comandos de la CLI, las bibliotecas cliente y las APIs de Lakehouse no cambian y siguen haciendo referencia a BigLake.

Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Acerca del extremo del catálogo de REST de Apache Iceberg

Lakehouse sin fronteras administra los metadatos a través del catálogo de tiempo de ejecución de Lakehouse. Cuando usas el extremo del catálogo de REST de Apache Iceberg, el sistema organiza los datos en una jerarquía de recursos estricta. La configuración del catálogo determina los tipos de almacenamiento admitidos y los comportamientos de enrutamiento regional.

Funciones y cumplimiento

El catálogo de entorno de ejecución de Lakehouse se creó para integrarse en motores de consulta compatibles con Iceberg, ya que admite formatos de tabla estándar y cumple con las APIs abiertas.

Formatos de tabla admitidos

Se admiten las tablas de Apache Iceberg V2 (DG) y V3 (versión preliminar). Las tablas de Iceberg V1 no son compatibles. Antes de usar tablas V1 existentes con el extremo del catálogo de REST de Apache Iceberg, debes actualizarlas a una versión compatible. Para obtener más información, consulta Actualiza las tablas de Iceberg V1 a V2.

Cumplimiento de la API y operaciones de REST

El catálogo de tiempo de ejecución de Lakehouse implementa la API de catálogo de REST de Apache Iceberg, que es un estándar abierto. Los motores de consultas de clientes interactúan con el catálogo usando las APIs de catálogo de REST estándar. Para obtener más información, consulta Cómo Lakehouse implementa la API de catálogo de REST de Apache Iceberg.

Jerarquía de recursos

El extremo del catálogo de REST de Apache Iceberg usa una jerarquía de recursos para organizar tus datos. En la siguiente tabla, se proporciona una descripción general de estos recursos:

Recurso	Descripción
Catálogo	Un catálogo, el contenedor de nivel superior, te permite organizar los espacios de nombres y las tablas en grupos lógicos dividiéndolos en diferentes catálogos. Cada catálogo está respaldado por ubicaciones de almacenamiento de almacén designadas (como uno o más buckets de Cloud Storage) que almacenan sus metadatos y archivos de datos subyacentes.
Espacio de nombres	Es una agrupación lógica que se usa para organizar tablas dentro de un catálogo, que funciona como bases de datos, esquemas o directorios.
Tabla	Las tablas contienen definiciones de filas y columnas que se pueden consultar.

Catálogos y ubicaciones de almacenamiento

La configuración de un catálogo determina cómo funciona y se integra en los servicios de Google Cloud. Puedes configurar un catálogo de varios buckets (recomendado) o un catálogo de un solo bucket.

Ambas opciones admiten la venta de credenciales.

Cuando configuras motores de consulta de cliente (como Spark o Trino) para conectarte al extremo del catálogo de REST de Apache Iceberg, especificas la ruta de acceso del almacén según el tipo de catálogo:

Catálogo de bucket buckets: Establece la ruta de acceso del almacén en bl://projects/PROJECT_ID/catalogs/CATALOG_ID.
Catálogo de un solo bucket: Establece la ruta de acceso del almacén en gs://CLOUD_STORAGE_BUCKET_NAME.

Catálogo de varios bucket (recomendado)

Este enfoque te permite asignar un nombre a tu catálogo de forma independiente de cualquier nombre de bucket y configurar varios buckets para un solo catálogo. En la API subyacente, esto corresponde al parámetro de configuración CATALOG_TYPE_BIGLAKE.

Consideraciones:

Configuración del almacén del cliente (bl://): Cuando configures un cliente de Iceberg para conectarte a un catálogo de varios bucket, especifica la ruta de acceso del almacén con el formato de URI bl://: bl://projects/PROJECT_ID/catalogs/CATALOG_ID. El formato bl:// se usa exclusivamente durante la configuración del cliente para identificar el catálogo. Cuando creas o configuras el catálogo en Google Cloud, las ubicaciones de almacenamiento (default_location y restricted_locations) siempre se especifican como rutas de acceso de Cloud Storage (gs://).
Cantidad máxima de ubicaciones de almacenamiento: Además de default_location, puedes especificar hasta 128 buckets de Cloud Storage o rutas de acceso secundarias en restricted_locations por catálogo.
Ubicación predeterminada: Proporcionas una ruta de acceso a un bucket (default_location) o una ruta de acceso secundaria (como gs://my-bucket/path) para que actúe como la ubicación de almacenamiento predeterminada. Todos los recursos del catálogo (espacios de nombres y tablas) deben estar ubicados en la ruta de acceso especificada. Por ejemplo, si especificas gs://my-bucket/path, no puedes alojar espacios de nombres ni tablas en gs://my-bucket/another/path. Para los espacios de nombres creados sin una ubicación especificada, se usa default_location.
Ubicaciones restringidas: También puedes proporcionar una configuración restricted_locations opcional para buckets o rutas de acceso adicionales en los que se pueden crear espacios de nombres y tablas. Si especificas una ruta de acceso secundaria (como gs://my-bucket/path), todos los recursos que se creen con esa configuración deben estar en esa ruta de acceso (por ejemplo, gs://my-bucket/another/path no puede alojar espacios de nombres ni tablas).
Requisitos del grupo de regiones geográficas: Aunque los buckets pueden ser entre proyectos, entre regiones y tener diferentes configuraciones (como región única, birregional o multirregional), todas las ubicaciones de Cloud Storage en la ubicación predeterminada y las ubicaciones restringidas deben estar en el mismo grupo de regiones geográficas (como EE.UU., Europa, Canadá o Asia). Por ejemplo, no puedes configurar un bucket multirregional de EE.UU. con un bucket en Europa o Canadá.
Varios catálogos por bucket: Puedes tener varios catálogos que apunten al mismo bucket (por ejemplo, con diferentes ubicaciones predeterminadas o ubicaciones restringidas). Sin embargo, no se recomienda esta configuración, ya que puede provocar conflictos de metadatos, reemplazos accidentales de datos o problemas de seguridad, como la filtración de permisos.
Espacios de nombres: Permiten especificar ubicaciones de espacios de nombres personalizados, siempre que estén en una ruta de acceso configurada en las ubicaciones predeterminadas o restringidas. Ten en cuenta que las tablas creadas en estos catálogos tendrán un sufijo de cadena aleatorio que se agregará automáticamente a sus rutas de acceso físicas para evitar conflictos (por ejemplo, gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}). Para obtener más información, consulta Reglas de seguridad y administración de tablas.

Catálogo de un solo bucket

Este es el enfoque heredado en el que el catálogo administra directamente los metadatos y los archivos de datos de Apache Iceberg en un solo bucket de Cloud Storage (gs://) que especificas. En la API subyacente, esto corresponde a la configuración CATALOG_TYPE_GCS_BUCKET.

En el caso de los catálogos de un solo bucket, el nombre del catálogo se establece como el nombre del bucket.

Por ejemplo, si asignas el nombre iceberg-bucket a tu bucket, tanto el catálogo como el bucket compartirán ese nombre. Usa este nombre cuando consultes tu catálogo en BigQuery con la sintaxis P.C.N.T, por ejemplo, my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table.

Consideraciones:

Limitaciones de los tipos de catálogos heredados. No se recomienda usar la configuración heredada de un solo bucket para proyectos nuevos. Esta configuración tiene varias limitaciones importantes:
- Nombre del catálogo: Se bloquea con el nombre del bucket de Cloud Storage subyacente.
- Proyecto: Se bloquea en el proyecto del bucket (no se admiten catálogos entre proyectos).
- Región: Se deriva estrictamente de la ubicación del bucket y no se puede personalizar.
- Almacenamiento: Restringe tu catálogo a un solo bucket (sin ubicaciones restringidas).
Configuración del almacén del cliente (gs://): Cuando configures un cliente de Iceberg para un catálogo de un solo bucket, especifica la ruta del bucket de Cloud Storage (gs://CLOUD_STORAGE_BUCKET_NAME) como la ubicación del almacén.
Restricción de un catálogo por bucket: Para este tipo de catálogo heredado, solo puedes tener un catálogo por bucket, y el nombre del catálogo debe coincidir con el nombre del bucket.
Actualiza a un catálogo de varios buckets (recomendado): Puedes actualizar un catálogo de un solo bucket existente a un catálogo de varios buckets (recomendado). El catálogo actualizado conserva el nombre del bucket original. Después de eso, puedes asociar varios buckets con el catálogo y configurar ubicaciones restringidas.

Regiones de buckets y catálogos

La región de un extremo de catálogo en el catálogo de entorno de ejecución de Lakehouse se determina según la región de su bucket de Cloud Storage subyacente:

Catálogo de varios buckets (recomendado): La región del catálogo se deriva del bucket configurado en default_location.
Catálogo de un solo bucket: La región del catálogo se deriva estrictamente del bucket asociado con el catálogo y no se puede personalizar.

La región del catálogo asignada varía según el tipo de región del bucket:

Región única: La región del catálogo coincide exactamente con la región del bucket.
Birregional: La región del catálogo coincide con la región doble del bucket (como ASIA1 o NAM4).
Multirregión: La región del catálogo se establece en una ubicación regional específica dentro del dominio geográfico de la multirregión. De forma predeterminada, es posible que esto no se alinee con las multirregiones comunes de BigQuery, como US y EU (por ejemplo, un bucket multirregional US se asigna a us-central1 o us-east4).

Cuando BigQuery ejecuta una consulta en tablas de estos catálogos, enruta la consulta a la región principal del catálogo. Si consultas tablas en una región virtual específica (como US o EU) y los metadatos del catálogo no están presentes en esa ubicación, la consulta falla.

Regiones principales para multirregiones

Para permitir que BigQuery consulte tus tablas de catálogo desde la multirregión US o EU, especifica US o EU como la región principal cuando crees el catálogo.

Puedes especificar una multirregión (US o EU) como la región principal en los siguientes parámetros de configuración:

Si el bucket default_location es el siguiente:

Un bucket multirregional US o EU.
Un bucket de una sola región dentro de esas multirregiones (como us-central1 o europe-west4).
Un bucket birregional o birregional personalizado dentro de esas áreas (como NAM4 o EUR4).

La réplica principal se define cuando creas el catálogo, pero puedes realizar una conmutación por error de forma dinámica llamando a FailoverCatalog. Para obtener más información, consulta Crea un catálogo.

Para enrutar las solicitudes directamente a una región específica para los requisitos de residencia y soberanía de los datos, puedes usar extremos regionales (biglake.LOCATION.rep.googleapis.com). Para obtener más información, consulta Extremos regionales de Lakehouse.

Consulta catálogos desde BigQuery

Cuando consultas tablas del catálogo de entorno de ejecución de Lakehouse desde BigQuery, usas una estructura de nombres de cuatro partes, que suele denominarse P.C.N.T:

Proyecto: Es el ID del proyecto de Google Cloud que posee el catálogo.
Catálogo: Es el nombre del catálogo de tiempo de ejecución de Lakehouse.
Namespace: Es el espacio de nombres de Apache Iceberg (equivalente a un conjunto de datos de BigQuery).
Tabla: Es el nombre de la tabla.

Por ejemplo, my-project.lakehouse-catalog-id.my-namespace.my-table.

Acerca del extremo del catálogo de REST de Apache Iceberg Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.