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

Lakehouse para Apache Iceberg administra los metadatos a través del catálogo de entorno 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 compatibles, los comportamientos de enrutamiento regionales y las opciones de federación de consultas.

Capacidades y cumplimiento

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

Formatos de tabla compatibles

Se admiten las tablas de Apache Iceberg V2 (GA) y V3 (versión preliminar). No se admiten las tablas de Iceberg V1. Antes de usar las 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 entorno de ejecución de Lakehouse implementa la API de catálogo de REST de Apache Iceberg estándar abierta. Los motores de consultas del cliente interactúan con el catálogo mediante 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 alto nivel de estos recursos:

Recurso Descripción
Catálogo Como contenedor de nivel superior, un catálogo te permite organizar espacios de nombres y tablas en grupos lógicos dividiéndolos en diferentes catálogos. Cada catálogo está respaldado por una ubicación de almacenamiento de almacén de datos designada (como un bucket de Cloud Storage o un proxy de federación de BigQuery) que almacena 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. Esto 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 opera y se integra con los servicios de Google Cloud. Puedes configurar un catálogo de varios buckets (bl://) (recomendado) o un catálogo de un solo bucket (gs://).

Ambas opciones admiten la venta de credenciales para un control de acceso detallado.

Catálogo de varios bucket (bl://) (recomendado)

Este enfoque te permite nombrar 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 a la CATALOG_TYPE_BIGLAKE configuración.

Consideraciones:

  • Ubicación predeterminada: Proporcionas una ruta de acceso a un bucket (default_location) o una subruta de acceso (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 ubicarse 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 opcional restricted_locations para buckets o rutas de acceso adicionales en los que se pueden crear espacios de nombres y tablas. Si especificas una subruta de acceso (como gs://my-bucket/path), todos los recursos creados 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: Si bien los buckets pueden ser entre proyectos, entre regiones y tener diferentes configuraciones (como región única, región doble o multirregión), 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 a la misma 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, sobrescrituras de datos accidentales 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 agregado 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 Administración de tablas y reglas de seguridad.

Catálogo de un solo bucket (gs://)

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 que especificas. En la API subyacente, esto corresponde a la CATALOG_TYPE_GCS_BUCKET configuración.

Para los catálogos de un solo bucket, el nombre del catálogo se establece en el nombre de tu bucket.

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 son iceberg-bucket. Esto se usa más adelante cuando consultas 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 del tipo de catálogo heredado. No se recomienda usar la configuración heredada de un solo bucket para proyectos nuevos. Esta configuración tiene varias limitaciones críticas:

    • Nombre del catálogo: Está bloqueado en el nombre del bucket de Cloud Storage subyacente.
    • Proyecto: Está bloqueado 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).

  • 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 al catálogo de varios buckets (bl://) (recomendado): puedes actualizar un catálogo de un solo bucket (gs://) existente a un catálogo de varios buckets (bl://) (recomendado). El catálogo actualizado conserva el nombre original del bucket. Después de eso, puedes asociar varios buckets con el catálogo y configurar ubicaciones restringidas.

Regiones de bucket y catálogo

La región de un extremo de catálogo en el catálogo de entorno de ejecución de Lakehouse está determinada por la región de su bucket de Cloud Storage subyacente:

  • **Catálogo de varios buckets (bl://)** (recomendado): La región del catálogo se deriva del bucket configurado en default_location.
  • Un solo bucket (gs://): 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 birregional 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, la enruta 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 las tablas de tu 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 las siguientes configuraciones:

Si el bucket default_location es lo siguiente:

  • Un bucket multirregional US o EU.
  • Un bucket de región única 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.

Consulta catálogos desde BigQuery

Cuando consultas tablas de catálogo de entorno de ejecución de Lakehouse desde BigQuery, usas una estructura de nombres de cuatro partes, que a menudo se conoce como P.C.N.T:

  • Proyecto: Es el ID del proyecto al que pertenece el catálogo. Google Cloud
  • C atálogo: Es el nombre del catálogo de entorno 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.

Pasos siguientes