Planifier des requêtes

Cette page décrit comment programmer des requêtes récurrentes dans BigQuery.

Présentation

Vous pouvez programmer des requêtes à exécuter de façon récurrente. Les requêtes programmées doivent être écrites en SQL standard et peuvent inclure des instructions en langage de définition de données (LDD) et en langage de manipulation de données (LMD). La chaîne de requête et la table de destination peuvent être paramétrées, ce qui vous permet d'organiser les résultats de la requête par date et heure.

Avant de commencer

Avant de créer une requête programmée, veuillez effectuer les actions suivantes :

• Les requêtes programmées utilisent les fonctionnalités du Service de transfert de données BigQuery. Vérifiez que vous avez effectué toutes les actions requises sur la page Activer le service de transfert de données BigQuery.

• Si vous créez une requête programmée à l'aide de l'UI Web classique de BigQuery, autorisez les pop-ups provenant de bigquery.cloud.google.com dans votre navigateur pour pouvoir afficher la fenêtre des autorisations. Vous devez autoriser le service de transfert de données BigQuery à gérer votre requête programmée.

Autorisations requises

Avant de programmer une requête, procédez comme suit :

• Assurez-vous que la personne qui crée le transfert dispose des autorisations requises suivantes dans BigQuery :

  • Autorisations bigquery.jobs.create ou bigquery.transfers.update pour créer le transfert
  • Autorisations bigquery.datasets.update sur l'ensemble de données cible

  Le rôle Cloud IAM prédéfini bigquery.jobUser inclut des autorisations bigquery.jobs.create. Pour en savoir plus sur les rôles Cloud IAM dans BigQuery, consultez la page Rôles et autorisations prédéfinis.

Avant de modifier une requête programmée, procédez comme suit :

• Assurez-vous que la personne qui modifie la requête programmée dispose de l'une des autorisations requises suivantes dans BigQuery :
  • Autorisations bigquery.jobs.create (la personne doit être le créateur de la planification)
  • Autorisations bigquery.transfers.update

Options de configuration

Chaîne de requête

La chaîne de requête doit être valide et écrite en SQL standard. À chaque exécution, une requête programmée peut recevoir les paramètres de requête suivants.

Pour tester manuellement une chaîne de requête avec les paramètres @run_time et @run_date avant de programmer une requête, utilisez l'interface de ligne de commande.

Paramètres disponibles

Paramètre	Type SQL standard	Valeur
@run_time	TIMESTAMP	Représenté en temps UTC. 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 la requête programmée est définie sur "toutes les 24 heures", la différence de run_time entre deux requêtes consécutives sera exactement de 24 heures, même si le temps d'exécution réel peut varier légèrement.
@run_date	DATE	Représente une date de calendrier logique.

Exemple

Le paramètre @run_time fait partie de la chaîne de requête de l'exemple suivant, où une requête est exécutée sur un ensemble de données public nommé hacker_news.stories.

SELECT @run_time AS time,
  title,
  author,
  text
FROM `bigquery-public-data.hacker_news.stories`
LIMIT
  1000

Table de destination

Lorsque vous configurez la requête programmée et que la table de destination pour afficher les résultats n'existe pas, BigQuery va tenter de créer cette table.

Si vous utilisez une requête LDD ou LMD :

• Dans Cloud Console, choisissez la région ou l'emplacement de traitement. L'emplacement de traitement est requis pour les requêtes LDD ou LMD qui créent la table de destination.
• Dans l'UI Web classique de BigQuery, laissez la table de destination vide.

Si la table cible existe, le schéma de la table de destination peut être mis à jour en fonction des résultats de la requête, si vous ajoutez des colonnes au schéma (ALLOW_FIELD_ADDITION) ou assouplissez le mode d'une colonne en passant de REQUIRED à NULLABLE (ALLOW_FIELD_RELAXATION). Dans tous les autres cas, les modifications du schéma de table entre les exécutions de requêtes entraînent l'échec de la requête programmée.

Les requêtes peuvent référencer des tables provenant de différents projets et de différents ensembles de données. Lors de la configuration de votre requête programmée, il n'est pas nécessaire d'ajouter l'ensemble de données de destination au nom de la table. L'ensemble de données de destination est à spécifier séparément.

Préférence d'écriture

L'option d'écriture que vous choisissez permet de déterminer la manière dont les résultats de votre requête sont écrits sur une table de destination existante.

• WRITE_TRUNCATE : si la table existe, BigQuery écrase les données de la table.
• WRITE_APPEND : si la table existe, BigQuery ajoute les données à la table.

Si vous utilisez une requête LDD ou LMD :

• Dans Cloud Console, l'option de préférence d'écriture ne s'affiche pas.
• Dans l'interface utilisateur Web classique de BigQuery, laissez la préférence d'écriture vide.

Une table de destination est créée, écrasée ou modifiée seulement dans le cas où BigQuery est en mesure d'exécuter correctement la requête. Ces actions de création, d'écrasement ou d'ajout prennent la forme d'une mise à jour atomique en fin de tâche.

Filtrage par cluster

Les requêtes programmées peuvent générer un clustering sur les nouvelles tables uniquement, lorsque la table est créée avec une instruction CREATE TABLE AS SELECT. Consultez la section Créer une table en cluster à partir d'un résultat de requête de la page Utiliser les instructions de langage de définition de données.

Options de partitionnement

Les requêtes programmées peuvent générer des tables de destination partitionnées ou non partitionnées. Le partitionnement n'est pas disponible dans Cloud Console, mais dans l'interface utilisateur Web classique de BigQuery, l'interface de ligne de commande et les méthodes de configuration de l'API. Si vous utilisez une requête LDD ou LMD avec partitionnement, laissez le champ de partitionnement vide.

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

• Tables partitionnées par temps d'ingestion : tables partitionnées en fonction de l'horaire d'exécution de la requête programmée
• Tables partitionnées en fonction d'une colonne : tables partitionnées en fonction d'une colonne TIMESTAMP ou DATE

Pour les tables partitionnées en fonction d'une colonne :

• Dans l'interface utilisateur Web classique de BigQuery, si la table de destination doit être partitionnée en fonction d'une colonne, vous devez spécifier le nom de la colonne dans le champ de partitionnement au moment de configurer la requête programmée. Pour les tables partitionnées par date d'ingestion et les tables non partitionnées, laissez le champ de partitionnement vide.

Pour les tables partitionnées par date d'ingestion :

• Indiquez le partitionnement de la date dans le nom de la table de destination. Reportez-vous à la syntaxe de modélisation de nom de table, expliquée ci-dessous.

Exemples de partitionnement

• Table sans partitionnement
  • Table de destination : mytable
  • Champ de partitionnement : laisser vide
• Table partitionnée par date d'ingestion
  • Table de destination : mytable$YYYYMMDD
  • Champ de partitionnement : laisser vide
• Table partitionnée en colonnes
  • Table de destination : mytable
  • Champ de partitionnement : nom de la colonne TIMESTAMP ou DATE utilisée pour partitionner la table

Paramètres disponibles

Lors de la configuration de la requête programmée, vous pouvez définir la manière dont vous souhaitez partitionner la table de destination avec des 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 la requête programmée est définie sur "toutes les 24 heures", la différence de run_time entre deux requêtes consécutives sera exactement de 24 heures, même si le temps d'exécution réel peut varier légèrement. Consultez 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 requêtes programmées supportent les paramètres d'exécution dans le nom de la table de destination avec 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	Objectif
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|"%H%M%s"}	20180215_mytable_000137

Utiliser un compte de service

Remarque : L'utilisation des comptes de service avec des requêtes programmées est en version bêta.

Vous pouvez configurer une requête programmée pour l'authentification avec un compte de service. Un compte de service est un compte Google associé à votre projet Google Cloud. Le compte de service peut exécuter des tâches associées à ses propres identifiants de service, plutôt qu'aux identifiants de l'utilisateur final (par exemple, pour exécuter un pipeline de traitement par lot ou une requête programmée).

Pour en savoir plus sur l'authentification avec des comptes de service, consultez la page Présentation de l'authentification.

• Vous avez la possibilité de configurer la requête programmée avec un compte de service sous Configurer une requête programmée dans Options avancées.

• Vous pouvez mettre à jour une requête programmée existante avec les identifiants d'un compte de service à l'aide de l'interface de ligne de commande. Consultez la section Mettre à jour les identifiants d'une requête programmée.

• La mise à jour d'une requête programmée pour qu'elle utilise des identifiants de compte de service n'est pas disponible pour le moment dans l'UI Web de BigQuery.

• La création ou la mise à jour de requêtes programmées pour qu'elles utilisent des comptes de service n'est pas disponible dans l'UI Web classique.

Configurer une requête programmée

Console

1. Ouvrez l'UI Web de BigQuery dans Cloud Console.

   Accéder à Cloud Console

2. Exécutez la requête de votre choix. Lorsque vous êtes satisfait de vos résultats, cliquez sur Schedule Query (Programmer la requête) et sur Créer une requête programmée.

   

3. Les options de requête programmées s'ouvrent dans le volet New scheduled query (Nouvelle requête programmée).

4. Dans le volet New scheduled query (Nouvelle requête programmée) :

   • Sous Name for the scheduled query (Nom de la requête programmée), saisissez un nom, tel que My scheduled query. Le nom de la requête programmée peut être n'importe quelle valeur vous permettant d'identifier facilement la requête programmée si vous devez la modifier ultérieurement.

   • (Facultatif) Sous Schedule options (Options de programmation), vous pouvez conserver la valeur par défaut Daily (Tous les jours, soit toutes les 24 heures en fonction de l'heure de création) ou cliquer sur Schedule start time (Programmer une heure de début) pour modifier l'heure d'exécution. Vous pouvez également modifier l'intervalle d'exécution et le définir sur "Toutes les semaines", "Tous les mois" ou "Personnalisé". Lorsque vous sélectionnez Custom (Personnalisé), vous devez ajouter une spécification temporelle de type Cron, par exemple every 3 hours. La période la plus courte autorisée est de 15 minutes. Consultez les informations concernant le champ schedule dans la section TransferConfig pour découvrir d'autres valeurs d'API valides.

     

5. Pour une requête SELECT SQL standard, fournissez les informations concernant l'ensemble de données de destination.

   • Sous Dataset name (Nom de l'ensemble de données), sélectionnez l'ensemble de données de destination.
   • Sous Table name (Nom de la table), entrez le nom de la table de destination.
   • Pour une requête LDD ou LMD, cette option n'est pas affichée.

6. Sous Destination table write preference (Préférence d'écriture pour la table de destination), choisissez WRITE_TRUNCATE pour remplacer la table de destination ou WRITE_APPEND pour ajouter des données à la table.

   • Pour une requête LDD ou LMD, cette option n'est pas affichée.

   

7. (Facultatif) Options avancées  :

   • (Facultatif) CMEK : Si vous utilisez des clés de chiffrement gérées par le client, vous pouvez sélectionner Customer-managed key (Clé gérée par le client) sous Advanced options (Options avancées). La liste des clés CMEK disponibles s'affiche.

   • (Facultatif) Authentification avec un compte de service : Si un ou plusieurs comptes de service sont associés à votre projet GCP, vous pouvez en associer un à votre requête programmée plutôt que d'utiliser vos propres identifiants. Sous Scheduled query credential (Identifiants de requête programmée), cliquez sur le menu pour afficher la liste de vos comptes de service disponibles.

     

8. Configurations supplémentaires :

   • (Facultatif) Cochez la case Send email notifications (Envoyer des notifications par e-mail) pour autoriser les notifications par e-mail en cas d'échec de l'exécution des transferts.

   • Pour les requêtes LDD/LMD, choisissez la région ou l'emplacement de traitement dans le champ Processing location (emplacement de traitement).

   • (Facultatif) Pour le champ Cloud Pub/Sub topic (Sujet Cloud Pub/Sub), saisissez le nom de votre sujet (par exemple, projects/myproject/topics/mytopic).

     

9. Cliquez sur le bouton Schedule (Programmer).

UI classique

1. Accédez à l'UI Web classique de BigQuery.

   Accéder à l'UI Web de BigQuery

2. Exécutez la requête de votre choix.

   

3. Lorsque vous êtes satisfait de vos résultats, cliquez sur Programmer une requête. Les options de requête programmées s'ouvrent sous la zone de requête.

4. Sur la page Nouvelle requête programmée :

   • Pour Destination dataset (Ensemble de données de destination), sélectionnez l'ensemble de données approprié.
   • Pour Display name (Nom à afficher), saisissez un nom pour la requête programmée, tel que My scheduled query. Le nom de la requête programmée peut être n'importe quelle valeur vous permettant d'identifier facilement la requête programmée si vous devez la modifier ultérieurement.
   • Pour Destination table (Table de destination) :
     • Pour une requête SQL standard, saisissez le nom de la table de destination.
     • Pour une requête LDD ou LMD, laissez ce champ vide.
   • Pour Write preference (Préférence d'écriture) :
     • Pour une requête SQL standard, choisissez WRITE_TRUNCATE pour écraser la table de destination ou WRITE_APPEND pour ajouter des données à la table.
     • Pour une requête LDD ou LMD, choisissez Unspecified (Non spécifié).

   • (Facultatif) Pour Partitioning field (Champ de partitionnement) :

     • Pour une requête SQL standard, si la table de destination est une table partitionnée en colonnes, saisissez le nom de la colonne où la table doit être partitionnée. Laissez ce champ vide pour les tables partitionnées par date d'ingestion et les tables non partitionnées.
     • Pour une requête LDD ou LMD, laissez ce champ vide.

   • (Facultatif) Pour Destination table KMS key (Clé du service de gestion des clés de la table de destination), si vous utilisez des clés de chiffrement gérées par le client, vous pouvez sélectionner Customer-managed key (Clé gérée par le client) ici.

     

   • (Facultatif) Pour Schedule (Programmation), vous pouvez conserver la valeur par défaut Daily (toutes les 24 heures, en fonction de l'heure de création) ou cliquer sur Edit (Modifier) pour modifier l'heure d'exécution. Vous pouvez également modifier l'intervalle d'exécution et le définir sur "Toutes les semaines", "Tous les mois" ou "Personnalisé". Lorsque vous sélectionnez Custom (Personnalisé), vous devez ajouter une spécification temporelle de type Cron, par exemple every 3 hours. La période la plus courte autorisée est de quinze minutes. Consultez les informations concernant le champ schedule dans la section TransferConfig pour découvrir d'autres valeurs d'API valides.

     

   • (Facultatif) Développez la section Advanced (Avancé), puis configurez les notifications.

     • (Facultatif) Pour le champ Cloud Pub/Sub topic (Sujet Cloud Pub/Sub), saisissez le nom de votre sujet (par exemple, projects/myproject/topics/mytopic).

     • Cochez la case Send email notifications (Envoyer des notifications par e-mail) pour autoriser les notifications par e-mail en cas d'échec de l'exécution des transferts.

       

5. Cliquez sur Ajouter.

bq

Il existe deux façons de planifier une requête par interface de ligne de commande. Avec l'option 2, vous pouvez planifier la requête avec davantage d'options.

Option 1 : Utilisez la commande bq query.

Cette méthode vous permet d'ajouter les options destination_table (ou target_dataset), --schedule et --display_name à votre commande bq query pour créer une requête programmée.

bq query \
--display_name=name \
--destination_table=table \
--schedule=interval

Remplacez l'élément suivant :

• name. Nom de la requête programmée à afficher. Le nom à afficher peut être n'importe quelle valeur vous permettant d'identifier facilement la requête programmée si vous devez la modifier ultérieurement.
• table. La table de destination des résultats de la requête.
  • --target_dataset est un autre moyen de nommer l'ensemble de données cible pour les résultats de la requête, en cas d'utilisation avec des requêtes LDD/LMD.
  • Utilisez --destination_table ou --target_dataset, mais pas les deux.
• interval. En cas d'utilisation avec bq query, définit une requête programmée récurrente. La fréquence programmée d'exécution de la requête est requise. Exemples :
  • --schedule='every 24 hours'
  • --schedule='every 3 hours'

Indicateurs facultatifs :

• --project_id est l'ID de votre projet. Si --project_id n'est pas spécifié, le projet par défaut est utilisé.

• --replace tronque la table de destination et écrit de nouveaux résultats à chaque exécution de la requête programmée.

• --append_table ajoute les résultats à la table de destination.

Si ni "--replace" ni "--append_table" n'est spécifié lors de la programmation de la requête, aucune préférence d'écriture n'est définie. Selon la requête, cela pourrait entraîner une erreur lors des exécutions programmées suivantes.

Par exemple, la commande suivante crée une requête programmée nommée My Scheduled Query à l'aide de la requête simple SELECT 1 from mydataset.test. La table de destination est mytable dans l'ensemble de données mydataset. La requête programmée est créée dans le projet par défaut :

    bq query \
    --use_legacy_sql=false \
    --destination_table=mydataset.mytable \
    --display_name='My Scheduled Query' \
    --replace=true \
    'SELECT
      1
    FROM
      mydataset.test'

Option 2 : Utilisez la commande bq mk.

Les requêtes programmées sont une sorte de transfert. Pour planifier une requête, vous pouvez utiliser l'interface de ligne de commande du service de transfert de données BigQuery pour créer une configuration de transfert.

Pour être programmées, les requêtes doivent être en SQL standard.

Saisissez la commande bq mk, puis spécifiez l'option de création de transfert --transfer_config. Les options suivantes sont également requises :

• --data_source
• --target_dataset (facultatif pour les requêtes LDD/LMD)
• --display_name
• --params

Indicateurs facultatifs :

• --project_id est l'ID de votre projet. Si --project_id n'est pas spécifié, le projet par défaut est utilisé.

• --schedule correspond à la fréquence d'exécution de la requête. Si --schedule n'est pas indiqué, la valeur par défaut est de toutes les 24 heures à partir de l'heure de création.

• Pour les requêtes LDD/LMD, vous pouvez également fournir l'option --location pour spécifier une région particulière de traitement. Si --location n'est pas spécifié, l'emplacement Google Cloud global est utilisé.

• --service_account_name permet d'authentifier votre requête programmée avec un compte de service plutôt qu'avec votre compte utilisateur individuel. Remarque : L'utilisation des comptes de service avec des requêtes programmées est en version bêta.

bq mk \
--transfer_config \
--project_id=project_id \
--target_dataset=dataset \
--display_name=name \
--params='parameters' \
--data_source=data_source

Remplacez l'élément suivant :

• dataset. Ensemble de données cible pour la configuration de transfert.
  • Ce paramètre est facultatif pour les requêtes LDD/LMD. Il est obligatoire pour toutes les autres requêtes.
• name. Nom à afficher pour la configuration de transfert. Le nom à afficher peut être n'importe quelle valeur permettant d'identifier facilement la requête programmée (transfert) si vous devez la modifier ultérieurement.
• parameters. Contient les paramètres de la configuration de transfert créée au format JSON. Exemple : --params='{"param":"param_value"}'.
  • Pour une requête programmée, vous devez fournir le paramètre query.
  • Le paramètre destination_table_name_template est le nom de votre table de destination.
    • Ce paramètre est facultatif pour les requêtes LDD/LMD. Il est obligatoire pour toutes les autres requêtes.
  • Pour le paramètre write_disposition, vous pouvez choisir WRITE_TRUNCATE pour tronquer (écraser) la table de destination ou WRITE_APPEND pour ajouter les résultats de la requête à la table de destination.
    • Ce paramètre est facultatif pour les requêtes LDD/LMD. Il est obligatoire pour toutes les autres requêtes.
  • (Facultatif) Le paramètre destination_table_kms_key concerne les clés de chiffrement gérées par le client.
  • (Facultatif) Le paramètre --service_account_name permet l'authentification avec un compte de service plutôt qu'avec un compte utilisateur individuel.
• data_source. La source de données : scheduled_query.

Remarque : Pour écrire les résultats dans une table partitionnée par date d'ingestion, reportez-vous aux instructions de la section Table de destination. Une requête programmée échoue si vous créez une configuration de transfert avec le paramètre destination_table_name_template défini sur une table partitionnée par date d'ingestion, tout en générant une erreur si vous définissez le paramètre partitioning_field avec un partitionnement par date d'ingestion.

Remarque : Actuellement, vous ne pouvez pas configurer de notifications à l'aide de l'outil de ligne de commande.

Par exemple, la commande suivante crée une configuration de transfert de requête programmée nommée My Scheduled Query avec la requête simple SELECT 1 from mydataset.test. La table de destination mytable est tronquée à chaque écriture et l'ensemble de données cible est mydataset. La requête programmée est créée dans le projet par défaut et s'authentifie avec un compte de service :

bq mk \
--transfer_config \
--target_dataset=mydataset \
--display_name='My Scheduled Query' \
--params='{"query":"SELECT 1 from mydataset.test","destination_table_name_template":"mytable","write_disposition":"WRITE_TRUNCATE"}' \
--data_source=scheduled_query \
--service_account_name=[e-mail]

La première fois que vous exécutez la commande, vous recevez un message de ce type :

[URL omitted] Please copy and paste the above URL into your web browser and follow the instructions to retrieve an authentication code.

Suivez les instructions du message et collez le code d'authentification sur la ligne de commande.

API

Utilisez la méthode projects.locations.transferConfigs.create et fournissez une instance de la ressource TransferConfig.

Python

Avant d'essayer l'exemple ci-dessous, suivez la procédure de configuration pour Python décrite dans le guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery en langage Python.

Afficher sur GitHub Commentaires

from google.cloud import bigquery_datatransfer_v1
import google.protobuf.json_format

client = bigquery_datatransfer_v1.DataTransferServiceClient()

# TODO(developer): Set the project_id to the project that contains the
#                  destination dataset.
# project_id = "your-project-id"

# TODO(developer): Set the destination dataset. The authorized user must
#                  have owner permissions on the dataset.
# dataset_id = "your_dataset_id"

# TODO(developer): The first time you run this sample, set the
# authorization code to a value from the URL:
# https://www.gstatic.com/bigquerydatatransfer/oauthz/auth?client_id=433065040935-hav5fqnc9p9cht3rqneus9115ias2kn1.apps.googleusercontent.com&scope=https://www.googleapis.com/auth/bigquery%20https://www.googleapis.com/auth/drive&redirect_uri=urn:ietf:wg:oauth:2.0:oob
#
# authorization_code = "_4/ABCD-EFGHIJKLMNOP-QRSTUVWXYZ"
#
# You can use an empty string for authorization_code in subsequent runs of
# this code sample with the same credentials.
#
# authorization_code = ""

# Use standard SQL syntax for the query.
query_string = """
SELECT
  CURRENT_TIMESTAMP() as current_time,
  @run_time as intended_run_time,
  @run_date as intended_run_date,
  17 as some_integer
"""

parent = client.project_path(project_id)

transfer_config = google.protobuf.json_format.ParseDict(
    {
        "destination_dataset_id": dataset_id,
        "display_name": "Your Scheduled Query Name",
        "data_source_id": "scheduled_query",
        "params": {
            "query": query_string,
            "destination_table_name_template": "your_table_{run_date}",
            "write_disposition": "WRITE_TRUNCATE",
            "partitioning_field": "",
        },
        "schedule": "every 24 hours",
    },
    bigquery_datatransfer_v1.types.TransferConfig(),
)

response = client.create_transfer_config(
    parent, transfer_config, authorization_code=authorization_code
)

print("Created scheduled query '{}'".format(response.name))

Afficher l'état d'une requête programmée

UI Web

Pour afficher l'état de vos requêtes programmées, cliquez sur Scheduled queries (Requêtes programmées) dans le volet de navigation. Actualisez la page pour afficher l'état actualisé de vos requêtes programmées. Cliquez sur une requête programmée pour en savoir plus sur celle-ci.

UI classique

Pour afficher l'état de vos requêtes programmées, cliquez sur Scheduled queries (Requêtes programmées) dans le volet de navigation. Actualisez la page pour afficher l'état actualisé de vos requêtes programmées. Cliquez sur une requête programmée pour en savoir plus sur celle-ci.

bq

Les requêtes programmées sont une sorte de transfert. Pour afficher les détails d'une requête programmée, vous pouvez tout d'abord utiliser l'interface de ligne de commande du service de transfert de données BigQuery pour répertorier vos configurations de transfert.

Saisissez la commande bq ls, puis spécifiez l'option de transfert --transfer_config. Les options suivantes sont également requises :

• --transfer_location

Exemple :

bq ls \
--transfer_config \
--transfer_location=us \

Pour afficher les détails d'une seule requête programmée, saisissez la commande bq show et indiquez le transfer_path de cette requête programmée/configuration de transfert.

Exemple :

bq show \
--transfer_config \
projects/862514376110/locations/us/transferConfigs/5dd12f26-0000-262f-bc38-089e0820fe38 \

API

Utilisez la méthode projects.locations.transferConfigs.list et fournissez une instance de la ressource TransferConfig.

Mettre à jour les identifiants d'une requête programmée

UI Web

Pour mettre à jour les identifiants existants d'une requête programmée, procédez comme suit :

1. Recherchez et affichez l'état d'une requête programmée.

2. Cliquez sur le bouton MORE (Plus), puis sélectionnez Update credentials (Mettre à jour les identifiants).

   

Le remplacement des identifiants utilisés dans une requête programmée par des identifiants de compte de service n'est pas disponible pour le moment dans l'UI Web.

UI classique

1. Recherchez et affichez l'état d'une requête programmée.

2. Cliquez sur une requête programmée de la liste. Le bouton Update credentials (Mettre à jour les identifiants) s'affiche alors sous les détails de cette requête programmée.

   

bq

Les requêtes programmées sont une sorte de transfert. Pour mettre à jour les identifiants d'une requête programmée, vous pouvez utiliser l'interface de ligne de commande du service de transfert de données BigQuery afin de mettre à jour la configuration de transfert.

Saisissez la commande bq update, puis spécifiez l'option de transfert --transfer_config. Les options suivantes sont également requises :

• --update_credentials

Option facultative :

• --service_account_name permet d'authentifier votre requête programmée avec un compte de service plutôt qu'avec votre compte utilisateur individuel.

Remarque : L'utilisation des comptes de service avec des requêtes programmées est en version bêta.

Par exemple, la commande suivante met à jour la configuration de transfert d'une requête programmée pour qu'elle s'authentifie avec un compte de service :

bq update \
--transfer_config \
--update_credentials \
--service_account_name=[e-mail] projects/862514376110/locations/us/transferConfigs/5dd12f26-0000-262f-bc38-089e0820fe38 \

Configurer une requête manuelle en fonction de dates de l'historique

En plus de la programmation de l'exécution ultérieure d'une requête, vous pouvez également déclencher des exécutions immédiates manuellement. Le déclenchement d'une exécution immédiate est nécessaire si votre requête utilise le paramètre run_date et qu'il existe des problèmes lors d'une exécution précédente.

Par exemple, tous les jours à 09h00, vous interrogez une table source sur les lignes correspondant à la date du jour. Cependant, vous constatez que les données n'ont pas été ajoutées à la table source au cours des trois derniers jours. Dans ce cas, vous pouvez configurer la requête pour qu'elle s'exécute sur des données historiques dans une plage de dates que vous spécifiez. Votre requête est exécutée en utilisant des combinaisons de run_date et run_time correspondant aux dates que vous avez configurées dans votre requête programmée.

Après avoir configuré une requête programmée, vous pouvez l'exécuter en utilisant une plage de dates historique en procédant comme suit :

Console

Après avoir cliqué sur Programmer pour enregistrer votre requête programmée, vous pouvez cliquer sur le bouton Requêtes programmées pour afficher la liste des requêtes actuellement programmées. Cliquez sur n'importe quel nom pour afficher les détails de programmation de cette requête. En haut à droite de la page, cliquez sur Schedule backfill (Programmer le remplissage) pour spécifier une plage de dates historique.

Les durées d'exécution choisies sont comprises dans la plage sélectionnée, y compris la première date et à l'exclusion de la dernière date.

Les plages de dates que vous fournissez sont affichées au format UTC, mais la programmation de votre requête est affichée dans votre fuseau horaire local (voir l'exemple 2 ci-dessous pour résoudre ce problème).

Vous pouvez utiliser l'UI Web classique pour éviter cet écart de fuseau horaire et pour définir des limites de temps plus précises.

Exemple 1

Votre requête programmée est configurée pour s'exécuter selon l'heure du Pacifique every day 09:00. Il vous manque des données pour le 1er, le 2 et le 3 janvier. Choisissez la plage de dates historique suivante :

Start Time = 1/1/19
End Time = 1/4/19

Votre requête s'exécute avec les paramètres run_date et run_time correspondant aux heures suivantes :

• 1/1/19 09:00 (Heure du Pacifique)
• 1/2/19 09:00 (Heure du Pacifique)
• 1/3/19 09:00 (Heure du Pacifique)

Exemple 2

Votre requête programmée est configurée pour s'exécuter selon l'heure du Pacifique every day 23:00. Il vous manque des données pour le 1er, le 2 et le 3 janvier. Choisissez les plages de dates historiques suivantes (les dates ultérieures sont choisies, car UTC a une date différente à 23h00, heure du Pacifique) :

Start Time = 1/2/19
End Time = 1/5/19

Votre requête s'exécute avec les paramètres run_date et run_time correspondant aux heures suivantes :

• 1/2/19 09:00 (UTC) ou 1/1/2019 23:00 (Heure du Pacifique)
• 1/3/19 09:00 (UTC) ou 1/2/2019 23:00 (Heure du Pacifique)
• 1/4/19 09:00 (UTC) ou 1/3/2019 23:00 (Heure du Pacifique)

Après avoir configuré les exécutions manuelles, actualisez la page pour les afficher dans la liste des exécutions.

UI classique

Une fois que vous avez cliqué sur Ajouter pour enregistrer votre requête programmée, les détails de la requête s'affichent. Sous les détails, cliquez sur le bouton Start Manual Runs (Démarrer les exécutions manuelles) pour spécifier une plage de dates historique.

Vous pouvez affiner davantage la plage de dates pour définir une heure de début et de fin, ou laisser les champs de l'heure à 00:00:00.

Exemple 1

Si votre requête programmée est définie pour s'exécuter every day 14:00 et que vous appliquez la plage de dates de l'historique suivante :

Start Time = 2/21/2018 00:00:00 AM
End Time = 2/24/2018 00:00:00 AM

Votre requête s'exécute aux heures suivantes :

• 2/21/2018 14:00:00
• 2/22/2018 14:00:00
• 2/23/2018 14:00:00

Exemple 2

Si votre requête programmée est définie pour s'exécuter every fri at 01:05 et que vous appliquez la plage de dates de l'historique suivante :

Start Time = 2/1/2018 00:00:00 (un jeudi)
End Time = 2/24/2018 00:00:00 AM (également un jeudi)

Votre requête s'exécute aux heures suivantes :

• 2/2/2018 01:05:00
• 2/9/2018 01:05:00

bq

Pour exécuter manuellement la requête sur une plage de dates historique :

Entrez la commande bq mk et fournissez l'option d'exécution de transfert --transfer_run. Les options suivantes sont également requises :

• --start_time
• --end_time

bq mk \
--transfer_run \
--start_time='start_time' \
--end_time='end_time' \
resource_name

Remplacez l'élément suivant :

• start_time et end_time. Horodatages se terminant par Z ou contenant un décalage de fuseau horaire valide. Exemples :
  • 2017-08-19T12:11:35.00Z
  • 2017-05-25T00:00:00+00:00
• resource_name. Nom de ressource de la requête programmée (ou du transfert). Le nom de ressource est également appelé configuration de transfert.

Par exemple, la commande suivante programme un remplissage pour une ressource de requête programmée (ou une configuration de transfert) : projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7.

  bq mk \
  --transfer_run \
  --start_time 2017-05-25T00:00:00Z \
  --end_time 2017-05-25T00:00:00Z \
  projects/myproject/locations/us/transferConfigs/1234a123-1234-1a23-1be9-12ab3c456de7

API

Exécutez la méthode projects.locations.transferConfigs.scheduleRun et fournissez le chemin d'accès à la ressource TransferConfig.

Quotas

Une requête programmée est exécutée en fonction du projet et des identifiants du créateur, comme si vous exécutiez vous-même la requête. Une requête programmée est soumise aux mêmes quotas et restrictions BigQuery que les requêtes manuelles.

Tarifs

Les prix des requêtes programmées sont les mêmes que pour les requêtes BigQuery.

Limites et problèmes connus

Régions

Les requêtes inter-régions ne sont pas prises en charge et la table de destination de votre requête programmée doit se trouver dans la même région que les données interrogées. Veuillez consulter la page Zones des ensembles de données pour plus d'informations sur les régions et les zones multirégionales.

Drive

Vous pouvez interroger les données Drive dans une requête programmée. Si vous programmez une requête existante, vous devrez peut-être cliquer sur Update Credentials (Mettre à jour les informations d'identification) sur l'écran de détails de la requête programmée. Attendez 10 à 20 minutes pour que la modification soit prise en compte. Vous devrez peut-être vider le cache de votre navigateur. Les identifiants sont automatiquement mis à jour pour les nouvelles requêtes programmées.