bq-Befehlszeilentool verwenden

Das bq-Befehlszeilentool ist ein Python-basiertes Befehlszeilentool für BigQuery. Diese Seite bietet allgemeine Informationen zur Verwendung des bq-Befehlszeilentools.

Eine vollständige Referenz aller bq-Befehle und -Flags finden Sie in der Referenz zum bq-Befehlszeilentool.

Hinweis

Bevor Sie das bq-Befehlszeilentool verwenden können, müssen Sie mit der Google Cloud Console ein Projekt erstellen oder auswählen und das Cloud SDK installieren.

Melden Sie sich bei Ihrem Google-Konto an.
Wenn Sie noch kein Konto haben, melden Sie sich hier für ein neues Konto an.

Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.

Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

Zur Projektauswahl

Installieren und initialisieren Sie das Cloud SDK.

BigQuery ist in neuen Projekten automatisch aktiviert. Zum Aktivieren von BigQuery in einem vorhandenen Projekt wechseln Sie zu Aktivieren Sie die BigQuery API.
Aktivieren Sie die API
.
BigQuery bietet eine Sandbox, wenn Sie für Ihr Projekt keine Kreditkarte angeben oder die Abrechnung nicht aktivieren möchten. Die Schritte in diesem Thema funktionieren für Projekte mit und ohne aktivierter Abrechnung. Wenn Sie die Abrechnung aktivieren möchten, lesen Sie die Informationen unter Abrechnungseinstellungen eines Projekts ändern.

Anstatt das Cloud SDK herunterzuladen und zu installieren, können Sie eine vorinstallierte Version des Cloud SDK in Google Cloud Shell verwenden.

Allgemeine Verwendung

Flag-Positionierung

Das bq-Befehlszeilentool unterstützt zwei Arten von Flags: globale und befehlsspezifische Flags. Diese sollten in der hier gezeigten Reihenfolge verwendet werden:

bq --global_flag argument bq_command --command-specific_flag argument

Globale Flags (oder allgemeine Flags) können in allen Befehlen verwendet werden.
Befehlsspezifische Flags gelten für einen bestimmten Befehl.

Trennen Sie mehrere globale oder befehlsspezifische Flags durch ein Leerzeichen. Beispiel:

bq \
--global_flag argument \
--global_flag argument \
bq_command \
--command-specific_flag argument \
--command-specific_flag argument

Sie können Befehlsargumente auf eine der folgenden Arten angeben:

--flag=argument
--flag='argument'
--flag="argument"
--flag argument
--flag 'argument'
--flag "argument"

Alle diese Methoden werden in der BigQuery-Dokumentation verwendet.

Bei einigen Befehlen müssen Argumente in einfache oder doppelte Anführungszeichen gesetzt werden. Dies gilt vor allem dann, wenn das Argument Leerzeichen, Kommas oder andere Sonderzeichen enthält. Beispiel:

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

Flags mit booleschen Werten können ohne Argument angegeben werden. Wenn Sie true oder false angeben, müssen Sie =argument angeben.

Der folgende Befehl gibt beispielsweise für das boolesche Flag --use_legacy_sql "false" an, da vor dem Flag no hinzugefügt wird:

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

Alternativ können Sie mit dem folgenden Befehl false als Argument des Flags angeben:

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

Eine Liste der verfügbaren globalen und befehlsspezifischen Flags finden Sie in der Referenz zum bq-Befehlszeilentool.

Abfragen über das `bq`-Befehlszeilentool ausführen

So führen Sie eine Abfrage aus der Google Cloud Console über das bq-Befehlszeilentool aus:

Fügen Sie die Abfrage so in einen bq query-Befehl ein:

bq query --use_legacy_sql=false "QUERY"
Ersetzen Sie in der Abfrage alle einfachen Anführungszeichen (') durch doppelte Anführungszeichen (").
Kommentare aus der Abfrage entfernen.

Beispiel: Transformieren Sie die folgende Google Cloud Console-Abfrage:

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

in eine Abfrage des bq-Befehlszeilentools:

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'

Weitere Informationen finden Sie unter Interaktive Jobs und Batch-Abfragejobs ausführen.

Hilfe

Mit den folgenden Befehlen können Sie Hilfe für das bq-Befehlszeilentool anfordern:

Wenn Sie die installierte Version von bq ermitteln möchten, geben Sie bq version ein.
Wenn Sie eine vollständige Liste der Befehle wünschen, geben Sie bq help ein.
Wenn Sie eine Liste der globalen Flags sehen möchten, geben Sie bq --help ein.
Wenn Sie Hilfe zu einem bestimmten Befehl benötigen, geben Sie bq help command ein.
Wenn Sie Hilfe zu einem bestimmten Befehl sowie eine Liste der globalen Flags wünschen, geben Sie bq command --help ein.

Debugging

Zum Debuggen von bq können Sie die folgenden Befehle eingeben:

Gesendete und empfangene Anfragen ansehen

Fügen Sie das Flag --apilog=path_to_file hinzu, um ein Log der Operationen in einer lokalen Datei zu speichern. bq führt standardmäßige REST-basierte API-Aufrufe durch, deren Anzeige nützlich sein kann. Es ist auch hilfreich, wenn Sie beim Melden von Problemen dieses Log als Anhang hinzufügen. Wenn Sie anstelle eines Dateipfads - oder stdout verwenden, wird das Log in der Google Cloud Console ausgegeben. Wenn Sie --apilog auf stderr setzen, erfolgt die Ausgabe in die Standardfehlerdatei.
Fehler beheben

Geben Sie das Flag --format=prettyjson ein, wenn Sie den Jobstatus abrufen oder sich detaillierte Informationen zu Ressourcen wie Tabellen und Datasets anzeigen lassen möchten. Mit diesem Flag wird die Antwort im JSON-Format einschließlich des Attributs reason ausgegeben. Mit dem Attribut reason können Sie Schritte zur Fehlerbehebung suchen.

Standardwerte für Befehlszeilen-Flags festlegen

Sie können Standardwerte für Befehlszeilen-Flags festlegen. Dazu beziehen Sie diese in die Konfigurationsdatei .bigqueryrc des bq-Befehlszeilentools ein. Bevor Sie Ihre Standardoptionen konfigurieren, müssen Sie zuerst eine .bigqueryrc-Datei erstellen. Sie können zum Erstellen der Datei Ihren bevorzugten Texteditor verwenden. Nachdem Sie die Datei .bigqueryrc erstellt haben, können Sie den Pfad zur Datei mit dem globalen Flag --bigqueryrc angeben.

Wenn das Flag --bigqueryrc nicht angegeben ist, wird die Umgebungsvariable BIGQUERYRC verwendet. Wenn diese nicht angegeben ist, wird der Pfad ~/.bigqueryrc verwendet. Der Standardpfad ist $HOME/.bigqueryrc.

Flags zu `.bigqueryrc` hinzufügen

So fügen Sie .bigqueryrc Standardwerte für Befehlszeilen-Flags hinzu:

Fügen Sie globale Flags ohne Kopfzeilen am Anfang der Datei ein.
Geben Sie für befehlsspezifische Flags in Klammern den Befehlsnamen ein und fügen Sie darunter die befehlsspezifischen Flags (eines pro Zeile) im folgenden Format hinzu:

command
--command-specific_flag=argument
--command-specific_flag=argument

Wenn Sie in .bigqueryrc Befehlszeilen-Flags eingeben, müssen Sie das Argument des Flags im Format =argument angeben.

.bigqueryrc wird bei jeder Ausführung von bq gelesen, sodass Änderungen sofort aktualisiert werden sollten. Wenn Sie bq im interaktiven Modus (bq shell) ausführen, müssen Sie die Shell neu starten, damit die Änderungen wirksam werden.

Beispiel

In diesem Beispiel werden für die folgenden globalen Flags Standardwerte festgelegt:

--apilog ist auf stdout gesetzt, um die Debugging-Ausgabe in der Google Cloud Console auszugeben.
--format ist auf prettyjson gesetzt, damit die Befehlsausgabe in einem für Menschen lesbaren JSON-Format angezeigt wird.
--location ist auf den multiregionalen Standort US gesetzt.

In diesem Beispiel werden Standardwerte für die folgenden befehlsspezifischen query-Flags festgelegt:

Für --use_legacy_sql wird false festgelegt, damit Standard-SQL als Standardabfragesyntax verwendet wird.

Hinweis: Sie können --nouse_legacy_sql nicht in .bigqueryrc verwenden.
--max_rows ist auf 100 gesetzt, um die Anzahl der Zeilen in der Abfrageausgabe zu steuern.
--maximum_bytes_billed wird auf 10.000.000 Byte (10 MB) gesetzt, damit keine Abfragen durchgeführt werden, die mehr als 10 MB Daten lesen.

In diesem Beispiel wird für das folgende befehlsspezifische load-Flag ein Standardwert festgelegt:

--destination_kms_key ist auf projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey gesetzt.

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

Mit dem folgenden Befehl bestätigen Sie Ihre Einstellungen:

cat ~/.bigqueryrc

`bq` in einer interaktiven Shell ausführen

Sie können bq in einer interaktiven Shell ausführen. Hier brauchen Sie den Befehlen nicht bq voranzustellen. Zum Starten des interaktiven Modus geben Sie bq shell ein. Nach dem Start der Shell ändert sich die Eingabeaufforderung in die ID Ihres Standardprojekts. Zum Beenden des interaktiven Modus geben Sie exit ein.

`bq` in einem Skript ausführen

Sie können bq in einem Skript ausführen, wie Sie einen Befehl des gcloud-Befehlszeilentools ausführen. Das folgende Beispiel zeigt die Befehle gcloud und bq in einem Bash-Skript:

#!/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'

Beispiele

Befehlszeilenbeispiele finden Sie im gesamten Anleitungsabschnitt der BigQuery-Dokumentation. Nachfolgend sind Links zu gängigen Befehlszeilenaufgaben aufgeführt, etwa zum Erstellen, Abrufen, Auflisten, Löschen und Ändern von BigQuery-Ressourcen.

Ressourcen erstellen

Informationen zum Erstellen von Ressourcen mit dem bq-Befehlszeilentool finden Sie unter:

Beispiele zum Erstellen einer Tabelle mit einer Datendatei finden Sie unter Daten laden.

Informationen zu Ressourcen abrufen

Informationen zum Abrufen von Angaben zu Ressourcen mit dem bq-Befehlszeilentool finden Sie unter:

Ressourcen auflisten

Informationen zum Auflisten von Ressourcen mit dem bq-Befehlszeilentool finden Sie unter:

Ressourcen aktualisieren

Informationen zum Aktualisieren von Ressourcen mit dem bq-Befehlszeilentool finden Sie unter:

Daten laden

Informationen zum Laden von Daten mit dem bq-Befehlszeilentool finden Sie unter:

Daten abfragen

Informationen zum Abfragen von Daten mit dem bq-Befehlszeilentool finden Sie unter:

Externe Datenquellen verwenden

Informationen zum Abfragen von Daten in externen Datenquellen mit dem bq-Befehlszeilentool finden Sie unter:

Daten exportieren

Informationen zum Exportieren von Daten mit dem bq-Befehlszeilentool finden Sie unter:

In BigQuery gespeicherte Daten exportieren

BigQuery Data Transfer Service verwenden

Informationen zum Verwenden des bq-Befehlszeilentools mit dem BigQuery Data Transfer Service finden Sie unter: