Parámetros de tiempo de ejecución en transferencias de Amazon S3

Cuando configuras una transferencia de datos en Cloud Storage, Azure Blob Storage o Amazon Simple Storage Service (Amazon S3), puedes parametrizar el URI (o la ruta de datos) y la tabla de destino. La parametrización le permite cargar datos de segmentos organizados por fecha. Estos parámetros se denominan parámetros de tiempo de ejecución para distinguirlos de los parámetros de consulta.

Cuando usas parámetros de entorno de ejecución en una transferencia, puedes hacer lo siguiente:

  • Especifica cómo quieres crear las particiones de la tabla de destino
  • Recuperar archivos que coincidan con una fecha concreta

Parámetros de tiempo de ejecución disponibles

Cuando configures la transferencia de Cloud Storage, Blob Storage o Amazon S3, puedes especificar cómo quieres particionar la tabla de destino mediante parámetros de tiempo de ejecución.

Parámetro Tipo de plantilla Valor
run_time Marca de tiempo con formato En hora UTC, según la programación. En el caso de las transferencias programadas periódicamente, run_time representa la hora de ejecución prevista. Por ejemplo, si la transferencia se configura como "cada 24 horas", la diferencia run_time entre dos consultas consecutivas será exactamente de 24 horas, aunque el tiempo de ejecución real pueda variar ligeramente.

Consulta TransferRun.runTime.
run_date Cadena de fecha Fecha del parámetro run_time con el siguiente formato: %Y%m%d. Por ejemplo, 20180101. Este formato es compatible con las tablas con particiones por hora de ingestión.

Sistema de plantillas

Las transferencias de Cloud Storage, Blob Storage y Amazon S3 admiten parámetros de entorno de ejecución en el nombre de la tabla de destino mediante una sintaxis de plantilla.

Sintaxis de las plantillas de parámetros

La sintaxis de las plantillas admite plantillas de cadenas básicas y desfases de tiempo. Los parámetros se hacen referencia en los siguientes formatos:

  • {run_date}
  • {run_time[+\-offset]|"time_format"}
Parámetro Purpose
run_date Este parámetro se sustituye por la fecha en formato YYYYMMDD.
run_time Este parámetro admite las siguientes propiedades:


offset
Diferencia horaria expresada en horas (h), minutos (m) y segundos (s) en ese orden. No se admiten
días (d).
Se admiten decimales, por ejemplo: 1.5h.

time_format
Una cadena de formato. Los parámetros de formato más habituales son los años (%Y), los meses (%m) y los días (%d).
En el caso de las tablas particionadas, el sufijo obligatorio es AAAAMMDD, que equivale a "%Y%m%d".

Consulta más información sobre cómo dar formato a elementos de fecha y hora.

Notas de uso:
  • No se permite ningún espacio en blanco entre run_time, offset y el formato de hora.
  • Para incluir llaves literales en la cadena, puedes usar el carácter de escape '\{' and '\}'.
  • Para incluir comillas literales o una barra vertical en time_format, como "YYYY|MM|DD", puedes usar el carácter de escape en la cadena de formato: '\"' o '\|'.

Ejemplos de plantillas de parámetros

En estos ejemplos se muestra cómo especificar nombres de tabla de destino con diferentes formatos de hora y cómo compensar el tiempo de ejecución.
run_time (UTC) Parámetro de plantilla Nombre de la tabla de destino de salida
2018-02-15 00:00:00 mytable mytable
2018-02-15 00:00:00 mytable_{run_time|"%Y%m%d"} mytable_20180215
2018-02-15 00:00:00 mytable_{run_time+25h|"%Y%m%d"} mytable_20180216
2018-02-15 00:00:00 mytable_{run_time-1h|"%Y%m%d"} mytable_20180214
2018-02-15 00:00:00 mytable_{run_time+1.5h|"%Y%m%d%H"}
o
mytable_{run_time+90m|"%Y%m%d%H"}		 mytable_2018021501
2018-02-15 00:00:00 {run_time+97s|"%Y%m%d"}_mytable_{run_time+97s|"%H%M%S"} 20180215_mytable_000137

Opciones de partición

Hay dos tipos de tablas con particiones en BigQuery:

  • Tablas con particiones por hora de ingestión. En el caso de las transferencias de Cloud Storage, Blob Storage y Amazon S3, el tiempo de ingestión es el tiempo de ejecución de la transferencia.
  • Tablas con particiones basadas en una columna. El tipo de columna debe ser TIMESTAMP o DATE.

Si la tabla de destino tiene particiones por columnas, debes identificar la columna de partición al crear la tabla de destino y especificar su esquema. Consulta más información sobre cómo crear tablas con particiones basadas en columnas en el artículo Crear y usar tablas con particiones.

Ejemplos de particiones

Notas sobre el uso de parámetros

  • Si particiona los datos en función de su zona horaria local, debe calcular manualmente la diferencia horaria con respecto al UTC mediante el mecanismo de diferencia de la sintaxis de plantillas.
  • No se pueden especificar minutos en los parámetros.
  • Se pueden usar comodines en el URI o en la ruta de datos junto con parámetros en el nombre de la tabla de destino.

Ejemplos de parámetros de tiempo de ejecución

En los siguientes ejemplos se muestra cómo combinar el carácter comodín y los parámetros en casos prácticos habituales. Supongamos que la tabla se llama mytable y que la run_time es 2018-02-15 00:00:00 (UTC) en todos los ejemplos.

Transferir datos a una tabla sin particiones

Este caso práctico se aplica a la carga de archivos nuevos desde un segmento de Cloud Storage, Blob Storage o Amazon S3 en una tabla sin particiones. En este ejemplo se usa un comodín en el URI o en la ruta de datos y se utiliza una transferencia de actualización ad hoc para recoger los archivos nuevos.

Fuente de datos URI de origen o ruta de datos Nombre de la tabla de destino
Cloud Storage gs://bucket/*.csv mytable
Amazon S3 s3://bucket/*.csv mytable
Almacenamiento de blobs *.csv mytable

Cargar una captura de todos los datos en una tabla con particiones por hora de ingestión

En este caso, todos los datos del URI o de la ruta de datos especificados se transfieren a una tabla particionada por la fecha actual. En una transferencia de actualización, esta configuración recoge los archivos añadidos desde la última carga y los añade a una partición concreta.

Fuente de datos URI de origen o ruta de datos Nombre de la tabla de destino parametrizado Nombre de la tabla de destino evaluada
Cloud Storage gs://bucket/*.csv mytable${run_time|"%Y%m%d"} mytable$20180215
Amazon S3 s3://bucket/*.csv mytable${run_time|"%Y%m%d"} mytable$20180215
Almacenamiento de blobs *.csv mytable${run_time|"%Y%m%d"} mytable$20180215

En este caso práctico, los datos de hoy se transfieren a una tabla con particiones por la fecha de hoy. Este ejemplo también se aplica a una transferencia de actualización que obtiene los archivos recién añadidos que coinciden con una fecha determinada y carga los datos en la partición correspondiente.

Fuente de datos URI o ruta de datos parametrizados Nombre de la tabla de destino parametrizado URI o ruta de datos evaluados Nombre de la tabla de destino evaluada
Cloud Storage gs://bucket/events-{run_time|"%Y%m%d"}/*.csv mytable${run_time|"%Y%m%d"} gs://bucket/events-20180215/*.csv mytable$20180215
Amazon S3 s3://bucket/events-{run_time|"%Y%m%d"}/*.csv mytable${run_time|"%Y%m%d"} s3://bucket/events-20180215/*.csv mytable$20180215
Almacenamiento de blobs events-{run_time|"%Y%m%d"}/*.csv mytable${run_time|"%Y%m%d"} events-20180215/*.csv mytable$20180215

Siguientes pasos