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.

  1. 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.

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

    Accéder au sélecteur de projet

  3. Installez et initialisez le SDK Cloud.
  4. 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

    .
  5. 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.

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 options globales et propres à une 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 commande
  • ARGUMENT : 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 :

  1. Incluez la requête dans une commande bq query comme suit : bq query --use_legacy_sql=false 'QUERY'. Remplacez QUERY par la requête.
  2. Remplacez tous les guillemets simples (') dans la requête par des guillemets doubles (").
  3. 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é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. Remplacez PATH_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 de stdout au lieu d'un chemin imprime le journal dans Google Cloud Console. La définition de --apilog sur stderr génère un résultat dans le fichier d'erreur standard.

  • 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 .bigqueryrc de l'outil de ligne de commande bq. 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 son chemin d'accès à 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 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 sur stdout pour imprimer le résultat de débogage dans Cloud Console.
  • L'option globale --format est définie sur prettyjson 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égional US.

  • L'option --use_legacy_sql spécifique à la commande query est définie sur false pour utiliser le langage SQL standard comme syntaxe de requête par défaut.

  • L'option --max_rows spécifique à la commande query est définie sur 100 pour contrôler le nombre de lignes dans le résultat de la requête.

  • L'option --maximum_bytes_billed spécifique à la commande query 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 commande load est définie sur projects/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 de l'outil de ligne de commande gcloud. 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'

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

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 :

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 :

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

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 :

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