bq-Befehlszeilentool entdecken

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.

Hinweise

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

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

    3.

  3. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

    4.
  4. BigQuery ist in neuen Projekten automatisch aktiviert. Zum Aktivieren von BigQuery in einem vorhandenen Projekt wechseln Sie zu

    Enable the BigQuery API.

    Enable the API

    .
  5. Optional: Aktivieren Sie die Abrechnung für das Projekt. Die Abrechnung funktioniert auch dann, wenn Sie die Abrechnung nicht aktivieren oder keine Kreditkarte angeben möchten. BigQuery bietet Ihnen eine Sandbox zum Ausführen dieser Schritte. Weitere Informationen finden Sie unter BigQuery-Sandbox aktivieren.

bq-Befehle in Cloud Shell eingeben

Sie können die Befehle des bq-Befehlszeilentools in Cloud Shell entweder über die Google Cloud Console oder über die Google Cloud CLI eingeben.

Flags und Argumente positionieren

Das bq-Befehlszeilentool unterstützt zwei Arten von Flags:

  • Globale Flags können in allen Befehlen verwendet werden.
  • Befehlsspezifische Flags gelten für einen bestimmten Befehl.

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

Fügen Sie globale Flags vor dem Befehl bq ein und fügen Sie dann befehlsspezifische Flags ein. Sie können mehrere globale oder befehlsspezifische Flags verwenden. Beispiel:

bq --location=us mk --reservation --project_id=project reservation_name

Sie können Befehlsargumente auf folgende Arten angeben:

  • --FLAG ARGUMENT (wie in den vorherigen Beispielen gezeigt)
  • --FLAG=ARGUMENT
  • --FLAG='ARGUMENT'
  • --FLAG="ARGUMENT"
  • --FLAG 'ARGUMENT'
  • --FLAG "ARGUMENT"

Dabei gilt:

  • FLAG: ein globales oder befehlsspezifisches Flag
  • ARGUMENT: das Argument des Flags

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 das Format FLAG=ARGUMENT verwenden.

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, um false als Argument des Flags anzugeben, Folgendes eingeben:

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

Abfragen über das bq-Befehlszeilentool ausführen

Gehen Sie so vor, um eine Abfrage, die Sie in der Google Cloud Console entwickelt haben, über das bq-Befehlszeilentool auszuführen:

  1. Fügen Sie die Abfrage so in einen bq query-Befehl ein: bq query --use_legacy_sql=false 'QUERY'. Ersetzen Sie QUERY durch die Abfrage.

  2. Formatieren Sie den Abfragestring.

    Wenn Sie innerhalb der Abfrage zusätzliche Stringliterale verwenden müssen, folgen Sie den Anführungszeichen für die verwendete Shell, z. B. Bash oder PowerShell.

    Das folgende Beispiel zeigt einen typischen Ansatz in Bash: Die Stringliterale in der Abfrage werden in doppelte Anführungszeichen gesetzt und die Abfrage selbst in einfache Anführungszeichen:

    'SELECT * FROM mydataset.mytable WHERE column1 = "value";'

    Wenn Sie die Abfrage von einem anderen Speicherort kopieren, müssen Sie auch alle Kommentare in 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

Geben Sie die folgenden Befehle ein, um Hilfe für das bq-Befehlszeilentool zu erhalten:

  • Geben Sie für die installierte Version des bq-Befehlszeilentools 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.

Ersetzen Sie COMMAND durch den Befehl, bei dem Sie Hilfe benötigen.

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 nach dem Befehlsnamen das befehlsspezifische Flag (eines pro Zeile) hinzu.

Beispiel:

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

Im vorherigen Beispiel werden Standardwerte für die folgenden Flags festgelegt:

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

  • Das query-befehlsspezifische Flag --use_legacy_sql wurde auf false gesetzt, um GoogleSQL als Standardabfragesyntax zu verwenden.

  • Das query-befehlsspezifische Flag --max_rows wurde auf 100 gesetzt, um die Anzahl der Zeilen in der Abfrageausgabe zu steuern.

  • Das query-befehlsspezifische Flag --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.

  • Das load-befehlsspezifische Flag--destination_kms_key ist auf projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey gesetzt.

bq-Befehlszeilentool in einer interaktiven Shell ausführen

Sie können das bq-Befehlszeilentool 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-Befehlszeilentool in einem Skript ausführen

Sie können das bq-Befehlszeilentool in einem Skript ausführen, so wie Sie einen Google Cloud CLI-Befehl ausführen würden. 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'

bq-Befehle über ein Dienstkonto ausführen

Sie können ein Dienstkonto verwenden, um in Ihrem Namen autorisierte API-Aufrufe auszuführen oder Abfragejobs auszuführen. Autorisieren Sie den Zugriff auf Google Cloud über das Dienstkonto, um ein Dienstkonto im bq-Befehlszeilentool zu verwenden. Weitere Informationen finden Sie unter gcloud auth activate-service-account.

Wenn Sie bq-Befehle mit der Identitätsübertragung für ein Dienstkonto ausführen möchten, führen Sie den folgenden Befehl aus:

gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_NAME

SERVICE_ACCOUNT_NAME durch den Namen Ihres Dienstkontos ersetzen.

bq-Befehle, die Sie ausführen, verwenden jetzt die Anmeldedaten des Dienstkontos.

Führen Sie den folgenden Befehl aus, um die Ausführung von bq-Befehlen über ein Dienstkonto zu beenden:

gcloud config unset auth/impersonate_service_account

Beispiele

Befehlszeilenbeispiele finden Sie im gesamten Anleitungsabschnitt der BigQuery-Dokumentation. In diesem Abschnitt 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 hier:

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

Informationen zu Ressourcen abrufen

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

Ressourcen auflisten

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

Jobs auflisten

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

Ressourcen aktualisieren

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

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:

BigQuery Data Transfer Service verwenden

Weitere Informationen zur Verwendung des bq-Befehlszeilentools mit dem BigQuery Data Transfer Service finden Sie unter:

Fehler im bq-Befehlszeilentool beheben

In diesem Abschnitt erfahren Sie, wie Sie Probleme mit dem bq-Befehlszeilentool beheben.

gcloud-Befehlszeile auf dem neuesten Stand halten

Wenn Sie das bq-Befehlszeilentool über die Google Cloud CLI verwenden, achten Sie darauf, dass Sie die neuesten Funktionen und Fehlerkorrekturen des bq-Befehlszeilentools haben. Halten Sie dazu Ihre gcloud CLI auf dem neuesten Stand. Geben Sie den folgenden Befehl in Cloud Shell ein, um festzustellen, ob Sie die neueste Version der gcloud CLI ausführen:

gcloud components list

In den ersten beiden Zeilen der Ausgabe werden die Versionsnummer Ihrer aktuellen gcloud CLI-Installation und die Versionsnummer der neuesten verfügbaren gcloud CLI angezeigt. Wenn Sie feststellen, dass Ihre Version nicht mehr aktuell ist, können Sie Ihre gcloud CLI-Installation auf die neueste Version aktualisieren. Geben Sie dazu den folgenden Befehl in Cloud Shell ein:

gcloud components update

Debugging

Mit den folgenden Befehlen können Sie Fehler im bq-Befehlszeilentool beheben:

  • Gesendete und empfangene Anfragen ansehen. Fügen Sie das Flag --apilog=PATH_TO_FILE hinzu, um ein Log des Vorgangs in einer lokalen Datei zu speichern. Ersetzen Sie PATH_TO_FILE durch den Pfad, unter dem Sie das Log speichern möchten. Das bq-Befehlszeilentool 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 Pfads - oder stdout verwenden, wird das Log in der Google Cloud Console ausgegeben. Wenn Sie --apilog auf stderr setzen, erfolgt die Ausgabe in die Standardfehlerdatei. Verwenden Sie das Flag --httplib2_debuglevel=LOG_LEVEL, um mehr Anfragen zu protokollieren. Je höher LOG_LEVEL ist, desto mehr Informationen zu den HTTP-Anfragen werden protokolliert.

  • Fehlerbehebung. 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. Verwenden Sie das Flag --debug_mode, um weitere Informationen zu Fehlern bei der Ausführung zu erhalten.