À l'aide de 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. Pour en savoir plus, consultez la page Activer le bac à sable BigQuery.
   Remarque : Si votre projet dispose d'un compte de facturation et que vous souhaitez utiliser le bac à sable BigQuery, désactivez la facturation pour votre projet.

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 :

  Activer 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 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 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 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 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'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 faire de GoogleSQL la 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 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 tâches 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 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 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 bq 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 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.