Consultar formatos de tabla abiertos con manifiestos

En este documento se describe cómo usar archivos de manifiesto para consultar datos almacenados en formatos de tabla abiertos, como Apache Hudi y Delta Lake.

Algunos formatos de tabla abiertos, como Hudi y Delta Lake, exportan su estado actual como uno o varios archivos de manifiesto. Un archivo de manifiesto contiene una lista de archivos de datos que forman tablas. Con la compatibilidad con manifiestos de BigQuery, puedes consultar y cargar datos almacenados en formatos de tabla abiertos.

Antes de empezar

Roles obligatorios

Para consultar tablas de BigLake basadas en datos de Hudi y Delta Lake, asegúrate de tener los siguientes roles:

  • Usuario de conexión de BigQuery (roles/bigquery.connectionUser)
  • Lector de datos de BigQuery (roles/bigquery.dataViewer)
  • Usuario de BigQuery (roles/bigquery.user)

También puedes consultar tablas externas de Hudi. Sin embargo, le recomendamos que actualice la tabla externa a BigLake. Para consultar tablas externas de Hudi, asegúrate de tener los siguientes roles:

  • Lector de datos de BigQuery (roles/bigquery.dataViewer)
  • Usuario de BigQuery (roles/bigquery.user)
  • Lector de objetos de Storage (roles/storage.objectViewer)

En función de tus permisos, puedes asignarte estos roles o pedirle a tu administrador que te los asigne. Para obtener más información sobre cómo conceder roles, consulta el artículo Ver los roles que se pueden conceder en los recursos.

Para ver los permisos exactos que se necesitan para consultar tablas de BigLake, despliega la sección Permisos obligatorios:

Permisos obligatorios

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

Consultar cargas de trabajo de Hudi

Para consultar datos de Hudi, sigue estos pasos:

  1. Crea una tabla externa basada en datos de Hudi.
  2. Actualiza la tabla externa a BigLake.

Crear tablas externas de Hudi

Cuando sincronices tablas con la herramienta de sincronización de Hudi y BigQuery, habilita la marca use-bq-manifest-file para cambiar al método de archivo de manifiesto. Esta marca también exporta un archivo de manifiesto en un formato compatible con BigQuery y lo usa para crear una tabla externa con el nombre especificado en el parámetro --table.

Para crear una tabla externa de Hudi, sigue estos pasos:

  1. Para crear una tabla externa de Hudi, envía una tarea a un clúster de Dataproc. Cuando compiles el conector Hudi-BigQuery, habilita la marca use-bq-manifest-file para cambiar al método del archivo de manifiesto. Esta marca exporta un archivo de manifiesto en un formato compatible con BigQuery y lo usa para crear una tabla externa con el nombre especificado en el parámetro --table.

    spark-submit \
   --master yarn \
   --packages com.google.cloud:google-cloud-bigquery:2.10.4 \
   --class org.apache.hudi.gcp.bigquery.BigQuerySyncTool  \
   JAR \
   --project-id PROJECT_ID \
   --dataset-name DATASET \
   --dataset-location LOCATION \
   --table TABLE \
   --source-uri URI  \
   --source-uri-prefix URI_PREFIX \
   --base-path BASE_PATH  \
   --partitioned-by PARTITION_BY \
   --use-bq-manifest-file

    Haz los cambios siguientes:

    • JAR: Si usas el conector Hudi-BigQuery, especifica hudi-gcp-bundle-0.14.0.jar. Si usas el componente Hudi en Dataproc 2.1, especifica /usr/lib/hudi/tools/bq-sync-tool/hudi-gcp-bundle-0.12.3.1.jar

    • PROJECT_ID: el ID del proyecto en el que quieres crear la tabla BigLake de Hudi.

    • DATASET: el conjunto de datos en el que quiere crear la tabla Hudi BigLake

    • LOCATION: la ubicación en la que quieres crear la tabla BigLake de Hudi

    • TABLE: el nombre de la tabla que quieres crear

      Si vas a cambiar de la versión anterior del conector Hudi-BigQuery (0.13.0 y versiones anteriores) que creaba vistas en los archivos de manifiesto, asegúrate de usar el mismo nombre de tabla para poder conservar el código de la canalización de datos posterior.

    • URI: el URI de Cloud Storage que has creado para almacenar el archivo de manifiesto de Hudi

      Este URI apunta a la partición de primer nivel. Asegúrate de incluir la clave de partición. Por ejemplo, gs://mybucket/hudi/mydataset/EventDate=*

    • URI_PREFIX: el prefijo de la ruta del URI de Cloud Storage. Normalmente, es la ruta a las tablas de Hudi.

    • BASE_PATH: la ruta base de las tablas de Hudi

      Por ejemplo, gs://mybucket/hudi/mydataset/

    • PARTITION_BY: el valor de la partición

      Por ejemplo, EventDate

    Para obtener más información sobre la configuración del conector, consulta el artículo sobre el conector Hudi-BigQuery.

  2. Para definir controles pormenorizados adecuados o acelerar el rendimiento habilitando el almacenamiento en caché de metadatos, consulte Actualizar tablas BigLake.

Consultar cargas de trabajo delta

Ahora se admiten de forma nativa las tablas delta. Recomendamos crear tablas Delta BigLake para cargas de trabajo Delta. Las tablas de BigLake de Delta Lake admiten tablas de Delta Lake más avanzadas, incluidas las tablas con reasignación de columnas y vectores de eliminación. Además, las tablas Delta BigLake leen directamente la última instantánea, por lo que las actualizaciones están disponibles al instante.

Para consultar cargas de trabajo de Delta, sigue estos pasos:

  1. Genera un archivo de manifiesto.
  2. Crea una tabla de BigLake basada en el archivo de manifiesto.
  3. Configura controles pormenorizados adecuados o acelera el rendimiento habilitando el almacenamiento en caché de metadatos. Para ello, consulta Actualizar tablas de BigLake.

Generar un archivo de manifiesto

BigQuery admite el archivo de manifiesto en formato SymLinkTextInputFormat, que es una lista de URIs delimitada por saltos de línea. Para obtener más información sobre cómo generar un archivo de manifiesto, consulta Configurar la integración de Presto con Delta Lake y consultar tablas Delta.

Para generar un archivo de manifiesto, envía un trabajo a un clúster de Dataproc:

SQL

Con Spark, ejecuta el siguiente comando en una tabla delta ubicada en path-to-delta-table:

GENERATE symlink_format_manifest FOR TABLE delta.`<path-to-delta-table>`

Scala

Con Spark, ejecuta el siguiente comando en una tabla delta ubicada en path-to-delta-table:

val deltaTable = DeltaTable.forPath(<path-to-delta-table>)
deltaTable.generate("symlink_format_manifest")

Java

Con Spark, ejecuta el siguiente comando en una tabla delta ubicada en path-to-delta-table:

DeltaTable deltaTable = DeltaTable.forPath(<path-to-delta-table>);
deltaTable.generate("symlink_format_manifest");

Python

Con Spark, ejecuta el siguiente comando en una tabla delta ubicada en path-to-delta-table:

deltaTable = DeltaTable.forPath(<path-to-delta-table>)
deltaTable.generate("symlink_format_manifest")

Crear tablas Delta BigLake

Para crear una tabla de BigLake Delta, usa la declaración CREATE EXTERNAL TABLE con el campo file_set_spec_type definido como NEW_LINE_DELIMITED_MANIFEST:

  1. Ve a la página BigQuery.

    Ir a BigQuery

  2. En el editor de consultas, ejecuta la instrucción CREATE EXTERNAL TABLE:

    CREATE EXTERNAL TABLE PROJECT_ID.DATASET_NAME.TABLE_NAME
WITH PARTITION COLUMNS(
`PARTITION_COLUMN PARTITION_COLUMN_TYPE`,)
WITH CONNECTION `PROJECT_IDREGION.CONNECTION_NAME`
OPTIONS (
   format = "DATA_FORMAT",
   uris = ["URI"],
   file_set_spec_type = 'NEW_LINE_DELIMITED_MANIFEST',
   hive_partition_uri_prefix = "PATH_TO_DELTA_TABLE"
   max_staleness = STALENESS_INTERVAL,
   metadata_cache_mode = 'CACHE_MODE');

    Haz los cambios siguientes:

    • DATASET_NAME: el nombre del conjunto de datos que has creado
    • TABLE_NAME: el nombre que quieras asignar a esta tabla
    • REGION: la ubicación donde se encuentra la conexión (por ejemplo, us-east1)
    • CONNECTION_NAME: el nombre de la conexión que has creado
    • DATA_FORMAT: cualquiera de los formatos admitidos (como PARQUET)
    • URI: la ruta al archivo de manifiesto (por ejemplo, gs://mybucket/path)
    • PATH_TO_DELTA_TABLE: prefijo común de todos los URIs de origen antes de que empiece la codificación de la clave de partición
    • STALENESS_INTERVAL: especifica si las operaciones de la tabla de BigLake usan metadatos almacenados en caché y cómo de actualizados deben estar los metadatos almacenados en caché para que la operación los use. Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta el artículo Almacenamiento en caché de metadatos para mejorar el rendimiento.

      Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Este es el valor predeterminado.

      Para habilitar el almacenamiento en caché de metadatos, especifica un valor de literal de intervalo entre 30 minutos y 7 días. Por ejemplo, especifica INTERVAL 4 HOUR para un intervalo de obsolescencia de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se han actualizado en las últimas 4 horas. Si los metadatos almacenados en caché son anteriores a esa fecha, la operación recupera los metadatos de Delta Lake.

    • CACHE_MODE: especifica si la caché de metadatos se actualiza automáticamente o manualmente. Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta Almacenamiento en caché de metadatos para mejorar el rendimiento.

      Defina el valor AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, que suele ser de entre 30 y 60 minutos.

      Seleccione MANUAL si quiere actualizar la caché de metadatos según la programación que determine. En ese caso, puedes llamar al BQ.REFRESH_EXTERNAL_METADATA_CACHEprocedimiento del sistema para actualizar la caché.

      Debes definir CACHE_MODE si STALENESS_INTERVAL tiene un valor superior a 0.

    Ejemplo:

    CREATE EXTERNAL TABLE mydataset.mytable
WITH CONNECTION `us-east1.myconnection`
OPTIONS (
    format="PARQUET",
    uris=["gs://mybucket/path/partitionpath=*"],
    file_set_spec_type = 'NEW_LINE_DELIMITED_MANIFEST'
    hive_partition_uri_prefix = "gs://mybucket/path/"
    max_staleness = INTERVAL 1 DAY,
    metadata_cache_mode = 'AUTOMATIC'
);

Actualizar tablas de BigLake

También puedes acelerar el rendimiento de tus cargas de trabajo aprovechando el almacenamiento en caché de metadatos y las vistas materializadas. Si quieres usar el almacenamiento en caché de metadatos, puedes especificar la configuración correspondiente al mismo tiempo. Para obtener detalles de la tabla, como el formato de origen y el URI de origen, consulta Obtener información de la tabla.

Para actualizar una tabla externa a una tabla de BigLake o actualizar una tabla de BigLake, selecciona una de las siguientes opciones:

SQL

Usa la CREATE OR REPLACE EXTERNAL TABLEdeclaración de DDL para actualizar una tabla:

  1. En la Google Cloud consola, ve a la página BigQuery.

    Ir a BigQuery

  2. En el editor de consultas, introduce la siguiente instrucción:

    CREATE OR REPLACE EXTERNAL TABLE
  `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
  WITH CONNECTION {`REGION.CONNECTION_ID` | DEFAULT}
  OPTIONS(
    format ="TABLE_FORMAT",
    uris = ['BUCKET_PATH'],
    max_staleness = STALENESS_INTERVAL,
    metadata_cache_mode = 'CACHE_MODE'
    );

    Haz los cambios siguientes:

    • PROJECT_ID: el nombre del proyecto que contiene la tabla
    • DATASET: el nombre del conjunto de datos que contiene la tabla
    • EXTERNAL_TABLE_NAME: el nombre de la tabla
    • REGION: la región que contiene la conexión
    • CONNECTION_ID: el nombre de la conexión que se va a usar

      Para usar una conexión predeterminada, especifica DEFAULT en lugar de la cadena de conexión que contiene REGION.CONNECTION_ID.

    • TABLE_FORMAT: el formato que usa la tabla

      No puedes cambiar este ajuste al actualizar la tabla.

    • BUCKET_PATH: la ruta al segmento de Cloud Storage que contiene los datos de la tabla externa, con el formato ['gs://bucket_name/[folder_name/]file_name'].

      Puede seleccionar varios archivos del segmento especificando un carácter comodín de asterisco (*) en la ruta. Por ejemplo, ['gs://mybucket/file_name*']. Para obtener más información, consulta Compatibilidad con comodines para URIs de Cloud Storage.

      Puedes especificar varios segmentos para la opción uris proporcionando varias rutas.

      En los siguientes ejemplos se muestran valores de uris válidos:

      • ['gs://bucket/path1/myfile.csv']
      • ['gs://bucket/path1/*.csv']
      • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

      Si especifica valores de uris que se dirijan a varios archivos, todos esos archivos deben compartir un esquema compatible.

      Para obtener más información sobre cómo usar URIs de Cloud Storage en BigQuery, consulta Ruta de recursos de Cloud Storage.

    • STALENESS_INTERVAL: especifica si las operaciones de la tabla usan metadatos almacenados en caché y cuánto tiempo deben haber pasado desde que se almacenaron en caché para que la operación los use.

      Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta Almacenamiento en caché de metadatos para mejorar el rendimiento.

      Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Este es el valor predeterminado.

      Para habilitar el almacenamiento en caché de metadatos, especifica un valor de literal de intervalo entre 30 minutos y 7 días. Por ejemplo, especifica INTERVAL 4 HOUR para un intervalo de obsolescencia de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se han actualizado en las últimas 4 horas. Si los metadatos almacenados en caché son anteriores a esa fecha, la operación recupera los metadatos de Cloud Storage.

    • CACHE_MODE: especifica si la caché de metadatos se actualiza automáticamente o manualmente.

      Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta el artículo Almacenamiento en caché de metadatos para mejorar el rendimiento.

      Defina el valor AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, que suele ser de entre 30 y 60 minutos.

      Seleccione MANUAL si quiere actualizar la caché de metadatos según la programación que determine. En ese caso, puedes llamar al BQ.REFRESH_EXTERNAL_METADATA_CACHEprocedimiento del sistema para actualizar la caché.

      Debes definir CACHE_MODE si STALENESS_INTERVAL tiene un valor superior a 0.

  3. Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.

bq

Usa los comandos bq mkdef y bq update para actualizar una tabla:

  1. Genera una definición de tabla externa que describa los aspectos de la tabla que quieres cambiar:

    bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \
--source_format=TABLE_FORMAT \
--metadata_cache_mode=CACHE_MODE \
"BUCKET_PATH" > /tmp/DEFINITION_FILE

    Haz los cambios siguientes:

    • PROJECT_ID: el nombre del proyecto que contiene la conexión
    • REGION: la región que contiene la conexión
    • CONNECTION_ID: el nombre de la conexión que se va a usar
    • TABLE_FORMAT: el formato que usa la tabla. No puedes cambiar este ajuste al actualizar la tabla.

    • CACHE_MODE: especifica si la caché de metadatos se actualiza automáticamente o manualmente. Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta Almacenamiento en caché de metadatos para mejorar el rendimiento.

      Defina el valor AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, que suele ser de entre 30 y 60 minutos.

      Introduzca MANUAL si quiere actualizar la caché de metadatos según la programación que determine. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.

      Debes definir CACHE_MODE si STALENESS_INTERVAL tiene un valor superior a 0.

    • BUCKET_PATH: la ruta al segmento de Cloud Storage que contiene los datos de la tabla externa, con el formato gs://bucket_name/[folder_name/]file_name.

      Puedes limitar los archivos seleccionados del segmento especificando un carácter comodín de asterisco (*) en la ruta. Por ejemplo, gs://mybucket/file_name*. Para obtener más información, consulta Compatibilidad con comodines en URIs de Cloud Storage.

      Puedes especificar varios segmentos para la opción uris proporcionando varias rutas.

      En los siguientes ejemplos se muestran valores de uris válidos:

      • gs://bucket/path1/myfile.csv
      • gs://bucket/path1/*.csv
      • gs://bucket/path1/*,gs://bucket/path2/file00*

      Si especifica valores de uris que se dirijan a varios archivos, todos esos archivos deben compartir un esquema compatible.

      Para obtener más información sobre cómo usar URIs de Cloud Storage en BigQuery, consulta Ruta de recursos de Cloud Storage.

    • DEFINITION_FILE: el nombre del archivo de definición de tabla que estás creando.

  2. Actualiza la tabla con la nueva definición de tabla externa:

    bq update --max_staleness=STALENESS_INTERVAL \
--external_table_definition=/tmp/DEFINITION_FILE \
PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME

    Haz los cambios siguientes:

    • STALENESS_INTERVAL: especifica si las operaciones de la tabla usan metadatos almacenados en caché y cómo de actualizados deben estar los metadatos almacenados en caché para que la operación los use. Para obtener más información sobre las consideraciones relativas al almacenamiento en caché de metadatos, consulta Almacenamiento en caché de metadatos para mejorar el rendimiento.

      Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Este es el valor predeterminado.

      Para habilitar el almacenamiento en caché de metadatos, especifica un valor de intervalo de entre 30 minutos y 7 días con el formato Y-M D H:M:S descrito en la documentación del INTERVAL tipo de datos. Por ejemplo, especifica 0-0 0 4:0:0 para un intervalo de obsolescencia de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se han actualizado en las últimas 4 horas. Si los metadatos almacenados en caché son anteriores a ese periodo, la operación recupera los metadatos de Cloud Storage.

    • DEFINITION_FILE: el nombre del archivo de definición de la tabla que has creado o actualizado.

    • PROJECT_ID: el nombre del proyecto que contiene la tabla.

    • DATASET: el nombre del conjunto de datos que contiene la tabla.

    • EXTERNAL_TABLE_NAME: el nombre de la tabla

Consultar tablas de BigLake y externas

Después de crear una tabla de BigLake, puedes consultarla con la sintaxis de GoogleSQL, igual que si fuera una tabla estándar de BigQuery. Por ejemplo, SELECT field1, field2 FROM mydataset.my_cloud_storage_table;.

Limitaciones

  • BigQuery solo admite consultas de tablas de lector de Delta Lake v1.

  • La integración de Hudi y BigQuery solo funciona con tablas copy-on-write con particiones de estilo Hive.

Siguientes pasos