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. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. BigQuery ist in neuen Projekten automatisch aktiviert. So aktivieren Sie BigQuery in einem vorhandenen Projekt:

   Enable the BigQuery API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

3. 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 -Konsole oder über die Google Cloud CLI eingeben.

• Wenn Sie das bq-Befehlszeilentool in der Google Cloud -Konsole 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 Konsole 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, bei dem Stringliterale in der Abfrage mit doppelten Anführungszeichen und die Abfrage selbst mit einfachen Anführungszeichen gekennzeichnet werden:

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

   Wenn Sie die Abfrage von einem anderen Ort 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.

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 derGoogle 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
• Bigtable-Daten abfragen
• Cloud Storage-Daten abfragen
• Google Drive-Daten 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
• Übertragungen verwalten

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. Bei einem höheren LOG_LEVEL werden mehr Informationen zu den HTTP-Anfragen 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. Weitere Informationen zu Fehlern während der Ausführung erhalten Sie mit dem Flag --debug_mode.