Conceptos de extremos del catálogo de REST de Apache Iceberg

El catálogo de tiempo de ejecución de Lakehouse proporciona una administración centralizada de metadatos para Google Cloud Lakehouse. En este documento, se describen los conceptos básicos del catálogo del entorno de ejecución de Lakehouse, con un enfoque en el extremo del catálogo de REST de Apache Iceberg, su jerarquía de recursos y otros tipos de catálogos admitidos.

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 Un catálogo es el contenedor de nivel superior que te permite organizar los espacios de nombres y las tablas en grupos lógicos dividiéndolos en diferentes catálogos.
Espacio de nombres Es una agrupación lógica que se usa para organizar tablas dentro de un catálogo. Funciona como bases de datos, esquemas o directorios.
Tabla Las tablas contienen definiciones de filas y columnas que se pueden consultar.

Tipos de catálogos admitidos

Cuando configuras tu cliente, especificas una ubicación de almacén. Esta elección determina cómo opera tu catálogo y cómo se integra con otros servicios deGoogle Cloud . En la siguiente tabla, se describen los tipos de catálogos admitidos:

Tipo de catálogo Descripción
Bucket de Cloud Storage Todos los datos de un catálogo se almacenan en un solo bucket de Cloud Storage. Para los datos que se comparten en varios buckets, se requieren varios catálogos.
Federación del catálogo de BigQuery Te permite usar el extremo del catálogo REST de Apache Iceberg para administrar y consultar tablas que son visibles para BigQuery. Para obtener más información, consulta Federación de catálogos con BigQuery.

Detalles del almacén

Recomendado

  • Almacén de buckets de Cloud Storage (gs://): Este es el enfoque estándar en el que el catálogo administra directamente los metadatos y los archivos de datos de Apache Iceberg en un bucket de Cloud Storage que especificas. Esta opción te brinda control directo sobre el diseño de tus datos y admite la venta de credenciales para un control de acceso detallado. Esto te permite crear y administrar tablas de catálogos de REST de Iceberg de Lakehouse.

    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 usará más adelante cuando consultes tu catálogo en BigQuery con la sintaxis de P.C.N.T. Por ejemplo, my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table.

Alternativa

  • Federación del catálogo de BigQuery (bq://): Este enfoque te permite usar el extremo del catálogo de REST de Apache Iceberg para administrar y consultar tablas que son visibles para BigQuery, sin necesidad de crear un recurso de catálogo. Para obtener más información, consulta Federación de catálogos con BigQuery.

Regiones de buckets y catálogos

En el caso de los almacenes de bucket de Cloud Storage en el catálogo del entorno de ejecución de Lakehouse, el sistema selecciona la región del catálogo para que coincida con la región del bucket subyacente:

  • Buckets de una sola región: La región del catálogo coincide exactamente con la región del bucket.

  • Buckets birregionales: Incluyen regiones dobles predefinidas y definidas por el usuario, como ASIA1 y NAM4. La región del catálogo coincide con las regiones duales.

  • Buckets multirregionales: El sistema selecciona ubicaciones regionales para el catálogo dentro del dominio geográfico de la multirregión. De forma predeterminada, es posible que estas ubicaciones no coincidan con las ubicaciones comunes de BigQuery, como US y EU. En cambio, son ubicaciones regionales dentro del dominio geográfico (por ejemplo, us-central1 y us-east4 para un bucket multirregional US).

Cuando BigQuery ejecuta una consulta en las tablas de estos catálogos, la enruta a la región principal del catálogo. Si ejecutas una consulta 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, es posible que la consulta falle.

Especifica regiones principales para las multirregiones de EE.UU. y la UE

En el caso de los catálogos que usan un bucket multirregional US o EU, puedes especificar la región principal cuando creas el catálogo para asegurarte de que BigQuery pueda acceder a él desde las regiones correspondientes.

  • Multirregión de la UE de Cloud Storage: Especifica EU o europe-west4.
  • Multirregión de EE.UU. de Cloud Storage: Especifica US o us-central1.

El sistema selecciona la réplica principal de un catálogo cuando lo creas, pero puedes actualizarla de forma dinámica llamando a FailoverCatalog. Para obtener más información sobre cómo definir ubicaciones principales, consulta cómo usar el extremo del catálogo REST de Apache Iceberg.

Cómo consultar catálogos

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

  • Proyecto: Es el Google Cloud ID del proyecto propietario del catálogo.
  • Catálogo: Es el nombre del catálogo del 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.

Federación de catálogos con BigQuery

Puedes usar la interfaz del extremo del catálogo REST de Apache Iceberg para administrar y consultar tablas que son visibles para BigQuery.

Los catálogos de la federación de catálogos de BigQuery no requieren que crees un recurso de catálogo, sino que se pueden usar en cualquier proyecto que tenga habilitada la API de BigQuery. Esto te permite hacer lo siguiente:

Como BigQuery administra estos recursos, debes tener los permisos necesarios aplicables. No se admite la venta de credenciales para los catálogos federados.

Para habilitar la federación, configura tu cliente con el formato de almacén bq://projects/PROJECT_ID en el campo WAREHOUSE_PATH de los ejemplos de configuración del cliente en usa el extremo del catálogo REST de Apache Iceberg. También puedes incluir una ubicación de BigQuery para restringir las solicitudes futuras a una sola ubicación con el formato bq://projects/PROJECT_ID/locations/LOCATION.

Pasos siguientes