Explorer l'outil de ligne de commande bq
L'outil de ligne de commande bq est un outil de ligne de commande basé sur Python pour BigQuery. Cette page contient des informations générales sur l'utilisation de l'outil de ligne de commande bq.
Pour obtenir une explication complète de toutes les commandes et options de bq
, consultez la documentation de référence de l'outil de ligne de commande bq.
Avant de commencer
Avant de pouvoir utiliser l'outil de ligne de commande bq, vous devez utiliser Google Cloud Console pour créer ou sélectionner un projet.
- Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
- BigQuery est automatiquement activé dans les nouveaux projets.
Pour activer BigQuery dans un projet préexistant, accédez à
Enable the BigQuery API.
. - Facultatif : Activez la facturation pour le projet. Les étapes décrites dans ce document demeurent valables, même si vous ne souhaitez pas activer la facturation ou fournir une carte de crédit. BigQuery fournit un bac à sable permettant d'accomplir les étapes. Pour en savoir plus, consultez la page Activer le bac à sable BigQuery.
Saisir des commandes bq
dans Cloud Shell
Vous pouvez saisir des commandes de l'outil de ligne de commande bq dans Cloud Shell à partir de Google Cloud Console ou de Google Cloud CLI.
Pour utiliser l'outil de ligne de commande bq depuis la console Google Cloud, activez Cloud Shell :
Pour utiliser l'outil de ligne de commande bq de gcloud CLI, installez et configurez gcloud CLI.
Positionner les options et les arguments
L'outil de ligne de commande bq accepte deux types d'options :
- Les options globales peuvent être utilisées dans toutes les commandes.
- Les indicateurs spécifiques aux commandes s'appliquent à une commande spécifique.
Pour obtenir la liste des indicateurs globaux et spécifiques à la commande, consultez la documentation de référence de l'outil de ligne de commande bq.
Placez toutes les options globales avant la commande bq
, puis ajoutez les options spécifiques aux commandes. Vous pouvez inclure plusieurs options globales ou spécifiques aux commandes. Exemple :
bq --location=us mk --reservation --project_id=project reservation_name
Vous pouvez spécifier les arguments de la commande de l'une des manières suivantes :
--FLAG ARGUMENT
(comme illustré dans les exemples précédents)--FLAG=ARGUMENT
--FLAG='ARGUMENT'
--FLAG="ARGUMENT"
--FLAG 'ARGUMENT'
--FLAG "ARGUMENT"
Remplacez les éléments suivants :
FLAG
: option globale ou spécifique à une commandeARGUMENT
: argument de l'option
Certaines commandes nécessitent d'encadrer les arguments par des guillemets simples ou doubles. Cela est souvent vrai lorsque l'argument contient des espaces, des virgules ou d'autres caractères spéciaux. Exemple :
bq query --nouse_legacy_sql \ 'SELECT COUNT(*) FROM `bigquery-public-data`.samples.shakespeare'
Les indicateurs avec des valeurs booléennes peuvent être spécifiés sans argument. Si vous spécifiez true
ou false
, vous devez utiliser le format FLAG=ARGUMENT
.
Par exemple, cette commande spécifie "false" pour l'option booléenne --use_legacy_sql
en plaçant no
au début de l'option :
bq query --nouse_legacy_sql \ 'SELECT COUNT(*) FROM `bigquery-public-data`.samples.shakespeare'
Vous pouvez également spécifier false
comme argument de l'option en saisissant la commande suivante :
bq query --use_legacy_sql=false \ 'SELECT COUNT(*) FROM `bigquery-public-data`.samples.shakespeare'
Exécuter des requêtes à partir de l'outil de ligne de commande bq
Pour ajouter une requête que vous avez développée dans Google Cloud Console et l'exécuter dans l'outil de ligne de commande bq, procédez comme suit :
- Incluez la requête dans une commande
bq query
comme suit :bq query --use_legacy_sql=false 'QUERY'
. RemplacezQUERY
par la requête. - Remplacez tous les guillemets simples (
'
) dans la requête par des guillemets doubles ("
). Vérifiez que la requête est placée entre guillemets simples ('
). - Supprimez les commentaires de la requête.
Par exemple, transformez la requête Google Cloud Console suivante :
-- count Shakespeare's use of the string "raisin"
SELECT
word,
SUM(word_count) AS count
FROM
`bigquery-public-data`.samples.shakespeare
WHERE
word LIKE '%raisin%'
GROUP BY
word
dans une requête de l'outil de ligne de commande bq comme suit :
bq query --use_legacy_sql=false \
'SELECT
word,
SUM(word_count) AS count
FROM
`bigquery-public-data`.samples.shakespeare
WHERE
word LIKE "%raisin%"
GROUP BY
word'
Pour en savoir plus, consultez la page Exécuter des tâches de requête interactives et par lot.
Obtenir de l'aide
Pour obtenir de l'aide sur l'outil de ligne de commande bq, vous pouvez saisir les commandes suivantes :
- Pour connaître la version installée de l'outil de ligne de commande bq, saisissez
bq version
. - Pour obtenir la liste complète des commandes, saisissez
bq help
. - Pour obtenir la liste des options globales, saisissez
bq --help
. - Pour obtenir de l'aide sur une commande spécifique, saisissez
bq help COMMAND
. - Pour obtenir de l'aide sur une commande spécifique et consulter la liste des options globales, saisissez
bq COMMAND --help
.
Remplacez COMMAND
par la commande pour laquelle vous avez besoin d'aide.
Définir des valeurs par défaut pour les indicateurs de ligne de commande
Vous pouvez définir des valeurs par défaut pour les options de ligne de commande en les incluant dans le fichier de configuration bq de l'outil de ligne de commande .bigqueryrc
. Avant de configurer vos options par défaut, vous devez d'abord créer un fichier .bigqueryrc
. dans l'éditeur de texte de votre choix. Après avoir créé le fichier .bigqueryrc
, vous pouvez spécifier le chemin d'accès au fichier à l'aide de l'option globale --bigqueryrc
.
Si l'option --bigqueryrc
n'est pas spécifiée, la variable d'environnement BIGQUERYRC
est utilisée. Si elle n'est pas spécifiée, le chemin ~/.bigqueryrc
est utilisé. Le chemin par défaut est $HOME/.bigqueryrc
.
Ajouter des options à .bigqueryrc
Pour ajouter des valeurs par défaut pour les options de ligne de commande dans .bigqueryrc
:
- Placez les options globales en haut du fichier, sans en-tête.
- Pour les options spécifiques aux commandes, saisissez le nom de la commande entre crochets et ajoutez les options spécifiques aux commandes (une par ligne) après le nom de la commande.
Exemple :
--apilog=stdout --format=prettyjson --location=US [query] --use_legacy_sql=false --max_rows=100 --maximum_bytes_billed=10000000 [load] --destination_kms_key=projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey
L'exemple précédent définit les valeurs par défaut des options suivantes :
- L'option globale
--apilog
est définie surstdout
pour imprimer le résultat de débogage dans la console Google Cloud. - L'option globale
--format
est définie surprettyjson
pour afficher le résultat de la commande dans un format JSON lisible par l'homme. - L'option globale
--location
est définie sur l'emplacement multirégionalUS
. L'option
--use_legacy_sql
spécifique à la commandequery
est définie surfalse
pour faire de GoogleSQL la syntaxe de requête par défaut.L'option
--max_rows
spécifique à la commandequery
est définie sur100
pour contrôler le nombre de lignes dans le résultat de la requête.L'option
--maximum_bytes_billed
spécifique à la commandequery
est définie sur 10 000 000 octets (10 Mo) pour que les requêtes lisant plus de 10 Mo de données échouent.L'option
--destination_kms_key
spécifique à la commandeload
est définie surprojects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey
.
Exécuter l'outil de ligne de commande bq dans une interface système interactive
Vous pouvez exécuter l'outil de ligne de commande bq dans une interface système interactive où vous n'avez pas besoin d'ajouter le préfixe bq
aux commandes. Pour lancer le mode interactif, saisissez bq shell
.
Après avoir lancé l'interface, l'invite bascule vers l'ID de votre projet par défaut.
Pour quitter le mode interactif, saisissez exit
.
Exécuter l'outil de ligne de commande bq dans un script
Vous pouvez exécuter l'outil de ligne de commande bq dans un script, de la même manière que vous exécutez une commande Google Cloud CLI. Voici un exemple de commandes gcloud
et bq
dans un script bash :
#!/bin/bash
gcloud config set project myProject
bq query --use_legacy_sql=false --destination_table=myDataset.myTable \
'SELECT
word,
SUM(word_count) AS count
FROM
`bigquery-public-data`.samples.shakespeare
WHERE
word LIKE "%raisin%"
GROUP BY
word'
Exécuter des commandes bq
à partir d'un compte de service
Vous pouvez utiliser un compte de service pour effectuer des appels d'API autorisés ou pour exécuter des jobs de requête en votre nom. Pour utiliser un compte de service dans l'outil de ligne de commande bq, autorisez l'accès à Google Cloud à partir de ce compte de service. Pour en savoir plus, consultez la section gcloud auth activate-service-account.
Pour commencer à exécuter les commandes bq
en utilisant l'emprunt d'identité d'un compte de service, exécutez la commande suivante :
gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_NAME
Remplacez SERVICE_ACCOUNT_NAME
par le nom de votre compte de service.
Les commandes bq
que vous exécutez maintenant utilisent les identifiants du compte de service.
Pour arrêter l'exécution des commandes bq
à partir d'un compte de service, exécutez la commande suivante :
gcloud config unset auth/impersonate_service_account
Examples
Pour retrouver des exemples de ligne de commande, consultez la section Guides pratiques de la documentation BigQuery. Cette section répertorie les liens vers des tâches fréquemment réalisées en ligne de commande, telles que créer, obtenir, lister, supprimer et modifier des ressources BigQuery.
Créer des ressources
Pour en savoir plus sur l'utilisation de l'outil de ligne de commande bq pour créer des ressources, consultez les ressources suivantes :
- Créer un ensemble de données
- Créer une table vide avec une définition de schéma
- Créer une table à partir d'un résultat de requête
- Créer une table partitionnée par temps d'ingestion
- Créer une vue
Pour obtenir des exemples de création de table à partir d'un fichier de données, consultez la section Chargement des données.
Obtenir des informations sur les ressources
Pour en savoir plus sur l'utilisation de l'outil de ligne de commande bq pour obtenir des informations sur les ressources, consultez les ressources suivantes :
- Obtenir des informations sur les ensembles de données
- Obtenir des informations sur les tables
- Obtenir des informations sur les vues
Répertorier des ressources
Pour en savoir plus sur l'utilisation de l'outil de ligne de commande bq pour répertorier des ressources, consultez les ressources suivantes :
Répertorier les tâches
Pour en savoir plus sur l'utilisation de l'outil de ligne de commande bq pour répertorier des jobs, consultez les ressources suivantes :
Mettre à jour des ressources
Pour plus d'informations sur l'utilisation de l'outil de ligne de commande bq pour mettre à jour des ressources, consultez les ressources suivantes :
- Mettre à jour les propriétés des ensembles de données
- Mettre à jour les propriétés d'une table
- Mettre à jour les propriétés d'une vue
Chargement des données
Pour en savoir plus sur l'utilisation de l'outil de ligne de commande bq pour charger des données, consultez les ressources suivantes :
- Charger des données Avro depuis Cloud Storage
- Charger des données JSON à partir de Cloud Storage
- Charger des données CSV à partir de Cloud Storage
- Charger des données depuis un fichier local
Interroger les données
Pour en savoir plus sur l'utilisation de l'outil de ligne de commande bq pour interroger des données, consultez les ressources suivantes :
Utiliser des sources de données externes
Pour en savoir plus sur l'utilisation de l'outil de ligne de commande bq pour interroger des données dans des sources de données externes, consultez les ressources suivantes :
- Créer une définition de table à l'aide d'un fichier de schéma JSON
- Interroger des données Bigtable à l'aide de tables externes permanentes
- Interroger des données Cloud Storage à l'aide de tables externes permanentes
- Interroger des données Google Drive à l'aide de tables externes permanentes
Exportation de données
Pour en savoir plus sur l'utilisation de l'outil de ligne de commande bq pour exporter des données, consultez les ressources suivantes :
Utiliser le service de transfert de données BigQuery
Pour en savoir plus sur l'utilisation de l'outil de ligne de commande bq avec le service de transfert de données BigQuery, consultez les ressources suivantes :
- Configurer un transfert Amazon S3
- Configurer un transfert Campaign Manager
- Configurer un transfert Cloud Storage
- Configurer un transfert Google Ad Manager
- Configurer un transfert Google Ads
- Configurer un transfert Google Merchant Center (version bêta)
- Configurer un transfert Google Play
- Configurer un transfert Search Ads 360 (version bêta)
- Configurer un transfert de chaîne YouTube
- Configurer un transfert de propriétaire de contenu YouTube
- Migrer des données depuis Amazon Redshift
- Migrer des données depuis Teradata
- Obtenir des informations sur les configurations de transfert
- Répertorier les configurations de transfert
- Afficher l'historique d'exécution
- Afficher les détails d'une exécution de transfert et les messages de journal
- Mettre à jour des configurations de transfert
Résoudre les problèmes liés à l'outil de ligne de commande bq
Cette section explique comment résoudre les problèmes liés à l'outil de ligne de commande bq.
Maintenir votre gloud CLI à jour
Si vous utilisez l'outil de ligne de commande bq à partir de Google Cloud CLI, assurez-vous de disposer des dernières fonctionnalités et des derniers correctifs pour l'outil de ligne de commande en conservant votre installation gcloud CLI à jour. Pour savoir si vous utilisez la dernière version de gcloud CLI, saisissez la commande suivante dans Cloud Shell :
gcloud components list
Les deux premières lignes du résultat affichent le numéro de version de votre installation actuelle de gcloud CLI ainsi que le numéro de la version la plus récente de gcloud CLI. Si vous constatez que votre version est obsolète, vous pouvez mettre à jour votre installation de gcloud CLI vers la version la plus récente en saisissant la commande suivante dans Cloud Shell :
gcloud components update
Débogage
Vous pouvez saisir les commandes suivantes pour déboguer l'outil de ligne de commande bq :
Afficher les requêtes envoyées et reçues. Ajoutez l'option
--apilog=PATH_TO_FILE
pour enregistrer un journal des opérations dans un fichier local. RemplacezPATH_TO_FILE
par le chemin d'accès de l'emplacement dans lequel vous souhaitez enregistrer le journal. L'outil de ligne de commande bq fonctionne avec des appels standards à l'API REST, qu'il peut être utile de consulter. Il est également utile de joindre ce journal lorsque vous signalez des problèmes. L'utilisation de-
ou destdout
au lieu d'un chemin imprime le journal dans Google Cloud Console. La définition de--apilog
surstderr
génère un résultat dans le fichier d'erreur standard. Pour consigner d'autres requêtes, utilisez l'option--httplib2_debuglevel=LOG_LEVEL
. Une valeurLOG_LEVEL
plus élevée enregistre davantage d'informations sur les requêtes HTTP.Résoudre les erreurs. Saisissez l'option
--format=prettyjson
lors de l'obtention de l'état d'une tâche ou lors de l'affichage d'informations détaillées sur des ressources, telles que des tables et des ensembles de données. L'utilisation de cette option génère la réponse au format JSON, en incluant la propriétéreason
. Vous pouvez rechercher des procédures de dépannage à l'aide de la propriétéreason
. Pour en savoir plus sur les erreurs d'exécution, utilisez l'option--debug_mode
.