Paramètres d'exécution dans les transferts Cloud Storage

Lorsque vous configurez un transfert de données dans Cloud Storage, Azure Blob Storage ou Amazon Simple Storage Service (Amazon S3), vous pouvez paramétrer l'URI (ou le chemin d'accès aux données) et la table de destination. Le paramétrage vous permet de charger des données à partir de buckets organisés par date. Ces paramètres sont appelés runtime parameters ou paramètres d'exécution pour les distinguer des paramètres de requête.

Lorsque vous utilisez des paramètres d'exécution dans le cadre d'un transfert, vous pouvez effectuer les opérations suivantes :

  • Définir la manière dont vous souhaitez partitionner la table de destination
  • Récupérer des fichiers qui correspondent à une date particulière

Paramètres d'exécution disponibles

Lorsque vous configurez le transfert Cloud Storage, Blob Storage ou Amazon S3, vous pouvez spécifier le mode de partitionnement de la table de destination à l'aide de paramètres d'exécution.

Paramètre Type de modèle Valeur
run_time Horodatage formaté En heure UTC, selon l'exécution programmée. Pour les requêtes programmées de façon récurrente, run_time représente l'heure d'exécution prévue. Par exemple, si le transfert est programmé pour s'exécuter "toutes les 24 heures", la différence de run_time entre deux transferts consécutifs sera exactement de 24 heures, même si le temps d'exécution réel peut varier légèrement.

Reportez-vous à TransferRun.runTime.
run_date Chaîne de date Date du paramètre run_time au format %Y%m%d, par exemple, 20180101. Ce format est compatible avec les tables partitionnées par date d'ingestion.

Système de modélisation

Les transferts Cloud Storage, Blob Storage et Amazon S3 acceptent les paramètres d'exécution dans le nom de la table de destination grâce à une syntaxe de modélisation.

Syntaxe des paramètres de modélisation

La syntaxe de modélisation supporte la modélisation de base des chaînes et le décalage horaire. Les paramètres sont référencés dans les formats suivants :

  • {run_date}
  • {run_time[+\-offset]|"time_format"}
Paramètre Purpose
run_date Ce paramètre est remplacé par la date au format YYYYMMDD.
run_time Ce paramètre accepte les propriétés suivantes :


offset
Décalage horaire exprimé en heures (h), minutes (m) et secondes (s), selon cet ordre.
Les jours (d) ne sont pas acceptés.
Les valeurs décimales sont autorisées, par exemple : 1.5h.

time_format
Chaîne de mise en forme. Les paramètres de mise en forme les plus courants sont les années (%Y), les mois (%m) et les jours (%d).
YYYYMMDD est le suffixe requis pour les tables partitionnées ; cela équivaut à "%Y%m%d".

Pour en savoir plus, consultez la section concernant la mise en forme des éléments "datetime".

Remarques sur l'utilisation :
  • Aucun espace n'est autorisé entre run_time, offset et time format.
  • Pour inclure des accolades littérales dans la chaîne, vous pouvez les échapper comme ceci : '\{' and '\}'.
  • Pour inclure des guillemets littéraux ou une barre verticale au format time_format, comme dans "YYYY|MM|DD", vous pouvez les échapper au format de chaîne suivant : '\"' ou '\|'.

Exemples de paramètres de modélisation

Les exemples suivants permettent d'illustrer la manière de définir les noms d'une table de destination avec différents formats d'heure, et en incluant un décalage de l'exécution.
run_time (UTC) Paramètre modélisé Nom de la table de destination de sortie
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"}
ou
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

Options de partitionnement

Il existe deux types de tables partitionnées dans BigQuery :

  • Tables partitionnées par date d'ingestion : pour les transferts Cloud Storage, Blob Storage et Amazon S3, le temps d'ingestion est la durée d'exécution du transfert.
  • Tables partitionnées en fonction d'une colonne : Le type de colonne doit être TIMESTAMP ou DATE.

Si la table de destination est partitionnée en fonction d'une colonne, vous identifiez la colonne partitionnée lorsque vous créez la table de destination et spécifiez son schéma. Pour plus d'informations sur la création de tables partitionnées en colonnes, consultez la section Créer et utiliser des tables partitionnées.

Exemples de partitionnement

  • Table sans partitionnement
    • Table de destination : mytable
  • Table partitionnée par date d'ingestion
    • Table de destination : mytable$YYYYMMDD
    • Notez qu'il n'est pas possible de spécifier les minutes.
  • Table partitionnée en colonnes
    • Table de destination : mytable
    • Spécifiez la colonne partitionnée en tant que colonne TIMESTAMP ou DATE lorsque vous créez le schéma de la table.

Remarques concernant l'utilisation des paramètres

  • Si vous partitionnez vos données en fonction de votre fuseau horaire local, vous devez calculer manuellement le décalage horaire à partir de l'heure UTC à l'aide du mécanisme de décalage de la syntaxe de modélisation.
  • Il n'est pas possible de spécifier les minutes dans les paramètres.
  • Il est possible d'utiliser de caractères génériques pour l'URI ou le chemin d'accès aux données avec des paramètres sur le nom de la table de destination.

Exemples de paramètres d'exécution

Les exemples suivants montrent comment combiner caractères génériques et paramètres pour des cas d'utilisation courants. Supposons que le nom de la table soit mytable et que run_time soit 2018-02-15 00:00:00 (UTC) pour tous les exemples.

Transférer des données vers une table non partitionnée

Ce cas d'utilisation s'applique au chargement de nouveaux fichiers à partir d'un bucket Cloud Storage, Blob Storage ou Amazon S3 et vers une table non partitionnée. Cet exemple utilise un caractère générique dans l'URI ou le chemin d'accès aux données, et utilise un transfert d'actualisation ad hoc pour récupérer les nouveaux fichiers.

Source de données Chemin d'accès aux données ou URI source Nom de la table de destination
Cloud Storage gs://bucket/*.csv mytable
Amazon S3 s3://bucket/*.csv mytable
Stockage de blobs *.csv mytable

Charger un instantané de toutes les données dans une table partitionnée par date d'ingestion

Dans ce cas, toutes les données de l'URI ou du chemin d'accès aux données spécifié sont transférées vers une table partitionnée à la date du jour. Lors d'un transfert d'actualisation, cette configuration récupère les fichiers récemment ajoutés depuis le dernier chargement, et les ajoute à une partition particulière.

Source de données Chemin d'accès aux données ou URI source Nom paramétré de la table de destination Nom évalué de la table de destination
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
Stockage de blobs *.csv mytable${run_time|"%Y%m%d"} mytable$20180215

Ce cas d'utilisation transfère les données du jour dans une table partitionnée à la date du jour. Cet exemple s'applique également à un transfert d'actualisation qui récupère les fichiers récemment ajoutés correspondant à une date donnée, et charge les données dans la partition correspondante.

Source de données Chemin d'accès aux données ou URI paramétré Nom paramétré de la table de destination Chemin d'accès aux données ou URI évalué Nom évalué de la table de destination
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
Stockage de blobs events-{run_time|"%Y%m%d"}/*.csv mytable${run_time|"%Y%m%d"} events-20180215/*.csv mytable$20180215

Étapes suivantes