Utiliser l'outil de ligne de commande bq

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 de tous les indicateurs 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 BigQuery, servez-vous de la console Google Cloud Platform pour créer ou sélectionner un projet et installer le SDK Cloud.

1. Connectez-vous à votre compte Google.

   Si vous n'en possédez pas déjà un, vous devez en créer un.

2. Sélectionnez ou créez un projet Google Cloud Platform.

   Remarque : Si vous ne prévoyez pas de conserver les ressources créées au cours de 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 en supprimant toutes les ressources qui lui sont associées.

   Accéder à la page "Gérer les ressources"

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 BigQueryl'API requise.

   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.

Utilisation générale

Positionnement de l'indicateur

bq prend en charge deux types d'indicateurs : les indicateurs globaux et les indicateurs 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 définir =argument.

Par exemple, cette commande spécifie false pour l'indicateur booléen --use_legacy_sql en plaçant no au début de l'indicateur :

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

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

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

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.

Obtenir de l'aide

Vous pouvez utiliser 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 la liste complète des commandes, saisissez bq help.
• Pour obtenir la liste des indicateurs globaux, 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 avec la liste des indicateurs globaux, saisissez bq command --help.

Débogage

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

• Pour voir les demandes envoyées et reçues

  Ajoutez l'indicateur --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. Utiliser - ou stdout au lieu d'un chemin de fichier imprimera le journal sur la console. Envoyer --apilog vers stderr génère une sortie dans le fichier d'erreur standard.

• Pour aider à résoudre les erreurs

  Saisissez l'indicateur --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. Utiliser cet indicateur génère la réponse au format JSON, en incluant la propriété reason. Vous pouvez utiliser la propriété reason pour rechercher les procédures de dépannage.

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 indicateurs de ligne de commande en les incluant dans le fichier de configuration 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. 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'indicateur global --bigqueryrc.

Si l'indicateur --bigqueryrc n'est pas spécifié, la variable d'environnement BIGQUERYRC est utilisée. Si cette dernière 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 indicateurs au fichier .bigqueryrc

Pour ajouter des valeurs par défaut pour les indicateurs de ligne de commande dans le fichier .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 indicateurs de ligne de commande dans .bigqueryrc, vous devez spécifier l'argument de l'indicateur 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 la zone multirégionale US.

Cet exemple définit des valeurs par défaut pour les indicateurs query spécifiques à une commande suivants :

• --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'indicateur load spécifique à une commande suivant :

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

Lancer bq dans une interface système interactive

Vous pouvez exécuter bq dans une interface système interactive où vous n'avez pas besoin de préfixer les commandes avec bq. Pour démarrer ce 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 pour créer des ressources, consultez les sections :

• 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 pour obtenir des informations sur les ressources, consultez les sections :

• Obtenir des informations sur les ensembles de données
• Obtenir des informations sur les tables
• Obtenir des informations sur les vues

Lister les ressources

Pour en savoir plus sur l'utilisation de l'outil de ligne de commande pour lister les ressources, consultez les sections :

• Répertorier les ensembles de données
• Répertorier des tables
• Répertorier des vues

Mettre à jour les ressources

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

• 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 pour charger des données, consultez les sections :

• 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 pour interroger des données, consultez les sections :

• Exécuter des requêtes
• Écrire des résultats de requêtes
• 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 pour interroger des données dans des sources de données externes, consultez les sections :

• 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 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 avec le service de transfert de données BigQuery, consultez les pages suivantes :

• Configurer un transfert Campaign Manager
• Configurer un transfert Cloud Storage (version bêta)
• 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 (version bêta)
• Configurer un transfert de chaîne YouTube
• Configurer un transfert de propriétaire de contenu YouTube

• 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