Utiliser 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 commencer à utiliser l'outil de ligne de commande bq, utilisez Google Cloud Console pour créer ou sélectionner un projet et installer le SDK Cloud.

Connectez-vous à votre compte Google.
Si vous n'en possédez pas déjà un, vous devez en créer un.

Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

Accéder à la page de sélection du projet

Installez et initialisez le SDK Cloud.

BigQuery est automatiquement activé dans les nouveaux projets. Pour activer BigQuery dans un projet préexistant, accédez à Activez l'API BigQuery.
Activer l'API
.
BigQuery fournit un bac à sable si vous ne souhaitez pas ajouter une carte de crédit ni activer la facturation pour votre projet. Les étapes décrites sur cette page fonctionnent quel que soit l'état de facturation du projet. Si vous le souhaitez, vous pouvez également découvrir comment activer la facturation.

Au lieu de télécharger et d'installer le SDK Cloud, vous pouvez en utiliser une version préinstallée disponible dans Google Cloud Shell.

Utilisation générale

Positionnement de l'indicateur

bq accepte deux types d'options : les options globales et les options de commande. Ils doivent être utilisés dans l'ordre indiqué ci-dessous :

bq --global_flag argument bq_command --command-specific_flag argument

Les indicateurs globaux (ou indicateurs communs) peuvent être utilisés dans toutes les commandes.
Les indicateurs spécifiques aux commandes s'appliquent à une commande spécifique.

Séparez plusieurs indicateurs globaux ou spécifiques à une commande en utilisant un espace. Exemple :

bq \
--global_flag argument \
--global_flag argument \
bq_command \
--command-specific_flag argument \
--command-specific_flag argument

Vous pouvez spécifier les arguments de la commande de l'une des manières suivantes :

--flag=argument
--flag='argument'
--flag="argument"
--flag argument
--flag 'argument'
--flag "argument"

Chacune de ces méthodes est utilisée tout au long de la documentation BigQuery.

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 indiquer =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'

Mais vous pouvez aussi spécifier false comme argument de l'option, en saisissant :

bq query --use_legacy_sql=false \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

Pour obtenir la liste des options globales et propres à une commande, consultez la documentation de référence de l'outil de ligne de commande bq.

Obtenir de l'aide

Vous pouvez saisir les commandes suivantes pour obtenir de l'aide sur l'outil de ligne de commande bq :

Pour connaître la version installée de bq, saisissez bq version.
Pour obtenir une 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.

Débogage

Vous pouvez saisir les commandes suivantes pour déboguer bq :

Voir les demandes envoyées et reçues

Ajoutez l'option --apilog=path_to_file pour enregistrer un journal des opérations dans un fichier local. 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 stdout au lieu d'un chemin de fichier imprimera le journal sur la console. La définition de --apilog sur stderr génère un résultat dans le fichier d'erreur standard.
Pour aider à 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.

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 de l'outil de ligne de commande bq — .bigqueryrc. Avant de configurer vos options par défaut, vous devez d'abord créer un fichier .bigqueryrc. Vous pouvez utiliser l'éditeur de texte de votre choix pour créer le fichier. 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 celle-ci 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 indicateurs globaux en haut du fichier, sans en-tête.
Pour les indicateurs spécifiques à une commande, saisissez le nom de la commande (entre parenthèses), et ajoutez les indicateurs spécifiques à la commande (un par ligne) en dessous au format suivant :

command
--command-specific_flag=argument
--command-specific_flag=argument

Lorsque vous saisissez des options de ligne de commande dans .bigqueryrc, vous devez spécifier l'argument de l'option au format =argument.

.bigqueryrc est lu à chaque fois que vous exécutez bq, et les modifications prennent donc effet immédiatement. Lorsque vous exécutez bq en mode interactif (bq shell), vous devez redémarrer l'interface système pour que les modifications soient appliquées.

Exemple

Cet exemple définit les valeurs par défaut pour les indicateurs globaux suivants :

--apilog est défini sur stdout pour imprimer les résultats du débogage sur la console.
--format est défini sur prettyjson pour afficher le résultat de la commande dans un format JSON lisible par l'homme.
--location est défini sur l'emplacement multirégional US.

Cet exemple définit des valeurs par défaut pour les options suivantes propres à la commande query :

--use_legacy_sql est défini sur false pour utiliser le langage SQL standard comme syntaxe de requête par défaut.
Remarque : Vous ne pouvez pas utiliser --nouse_legacy_sql dans .bigqueryrc.
--max_rows est défini sur 100 pour contrôler le nombre de lignes dans le résultat de la requête.
--maximum_bytes_billed est défini sur 10 000 000 octets (10 Mo) pour que les requêtes lisant plus de 10 Mo de données échouent.

Cet exemple définit une valeur par défaut pour l'option suivante propre à la commande load :

--destination_kms_key est défini sur projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey.

credential_file = path_to_credential_file
--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

Pour confirmer vos paramètres, saisissez la commande suivante :

cat ~/.bigqueryrc

Exécuter `bq` dans une interface système interactive

Vous pouvez exécuter 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.

Exemples

Pour retrouver des exemples de ligne de commande, consultez la section Guides pratiques de la documentation BigQuery. Vous trouverez ci-dessous des 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 sections suivantes :

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 sections :

Répertorier des ressources

Pour en savoir plus sur l'utilisation de l'outil de ligne de commande bq pour répertorier les ressources, consultez les sections :

Mettre à jour des ressources

Pour en savoir plus sur l'utilisation de l'outil de ligne de commande bq pour mettre à jour les ressources, consultez les sections :

Charger 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 sections :

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 sections :

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 sections :

Exporter des données

Pour en savoir plus sur l'utilisation de l'outil de ligne de commande bq pour exporter des données, consultez la section :

Exporter des données stockées dans BigQuery

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 pages suivantes :