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 pouvoir utiliser l'outil de ligne de commande bq, vous devez utiliser Google Cloud Console pour créer ou sélectionner un projet.

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.

   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 au sélecteur de projet

3. 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 au sélecteur de projet

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

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 du SDK Cloud.

• Pour utiliser l'outil de ligne de commande bq depuis Cloud Console, activez Cloud Shell :

  Activer Cloud Shell

• Pour utiliser l'outil de ligne de commande bq à partir du SDK Cloud, installez et configurez le SDK Cloud.

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

Remarque : Il est déconseillé de créer un fichier .bigqueryrc à l'aide de la commande bq init.

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.

  Remarque : Vous ne pouvez pas utiliser --nouse_legacy_sql dans .bigqueryrc.

• 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'

Exécuter des commandes bq à partir d'un compte de service

Pour exécuter des commandes bq à l'aide d'un compte de service, vous devez autoriser l'accès à Google Cloud à partir de ce compte de service. Pour en savoir plus, consultez la section gcloud auth activate-service-account.

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 :

• 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 ensembles de données
• Répertorier les tables
• Répertorier des vues

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

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 :

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

• Exécuter des requêtes
• Écrire des résultats de requête
• Exécuter des requêtes paramétrées

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

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 :

• 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 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 SDK Cloud à jour

Si vous utilisez l'outil de ligne de commande bq à partir du SDK Cloud, assurez-vous que vous disposez des dernières fonctionnalités et des derniers correctifs pour l'outil de ligne de commande bq en maintenant votre installation du SDK Cloud à jour. Pour savoir si vous utilisez la dernière version du SDK Cloud, 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 du SDK Cloud et le numéro de version du SDK Cloud le plus récent. Si vous constatez que votre version est obsolète, vous pouvez mettre à jour votre installation du SDK Cloud 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 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.