Consultar formatos de tabla abiertos con manifiestos

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

Algunos formatos de tabla abierta, como Hudi y Delta Lake, exportan su estado actual como uno o más archivos de manifiesto. Un archivo de manifiesto contiene una lista de archivos de datos que conforman tablas. Con la compatibilidad del manifiesto en BigQuery, puedes consultar y cargar datos almacenados en formatos de tabla abierta.

Antes de comenzar

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)
  • Visualizador de datos de BigQuery (roles/bigquery.dataViewer)
  • Usuario de BigQuery (roles/bigquery.user)

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

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

Según los permisos que tengas, puedes otorgarte estos roles o pedirle a tu administrador que te los otorgue. Para obtener más información sobre cómo otorgar roles, consulta Visualiza los roles que se pueden otorgar en los recursos.

Para ver los permisos exactos que necesitas para consultar las tablas de BigLake, expande la sección Permisos necesarios:

Permisos necesarios

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

Consulta las 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.

Crea tablas externas de Hudi

Cuando sincronices tablas con la herramienta de sincronización para Hudi y BigQuery, habilita la marca use-bq-manifest-file para pasar al enfoque del archivo de manifiesto. Esta marca también exporta un archivo de manifiesto en un formato que admite 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 un trabajo a un clúster de Dataproc existente. Cuando compiles el conector de Hudi-BigQuery, habilita la marca use-bq-manifest-file para pasar al enfoque del archivo de manifiesto. Esta marca exporta un archivo de manifiesto en un formato que admite 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

    Reemplaza lo siguiente:

    • JAR: Si usas el conector Hudi-BigQuery, especifica hudi-gcp-bundle-0.14.0.jar. Si usas el componente de 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 deseas crear la tabla de Hudi BigLake

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

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

    • TABLE: el nombre de la tabla que deseas crear

      Si pasas a la versión anterior del conector de Hudi-BigQuery (0.13.0 y anteriores) que creó vistas en los archivos de manifiesto, asegúrate de usar el mismo nombre de tabla que te permita mantener el código de canalización descendente existente.

    • URI: el URI de Cloud Storage que creaste 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 de URI de Cloud Storage, que suele ser la ruta de acceso a las tablas de Hudi

    • BASE_PATH: la ruta base para las tablas de Hudi

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

    • PARTITION_BY: el valor de partición

      Por ejemplo, EventDate

    Para obtener más información sobre la configuración del conector, consulta Conector de Hudi-BigQuery.

  2. Para configurar controles detallados precisos o acelerar el rendimiento a través de la habilitación del almacenamiento en caché de metadatos, consulta Actualiza las tablas de BigLake.

Consulta cargas de trabajo de Delta

Delta tables are now natively supported. We recommend creating Delta BigLake tables for Delta workloads. Delta Lake BigLake tables support more advanced Delta Lake tables, including tables with column remapping and deletion vectors. Additionally, Delta BigLake tables directly read the latest snapshot, so updates are instantly available.

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. Habilita el almacenamiento en caché de metadatos para establecer controles detallados adecuados o acelerar el rendimiento. Para ello, consulta Actualiza las tablas de BigLake.

Genera un archivo de manifiesto

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

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

SQL

Con Spark, ejecuta el siguiente comando en una tabla de Delta en la ubicación 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 de Delta en la ubicación 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 de Delta en la ubicación 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 de Delta en la ubicación path-to-delta-table:

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

Crea tablas de Delta BigLake

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

  1. Ve a la página de BigQuery.

    Ir a BigQuery

  2. En el editor de consultas, ejecuta la declaració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');

    Reemplaza lo siguiente:

    • DATASET_NAME: Es el nombre del conjunto de datos que creaste.
    • TABLE_NAME: Es el nombre que deseas asignar a esta tabla.
    • REGION: la ubicación en la que se encuentra la conexión (por ejemplo, us-east1).
    • CONNECTION_NAME: Es el nombre de la conexión que creaste.
    • DATA_FORMAT: cualquiera de los formats compatibles (como PARQUET)
    • URI: la ruta al archivo de manifiesto (por ejemplo, gs://mybucket/path).
    • PATH_TO_DELTA_TABLE: un prefijo común para todos los URI de origen antes de que empiece la codificación de la clave de partición
    • STALENESS_INTERVAL: especifica si las operaciones que se usan en la tabla de BigLake usan los metadatos almacenados en caché, y qué tan actuales deben ser los metadatos para que la operación los use. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

      Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.

      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 inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Delta Lake en su lugar.

    • CACHE_MODE: especifica si la caché de metadatos se actualiza de forma automática o manual. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

      Configúralo como AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.

      Configúralo como MANUAL si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.

      Debes configurar CACHE_MODE si STALENESS_INTERVAL está configurado en un valor mayor que 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'
);

Actualiza las tablas de BigLake

También puedes acelerar el rendimiento de tus cargas de trabajo si aprovechas el almacenamiento en caché de metadatos y las vistas materializadas. Si deseas usar el almacenamiento en caché de metadatos, puedes especificar una configuración para esto al mismo tiempo. Para obtener detalles de la tabla, como el formato de origen y el URI de origen, consulta Obtén información de la tabla.

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

SQL

Usa la declaración DDL CREATE OR REPLACE EXTERNAL TABLE para actualizar una tabla:

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

    Ir a BigQuery

  2. En el editor de consultas, escribe la siguiente oración:

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

    Reemplaza lo siguiente:

    • 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 usará
    • TABLE_FORMAT: el formato que usa la tabla

      No puedes cambiar esto cuando actualizas la tabla.

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

      Puedes elegir varios archivos del bucket si especificas un carácter comodín de asterisco (*) en la ruta de acceso. Un ejemplo es ['gs://mybucket/file_name*']. Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.

      Puedes especificar varios buckets para la opción uris si proporcionas varias rutas de acceso.

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

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

      Cuando especificas valores uris que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.

      Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.

    • STALENESS_INTERVAL: especifica si las operaciones en la tabla usan los metadatos almacenados en caché y qué tan recientes deben ser los metadatos almacenados en caché para que la operación los use.

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

      Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.

      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 inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Cloud Storage.

    • CACHE_MODE: especifica si la caché de metadatos se actualiza de forma automática o manual

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

      Configúralo como AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.

      Configúralo como MANUAL si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.

      Debes configurar CACHE_MODE si STALENESS_INTERVAL está configurado en un valor mayor que 0.

  3. Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta 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 se debe cambiar:

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

    Reemplaza lo siguiente:

    • 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 usará
    • TABLE_FORMAT: el formato que usa la tabla No puedes cambiar esto cuando actualizas la tabla.

    • CACHE_MODE: especifica si la caché de metadatos se actualiza de forma automática o manual. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

      Configúralo como AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.

      Configúralo como MANUAL si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.

      Debes configurar CACHE_MODE si STALENESS_INTERVAL está configurado en un valor mayor que 0.

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

      Puedes limitar los archivos elegidos del bucket si especificas un carácter comodín de asterisco (*) en la ruta de acceso. Un ejemplo es gs://mybucket/file_name*. Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.

      Puedes especificar varios buckets para la opción uris si proporcionas varias rutas de acceso.

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

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

      Cuando especificas valores uris que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.

      Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.

    • DEFINITION_FILE: el nombre del archivo de definición de tablas que crearás.

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

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

    Reemplaza lo siguiente:

    • STALENESS_INTERVAL: especifica si las operaciones en la tabla usan los metadatos almacenados en caché y qué tan recientes deben ser los metadatos almacenados en caché para que la operación los use. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

      Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.

      Para habilitar el almacenamiento en caché de metadatos, especifica un valor de intervalo entre 30 minutos y 7 días, mediante el siguiente comando:Y-M D H:M:S formato que se describe en elINTERVAL tipo de datos. Por ejemplo, especifica 0-0 0 4:0:0 para un intervalo de inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Cloud Storage.

    • DEFINITION_FILE: el nombre del archivo de definición de tablas que creaste o actualizaste.

    • 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.

Consulta BigLake y las tablas externas

Después de crear una tabla de BigLake, puedes consultarla con la sintaxis de GoogleSQL, de la misma manera que si fuese una tabla de BigQuery estándar. Un ejemplo es SELECT field1, field2 FROM mydataset.my_cloud_storage_table;.

Limitaciones

  • BigQuery solo admite la consulta de tablas del lector v1 de Delta Lake.

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

¿Qué sigue?