bq-Befehlszeilentool verwenden

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

Vorbereitung

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

  1. Melden Sie sich bei Ihrem Google-Konto an.

    Wenn Sie noch kein Konto haben, registrieren Sie sich hier für ein neues Konto.

  2. Wählen Sie in der Cloud Console auf der Projektauswahlseite ein Cloud-Projekt aus oder erstellen Sie eines.

    Zur Projektauswahl

  3. Installieren und initialisieren Sie das Cloud SDK.
  4. BigQuery ist in neuen Projekten automatisch aktiviert. Zum Aktivieren von BigQuery in einem bereits bestehenden Projekt wechseln Sie zu Aktivieren Sie die BigQuery API.

    Aktivieren Sie die API

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

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 eingeben, wird das Log in der Console angezeigt. 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 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 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.

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

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 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 mithilfe des Befehlszeilentools finden Sie unter:

Ressourcen auflisten

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

Ressourcen aktualisieren

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

Daten laden

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

Daten abfragen

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

Externe Datenquellen verwenden

Informationen zum Abfragen von Daten in externen Datenquellen mithilfe des Befehlszeilentools finden Sie unter:

Daten exportieren

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

BigQuery Data Transfer Service verwenden

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