Crea 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 detallado en un formato de solo lectura. Ya no se recomiendan estas tablas para la mayoría de los casos de uso. En su lugar, consulta Alternativas recomendadas.

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 búsqueda 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 Iceberg versión 2, incluida la combinación en la lectura. La compatibilidad con la versión 3 de Iceberg, incluidos los vectores de eliminación binarios, se encuentra en vista previa. Para enviar comentarios o hacer preguntas relacionadas con esta función de versión preliminar, comunícate con biglake-help@google.com.

Como administrador de BigQuery, puedes aplicar un control de acceso a nivel de fila y columna, incluido el enmascaramiento de datos en tablas. Para obtener información sobre cómo configurar el control de acceso a nivel de tabla, consulta Configura las políticas de control de acceso. Las políticas de acceso a las tablas también se aplican cuando usas la API de BigQuery Storage como fuente de datos para la tabla en Managed Service para Apache Spark y Spark sin servidores.

Según dónde se almacenen tus datos, te recomendamos las siguientes alternativas para acceder a las tablas de Iceberg cuyos metadatos no administraGoogle Cloud:

  • Datos de Cloud Storage o Amazon Simple Storage Service (Amazon S3) administrados por catálogos remotos, como AWS Glue, Databricks Unity Catalog y Snowflake Horizon Catalog Usa el catálogo de entorno de ejecución de Lakehouse con acceso a los datos en varias nubes. La función de acceso a los datos multinube del catálogo de entornos de ejecución de Lakehouse te permite consultar datos en otros proveedores de servicios en la nube directamente desde Google Cloud sin necesidad de migrar archivos ni crear canalizaciones de ETL complejas.
  • Tablas de Azure Blob Storage o Apache Iceberg que no administra un catálogo remoto compatible para el catálogo de entornos de ejecución de Lakehouse con acceso a datos entre nubes. Continúa con tablas externas de Apache Iceberg con archivos de metadatos JSON de Iceberg.

Antes de comenzar

Habilita las APIs de BigQuery Connection y BigQuery Reservation.

Roles necesarios para habilitar las APIs

Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

Habilitar las API

Roles obligatorios

Para obtener los permisos que necesitas para crear una tabla externa de Iceberg, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

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 una tabla externa 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 una tabla externa de Iceberg:

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

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

Crea tablas con un archivo de metadatos

Puedes crear tablas externas de Iceberg con un archivo de metadatos JSON. Sin embargo, debes actualizar el URI del archivo de metadatos JSON de forma manual para mantener actualizada la tabla externa de Iceberg. Si el URI no se mantiene actualizado, las consultas en BigQuery pueden fallar o proporcionar resultados diferentes de otros motores de consulta que usan directamente un catálogo de Iceberg.

Los archivos de metadatos de tablas de Iceberg se crean en el bucket de Cloud Storage que especificas cuando creas una tabla de Iceberg mediante Spark.

Selecciona una de las opciones siguientes:

SQL

Usa la sentencia 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"]
   )

Reemplaza el valor uris por el archivo de metadatos JSON más reciente para una instantánea de tabla específica.

Puedes habilitar requerir filtro de partición si configuras 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 usará al final del parámetro --external_table_definition. Para habilitar la opción de requerir filtro 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

Reemplaza lo siguiente:

  • TABLE_FORMAT: el formato de la tabla que deseas crear

    En este caso: ICEBERG.

  • URI: el archivo de metadatos JSON más reciente para una instantánea de tabla específica.

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

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

    • Ejemplo para AWS: s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Ejemplo para 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 ves los detalles de conexión en la consola de Google Cloud , el ID de conexión es el valor en la última sección del ID de conexión completamente calificado 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 deseas crear una tabla

    Por ejemplo, mydataset.

  • EXTERNAL_TABLE: el nombre de la tabla que deseas 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 tabla con los metadatos más recientes de la tabla. 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

    Reemplaza lo siguiente:

    • 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 deseas actualizar

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

    • TABLE: la tabla que deseas actualizar

API

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

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

Reemplaza lo siguiente:

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

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

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

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

Configura las políticas de control de acceso

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

Consulta datos históricos

Puedes acceder a las instantáneas de las tablas externas de Iceberg que se conservan en los metadatos de Iceberg con la cláusula FOR SYSTEM_TIME AS OF.

Las ventanas de retención de datos de viaje en el tiempo y seguridad ante fallas no son compatibles con ninguna tabla externa.

Asignación de datos

BigQuery convierte los tipos de datos de Iceberg en tipos de datos de BigQuery, 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

Además de las limitaciones de las tablas externas, las tablas externas de Iceberg tienen las siguientes limitaciones:

  • Las consultas que usan los Controles del servicio de VPC no son compatibles y generan un error, como NO_MATCHING_ACCESS_LEVEL.

  • Las tablas que usan la combinación en la lectura tienen las siguientes limitaciones:

    • Una consulta puede procesar hasta 100,000 entradas de vectores de eliminación en total en la tabla. En el caso de las tablas de la versión 3 de Iceberg que usan vectores de eliminación binarios, cada archivo de datos asociado con un vector de eliminación se considera una entrada de eliminación para este límite.
    • Cada archivo de datos se puede asociar con hasta 10,000 archivos de eliminación.
    • No se pueden aplicar más de 100,000 eliminaciones por igualdad a un archivo de datos.
    • Puedes evitar estas limitaciones compactando los archivos de eliminación y los vectores de eliminación con frecuencia, creando una vista sobre la tabla de Iceberg que evite las particiones que se mutan con frecuencia o filtrando las consultas en las columnas particionadas para reducir la cantidad de archivos de datos y vectores de eliminación analizados.

  • BigQuery admite la reducción de manifiestos con todas las funciones de transformación de particiones de Iceberg. Para obtener información sobre cómo reducir las particiones, consulta Consulta tablas particionadas. Las consultas que hacen referencia a las tablas externas de Iceberg deben contener literales en predicados en comparación con las columnas particionadas.

  • Solo se admiten archivos de datos de Apache Parquet.

  • No se admiten las siguientes funciones de la versión 3 de Iceberg:

    • Nuevos tipos de datos: Marca de tiempo en nanosegundos(zona horaria), desconocido, variante, geometría y geografía
    • Valores predeterminados iniciales
    • Claves de encriptación de tablas

Costos de la combinación en la lectura

La facturación a pedido de los datos de combinación en la lectura es la suma de los análisis de los siguientes datos:

  • Todos los bytes lógicos leídos en el archivo de datos (incluidas las filas marcadas como borradas por posición y las borradas por igualdad).
  • Son los bytes lógicos leídos al cargar los archivos de eliminación por igualdad, eliminación por posición y vector de eliminación para encontrar las filas borradas en un archivo de datos.

Exigir filtro de partición

Puedes exigir el uso de filtros de predicado si habilitas la opción Requerir filtro de partición para tu tabla de Iceberg. Si habilitas esta opción, los intentos de consultar la tabla sin especificar una cláusula WHERE que se alinee con cada archivo de manifiesto producirá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 eliminar particiones.

Puedes habilitar require_partition_filter de las siguientes maneras mientras creas una tabla de Iceberg:

SQL

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

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

Reemplaza lo siguiente:

  • TABLE: el nombre de la tabla que deseas crear.
  • PROJECT_ID: el ID del proyecto que contiene la tabla que deseas crear.
  • REGION: la ubicación en la que deseas crear la tabla de 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 de nube externa; como Amazon S3 o Azure Blob Storage.

    • Ejemplo para AWS: s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Ejemplo para 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 usará al final del parámetro --external_table_definition. Usa --require_partition_filter para habilitar el filtro de requerir partición. En el siguiente ejemplo, se crea una tabla externa de Iceberg llamada TABLE con el filtro 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

Reemplaza lo siguiente:

  • URI: el archivo de metadatos JSON más reciente para una instantánea de tabla específica

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

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

    • Ejemplo para AWS: s3://mybucket/iceberg/metadata/1234.metadata.json.
    • Ejemplo para 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 ves los detalles de conexión en la consola de Google Cloud , el ID de conexión es el valor en la última sección del ID de conexión completamente calificado 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

    que contiene la tabla que deseas actualizar. Por ejemplo, mydataset.

  • EXTERNAL_TABLE: el nombre de la tabla que deseas crear

    Por ejemplo, mytable.

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

Si no habilitas la opción exigir filtro de partición cuando creas la tabla particionada, puedes actualizar la tabla para agregar 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, ingresa el siguiente código:

bq update --require_partition_filter PROJECT_ID:DATASET.TABLE

¿Qué sigue?