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.

Hinweise

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

1. Melden Sie sich bei Ihrem Google Cloud-Konto an. Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

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

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

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

   BigQuery API aktivieren.

   Aktivieren Sie die 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.
   Hinweis:Deaktivieren Sie die Abrechnung für Ihr Projekt, wenn Ihr Projekt ein Rechnungskonto hat und Sie die BigQuery-Sandbox verwenden möchten.

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.

• Wenn Sie das bq-Befehlszeilentool in der Google Cloud Console verwenden möchten, aktivieren Sie Cloud Shell:

  Cloud Shell aktivieren

• Wenn Sie das bq-Befehlszeilentool der gcloud CLI verwenden möchten, installieren und konfigurieren Sie die gcloud CLI.

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. Ersetzen Sie alle einfachen Anführungszeichen (') innerhalb der Abfrage durch doppelte Anführungszeichen ("). Prüfen Sie, ob die Abfrage in einfache Anführungszeichen (') gesetzt ist.
3. 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

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.

Hinweis: Es wird nicht empfohlen, eine .bigqueryrc-Datei mit dem Befehl bq init zu erstellen.

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.

  Hinweis: Sie können --nouse_legacy_sql nicht in .bigqueryrc 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:

• Dataset erstellen
• Leere Tabelle mit einer Schemadefinition erstellen
• Tabelle aus einem Abfrageergebnis erstellen
• Partitionierte Tabelle mit Aufnahmezeit erstellen
• Ansicht erstellen

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:

• Informationen zu Datasets abrufen
• Informationen zu Tabellen abrufen
• Informationen zu Ansichten abrufen

Ressourcen auflisten

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

• Datasets auflisten
• Tabellen auflisten
• Ansichten auflisten

Jobs auflisten

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

• Jobs auflisten

Ressourcen aktualisieren

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

• Dataset-Attribute aktualisieren
• Tabellenattribute aktualisieren
• Ansichtsattribute aktualisieren

Daten laden

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

• Avro-Daten aus Cloud Storage laden
• JSON-Daten aus Cloud Storage laden
• CSV-Daten aus Cloud Storage laden
• Daten aus einer lokalen Datei laden

Daten abfragen

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

• Abfragen ausführen
• Abfrageergebnisse schreiben
• Parametrisierte Abfragen ausführen

Externe Datenquellen verwenden

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

• Tabellendefinition mithilfe einer JSON-Schemadatei erstellen
• Cloud Bigtable-Daten mithilfe permanenter externer Tabellen abfragen
• Cloud Storage-Daten mit permanenten externen Tabellen abfragen
• Google Drive-Daten mit permanenten externen Tabellen abfragen

Daten exportieren

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

• In BigQuery gespeicherte Daten exportieren

BigQuery Data Transfer Service verwenden

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

• Amazon S3-Übertragung einrichten
• Campaign Manager-Übertragung einrichten
• Cloud Storage-Übertragung einrichten
• Google Ad Manager-Übertragung einrichten
• Google Ads-Übertragung einrichten
• Google Merchant Center-Übertragung einrichten (Beta)
• Google Play-Übertragung einrichten
• Search Ads 360-Übertragung einrichten (Beta)
• YouTube-Kanalübertragung einrichten
• Übertragung für einen YouTube-Rechteinhaber einrichten
• Daten von Amazon Redshift migrieren
• Daten aus Teradata migrieren

• Informationen zu Übertragungskonfigurationen abrufen
• Übertragungskonfigurationen auflisten
• Ausführungsverlauf ansehen
• Details zur Übertragungsausführung und Logmeldungen aufrufen
• Übertragung aktualisieren

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 weitere Anfragen zu protokollieren. Ein höherer LOG_LEVEL protokolliert mehr Informationen zu den HTTP-Anfragen.

• 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. Weitere Informationen zu Fehlern während der Ausführung erhalten Sie mit dem Flag --debug_mode.