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.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

    3.

  3. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

    4.
  4. BigQuery est automatiquement activé dans les nouveaux projets. Pour activer BigQuery dans un projet préexistant, accédez à

    Enable the BigQuery API.

    Enable the API

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

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 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. Mettez en forme la chaîne de requête.

    Si vous devez utiliser des littéraux de chaîne supplémentaires dans la requête, vous devez respecter les règles relatives aux guillemets du shell que vous utilisez. Par exemple : Bash ou PowerShell.

    L'exemple suivant illustre une approche typique dans Bash, qui consiste à utiliser des guillemets doubles pour indiquer les littéraux de chaîne dans la requête, puis à placer la requête elle-même entre guillemets simples :

    'SELECT * FROM mydataset.mytable WHERE column1 = "value";'

    Si vous copiez la requête à partir d'un autre emplacement, vous devez également supprimer tous 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 sur stdout pour imprimer le résultat de débogage dans la console Google Cloud.
  • L'option globale --format est définie sur prettyjson pour afficher le résultat de la commande dans un format JSON lisible par l'humain.
  • 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 faire de GoogleSQL la 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 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

Exemples

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 :

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 :

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 :

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 :

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 :

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 :

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. 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 la console Google Cloud. La définition de --apilog sur stderr 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 valeur LOG_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.