Planifier des requêtes
Cette page décrit comment programmer des requêtes récurrentes dans BigQuery.
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). Vous pouvez organiser les résultats de la requête par date et heure en paramétrant la chaîne de requête et la table de destination.
Lorsque vous créez ou mettez à jour la programmation d'une requête, l'heure programmée pour la requête est convertie de votre heure locale en heure UTC. L'heure UTC n'est pas affectée par l'heure d'été.
Avant de commencer
- 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.
- Attribuez aux utilisateurs des rôles IAM (Identity and Access Management) incluant les autorisations nécessaires pour effectuer l'ensemble des tâches du présent document.
Autorisations requises
Pour planifier une requête, vous devez disposer des autorisations IAM suivantes :
Pour créer le transfert, vous devez disposer de l'autorisation
bigquery.transfers.update
ou des autorisationsbigquery.jobs.create
etbigquery.transfers.get
.Pour exécuter une requête programmée, vous devez disposer des autorisations
bigquery.jobs.create
etbigquery.datasets.update
sur l'ensemble de données cible.
Pour modifier une requête programmée, vous devez disposer des autorisations IAM suivantes :
bigquery.jobs.create
bigquery.transfers.update
Pour supprimer une requête programmée, vous devez disposer des autorisations IAM suivantes :
bigquery.transfers.update
Le rôle IAM prédéfini roles/bigquery.admin
inclut les autorisations nécessaires pour programmer ou modifier une requête.
Pour en savoir plus sur les rôles IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.
Pour créer ou mettre à jour des requêtes planifiées exécutées par un compte de service, vous devez avoir accès à ce compte de service. Pour plus d'informations sur l'attribution du rôle de compte de service aux utilisateurs, consultez la section Rôle Utilisateur du compte de service. Pour sélectionner un compte de service dans l'UI de requête programmée de Cloud Console, vous devez disposer des autorisations IAM suivantes :
iam.serviceAccounts.list
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'outil de ligne de commande bq
.
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
Si la table de destination de vos résultats n'existe pas lors de la configuration de la requête programmée, BigQuery tentera de créer la table pour vous.
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.
Si la table de destination existe, BigQuery peut mettre à jour le schéma de la table de destination en fonction des résultats de la requête. Pour ce faire, ajoutez des colonnes à l'aide de ALLOW_FIELD_ADDITION
ou assouplissez le mode d'une colonne en passant de REQUIRED
à NULLABLE
à l'aide de ALLOW_FIELD_RELAXATION
.
Sinon, 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.
L'ensemble de données et la table de destination d'une requête planifiée doivent se trouver dans le même projet que la requête planifiée.
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, vous ne pouvez pas utiliser l'option de préférence d'écriture.
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.
Clustering
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 est disponible dans les méthodes de configuration de Cloud Console, de l'outil de ligne de commande bq
et de l'API. Si vous utilisez une requête LDD ou LMD avec partitionnement, laissez le champ de partitionnement de la table de destination vide.
Il existe deux types de tables partitionnées dans BigQuery :
- Tables partitionnées par date 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
ouDATE
.
Pour les tables partitionnées sur une colonne, dans Cloud Console, spécifiez le nom de la colonne dans le champ de partitionnement de la table de destination lorsque vous configurez une requête programmée.
Pour les tables partitionnées par date d'ingestion, laissez le champ de partitionnement de la table de destination vide et indiquez le partitionnement de la date dans le nom de la table de destination. Pour en savoir plus, consultez la section Syntaxe des paramètres de modélisation.
Exemples de partitionnement
- Table sans partitionnement
- Table de destination :
mytable
- Champ de partitionnement : laisser vide
- Table de destination :
- Table partitionnée par date d'ingestion
- Table de destination :
mytable_{run_date}
- Champ de partitionnement : laisser vide
- Table de destination :
- Table partitionnée en colonnes
- Table de destination :
mytable
- Champ de partitionnement : nom de la colonne
TIMESTAMP
ouDATE
utilisée pour partitionner la table
- Table de destination :
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 2018-01-01 . 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 :
|
- 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 |
Utiliser un compte de service
Vous pouvez configurer une requête programmée pour l'authentification comme 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, telles que des requêtes programmées ou des pipelines de traitement par lot, avec ses propres identifiants de service plutôt que ceux d'un utilisateur final.
Pour en savoir plus sur l'authentification avec des comptes de service, consultez la page Présentation de l'authentification.
Vous pouvez configurer la requête programmée avec un compte de service à l'aide des 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'outil de ligne de commande
bq
. Pour en savoir plus, 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 actuellement pas disponible dans Cloud Console.
Configurer des requêtes programmées
Pour obtenir une description de la syntaxe de programmation, consultez la section Mettre en forme l'élément schedule.
Console
Ouvrez la page BigQuery dans Cloud Console.
Exécutez la requête de votre choix. Lorsque vous êtes satisfait de vos résultats, cliquez sur Programmer et sur Créer une requête programmée.
Les options de requête programmées s'ouvrent dans le volet Nouvelle requête programmée.
Dans le volet New scheduled query (Nouvelle requête programmée) :
- Sous 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 toute valeur que vous pouvez identifier ultérieurement si vous devez modifier la requête. Facultatif : Par défaut, la requête est exécutée tous les jours. Vous pouvez modifier les options de programmation par défaut comme suit :
- Pour modifier la fréquence, modifiez l'option Repeats (Périodicité) de Daily (Tous les jours) à la fréquence souhaitée. Pour spécifier une fréquence personnalisée, sélectionnez Custom (Personnalisée), puis saisissez une spécification temporelle de type Cron dans le champ Custom schedule (Programmation personnalisée). Par exemple :
every 3 hours
. La période la plus courte autorisée est de 15 minutes. Consultez le champschedule
sousTransferConfig
pour obtenir une description des valeurs valides. Pour modifier l'heure de début, sélectionnez l'option Select start time (Sélectionner l'heure de début), saisissez la date et l'heure de début souhaitées, puis enregistrez votre modification.
Pour spécifier une heure de fin, sélectionnez l'option Select end time (Sélectionner une heure de fin), saisissez la date et l'heure de fin souhaitées, puis enregistrez votre modification.
Pour enregistrer la requête sans programmation afin de pouvoir l'exécuter à la demande ultérieurement, sélectionnez l'option On Demand (À la demande) comme valeur pour Repeats (Périodicité).
- Pour modifier la fréquence, modifiez l'option Repeats (Périodicité) de Daily (Tous les jours) à la fréquence souhaitée. Pour spécifier une fréquence personnalisée, sélectionnez Custom (Personnalisée), puis saisissez une spécification temporelle de type Cron dans le champ Custom schedule (Programmation personnalisée). Par exemple :
- Sous Nom de la requête programmée, saisissez un nom, tel que
Pour une requête
SELECT
en SQL standard, sélectionnez l'option Définir une table de destination pour les résultats de la requête et fournissez les informations suivantes sur 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.
- Sous Préférence d'écriture pour la table de destination, choisissez Ajouter à la table pour ajouter les données à la table ou Écraser la table pour écraser la table de destination.
Pour les requêtes LDD et LMD, choisissez la région ou l'emplacement de traitement dans le champ Emplacement de traitement.
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 Google Cloud, vous pouvez associer un compte de service à votre requête programmée plutôt que d'utiliser vos identifiants utilisateur. Sous Identifiants de requête programmée, cliquez sur le menu pour afficher la liste des comptes de service disponibles.
Configurations supplémentaires :
Facultatif : Cochez la case Envoyer des notifications par e-mail pour autoriser les notifications par e-mail en cas d'échec de l'exécution des transferts.
Facultatif : Pour le champ Sujet Cloud Pub/Sub, saisissez le nom de votre sujet (par exemple,
projects/myproject/topics/mytopic
).
Cliquez sur le bouton Schedule (Programmer).
bq
Option 1 : Utilisez la commande bq query
.
Pour créer une requête programmée, ajoutez les options destination_table
(ou target_dataset
), --schedule
et --display_name
à votre commande bq query
.
bq query \ --display_name=name \ --destination_table=table \ --schedule=interval
Remplacez les éléments suivants :
name
. Le nom de la requête programmée à afficher. Le nom à afficher peut être toute valeur que vous pouvez identifier ultérieurement si vous devez modifier la requête.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 et LMD.- Utilisez
--destination_table
ou--target_dataset
, mais pas les deux.
interval
. En cas d'utilisation avecbq 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.
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' \
--schedule='every 24 hours' \
--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'outil de ligne de commande bq
afin de créer une configuration de transfert.
Pour être programmées, les requêtes doivent être en SQL standard.
Saisissez la commande bq mk
et spécifiez les options requises suivantes :
--transfer_config
--data_source
--target_dataset
(facultatif pour les requêtes LDD et LMD)--display_name
--params
Options facultatives :
--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 et LMD, vous pouvez également définir 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.
bq mk \ --transfer_config \ --target_dataset=dataset \ --display_name=name \ --params='parameters' \ --data_source=data_source
Remplacez les éléments suivants :
dataset
. L'ensemble de données cible pour la configuration de transfert.- Ce paramètre est facultatif pour les requêtes LDD et LMD. Il est obligatoire pour toutes les autres requêtes.
name
. Le nom à afficher pour la configuration de transfert. Le nom à afficher peut être toute valeur que vous pouvez identifier ultérieurement si vous devez modifier la requête.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 et LMD. Il est obligatoire pour toutes les autres requêtes.
- Pour le paramètre
write_disposition
, vous pouvez choisirWRITE_TRUNCATE
pour tronquer (écraser) la table de destination ouWRITE_APPEND
pour ajouter les résultats de la requête à la table de destination.- Ce paramètre est facultatif pour les requêtes LDD et 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.
- Pour une requête programmée, vous devez fournir le paramètre
data_source
. La source de données :scheduled_query
.- Facultatif : Le paramètre
--service_account_name
permet l'authentification avec un compte de service plutôt qu'avec un compte utilisateur individuel.
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 comme 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=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com
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
.
Java
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Java.
Python
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
Configurer des requêtes programmées avec un compte de service
Java
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Java.
Python
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
Afficher l'état d'une requête programmée
Console
Pour afficher l'état de vos requêtes programmées, cliquez sur 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 afficher les détails.
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'outil de ligne de commande bq
afin de 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
.
Java
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Java.
Python
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
Mettre à jour les requêtes programmées
Console
Pour mettre à jour une requête programmée, procédez comme suit :
- Dans le volet de navigation, cliquez sur Requêtes programmées.
- Dans la liste des requêtes programmées, cliquez sur le nom de la requête que vous souhaitez modifier.
- Sur la page Détails de la requête programmée qui s'affiche, cliquez sur Modifier.
- Facultatif : modifiez le texte de la requête dans le volet de modification de la requête.
- Cliquez sur Schedule query (Programmer la requête), puis sélectionnez Update scheduled query (Mettre à jour la requête programmée).
- Facultatif : modifiez toute autre option de planification pour la requête.
- Cliquez sur Mettre à jour.
bq
Les requêtes programmées sont une sorte de transfert. Pour mettre à jour la requête programmée, vous pouvez utiliser l'outil de ligne de commande bq
afin de créer une configuration de transfert.
Saisissez la commande bq update
et spécifiez les options requises suivantes :
--transfer_config
--data_source
--target_dataset
(facultatif pour les requêtes LDD et LMD)--display_name
--params
Options facultatives :
--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 et LMD, vous pouvez également définir 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.
bq update \ --transfer_config \ --target_dataset=dataset \ --display_name=name \ --params='parameters'
Remplacez les éléments suivants :
dataset
. L'ensemble de données cible pour la configuration de transfert.- Ce paramètre est facultatif pour les requêtes LDD et LMD. Il est obligatoire pour toutes les autres requêtes.
name
. Le nom à afficher pour la configuration de transfert. Le nom à afficher peut être toute valeur que vous pouvez identifier ultérieurement si vous devez modifier la requête.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 et LMD. Il est obligatoire pour toutes les autres requêtes.
- Pour le paramètre
write_disposition
, vous pouvez choisirWRITE_TRUNCATE
pour tronquer (écraser) la table de destination ouWRITE_APPEND
pour ajouter les résultats de la requête à la table de destination.- Ce paramètre est facultatif pour les requêtes LDD et 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.
- Pour une requête programmée, vous devez fournir le paramètre
- Facultatif : Le paramètre
--service_account_name
permet l'authentification avec un compte de service plutôt qu'avec un compte utilisateur individuel.
Par exemple, la commande suivante met à jour 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
:
bq update \
--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"}' \
--service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com
API
Utilisez la méthode projects.transferConfigs.patch
et indiquez le nom de ressource du transfert à l'aide du paramètre transferConfig.name
. Si vous ne connaissez pas ce nom, exécutez la commande bq ls --transfer_config --transfer_location=location
pour afficher tous les transferts ou appelez la méthode projects.locations.transferConfigs.list
et indiquez l'ID de projet à l'aide du paramètre parent
.
Java
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Java.
Python
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
Mise à jour des identifiants d'une requête programmée
Si vous programmez une requête existante, il vous faudra peut-être mettre à jour les identifiants utilisateur de la requête. Les identifiants sont automatiquement mis à jour pour les nouvelles requêtes programmées.
Les situations suivantes peuvent également nécessiter la mise à jour des identifiants :
- Vous souhaitez interroger les données Drive dans une requête programmée.
Vous recevez une erreur INVALID_USER lorsque vous tentez de programmer la requête :
Error code 5 : Authentication failure: User Id not found. Error code: INVALID_USERID
Console
Pour mettre à jour les identifiants existants d'une requête programmée, procédez comme suit :
Recherchez et affichez l'état d'une requête programmée.
Cliquez sur le bouton MORE (Plus), puis sélectionnez Update credentials (Mettre à jour les identifiants).
Attendez 10 à 20 minutes pour que la modification soit prise en compte. Vous devrez peut-être vider le cache de votre navigateur.
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'outil de ligne de commande bq
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.
Par exemple, la commande suivante met à jour la configuration de transfert d'une requête programmée pour qu'elle s'authentifie comme compte de service :
bq update \
--transfer_config \
--update_credentials \
--service_account_name=abcdef-test-sa@abcdef-test.iam.gserviceaccount.com projects/862514376110/locations/us/transferConfigs/5dd12f26-0000-262f-bc38-089e0820fe38 \
Java
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Java.
Python
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
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 s'exécute avec des combinaisons de paramètres 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.
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 janvier, le 2 janvier 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 janvier, le 2 janvier 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 :
- 02/01/2019 06:00 (UTC) ou 01/01/2019 23:00 (Heure du Pacifique)
- 03/01/2019 06:00 (UTC) ou 02/01/2019 23:00 (Heure du Pacifique)
- 04/01/2019 06:00 (UTC) ou 03/01/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.
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
etend_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
Pour en savoir plus, consultez la page bq mk --transfer_run
.
API
Exécutez la méthode projects.locations.transferConfigs.scheduleRun et fournissez le chemin d'accès à la ressource TransferConfig.
Java
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Java.
Python
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
Supprimer des requêtes programmées
Console
Pour supprimer une requête programmée via la console :
Dans le volet de navigation, cliquez sur Requêtes programmées.
Dans la liste des requêtes programmées, cliquez sur le nom de la requête programmée que vous souhaitez supprimer.
Sur la page Détails de la requête programmée qui s'affiche, cliquez sur Supprimer.
Java
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Java.
Python
Pour savoir comment installer et utiliser la bibliothèque cliente pour BigQuery, consultez la page sur les bibliothèques clientes BigQuery. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery Python.
Quotas
Les requêtes programmées sont exécutées en fonction du projet et des identifiants du créateur, comme si vous exécutiez vous-même la requête.
Bien que les requêtes programmées utilisent des fonctionnalités du service de transfert de données BigQuery, il ne s'agit pas de transferts, et elles ne sont pas soumises au quota de tâches de chargement. Les requêtes programmées sont soumises aux mêmes quotas et limites BigQuery que les requêtes manuelles.
Tarifs
Les prix des requêtes programmées sont les mêmes que pour les requêtes BigQuery manuelles.
Régions où le service est disponible
Les requêtes programmées sont disponibles aux emplacements suivants.
Régions
Le tableau suivant répertorie les régions Amériques où BigQuery est disponible.Description de la région | Nom de la région | Détails |
---|---|---|
Iowa | us-central1 |
|
Las Vegas | us-west4 |
|
Los Angeles | us-west2 |
|
Montréal | northamerica-northeast1 |
|
Virginie du Nord | us-east4 |
|
Oregon | us-west1 |
|
Salt Lake City | us-west3 |
|
São Paulo | southamerica-east1 |
|
Santiago | southamerica-west1 |
|
Caroline du Sud | us-east1 |
|
Toronto | northamerica-northeast2 |
|
Description de la région | Nom de la région | Détails |
---|---|---|
Delhi | asia-south2 |
|
Hong Kong | asia-east2 |
|
Jakarta | asia-southeast2 |
|
Melbourne | australia-southeast2 |
|
Mumbai | asia-south1 |
|
Osaka | asia-northeast2 |
|
Séoul | asia-northeast3 |
|
Singapour | asia-southeast1 |
|
Sydney | australia-southeast1 |
|
Taïwan | asia-east1 |
|
Tokyo | asia-northeast1 |
Description de la région | Nom de la région | Détails |
---|---|---|
Belgique | europe-west1 |
|
Finlande | europe-north1 |
|
Francfort | europe-west3 |
|
Londres | europe-west2 |
|
Pays-Bas | europe-west4 |
|
Varsovie | europe-central2 |
|
Zurich | europe-west6 |
|
Emplacements multirégionaux
Le tableau suivant répertorie les emplacements multirégionaux où BigQuery est disponible.Description de la zone multirégionale | Nom de l'emplacement multirégional |
---|---|
Centres de données dans les États membres de l'Union européenne1 | EU |
Centres de données aux États-Unis | US |
1 Les données situées dans la zone multirégionale EU
ne sont pas stockées dans les centres de données des régions europe-west2
(Londres) ou europe-west6
(Zurich).
Étape suivante
- Pour obtenir un exemple de requête programmée qui utilise un compte de service et inclut les paramètres
@run_date
et@run_time
, consultez la page Créer des instantanés de table avec une requête programmée.