Descripción general de las vistas de Apache Iceberg

Las vistas de Apache Iceberg te permiten definir tablas lógicas abiertas y no materializadas con SQL y usarlas desde motores compatibles con Iceberg, como Apache Spark, Trino, Apache Flink, PyIceberg y dbt. Puedes usar las vistas de Iceberg para compilar canalizaciones de SQL modulares y exponer proyecciones seleccionadas sin copias en tablas de Iceberg. Las vistas de Iceberg se administran con el catálogo de tiempo de ejecución de Lakehouse a través del extremo del catálogo de REST de Apache Iceberg, y siguen la especificación de vista de Apache Iceberg y la especificación de OpenAPI de REST de Iceberg.

En este documento, se hace referencia a estas vistas como vistas de Iceberg.

A diferencia de las vistas autorizadas de BigQuery, las vistas de Iceberg se evalúan del lado del cliente con tu motor de procesamiento. Las vistas de Iceberg son objetos de catálogo que creas, administras y consultas desde motores de código abierto.

Funciones

Se admiten las siguientes capacidades:

  • Ciclo de vida completo de las vistas: Crea, reemplaza, modifica propiedades, enumera, inspecciona y descarta vistas de Iceberg desde motores de código abierto compatibles con Iceberg, como Apache Spark y Trino.
  • Definiciones de vistas enriquecidas: Define vistas con alias de columnas, comentarios a nivel de columna y de vista, propiedades personalizadas, uniones, agregaciones, expresiones de tabla comunes (CTE), UNION ALL, subconsultas, vistas anidadas y viajes en el tiempo en las tablas subyacentes.
  • Autenticación flexible: Usa las credenciales de usuario final o la venta de credenciales con buckets de Cloud Storage estándar y buckets con espacios de nombres jerárquicos.
  • Compatibilidad con catálogos: Crea vistas en catálogos de varios buckets y de un solo bucket.

Solo puedes crear, administrar y consultar vistas de Iceberg a través de motores de código abierto compatibles con Iceberg que se conecten al extremo del catálogo de REST de Apache Iceberg. Para obtener más información, consulta Limitaciones.

Para Spark, usa Spark 3.5 o una versión posterior con el entorno de ejecución de Iceberg 1.6.0 o una versión posterior. Usa el entorno de ejecución de Iceberg 1.10.0 o una versión posterior para que Spark descubra los extremos de vista admitidos a través de la respuesta GET /v1/config del catálogo. Establece spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions para que Spark delegue la vista de DDL y la resolución al extremo del catálogo de REST de Apache Iceberg.

Para Trino, usa Trino 482 o una versión posterior. Para obtener más información, consulta Compatibilidad con Trino.

Cómo funcionan las vistas de Iceberg

Una vista de Iceberg almacena su definición, esquema y propiedades de SQL en un archivo metadata.json con control de versiones en Cloud Storage, en VIEW_LOCATION/metadata/. El catálogo de tiempo de ejecución de Lakehouse hace un seguimiento de la ubicación actual de los metadatos para cada vista y la expone a través de los extremos de vista del extremo del catálogo de REST de Apache Iceberg.

Tu motor de procesamiento evalúa las vistas de Iceberg del lado del cliente. Cuando ejecutas SELECT * FROM my_view, el motor carga la definición de la vista desde el catálogo, resuelve cada tabla y vista anidada a la que se hace referencia y, luego, ejecuta la consulta en las tablas de Iceberg subyacentes. El catálogo no ejecuta la consulta en tu nombre.

Cada vez que reemplazas una vista por CREATE OR REPLACE VIEW, el catálogo escribe un archivo metadata.json nuevo, agrega una versión y un esquema nuevos a los metadatos de la vista y conserva el view-uuid de la vista. La propiedad version.history.num-entries limita la cantidad de versiones retenidas. Para obtener más información, consulta Cómo ver las propiedades.

Las tablas y las vistas comparten el mismo espacio de nombres de identificador dentro de un espacio de nombres de catálogo. No puedes crear una vista con el mismo nombre que una tabla existente ni reemplazar una tabla por una vista.

Roles y permisos requeridos

Debido a que tu Compute Engine evalúa las vistas del cliente, consultar una vista requiere permisos en la vista y en cada tabla y vista anidada a la que hace referencia la vista.

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

  • Crea, reemplaza, modifica y borra vistas: Editor de BigLake (roles/biglake.editor): tu proyecto
  • Enumera e inspecciona las definiciones de las vistas: Visualizador de BigLake (roles/biglake.viewer): tu proyecto
  • Consulta vistas en el modo de distribución de credenciales: Visualizador de BigLake (roles/biglake.viewer): tu proyecto
  • Consulta vistas en el modo de credenciales del usuario final:
    • Visualizador de BigLake (roles/biglake.viewer): tu proyecto
    • Visualizador de objetos de Storage (roles/storage.objectViewer): el bucket de Cloud Storage
  • Escribe archivos de metadatos de vista en el modo de credenciales del usuario final: Usuario de objetos de almacenamiento (roles/storage.objectUser): 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.

Estos roles predefinidos contienen los permisos necesarios para crear, administrar y consultar vistas de Iceberg. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear, administrar y consultar vistas de Iceberg:

  • Crea una vista:
    • biglake.views.create en el espacio de nombres
    • biglake.tables.get en cada tabla de Iceberg a la que hace referencia la vista
  • Vistas de lista: biglake.views.list en el espacio de nombres
  • Obtén detalles de la vista: biglake.views.get en la vista
  • Modifica una vista:
    • biglake.views.update en la vista
    • biglake.tables.get en cada tabla de Iceberg a la que hace referencia la definición de la vista nueva
  • Borrar una vista: biglake.views.delete en la vista
  • Consulta una vista:
    • biglake.views.get en la vista y en cualquier vista anidada
    • biglake.tables.get en cada tabla de Iceberg a la que hace referencia la vista
  • Lee los datos de la tabla en el modo de entrega de credenciales: biglake.tables.getData en cada tabla de Iceberg a la que hace referencia la vista
  • Lee los metadatos de la vista y los datos de la tabla en el modo de credenciales del usuario final: storage.objects.get en el bucket de Cloud Storage
  • Escribe archivos de metadatos de vista en el modo de credenciales del usuario final: storage.objects.create en el bucket de Cloud Storage

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

En la siguiente tabla, se asigna cada permiso de vista a las operaciones de extremo del catálogo de REST de Apache Iceberg que autoriza:

Permiso Recurso Operaciones de extremos Se incluye en los roles predefinidos
biglake.views.create Espacio de nombres CreateIcebergView roles/biglake.admin, roles/biglake.editor
biglake.views.get Ver GetIcebergView, CheckIcebergViewExists roles/biglake.admin, roles/biglake.editor, roles/biglake.viewer, roles/biglake.metadataViewer
biglake.views.update Ver UpdateIcebergView roles/biglake.admin, roles/biglake.editor
biglake.views.delete Ver DeleteIcebergView roles/biglake.admin, roles/biglake.editor
biglake.views.list Espacio de nombres ListIcebergViewIdentifiers roles/biglake.admin, roles/biglake.editor, roles/biglake.viewer, roles/biglake.metadataViewer

Para obtener más información, consulta Roles de IAM de Lakehouse.

Extremos de vista compatibles

Cuando un motor inicializa una sesión de catálogo con GET /v1/config?warehouse=WAREHOUSE_URI, el extremo del catálogo de REST de Apache Iceberg anuncia los siguientes extremos de vista en la lista endpoints. En la siguiente tabla, {prefix} es projects/PROJECT_ID/catalogs/CATALOG_ID.

Método y ruta de acceso Operación Descripción Permiso necesario
GET /v1/{prefix}/namespaces/{namespace}/views ListIcebergViewIdentifiers Enumera los identificadores de vista en el espacio de nombres. Admite pageToken y pageSize. No incluye tablas. biglake.views.list en el espacio de nombres
POST /v1/{prefix}/namespaces/{namespace}/views CreateIcebergView Crea una vista, escribe el archivo 00000-UUID.metadata.json inicial en Cloud Storage y registra la vista. biglake.views.create en el espacio de nombres
GET /v1/{prefix}/namespaces/{namespace}/views/{view} GetIcebergView Carga los metadatos de la vista actual y la ubicación de los metadatos. biglake.views.get en la vista
POST /v1/{prefix}/namespaces/{namespace}/views/{view} UpdateIcebergView Valida los requisitos de simultaneidad optimista y confirma las actualizaciones en un archivo metadata.json nuevo. biglake.views.update en la vista
DELETE /v1/{prefix}/namespaces/{namespace}/views/{view} DeleteIcebergView Quita la vista del catálogo y borra su política de Identity and Access Management (IAM) a nivel de la vista. biglake.views.delete en la vista
HEAD /v1/{prefix}/namespaces/{namespace}/views/{view} CheckIcebergViewExists Verifica si existe una vista. biglake.views.get en la vista

Acciones de administración

Puedes realizar las siguientes acciones de administración en tus vistas de Iceberg:

  • Crea una vista: Define una vista en una o más tablas de Iceberg con Spark o el extremo del catálogo de REST de Apache Iceberg (CreateIcebergView).
  • Vistas de lista: Enumera los identificadores de vista en un espacio de nombres con Spark o el extremo del catálogo de REST de Apache Iceberg (ListIcebergViewIdentifiers).
  • Obtén detalles de la vista: Inspecciona el esquema, la definición de SQL y las propiedades de una vista con Spark o el extremo del catálogo de REST de Apache Iceberg (GetIcebergView).
  • Consulta una vista: Ejecuta consultas en una vista desde un motor de código abierto compatible con Iceberg, como Spark.
  • Modifica una vista: Reemplaza la definición de la vista o actualiza sus propiedades con Spark o el extremo del catálogo de REST de Apache Iceberg (UpdateIcebergView).
  • Borra una vista: Quita una vista del catálogo con Spark o el extremo del catálogo de REST de Apache Iceberg (DeleteIcebergView).

Limitaciones

Las vistas de Iceberg tienen las siguientes limitaciones:

  • Solo motores de código abierto. Puedes crear, administrar y consultar vistas de Iceberg solo desde motores de código abierto compatibles con Iceberg a través del extremo del catálogo de REST de Apache Iceberg. BigQuery SQL, la herramienta de línea de comandos de bq, la consola de Google Cloud , gcloud CLI y Terraform no admiten vistas de Iceberg.
  • Tipos de catálogos admitidos. Las vistas de Iceberg solo se admiten en catálogos de varios buckets y de un solo bucket. El catálogo rechaza las operaciones de vista en los catálogos de BigQuery y los catálogos federados con un error 400 Bad Request (FAILED_PRECONDITION).
  • Operaciones de vista de REST no admitidas.
    • No se admite cambiar el nombre de una vista (POST /v1/{prefix}/views/rename o ALTER VIEW ... RENAME TO). Para cambiar el nombre de una vista, crea una vista con el nombre nuevo y, luego, borra la vista original.
    • No se admite el registro de un archivo de vista metadata.json existente (registerView).
    • No se admiten las vistas materializadas. Solo se admiten las vistas lógicas de Iceberg.
  • Viaje en el tiempo en las vistas. No puedes aplicar TIMESTAMP AS OF ni VERSION AS OF a un identificador de vista. Una definición de vista puede aplicar viajes en el tiempo a las tablas subyacentes que consulta. Para obtener más información, consulta Crea una vista con viaje en el tiempo en tablas subyacentes.
  • Consulta la ubicación de almacenamiento.
    • En los catálogos de un solo bucket, no se admiten las ubicaciones de vistas personalizadas. La ubicación de la vista debe coincidir con la ruta predeterminada NAMESPACE_LOCATION/VIEW_NAME.
    • En los catálogos de varios bucket, la ubicación de una vista personalizada debe estar dentro del prefijo del URI de almacenamiento del espacio de nombres y de las ubicaciones de almacenamiento permitidas del catálogo.
    • Después de crear una vista, su ubicación de almacenamiento es inmutable. Si intentas establecer una ubicación diferente, se producirá un error 400 Bad Request.

Ver las propiedades

Las vistas de Iceberg admiten las propiedades de vista definidas por Apache Iceberg. En la siguiente tabla, se describe cómo el catálogo controla estas propiedades:

Propiedad Valor predeterminado Comportamiento
write.metadata.compression-codec gzip De forma predeterminada, el catálogo escribe archivos .gz.metadata.json comprimidos con gzip. Establece en none para escribir archivos .metadata.json sin comprimir. El valor distingue mayúsculas de minúsculas. Puedes establecer esta propiedad en el momento de la creación o con ALTER VIEW ... SET TBLPROPERTIES.
write.metadata.path VIEW_LOCATION/metadata Se ignora para las vistas. El catálogo siempre escribe archivos de metadatos de vista en VIEW_LOCATION/metadata/VERSION-UUID.metadata.json.
version.history.num-entries 10 Debe ser un número entero positivo. Limita la cantidad de entradas que el catálogo conserva en la lista versions y version-log de la vista. Cuando una confirmación supera este límite, el catálogo quita las entradas más antiguas y siempre conserva la versión actual y las versiones que agregó la confirmación. El registro de versiones está destinado a la auditoría y la reversión administrativa; los motores de Compute Engine no admiten la consulta de versiones de vistas históricas con SQL.

¿Qué sigue?