Crear tablas externas de Apache Iceberg

Las tablas externas de Apache Iceberg te permiten acceder a las tablas de Apache Iceberg con un control de acceso más pormenorizado en formato de solo lectura. Esta función se diferencia de las tablas de BigLake para Apache Iceberg en BigQuery, que te permiten crear tablas de Iceberg en BigQuery en un formato de escritura.

Iceberg es un formato de tabla de código abierto que admite tablas de datos a escala de petabytes. La especificación abierta de Iceberg te permite ejecutar varios motores de consulta en una sola copia de los datos almacenados en un almacén de objetos. Las tablas externas de Apache Iceberg (en adelante, tablas externas de Iceberg) admiten la versión 2 de la especificación de Iceberg, incluida la función de fusión al leer.

Como administrador de BigQuery, puedes aplicar controles de acceso a nivel de fila y de columna, incluido el enmascaramiento de datos en las tablas. Para obtener información sobre cómo configurar el control de acceso a nivel de tabla, consulta Configurar políticas de control de acceso. Las políticas de acceso a tablas también se aplican cuando se usa la API Storage de BigQuery como fuente de datos de la tabla en Dataproc y Serverless Spark.

Puedes crear tablas externas de Iceberg de las siguientes formas:

  • Con metastore de BigLake (recomendado para Google Cloud) El metastore de BigLake se basa en el catálogo de BigQuery y se integra directamente con BigQuery. Las tablas del almacén de metadatos de BigLake se pueden modificar desde varios motores de código abierto y se pueden consultar desde BigQuery. BigLake Metastore también admite la integración directa con Apache Spark. Las tablas externas de Iceberg que usan el metastore de BigLake a veces se denominan tablas de Iceberg de BigLake.

  • Con AWS Glue Data Catalog (recomendado para AWS) AWS Glue es el método recomendado para AWS porque es un repositorio de metadatos centralizado en el que se define la estructura y la ubicación de los datos almacenados en varios servicios de AWS. Además, ofrece funciones como el descubrimiento automático de esquemas y la integración con las herramientas de analíticas de AWS.

  • Con archivos de metadatos JSON de Iceberg (opción recomendada para Azure). Si usas un archivo de metadatos JSON de Iceberg, debes actualizar manualmente el archivo de metadatos más reciente cada vez que se actualice la tabla. Puede usar un procedimiento almacenado de BigQuery para Apache Spark con el fin de crear tablas externas de Iceberg que hagan referencia a un archivo de metadatos de Iceberg.

Para ver una lista completa de las limitaciones, consulta Limitaciones.

Antes de empezar

Enable the BigQuery Connection and BigQuery Reservation APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Roles obligatorios

Para obtener los permisos que necesitas para crear una tabla externa de Iceberg, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en el proyecto:

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para crear una tabla externa de Iceberg. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Para crear una tabla externa de Iceberg, se necesitan los siguientes permisos:

  • bigquery.tables.create
  • bigquery.connections.delegate
  • bigquery.jobs.create

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

Crear tablas con BigLake Metastore

Te recomendamos que crees tablas externas de Iceberg con el metastore de BigLake. Puedes usar Apache Spark para crear estas tablas. Una forma cómoda de hacerlo es usar procedimientos almacenados de BigQuery. Para ver un ejemplo, consulta Crear y ejecutar un procedimiento almacenado.

Crear tablas con un archivo de metadatos

Puedes crear tablas externas de Iceberg con un archivo de metadatos JSON. Sin embargo, no es el método recomendado, ya que tienes que actualizar manualmente el URI del archivo de metadatos JSON para mantener actualizada la tabla externa de Iceberg. Si el URI no se mantiene actualizado, las consultas de BigQuery pueden fallar o proporcionar resultados diferentes a los de otros motores de consulta que usen directamente un catálogo de Iceberg.

Los archivos de metadatos de las tablas Iceberg se crean en el segmento de Cloud Storage que especifiques al crear una tabla Iceberg con Spark.

Selecciona una de las opciones siguientes:

SQL

Usa la instrucción CREATE EXTERNAL TABLE. En el siguiente ejemplo se crea una tabla externa de Iceberg llamada myexternal-table:

  CREATE EXTERNAL TABLE myexternal-table
  WITH CONNECTION `myproject.us.myconnection`
  OPTIONS (
         format = 'ICEBERG',
         uris = ["gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json"]
   )

Sustituye el valor uris por el archivo de metadatos JSON más reciente de una captura de tabla específica.

Para habilitar la opción require partition filter (requerir filtro de partición), define la marca require_partition_filter.

bq

En un entorno de línea de comandos, usa el comando bq mk --table con el decorador @connection para especificar la conexión que se va a usar al final del parámetro --external_table_definition. Para habilitar el filtro de requisito de partición, usa --require_partition_filter. 

bq mk 

    --table 

    --external_table_definition=TABLE_FORMAT=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID 

    PROJECT_ID:DATASET.EXTERNAL_TABLE

Haz los cambios siguientes:

  • TABLE_FORMAT: el formato de la tabla que quieres crear

    En este caso, ICEBERG.

  • URI: el archivo de metadatos JSON más reciente de una determinada instantánea de tabla.

    Por ejemplo, gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json.

    El URI también puede apuntar a una ubicación en la nube externa, como Amazon S3 o Azure Blob Storage.

    • Ejemplo de AWS: s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Ejemplo de Azure: azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.

  • CONNECTION_PROJECT_ID: el proyecto que contiene la conexión para crear la tabla externa de Iceberg. Por ejemplo, myproject.

  • CONNECTION_REGION: la región que contiene la conexión para crear la tabla externa de Iceberg. Por ejemplo, us.

  • CONNECTION_ID: el ID de conexión de la tabla, por ejemplo, myconnection

    Cuando consultas los detalles de la conexión en la consola de Google Cloud , el ID de conexión es el valor de la última sección del ID de conexión completo que se muestra en ID de conexión. Por ejemplo: projects/myproject/locations/connection_location/connections/myconnection

  • DATASET: el nombre del conjunto de datos de BigQuery en el que quieres crear una tabla

    Por ejemplo, mydataset.

  • EXTERNAL_TABLE: el nombre de la tabla que quieres crear

    Por ejemplo, mytable.

Actualizar metadatos de tablas

Si usas un archivo de metadatos JSON para crear una tabla externa de Iceberg, actualiza la definición de la tabla con los metadatos más recientes. Para actualizar el esquema o el archivo de metadatos, selecciona una de las siguientes opciones:

bq

  1. Crea un archivo de definición de tabla:

    bq mkdef --source_format=ICEBERG \
"URI" > TABLE_DEFINITION_FILE

  2. Usa el comando bq update con la marca --autodetect_schema:

    bq update --autodetect_schema --external_table_definition=TABLE_DEFINITION_FILE
PROJECT_ID:DATASET.TABLE

    Haz los cambios siguientes:

    • URI: tu URI de Cloud Storage con el archivo de metadatos JSON más reciente

      Por ejemplo, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.

    • TABLE_DEFINITION_FILE: el nombre del archivo que contiene el esquema de la tabla

    • PROJECT_ID: el ID del proyecto que contiene la tabla que quieres actualizar

    • DATASET: el conjunto de datos que contiene la tabla que quieres actualizar

    • TABLE: la tabla que quieras actualizar

API

Usa el método tables.patch con la propiedad autodetect_schema definida como true:

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables/TABLE?autodetect_schema=true

Haz los cambios siguientes:

  • PROJECT_ID: el ID del proyecto que contiene la tabla que quieres actualizar
  • DATASET: el conjunto de datos que contiene la tabla que quieres actualizar
  • TABLE: la tabla que quieras actualizar

En el cuerpo de la solicitud, especifica los valores actualizados de los siguientes campos:

{
     "externalDataConfiguration": {
      "sourceFormat": "ICEBERG",
      "sourceUris": [
        "URI"
      ]
    },
    "schema": null
  }'

Sustituye URI por el archivo de metadatos de Iceberg más reciente. Por ejemplo, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.

Configurar políticas de control de acceso

Puedes controlar el acceso a las tablas externas de Iceberg mediante la seguridad a nivel de columna, la seguridad a nivel de fila y el enmascaramiento de datos.

Consultar tablas externas de Iceberg

Para obtener más información, consulta Consultar datos de Iceberg.

Asignación de datos

BigQuery convierte los tipos de datos de Iceberg en tipos de datos de BigQuery, tal como se muestra en la siguiente tabla:

Tipo de datos Iceberg Tipo de datos de BigQuery
boolean BOOL
int INT64
long INT64
float FLOAT64
double FLOAT64
Decimal(P/S) NUMERIC or BIG_NUMERIC depending on precision
date DATE
time TIME
timestamp DATETIME
timestamptz TIMESTAMP
string STRING
uuid BYTES
fixed(L) BYTES
binary BYTES
list<Type> ARRAY<Type>
struct STRUCT
map<KeyType, ValueType> ARRAY<Struct<key KeyType, value ValueType>>

Limitaciones

Las tablas externas de Iceberg tienen limitaciones de tablas externas y las siguientes limitaciones:

  • Las tablas que usan la función de combinación al leer tienen las siguientes limitaciones:

    • Cada archivo de datos se puede asociar a un máximo de 10.000 archivos de eliminación.
    • No se pueden aplicar más de 100.000 IDs de igualdad a un archivo de eliminación.
    • Puedes evitar estas limitaciones compactando los archivos de eliminación con frecuencia o creando una vista en la parte superior de la tabla Iceberg que evite las particiones que se modifican con frecuencia.

  • BigQuery admite la eliminación de manifiestos mediante todas las funciones de transformación de particiones de Iceberg, excepto Bucket. Para obtener información sobre cómo eliminar particiones, consulta Consultar tablas con particiones. Las consultas que hacen referencia a tablas externas de Iceberg deben contener literales en predicados comparados con columnas que tengan particiones.

  • Solo se admiten archivos de datos Apache Parquet.

Costes de fusión al leer

La facturación bajo demanda de los datos de fusión al leer es la suma de las lecturas de los siguientes datos:

  • Todos los bytes lógicos leídos en el archivo de datos (incluidas las filas marcadas como eliminadas por posición y las eliminaciones por igualdad).
  • Bytes lógicos leídos al cargar los archivos de eliminación por igualdad y por posición para buscar las filas eliminadas en un archivo de datos.

Requerir filtro de partición

Puedes requerir el uso de filtros de predicado habilitando la opción require partition filter (requerir filtro de partición) en tu tabla Iceberg. Si habilitas esta opción, los intentos de consultar la tabla sin especificar una cláusula WHERE que se ajuste a cada archivo de manifiesto generarán el siguiente error:

Cannot query over table project_id.dataset.table without a
filter that can be used for partition elimination.

Cada archivo de manifiesto requiere al menos un predicado adecuado para la eliminación de particiones.

Puedes habilitar require_partition_filter de las siguientes formas al crear una tabla Iceberg :

SQL

Usa la instrucción CREATE EXTERNAL TABLE.En el siguiente ejemplo se crea una tabla externa de Iceberg llamada TABLE con el filtro de requisito de partición habilitado:

  CREATE EXTERNAL TABLE TABLE
  WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
  OPTIONS (
         format = 'ICEBERG',
         uris = [URI],
         require_partition_filter = true
   )

Haz los cambios siguientes:

  • TABLE: el nombre de la tabla que quieras crear.
  • PROJECT_ID: el ID del proyecto que contiene la tabla que quieres crear.
  • REGION: la ubicación en la que quieres crear la tabla Iceberg.

  • CONNECTION_ID: el ID de conexión. Por ejemplo, myconnection.

  • URI: el URI de Cloud Storage con el archivo de metadatos JSON más reciente.

    Por ejemplo, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.

    El URI también puede apuntar a una ubicación en la nube externa, como Amazon S3 o Azure Blob Storage.

    • Ejemplo de AWS: s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Ejemplo de Azure: azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.

bq

Usa el comando bq mk --table con el decorador @connection para especificar la conexión que se va a usar al final del parámetro --external_table_definition. Usa --require_partition_filter para habilitar el filtro de requisito de partición. En el siguiente ejemplo se crea una tabla externa de Iceberg llamada TABLE con el filtro de requisito de partición habilitado: 

bq mk \
    --table \
    --external_table_definition=ICEBERG=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID \
    PROJECT_ID:DATASET.EXTERNAL_TABLE \
    --require_partition_filter

Haz los cambios siguientes:

  • URI: el archivo de metadatos JSON más reciente de una determinada instantánea de tabla

    Por ejemplo, gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json.

    El URI también puede apuntar a una ubicación en la nube externa, como Amazon S3 o Azure Blob Storage.

    • Ejemplo de AWS: s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Ejemplo de Azure: azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.

  • CONNECTION_PROJECT_ID: el proyecto que contiene la conexión para crear la tabla externa de Iceberg. Por ejemplo, myproject.

  • CONNECTION_REGION: la región que contiene la conexión para crear la tabla externa de Iceberg. Por ejemplo, us.

  • CONNECTION_ID: : el ID de conexión. Por ejemplo, myconnection.

    Cuando consultas los detalles de la conexión en la consola de Google Cloud , el ID de conexión es el valor de la última sección del ID de conexión completo que se muestra en ID de conexión. Por ejemplo: projects/myproject/locations/connection_location/connections/myconnection

  • DATASET: el nombre de BigQuery

    conjunto de datos que contiene la tabla que quieres actualizar. Por ejemplo, mydataset.

  • EXTERNAL_TABLE: el nombre de la tabla que quieres crear

    Por ejemplo, mytable.

También puedes actualizar tu tabla Iceberg para habilitar el filtro de requisito de partición.

Si no habilitas la opción Requerir filtro de partición al crear la tabla particionada, puedes actualizar la tabla para añadir la opción.

bq

Usa el comando bq update y proporciona la marca --require_partition_filter.

Por ejemplo:

Para actualizar mypartitionedtable en mydataset en tu proyecto predeterminado, introduce lo siguiente:

bq update --require_partition_filter PROJECT_ID:DATASET.TABLE

Siguientes pasos