CSV-Daten aus Cloud Storage laden

Sie können aus Cloud Storage geladene CSV-Daten in eine neue Tabelle oder Partition laden bzw. an eine vorhandene Tabelle oder Partition anfügen. Es ist außerdem möglich, eine Tabelle oder Partition zu überschreiben. Beim Laden von Daten in BigQuery werden diese in ein Spaltenformat für Capacitor (BigQuery-Speicherformat) umgewandelt.

Wenn Sie Daten aus Cloud Storage in eine BigQuery-Tabelle laden, muss sich das Dataset, das die Tabelle enthält, am selben regionalen oder multiregionalen Standort wie der Cloud Storage-Bucket befinden.

Informationen zum Laden von CSV-Daten aus einer lokalen Datei finden Sie unter Daten aus einer lokalen Datenquelle in BigQuery laden. Einige der in dieser Anleitung verlinkten Ressourcen sind ggf. nur auf Englisch verfügbar.

Jetzt testen

Wenn Sie mit Google Cloud noch nicht vertraut sind, erstellen Sie einfach ein Konto, um die Leistungsfähigkeit von BigQuery 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.

BigQuery kostenlos testen

Beschränkungen

Beim Laden von Daten aus einem Cloud Storage-Bucket in BigQuery gelten die folgenden Beschränkungen:

  • Wenn für den Speicherort Ihres Datasets ein anderer Wert als der multiregionale Wert US festgelegt ist, muss sich der Cloud Storage-Bucket in derselben Region befinden oder in derselben Multiregion enthalten sein wie das Dataset.
  • BigQuery übernimmt bei externen Datenquellen keine Garantie für die Datenkonsistenz. Werden die zugrunde liegenden Daten während der Ausführung der Abfrage geändert, kann dies zu einem unerwarteten Verhalten führen.
  • BigQuery unterstützt nicht die Cloud Storage-Objektversionierung. Wenn Sie dem Cloud Storage-URI eine Generierungsnummer hinzufügen, schlägt der Ladejob fehl.

Beachten Sie beim Laden von CSV-Dateien in BigQuery Folgendes:

  • CSV-Dateien unterstützen keine verschachtelten oder wiederholten Daten.
  • Entfernen Sie BOM-Zeichen (Bytereihenfolge). Sie können unerwartete Probleme verursachen.
  • Wenn Sie die GZIP-Komprimierung verwenden, kann BigQuery die Daten nicht parallel lesen. Das Laden komprimierter CSV-Daten in BigQuery ist langsamer als das Laden nicht komprimierter Daten. Siehe Komprimierte und unkomprimierte Daten laden.
  • Es ist nicht möglich, sowohl komprimierte als auch nicht komprimierte Dateien in denselben Ladejob einzubeziehen.
  • Die maximale Größe für eine GZIP-Datei beträgt 4 GB.
  • Beim Laden von CSV-Daten mithilfe der automatischen Schemaerkennung werden Header nicht automatisch erkannt, wenn alle Spalten Stringtypen sind. Fügen Sie in diesem Fall die Eingabe eine numerische Spalte hinzu oder deklarieren Sie das Schema explizit.
  • Wenn Sie CSV- oder JSON-Daten laden, muss für Werte in DATE-Spalten der Bindestrich (-) als Trennzeichen verwendet werden und das Datum muss das Format YYYY-MM-DD (Jahr-Monat-Tag) haben.
  • Wenn Sie JSON- oder CSV-Daten laden, muss für Werte in TIMESTAMP-Spalten im Datumsabschnitt des Zeitstempels der Bindestrich (-) oder der Schrägstrich (/) als Trennzeichen verwendet werden und das Datum muss eines der folgenden Formate haben: YYYY-MM-DD (Jahr-Monat-Tag) oder YYYY/MM/DD (Jahr/Monat/Tag). Im hh:mm:ss-Abschnitt (Stunde-Minute-Sekunde) des Zeitstempels muss als Trennzeichen ein Doppelpunkt (:) verwendet werden.
  • Ihre Dateien müssen die unter Limits für Ladejobs beschriebenen Größenbeschränkungen für CSV-Dateien erfüllen.

Hinweis

Erteilen Sie IAM-Rollen (Identity and Access Management), über die Nutzer die erforderlichen Berechtigungen zum Ausführen der einzelnen Aufgaben in diesem Dokument erhalten, und erstellen Sie ein Dataset zum Speichern Ihrer Daten.

Erforderliche Berechtigungen

Zum Laden von Daten in BigQuery benötigen Sie IAM-Berechtigungen, um einen Ladejob auszuführen und Daten in BigQuery-Tabellen und -Partitionen zu laden. Zum Laden von Daten aus Cloud Storage sind außerdem IAM-Berechtigungen für den Zugriff auf den Bucket erforderlich, der Ihre Daten enthält.

Berechtigungen zum Laden von Daten in BigQuery

Wenn Sie Daten in eine neue BigQuery-Tabelle oder -Partition laden oder eine vorhandene Tabelle oder Partition anfügen oder überschreiben möchten, benötigen Sie die folgenden IAM-Berechtigungen:

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.tables.update
  • bigquery.jobs.create

Die folgenden vordefinierten IAM-Rollen enthalten jeweils die Berechtigungen, die zum Laden von Daten in eine BigQuery-Tabelle oder -Partition erforderlich sind:

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin (einschließlich der Berechtigung bigquery.jobs.create)
  • bigquery.user (einschließlich der Berechtigung bigquery.jobs.create)
  • bigquery.jobUser (einschließlich der Berechtigung bigquery.jobs.create)

Wenn Sie die Berechtigung bigquery.datasets.create haben, können Sie außerdem mit einem Ladejob Tabellen in den von Ihnen erstellten Datasets anlegen und aktualisieren.

Weitere Informationen zu IAM-Rollen und Berechtigungen in BigQuery finden Sie unter Vordefinierte Rollen und Berechtigungen.

Berechtigungen zum Laden von Daten aus Cloud Storage

Um die Berechtigungen zu erhalten, die Sie zum Laden von Daten aus einem Cloud Storage-Bucket benötigen, bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Storage Admin (roles/storage.admin) für den Bucket zu erteilen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Laden von Daten aus einem Cloud Storage-Bucket erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Daten aus einem Cloud Storage-Bucket zu laden:

  • storage.buckets.get
  • storage.objects.get
  • storage.objects.list (required if you are using a URI wildcard)

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Dataset erstellen

Erstellen Sie ein BigQuery-Dataset zum Speichern Ihrer Daten.

CSV-Komprimierung

Mit dem Dienstprogramm gzip können Sie CSV-Dateien komprimieren. Beachten Sie, dass gzip eine vollständige Dateikomprimierung durchführt, im Gegensatz zur Komprimierung von Dateiinhalten, die von Komprimierungscodecs für andere Dateiformate wie Avro durchgeführt wird. Die Verwendung von gzip zur Komprimierung Ihrer CSV-Dateien kann sich auf die Leistung auswirken; Weitere Informationen zu den Vor- und Nachteilen finden Sie unter Komprimierte und unkomprimierte Daten laden.

CSV-Daten in eine Tabelle laden

Wählen Sie eine der folgenden Optionen, um CSV-Daten aus Cloud Storage in eine neue BigQuery-Tabelle zu laden:

Console


Klicken Sie auf Anleitung, um eine detaillierte Anleitung für diese Aufgabe direkt im Cloud Shell-Editor zu erhalten:

Anleitung


  1. Öffnen Sie in der Google Cloud Console die Seite BigQuery.

    BigQuery aufrufen

  2. Maximieren Sie im Bereich Explorer Ihr Projekt und wählen Sie dann ein Dataset aus.
  3. Klicken Sie im Abschnitt Dataset-Informationen auf Tabelle erstellen.
  4. Geben Sie im Bereich Tabelle erstellen die folgenden Details an:
    1. Wählen Sie im Abschnitt Quelle in der Liste Tabelle erstellen aus die Option Google Cloud Storage aus. Führen Sie anschließend folgende Schritte aus:
      1. Wählen Sie eine Datei aus dem Cloud Storage-Bucket aus oder geben Sie den Cloud Storage-URI ein. In der Google Cloud Console kann zwar nur ein URI eingefügt werden, aber Platzhalter werden unterstützt. Der Cloud Storage-Bucket muss sich am selben Standort wie das Dataset befinden, das die Tabelle enthält, die Sie erstellen, anhängen oder überschreiben möchten. Wählen Sie eine Quelldatei aus, um eine BigQuery-Tabelle zu erstellen
      2. Wählen Sie unter Dateiformat die Option CSV aus.
    2. Geben Sie im Bereich Ziel die folgenden Details an:
      1. Wählen Sie bei Dataset das Dataset aus, in dem Sie die Tabelle erstellen möchten.
      2. Geben Sie im Feld Tabelle den Namen der Tabelle ein, die Sie erstellen möchten.
      3. Achten Sie darauf, dass das Feld Tabellentyp auf Native Tabelle eingestellt ist.
    3. Geben Sie im Abschnitt Schema die Schemadefinition ein. Wählen Sie Automatisch erkennen aus, um die automatische Erkennung eines Schemas zu aktivieren. Sie können Schemainformationen manuell mit einer der folgenden Methoden eingeben:
      • Option 1: Klicken Sie auf Als Text bearbeiten und fügen Sie das Schema in Form eines JSON-Arrays ein. Generieren Sie das Schema mit demselben Verfahren wie beim Erstellen einer JSON-Schemadatei, wenn Sie ein JSON-Array verwenden. Sie können das Schema einer vorhandenen Tabelle im JSON-Format ansehen. Geben Sie dafür folgenden Befehl ein:
            bq show --format=prettyjson dataset.table
            
      • Option 2: Klicken Sie auf Feld hinzufügen und geben Sie das Tabellenschema ein. Geben Sie für jedes Feld Name, Typ und Modus an.
    4. Optional: Geben Sie Partitions- und Clustereinstellungen an. Weitere Informationen finden Sie unter Partitionierte Tabellen erstellen und Geclusterte Tabellen erstellen und verwenden.
    5. Klicken Sie auf Erweiterte Optionen und gehen Sie so vor:
      • Lassen Sie unter Write preference (Schreibeinstellung) die Option Write if empty (Schreiben, wenn leer) ausgewählt. Mit dieser Option wird eine neue Tabelle erstellt und Ihre Daten werden in diese Tabelle geladen.
      • Übernehmen Sie für Anzahl zulässiger Fehler den Standardwert 0 oder geben Sie die maximale Anzahl von Zeilen mit Fehlern an, die ignoriert werden können. Wenn die Anzahl der Zeilen mit Fehlern diesen Wert überschreitet, führt der Job zu einer invalid-Meldung und schlägt fehl. Diese Option gilt nur für CSV- und JSON-Dateien.
      • Wenn Sie Werte in einer Zeile ignorieren möchten, die im Schema der Tabelle nicht vorhanden sind, wählen Sie Unbekannte Werte aus.
      • Wählen Sie bei Feldtrennzeichen das Zeichen aus, das die Zellen in Ihrer CSV-Datei trennt: Komma, Tab, Senkrechter Strich oder Benutzerdefiniert. Wenn Sie Benutzerdefiniert auswählen, geben Sie das Trennzeichen in das Feld Benutzerdefiniertes Feldtrennzeichen ein. Der Standardwert ist Komma.
      • Geben Sie unter Zu überspringende Kopfzeilen die Anzahl der Kopfzeilen an, die am Anfang der CSV-Datei übersprungen werden sollen. Der Standardwert ist 0.
      • Klicken Sie unter Zeilenumbrüche in Abschnitten in Anführungszeichen auf das Kästchen Zeilenumbrüche in Abschnitten in Anführungszeichen zulassen, um in Anführungszeichen eingeschlossene Datenabschnitte mit Zeilenumbruchzeichen in einer CSV-Datei zuzulassen. Der Standardwert ist false.
      • Klicken Sie unter Unvollständige Zeilen auf das Kästchen Unvollständige Zeilen zulassen, um Zeilen in CSV-Dateien zuzulassen, in denen nachgestellte optionale Spalten fehlen. Die fehlenden Werte werden wie Nullen behandelt. Wenn die Option nicht aktiviert ist, werden Datensätze mit fehlenden nachgestellten Spalten wie fehlerhafte Datensätze behandelt. Wenn zu viele fehlerhafte Datensätze vorhanden sind, wird im Jobergebnis ein Fehler wegen ungültiger Werte zurückgegeben. Der Standardwert ist false.
      • Klicken Sie unter Verschlüsselung auf Vom Kunden verwalteter Schlüssel, um einen Cloud Key Management Service-Schlüssel zu verwenden. Wenn Sie die Einstellung Von Google verwalteter Schlüssel übernehmen, verschlüsselt BigQuery inaktive Daten.
    6. Klicken Sie auf Tabelle erstellen.

SQL

Verwenden Sie die DDL-Anweisung LOAD DATA. Im folgenden Beispiel wird eine CSV-Datei in die neue Tabelle mytable geladen:

  1. Öffnen Sie in der Google Cloud Console die Seite BigQuery.

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

    LOAD DATA OVERWRITE mydataset.mytable
    (x INT64,y STRING)
    FROM FILES (
      format = 'CSV',
      uris = ['gs://bucket/path/file.csv']);
    

  3. Klicken Sie auf Ausführen.

Informationen zum Ausführen von Abfragen finden Sie unter Interaktive Abfrage ausführen.

bq

Verwenden Sie den Befehl bq load, geben Sie CSV mit dem Flag --source_format an und fügen Sie einen Cloud Storage-URI ein. Sie können einen einzelnen URI, eine durch Kommas getrennte Liste von URIs oder einen URI mit Platzhalter einfügen. Geben Sie das Schema inline bzw. in einer Schemadefinitionsdatei an oder verwenden Sie die automatische Schemaerkennung. Wenn Sie kein Schema angeben, --autodetect false ist und die Zieltabelle existiert, wird das Schema der Zieltabelle verwendet.

Optional: Geben Sie das Flag --location an und legen Sie als Wert Ihren Standort fest.

Andere optionale Flags sind:

  • --allow_jagged_rows: Wenn dieses Flag angegeben ist, werden Zeilen in CSV-Dateien zugelassen, in denen nachgestellte optionale Spalten fehlen. Die fehlenden Werte werden wie Nullen behandelt. Wenn die Option nicht aktiviert ist, werden Datensätze mit fehlenden nachgestellten Spalten wie fehlerhafte Datensätze behandelt. Wenn zu viele fehlerhafte Datensätze vorhanden sind, wird im Jobergebnis ein Fehler wegen ungültiger Werte zurückgegeben. Der Standardwert ist false.
  • --allow_quoted_newlines: Wenn dieses Flag angegeben ist, werden in Anführungszeichen eingeschlossene Datenabschnitte mit Zeilenumbruchzeichen in einer CSV-Datei zugelassen. Der Standardwert ist false.
  • --field_delimiter: Das Zeichen, das die Begrenzung zwischen Spalten in den Daten angibt. Sowohl \t als auch tab sind als Tabulatortrennzeichen zulässig. Der Standardwert ist ,.
  • --null_marker: Ein optionaler benutzerdefinierter String, der einen NULL-Wert in CSV-Daten darstellt.
  • --skip_leading_rows: Gibt die Anzahl der Header-Zeilen an, die am Anfang der CSV-Datei übersprungen werden sollen. Der Standardwert ist 0.
  • --quote: Das Anführungszeichen zum Umschließen von Datensätzen. Der Standardwert ist ". Wenn Sie kein Anführungszeichen angeben möchten, verwenden Sie einen leeren String.
  • --max_bad_records: Eine Ganzzahl, die die Höchstzahl ungültiger Datensätze angibt, bevor der gesamte Job fehlschlägt. Der Standardwert ist 0. Es werden höchstens fünf Fehler pro Typ zurückgegeben, unabhängig vom Wert --max_bad_records.
  • --ignore_unknown_values: Wenn dieses Flag angegeben ist, werden zusätzliche, nicht erkannte Werte in CSV- oder JSON-Daten zugelassen und ignoriert.
  • --autodetect: Wenn dieses Flag angegeben ist, wird die automatische Schemaerkennung für CSV- und JSON-Daten aktiviert.
  • --time_partitioning_type: Aktiviert die zeitbasierte Partitionierung für eine Tabelle und legt den Partitionstyp fest. Mögliche Werte sind HOUR, DAY, MONTH und YEAR. Dieses Flag ist optional, wenn Sie eine Tabelle erstellen, die nach einer DATE-, DATETIME- oder TIMESTAMP-Spalte partitioniert wird. Der Standardpartitionstyp für die zeitbasierte Partitionierung ist DAY. Sie können die Partitionierungsspezifikation für eine vorhandene Tabelle nicht ändern.
  • --time_partitioning_expiration: Eine Ganzzahl, die (in Sekunden) angibt, wann eine zeitbasierte Partition gelöscht werden soll. Die Ablaufzeit entspricht dem UTC-Datum der Partition plus dem ganzzahligen Wert.
  • --time_partitioning_field: Die DATE- oder TIMESTAMP-Spalte zum Erstellen einer partitionierten Tabelle. Wenn die zeitbasierte Partitionierung ohne Angabe dieses Werts aktiviert wird, erstellt BigQuery eine nach Aufnahmezeit partitionierte Tabelle.
  • --require_partition_filter: Wenn diese Option aktiviert ist, müssen die Nutzer eine WHERE-Klausel zur Angabe der abzufragenden Partitionen einfügen. Das Anfordern eines Partitionsfilters kann die Kosten senken und die Leistung verbessern. Weitere Informationen finden Sie unter Partitionierte Tabellen abfragen.
  • --clustering_fields: Eine durch Kommas getrennte Liste mit bis zu vier Spaltennamen zum Erstellen einer geclusterten Tabelle.
  • --destination_kms_key: Der Cloud KMS-Schlüssel für die Verschlüsselung der Tabellendaten.
  • --column_name_character_map: Definiert den Umfang und die Handhabung von Zeichen in Spaltennamen mit der Option, flexible Spaltennamen zu aktivieren. Erfordert die Option --autodetect für CSV-Dateien. Weitere Informationen finden Sie unter load_option_list.

    Weitere Informationen zum Befehl bq load finden Sie unter:

    Weitere Informationen zu partitionierten Tabellen finden Sie unter:

    Weitere Informationen zu geclusterten Tabellen finden Sie unter:

    Weitere Informationen zur Tabellenverschlüsselung finden Sie unter:

Geben Sie den folgenden Befehl ein, um CSV-Daten in BigQuery zu laden:

bq --location=location load \
--source_format=format \
dataset.table \
path_to_source \
schema

Dabei gilt:

  • location ist Ihr Standort. Das Flag --location ist optional. Wenn Sie BigQuery beispielsweise in der Region Tokio verwenden, können Sie für das Flag den Wert asia-northeast1 festlegen. Mit der Datei .bigqueryrc können Sie einen Standardwert für den Standort festlegen.
  • format ist CSV.
  • dataset ist ein vorhandenes Dataset.
  • table ist der Name der Tabelle, in die Sie Daten laden.
  • path_to_source ist ein vollständig qualifizierter Cloud Storage-URI oder eine durch Kommas getrennte Liste von URIs. Platzhalter werden ebenfalls unterstützt.
  • schema ist ein gültiges Schema. Das Schema kann als lokale JSON-Datei bereitgestellt oder als Bestandteil des Befehls inline eingegeben werden. Sie können statt der Schemadefinition auch das Flag --autodetect verwenden.

Beispiele:

Mit dem folgenden Befehl werden Daten aus gs://mybucket/mydata.csv in eine Tabelle mit dem Namen mytable in mydataset geladen. Das Schema ist in einer lokalen Schemadatei namens myschema.json definiert.

    bq load \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

Mit dem folgenden Befehl werden Daten aus gs://mybucket/mydata.csv in eine Tabelle mit dem Namen mytable in mydataset geladen. Das Schema ist in einer lokalen Schemadatei namens myschema.json definiert. Die CSV-Datei enthält zwei Header-Zeilen. Wenn --skip_leading_rows nicht angegeben ist, wird standardmäßig davon ausgegangen, dass die Datei keine Header enthält.

    bq load \
    --source_format=CSV \
    --skip_leading_rows=2
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

Mit dem folgenden Befehl werden Daten aus gs://mybucket/mydata.csv in eine nach Aufnahmezeit partitionierte Tabelle mit dem Namen mytable in mydataset geladen: Das Schema ist in einer lokalen Schemadatei namens myschema.json definiert:

    bq load \
    --source_format=CSV \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

Mit dem folgenden Befehl werden Daten aus gs://mybucket/mydata.csv in eine neue partitionierte Tabelle mit dem Namen mytable in mydataset geladen. Die Tabelle ist nach der Spalte mytimestamp partitioniert. Das Schema ist in einer lokalen Schemadatei namens myschema.json definiert.

    bq load \
    --source_format=CSV \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

Mit dem folgenden Befehl werden Daten aus gs://mybucket/mydata.csv in eine Tabelle mit dem Namen mytable in mydataset geladen. Das Schema wird automatisch erkannt.

    bq load \
    --autodetect \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv

Mit dem folgenden Befehl werden Daten aus gs://mybucket/mydata.csv in eine Tabelle mit dem Namen mytable in mydataset geladen. Das Schema ist inline im Format field:data_type,field:data_type definiert.

    bq load \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    qtr:STRING,sales:FLOAT,year:STRING

Mit dem folgenden Befehl werden Daten aus mehreren Dateien in gs://mybucket/ in eine Tabelle namens mytable in mydataset geladen. Für den Cloud Storage-URI wird ein Platzhalter verwendet. Das Schema wird automatisch erkannt.

    bq load \
    --autodetect \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata*.csv

Mit dem folgenden Befehl werden Daten aus mehreren Dateien in gs://mybucket/ in eine Tabelle namens mytable in mydataset geladen. Der Befehl enthält eine durch Kommas getrennte Liste von Cloud Storage-URIs mit Platzhaltern. Das Schema ist in einer lokalen Schemadatei namens myschema.json definiert.

    bq load \
    --source_format=CSV \
    mydataset.mytable \
    "gs://mybucket/00/*.csv","gs://mybucket/01/*.csv" \
    ./myschema.json

API

  1. Erstellen Sie einen load-Job, der auf die Quelldaten in Cloud Storage verweist.

  2. Optional: Geben Sie Ihren Standort im Attribut location im Abschnitt jobReference der Jobressource an.

  3. Das Attribut source URIs muss vollständig qualifiziert sein und das Format gs://bucket/object haben. Jeder URI kann ein Platzhalterzeichen (*) enthalten.

  4. Geben Sie das CSV-Datenformat an. Legen Sie dazu das Attribut sourceFormat auf CSV fest.

  5. Rufen Sie zum Prüfen des Jobstatus jobs.get(job_id*) auf, wobei job_id die ID des Jobs ist, der von der ursprünglichen Anfrage zurückgegeben wurde.

    • Wenn status.state = DONE zurückgegeben wird, wurde der Job erfolgreich abgeschlossen.
    • Wenn das Attribut status.errorResult zurückgegeben wird, ist die Anfrage fehlgeschlagen. Das Objekt enthält in diesem Fall Angaben zur Fehlerursache. Wenn eine Anfrage fehlschlägt, wird keine Tabelle erstellt und es werden keine Daten geladen.
    • Wenn status.errorResult nicht vorhanden ist, wurde der Job erfolgreich abgeschlossen. Es können aber einige nicht schwerwiegende Fehler aufgetreten sein, z. B. Probleme beim Importieren einiger Zeilen. Nicht schwerwiegende Fehler werden im Attribut status.errors des Objekts für den zurückgegebenen Job aufgeführt.

API-Hinweise:

  • Ladejobs sind atomar und konsistent. Wenn ein Ladejob fehlschlägt, sind keine der zu ladenden Daten verfügbar. Wenn ein Ladejob erfolgreich ist, sind alle Daten verfügbar.

  • Erstellen Sie als Best Practice eine nur einmal vorkommende ID und übergeben Sie diese als jobReference.jobId, wenn jobs.insert zum Erstellen eines Ladejobs aufgerufen wird. Diese Vorgehensweise ist weniger anfällig für Netzwerkfehler, da der Client anhand der bekannten Job-ID einen Abruf oder einen neuen Versuch ausführen kann.

  • Das Aufrufen von jobs.insert für eine bestimmte Job-ID ist idempotent. Das bedeutet, dass Sie den Aufruf für dieselbe Job-ID beliebig oft wiederholen können. Höchstens einer dieser Vorgänge ist dann erfolgreich.

C#

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der C#-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery C# API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.


using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsCsv
{
    public void LoadTableGcsCsv(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        var destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            // The source format defaults to CSV; line below is optional.
            SourceFormat = FileFormat.Csv,
            SkipLeadingRows = 1
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob = loadJob.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.

        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

Go

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Go in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Go API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importCSVExplicitSchema demonstrates loading CSV data from Cloud Storage into a BigQuery
// table and providing an explicit schema for the data.
func importCSVExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
	}
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteEmpty

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Java in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

// Sample to load CSV data from Cloud Storage into a new BigQuery table
public class LoadCsvFromGcs {

  public static void runLoadCsvFromGcs() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadCsvFromGcs(datasetName, tableName, sourceUri, schema);
  }

  public static void loadCsvFromGcs(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Skip header row in the file.
      CsvOptions csvOptions = CsvOptions.newBuilder().setSkipLeadingRows(1).build();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri, csvOptions).setSchema(schema).build();

      // Load data from a GCS CSV file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("CSV from GCS successfully added during load append job");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Node.js in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.csv';

async function loadCSVFromGCS() {
  // Imports a GCS file into a table with manually defined schema.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

PHP

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von PHP in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery PHP API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.csv';
$schema = [
    'fields' => [
        ['name' => 'name', 'type' => 'string'],
        ['name' => 'post_abbr', 'type' => 'string']
    ]
];
$loadConfig = $table->loadFromStorage($gcsUri)->schema($schema)->skipLeadingRows(1);
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Verwenden Sie die Methode Client.load_table_from_uri(), um Daten aus einer CSV-Datei in Cloud Storage zu laden. Geben Sie eine explizite Schemadefinition an. Legen Sie dazu für den Wert des Attributs LoadJobConfig.schema eine Liste mit SchemaField-Objekten fest.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
    skip_leading_rows=1,
    # The source format defaults to CSV, so the line below is optional.
    source_format=bigquery.SourceFormat.CSV,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)  # Make an API request.
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Ruby in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Ruby API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

require "google/cloud/bigquery"

def load_table_gcs_csv dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, skip_leading: 1 do |schema|
    schema.string "name"
    schema.string "post_abbr"
  end
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done! # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

CSV-Daten in eine Tabelle mit spaltenbasierter Zeitpartitionierung laden

So laden Sie CSV-Daten aus Cloud Storage in eine BigQuery-Tabelle mit spaltenbasierten Zeitpartitionierung:

Go

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Go-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Go API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.


import (
	"context"
	"fmt"
	"time"

	"cloud.google.com/go/bigquery"
)

// importPartitionedTable demonstrates specifing time partitioning for a BigQuery table when loading
// CSV data from Cloud Storage.
func importPartitionedTable(projectID, destDatasetID, destTableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states-by-date.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
		{Name: "date", Type: bigquery.DateFieldType},
	}
	loader := client.Dataset(destDatasetID).Table(destTableID).LoaderFrom(gcsRef)
	loader.TimePartitioning = &bigquery.TimePartitioning{
		Field:      "date",
		Expiration: 90 * 24 * time.Hour,
	}
	loader.WriteDisposition = bigquery.WriteEmpty

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Java-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobId;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TimePartitioning;
import java.time.Duration;
import java.time.temporal.ChronoUnit;
import java.util.UUID;

public class LoadPartitionedTable {

  public static void runLoadPartitionedTable() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "/path/to/file.csv";
    loadPartitionedTable(datasetName, tableName, sourceUri);
  }

  public static void loadPartitionedTable(String datasetName, String tableName, String sourceUri)
      throws Exception {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      // Configure time partitioning. For full list of options, see:
      // https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#TimePartitioning
      TimePartitioning partitioning =
          TimePartitioning.newBuilder(TimePartitioning.Type.DAY)
              .setField("date")
              .setExpirationMs(Duration.of(90, ChronoUnit.DAYS).toMillis())
              .build();

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .build();

      // Create a job ID so that we can safely retry.
      JobId jobId = JobId.of(UUID.randomUUID().toString());
      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).setJobId(jobId).build());

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Data successfully loaded into time partitioned table during load job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println(
          "Data not loaded into time partitioned table during load job \n" + e.toString());
    }
  }
}

Node.js

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Node.js-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states-by-date.csv';

async function loadTablePartitioned() {
  // Load data into a table that uses column-based time partitioning.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_new_table';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const partitionConfig = {
    type: 'DAY',
    expirationMs: '7776000000', // 90 days
    field: 'date',
  };

  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
        {name: 'date', type: 'DATE'},
      ],
    },
    location: 'US',
    timePartitioning: partitionConfig,
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);
}

Python

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Python-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
        bigquery.SchemaField("date", "DATE"),
    ],
    skip_leading_rows=1,
    time_partitioning=bigquery.TimePartitioning(
        type_=bigquery.TimePartitioningType.DAY,
        field="date",  # Name of the column to use for partitioning.
        expiration_ms=7776000000,  # 90 days.
    ),
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states-by-date.csv"

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Wait for the job to complete.

table = client.get_table(table_id)
print("Loaded {} rows to table {}".format(table.num_rows, table_id))

CSV-Daten an eine Tabelle anfügen oder eine Tabelle mit CSV-Daten überschreiben

Zusätzliche Daten können entweder aus Quelldateien oder durch das Anfügen von Abfrageergebnissen in eine Tabelle geladen werden.

In der Google Cloud Console können Sie mit der Option Schreibeinstellung festlegen, welche Aktion beim Laden von Daten aus einer Quelldatei oder aus einem Abfrageergebnis ausgeführt werden soll.

Sie haben folgende Möglichkeiten, wenn Sie zusätzliche Daten in eine Tabelle laden:

Console-Option bq-Tool-Flag BigQuery API-Attribut Beschreibung
Schreiben, wenn leer Nicht unterstützt WRITE_EMPTY Daten werden nur geschrieben, wenn die Tabelle leer ist.
An Tabelle anfügen --noreplace oder --replace=false. Wenn --[no]replace nicht angegeben ist, werden Daten standardmäßig angefügt. WRITE_APPEND (Standard) Daten werden an das Ende der Tabelle angefügt.
Tabelle überschreiben --replace oder --replace=true WRITE_TRUNCATE Alle vorhandenen Daten in einer Tabelle werden gelöscht, bevor die neuen Daten geschrieben werden. Mit dieser Aktion werden auch das Tabellenschema und die Sicherheit auf Zeilenebene gelöscht und alle Cloud KMS-Schlüssel entfernt.

Wenn Sie Daten in eine vorhandene Tabelle laden, kann der Ladejob die Daten anfügen oder die Tabelle damit überschreiben.

Console

  1. Öffnen Sie in der Google Cloud Console die Seite BigQuery.

    BigQuery aufrufen

  2. Maximieren Sie im Bereich Explorer Ihr Projekt und wählen Sie dann ein Dataset aus.
  3. Klicken Sie im Abschnitt Dataset-Informationen auf Tabelle erstellen.
  4. Geben Sie im Bereich Tabelle erstellen die folgenden Details an:
    1. Wählen Sie im Abschnitt Quelle in der Liste Tabelle erstellen aus die Option Google Cloud Storage aus. Führen Sie anschließend folgende Schritte aus:
      1. Wählen Sie eine Datei aus dem Cloud Storage-Bucket aus oder geben Sie den Cloud Storage-URI ein. In der Google Cloud Console kann zwar nur ein URI eingefügt werden, aber Platzhalter werden unterstützt. Der Cloud Storage-Bucket muss sich am selben Standort wie das Dataset befinden, das die Tabelle enthält, die Sie erstellen, anhängen oder überschreiben möchten. Wählen Sie eine Quelldatei aus, um eine BigQuery-Tabelle zu erstellen
      2. Wählen Sie unter Dateiformat die Option CSV aus.
    2. Geben Sie im Bereich Ziel die folgenden Details an:
      1. Wählen Sie bei Dataset das Dataset aus, in dem Sie die Tabelle erstellen möchten.
      2. Geben Sie im Feld Tabelle den Namen der Tabelle ein, die Sie erstellen möchten.
      3. Achten Sie darauf, dass das Feld Tabellentyp auf Native Tabelle eingestellt ist.
    3. Geben Sie im Abschnitt Schema die Schemadefinition ein. Wählen Sie Automatisch erkennen aus, um die automatische Erkennung eines Schemas zu aktivieren. Sie können Schemainformationen manuell mit einer der folgenden Methoden eingeben:
      • Option 1: Klicken Sie auf Als Text bearbeiten und fügen Sie das Schema in Form eines JSON-Arrays ein. Generieren Sie das Schema mit demselben Verfahren wie beim Erstellen einer JSON-Schemadatei, wenn Sie ein JSON-Array verwenden. Sie können das Schema einer vorhandenen Tabelle im JSON-Format ansehen. Geben Sie dafür folgenden Befehl ein:
            bq show --format=prettyjson dataset.table
            
      • Option 2: Klicken Sie auf Feld hinzufügen und geben Sie das Tabellenschema ein. Geben Sie für jedes Feld Name, Typ und Modus an.
    4. Optional: Geben Sie Partitions- und Clustereinstellungen an. Weitere Informationen finden Sie unter Partitionierte Tabellen erstellen und Geclusterte Tabellen erstellen und verwenden. Sie können eine Tabelle nicht durch Anfügen oder Überschreiben von Daten in eine partitionierte oder geclusterte Tabelle konvertieren. Die Google Cloud Console unterstützt nicht das Anfügen oder Überschreiben von Daten in partitionierten oder geclusterten Tabellen in einem Ladejob.
    5. Klicken Sie auf Erweiterte Optionen und gehen Sie so vor:
      • Wählen Sie unter Schreibeinstellung die Option An Tabelle anfügen oder Tabelle überschreiben aus.
      • Übernehmen Sie für Anzahl zulässiger Fehler den Standardwert 0 oder geben Sie die maximale Anzahl von Zeilen mit Fehlern an, die ignoriert werden können. Wenn die Anzahl der Zeilen mit Fehlern diesen Wert überschreitet, führt der Job zu einer invalid-Meldung und schlägt fehl. Diese Option gilt nur für CSV- und JSON-Dateien.
      • Wenn Sie Werte in einer Zeile ignorieren möchten, die im Schema der Tabelle nicht vorhanden sind, wählen Sie Unbekannte Werte aus.
      • Wählen Sie bei Feldtrennzeichen das Zeichen aus, das die Zellen in Ihrer CSV-Datei trennt: Komma, Tab, Senkrechter Strich oder Benutzerdefiniert. Wenn Sie Benutzerdefiniert auswählen, geben Sie das Trennzeichen in das Feld Benutzerdefiniertes Feldtrennzeichen ein. Der Standardwert ist Komma.
      • Geben Sie unter Zu überspringende Kopfzeilen die Anzahl der Kopfzeilen an, die am Anfang der CSV-Datei übersprungen werden sollen. Der Standardwert ist 0.
      • Klicken Sie unter Zeilenumbrüche in Abschnitten in Anführungszeichen auf das Kästchen Zeilenumbrüche in Abschnitten in Anführungszeichen zulassen, um in Anführungszeichen eingeschlossene Datenabschnitte mit Zeilenumbruchzeichen in einer CSV-Datei zuzulassen. Der Standardwert ist false.
      • Klicken Sie unter Unvollständige Zeilen auf das Kästchen Unvollständige Zeilen zulassen, um Zeilen in CSV-Dateien zuzulassen, in denen nachgestellte optionale Spalten fehlen. Die fehlenden Werte werden wie Nullen behandelt. Wenn die Option nicht aktiviert ist, werden Datensätze mit fehlenden nachgestellten Spalten wie fehlerhafte Datensätze behandelt. Wenn zu viele fehlerhafte Datensätze vorhanden sind, wird im Jobergebnis ein Fehler wegen ungültiger Werte zurückgegeben. Der Standardwert ist false.
      • Klicken Sie unter Verschlüsselung auf Vom Kunden verwalteter Schlüssel, um einen Cloud Key Management Service-Schlüssel zu verwenden. Wenn Sie die Einstellung Von Google verwalteter Schlüssel übernehmen, verschlüsselt BigQuery inaktive Daten.
    6. Klicken Sie auf Tabelle erstellen.

SQL

Verwenden Sie die DDL-Anweisung LOAD DATA. Im folgenden Beispiel wird eine CSV-Datei an die Tabelle mytable angehängt:

  1. Öffnen Sie in der Google Cloud Console die Seite BigQuery.

    BigQuery aufrufen

  2. Geben Sie im Abfrageeditor die folgende Anweisung ein:

    LOAD DATA INTO mydataset.mytable
    FROM FILES (
      format = 'CSV',
      uris = ['gs://bucket/path/file.csv']);
    

  3. Klicken Sie auf Ausführen.

Informationen zum Ausführen von Abfragen finden Sie unter Interaktive Abfrage ausführen.

bq

Verwenden Sie den Befehl bq load, geben Sie CSV mit dem Flag --source_format an und fügen Sie einen Cloud Storage-URI ein. Sie können einen einzelnen URI, eine durch Kommas getrennte Liste von URIs oder einen URI mit Platzhalter einfügen.

Geben Sie das Schema inline bzw. in einer Schemadefinitionsdatei an oder verwenden Sie die automatische Schemaerkennung. Wenn Sie kein Schema angeben, --autodetect false ist und die Zieltabelle existiert, wird das Schema der Zieltabelle verwendet.

Geben Sie das Flag --replace an, um die Tabelle zu überschreiben. Verwenden Sie das Flag --noreplace, um Daten an die Tabelle anzufügen. Wenn kein Flag angegeben ist, werden Daten standardmäßig angefügt.

Das Schema der Tabelle kann beim Anfügen oder Überschreiben von Daten geändert werden. Weitere Informationen zu unterstützten Schemaänderungen während eines Ladevorgangs finden Sie unter Tabellenschemas ändern.

Optional: Geben Sie das Flag --location an und legen Sie als Wert Ihren Standort fest.

Andere optionale Flags sind:

  • --allow_jagged_rows: Wenn dieses Flag angegeben ist, werden Zeilen in CSV-Dateien zugelassen, in denen nachgestellte optionale Spalten fehlen. Die fehlenden Werte werden wie Nullen behandelt. Wenn die Option nicht aktiviert ist, werden Datensätze mit fehlenden nachgestellten Spalten wie fehlerhafte Datensätze behandelt. Wenn zu viele fehlerhafte Datensätze vorhanden sind, wird im Jobergebnis ein Fehler wegen ungültiger Werte zurückgegeben. Der Standardwert ist false.
  • --allow_quoted_newlines: Wenn dieses Flag angegeben ist, werden in Anführungszeichen eingeschlossene Datenabschnitte mit Zeilenumbruchzeichen in einer CSV-Datei zugelassen. Der Standardwert ist false.
  • --field_delimiter: Das Zeichen, das die Begrenzung zwischen Spalten in den Daten angibt. Sowohl \t als auch tab sind als Tabulatortrennzeichen zulässig. Der Standardwert ist ,.
  • --null_marker: Ein optionaler benutzerdefinierter String, der einen NULL-Wert in CSV-Daten darstellt.
  • --skip_leading_rows: Gibt die Anzahl der Header-Zeilen an, die am Anfang der CSV-Datei übersprungen werden sollen. Der Standardwert ist 0.
  • --quote: Das Anführungszeichen zum Umschließen von Datensätzen. Der Standardwert ist ". Wenn Sie kein Anführungszeichen angeben möchten, verwenden Sie einen leeren String.
  • --max_bad_records: Eine Ganzzahl, die die Höchstzahl ungültiger Datensätze angibt, bevor der gesamte Job fehlschlägt. Der Standardwert ist 0. Es werden höchstens fünf Fehler pro Typ zurückgegeben, unabhängig vom Wert --max_bad_records.
  • --ignore_unknown_values: Wenn dieses Flag angegeben ist, werden zusätzliche, nicht erkannte Werte in CSV- oder JSON-Daten zugelassen und ignoriert.
  • --autodetect: Wenn dieses Flag angegeben ist, wird die automatische Schemaerkennung für CSV- und JSON-Daten aktiviert.
  • --destination_kms_key: Der Cloud KMS-Schlüssel für die Verschlüsselung der Tabellendaten.
bq --location=location load \
--[no]replace \
--source_format=format \
dataset.table \
path_to_source \
schema

Dabei gilt:

  • location ist Ihr Standort. Das Flag --location ist optional. Mit der Datei .bigqueryrc können Sie einen Standardwert für den Standort festlegen.
  • format ist CSV.
  • dataset ist ein vorhandenes Dataset.
  • table ist der Name der Tabelle, in die Sie Daten laden.
  • path_to_source ist ein vollständig qualifizierter Cloud Storage-URI oder eine durch Kommas getrennte Liste von URIs. Platzhalter werden ebenfalls unterstützt.
  • schema ist ein gültiges Schema. Das Schema kann als lokale JSON-Datei bereitgestellt oder als Bestandteil des Befehls inline eingegeben werden. Sie können statt der Schemadefinition auch das Flag --autodetect verwenden.

Beispiele:

Der folgende Befehl lädt Daten aus gs://mybucket/mydata.csv und überschreibt eine Tabelle namens mytable in mydataset. Das Schema wird mithilfe der automatischen Schemaerkennung definiert.

    bq load \
    --autodetect \
    --replace \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv

Mit dem folgenden Befehl werden Daten aus gs://mybucket/mydata.csv geladen und an eine Tabelle namens mytable in mydataset angefügt. Das Schema wird mithilfe der JSON-Schemadatei myschema.json definiert.

    bq load \
    --noreplace \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

API

  1. Erstellen Sie einen load-Job, der auf die Quelldaten in Cloud Storage verweist.

  2. Optional: Geben Sie Ihren Standort im Attribut location im Abschnitt jobReference der Jobressource an.

  3. Das Attribut source URIs muss vollständig qualifiziert sein und das Format gs://bucket/object haben. Sie können mehrere URIs als durch Kommas getrennte Liste einfügen. Platzhalter werden ebenfalls unterstützt.

  4. Geben Sie das Datenformat an. Legen Sie dazu das Attribut configuration.load.sourceFormat auf CSV fest.

  5. Geben Sie die Schreibeinstellung an. Legen Sie dazu das Attribut configuration.load.writeDisposition auf WRITE_TRUNCATE oder WRITE_APPEND fest.

Go

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Go in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Go API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importCSVTruncate demonstrates loading data from CSV data in Cloud Storage and overwriting/truncating
// data in the existing table.
func importCSVTruncate(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.csv")
	gcsRef.SourceFormat = bigquery.CSV
	gcsRef.AutoDetect = true
	gcsRef.SkipLeadingRows = 1
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteTruncate

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Java in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to overwrite the BigQuery table data by loading a CSV file from GCS
public class LoadCsvFromGcsTruncate {

  public static void runLoadCsvFromGcsTruncate() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    loadCsvFromGcsTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadCsvFromGcsTruncate(String datasetName, String tableName, String sourceUri)
      throws Exception {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);

      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(WriteDisposition.WRITE_TRUNCATE)
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job loadJob = bigquery.create(JobInfo.of(configuration));

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Table is successfully overwritten by CSV file loaded from GCS");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Node.js in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Node.js API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Wenn Sie die Zeilen in einer vorhandenen Tabelle ersetzen möchten, legen Sie den Wert writeDisposition im Parameter metadata auf 'WRITE_TRUNCATE' fest.

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.csv';

async function loadCSVFromGCSTruncate() {
  /**
   * Imports a GCS file into a table and overwrites
   * table data if table already exists.
   */

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    // Set the write disposition to overwrite existing table data.
    writeDisposition: 'WRITE_TRUNCATE',
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);
  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der PHP-Einrichtungsanleitung in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery PHP API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableId = 'The BigQuery table ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.csv';
$loadConfig = $table->loadFromStorage($gcsUri)->skipLeadingRows(1)->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});

// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

Wenn Sie die Zeilen in einer vorhandenen Tabelle ersetzen möchten, legen Sie das Attribut LoadJobConfig.write_disposition auf die SourceFormat WRITE_TRUNCATE fest.

import six

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

body = six.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    source_format=bigquery.SourceFormat.CSV,
    skip_leading_rows=1,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Mit Hive partitionierte CSV-Daten laden

BigQuery unterstützt das Laden von mit Hive partitionierten CSV-Daten, die in Cloud Storage gespeichert sind, und füllt die Hive-Partitionierungsspalten so aus, als wären Sie Spalten in der verwalteten BigQuery-Zieltabelle. Weitere Informationen finden Sie unter Extern partitionierte Daten aus Cloud Storage laden.

Details zum Laden von CSV-Daten

In diesem Abschnitt wird beschrieben, wie BigQuery verschiedene CSV-Formatierungsoptionen verarbeitet.

Codierung

BigQuery geht davon aus, dass CSV-Daten eine UTF-8-Codierung aufweisen. Wenn Sie CSV-Dateien mit anderen unterstützten Codierungstypen haben, sollten Sie die Codierung explizit angeben, damit BigQuery die Daten ordnungsgemäß in UTF-8 konvertieren kann.

BigQuery unterstützt folgende Codierungstypen für CSV-Dateien:

  • UTF-8
  • ISO-8859-1
  • UTF-16BE (UTF-16 Big Endian)
  • UTF-16LE (UTF-16 Little Endian)
  • UTF-32BE (UTF-32 Big Endian)
  • UTF-32LE (UTF-32 Little Endian)

Wenn Sie keine Codierung oder die UTF-8-Codierung angeben, wenn die CSV-Datei nicht UTF-8-codiert ist, versucht BigQuery, die Daten in UTF-8 zu konvertieren. Im Allgemeinen werden bei einer ISO-8859-1-codierten CSV-Datei Ihre Daten zwar erfolgreich geladen, aber möglicherweise nicht genau gemäß Ihren Erwartungen. Wenn die CSV-Datei mit UTF-16BE, UTF-16LE, UTF-32BE oder UTF-32LE codiert ist, kann das Laden fehlschlagen. Geben Sie mit dem Flag --encoding die richtige Codierung an, um unerwartete Fehler zu vermeiden.

Wenn BigQuery ein anderes Zeichen als das ASCII-Zeichen 0 nicht konvertieren kann, konvertiert BigQuery das Zeichen in das standardmäßige Unicode-Ersetzungszeichen: �.

Feldtrennzeichen:

Trennzeichen in CSV-Dateien können einzelne Zeichen sein. Wenn die Quelldatei die ISO-8859-1-Codierung verwendet, kann jedes Zeichen ein Trennzeichen sein. Wenn die Quelldatei die UTF-8-Codierung verwendet, kann jedes Zeichen im Dezimalbereich 1–127 (U+0001-U+007F) ohne Änderung verwendet werden. Sie können ein ISO-8859-1-Zeichen außerhalb dieses Bereichs als Trennzeichen einfügen und BigQuery interpretiert es richtig. Wenn Sie jedoch ein Multibyte-Zeichen als Trennzeichen verwenden, werden einige der Byte falsch als Teil des Feldwerts interpretiert.

Als bewährte Praxis empfiehlt sich die Verwendung von Standardtrennzeichen, wie z. B. Tab, senkrechter Strich oder Komma. Der Standardwert ist ein Komma.

Datentypen

Boolean. BigQuery kann eines der folgenden Paare für boolesche Daten parsen: 1 oder 0, true oder false, t oder f, yes oder no oder y oder n (Groß-/Kleinschreibung wird nicht berücksichtigt). Die automatische Schemaerkennung erkennt alle Werte außer 0 und 1 automatisch.

Byte Spalten mit BYTES-Typen müssen als Base64 codiert sein.

Date. Spalten mit DATE-Typen müssen das Format YYYY-MM-DD haben.

Datetime. Spalten mit DATETIME-Typen müssen das Format YYYY-MM-DD HH:MM:SS[.SSSSSS] haben.

Geografie: Spalten mit GEOGRAFIE-Typen müssen Strings in einem der folgenden Formate enthalten:

  • Well-known Text (WKT)
  • Well-known Binary (WKB)
  • GeoJSON

Wenn Sie WKB verwenden, sollte der Wert hex-codiert sein.

Die folgende Liste enthält Beispiele für gültige Daten:

  • WKT: POINT(1 2)
  • GeoJSON: { "type": "Point", "coordinates": [1, 2] }
  • Hex-codiertes WKB: 0101000000feffffffffffef3f0000000000000040

Lesen Sie vor dem Laden von Geografie-Daten auch den Abschnitt Raumbezogene Daten laden.

Intervall. Spalten mit INTERVAL-Typen müssen das Format Y-M D H:M:S[.F] haben, wobei gilt:

  • Y = Jahr. Unterstützter Bereich ist 0-10.000.
  • M = Monat. Unterstützter Bereich ist 1-12.
  • D = Tag. Unterstützter Bereich ist 1-[letzter Tag des angegebenen Monats].
  • H = Stunde.
  • M = Minute.
  • S = Sekunde.
  • [.F] = Bruchteile einer Sekunde bis zu sechs Stellen mit Genauigkeit bis zu Mikrosekunden.

Um einen negativen Wert anzugeben, stellen Sie dem Wert einen Bindestrich (-) voran.

Die folgende Liste enthält Beispiele für gültige Daten:

  • 10-6 0 0:0:0
  • 0-0 -5 0:0:0
  • 0-0 0 0:0:1.25

Zum Laden von INTERVALL-Daten müssen Sie den Befehl bq load verwenden und das Flag --schema verwenden, um ein Schema anzugeben. Sie können INTERVALL-Daten nicht über die Console hochladen.

JSON. Anführungszeichen werden mit der Zwei-Zeichen-Sequenz "" maskiert. Weitere Informationen finden Sie in einem Beispiel für das Laden von JSON-Daten aus einer CSV-Datei.

Zeit: Spalten mit TIME-Typen müssen das Format HH:MM:SS[.SSSSSS] haben.

Timestamp. BigQuery akzeptiert verschiedene Zeitstempelformate. Der Zeitstempel muss einen Datumsteil und einen Zeitteil enthalten.

  • Der Datumsteil kann das Format YYYY-MM-DD oder YYYY/MM/DD haben.

  • Der Zeitstempelteil muss als HH:MM[:SS[.SSSSSS]] formatiert sein. Sekunden und Sekundenbruchteile sind dabei optional.

  • Datum und Uhrzeit müssen durch ein Leerzeichen oder ein "T" getrennt sein.

  • Optional kann dem Datum und der Uhrzeit ein UTC-Versatz oder der UTC-Zonenbezeichner (Z) folgen. Weitere Informationen finden Sie unter Zeitzonen.

Alle folgenden Zeitstempelwerte sind zulässig:

  • 2018-08-19 12:11
  • 2018-08-19 12:11:35
  • 2018-08-19 12:11:35.22
  • 2018/08/19 12:11
  • 2018-07-05 12:54:00 UTC
  • 2018-08-19 07:11:35.220 -05:00
  • 2018-08-19T12:11:35.220Z

Wenn Sie ein Schema angeben, akzeptiert BigQuery als Zeitstempelwerte auch die Zeit der Unix-Epoche. Die automatische Schemaerkennung erkennt diesen Fall jedoch nicht und behandelt den Wert stattdessen als numerischen Typ oder als Stringtyp.

Beispiele für Zeitstempelwerte der Unix-Epoche:

  • 1534680695
  • 1.534680695e11

RANGE (Vorschau). Wird in CSV-Dateien im Format [LOWER_BOUND, UPPER_BOUND) dargestellt, wobei LOWER_BOUND und UPPER_BOUND gültige Strings DATE, DATETIME oder TIMESTAMP sind. NULL und UNBOUNDED stellen unbegrenzte Start- oder Endwerte dar.

Das folgende Beispiel zeigt CSV-Werte für RANGE<DATE>:

  • "[2020-01-01, 2021-01-01)"
  • "[UNBOUNDED, 2021-01-01)"
  • "[2020-03-01, NULL)"
  • "[UNBOUNDED, UNBOUNDED)"

Automatische Schemaerkennung

In diesem Abschnitt wird das Verhalten der automatischen Schemaerkennung beim Laden von CSV-Dateien beschrieben.

CSV-Trennzeichen

BigQuery erkennt die folgenden Trennzeichen:

  • Komma ( , )
  • Senkrechter Strich ( | )
  • Tabulator ( \t )

CSV-Header

BigQuery leitet Header ab, indem es die erste Zeile einer Datei mit anderen Zeilen in der Datei vergleicht. Wenn die erste Zeile nur Strings enthält und die anderen Zeilen andere Datentypen enthalten, geht BigQuery davon aus, dass es sich bei der ersten Zeile um eine Kopfzeile handelt. BigQuery weist Spaltennamen basierend auf den Feldnamen in der Kopfzeile zu. Die Namen werden möglicherweise entsprechend den Benennungsregeln für Spalten in BigQuery geändert. Zum Beispiel werden Leerzeichen durch Unterstriche ersetzt.

Andernfalls geht BigQuery davon aus, dass die erste Zeile eine Datenzeile ist und weist allgemeine Spaltennamen wie string_field_1 zu. Beachten Sie, dass die Spaltennamen nach dem Erstellen einer Tabelle nicht mehr im Schema aktualisiert werden können. Sie können die Namen jedoch manuell ändern, nachdem die Tabelle erstellt wurde. Eine weitere Option ist die Bereitstellung eines expliziten Schemas anstelle der automatischen Erkennung.

Möglicherweise haben Sie eine CSV-Datei mit einer Kopfzeile, in der alle Datenfelder Strings sind. In diesem Fall erkennt BigQuery nicht automatisch, dass die erste Zeile ein Header ist. Verwenden Sie die Option --skip_leading_rows, um die Kopfzeile zu überspringen. Andernfalls wird der Header als Daten importiert. In diesem Fall sollten Sie auch ein explizites Schema angeben, damit Sie Spaltennamen zuweisen können.

CSV-Zeilenvorschübe in Anführungszeichen

BigQuery erkennt Zeilenvorschubzeichen in Anführungszeichen in einer CSV-Datei und interpretiert das Zeilenvorschubzeichen in Anführungszeichen nicht als Zeilengrenze.

Fehler beim Parsen beheben

Wenn beim Parsen Ihrer CSV-Dateien ein Problem auftritt, wird die Ressource errors des Ladejobs mit den Fehlerdetails gefüllt.

Im Allgemeinen identifizieren diese Fehler den Anfang der problematischen Zeile mit einem Byte-Offset. Bei unkomprimierten Dateien können Sie mit dem Argument --recursive auf gcloud storage zugreifen, um auf die relevante Zeile zuzugreifen.

Führen Sie beispielsweise den Befehl bq load aus und erhalten Sie eine Fehlermeldung:

bq load
    --skip_leading_rows=1 \
    --source_format=CSV \
    mydataset.mytable \
    gs://my-bucket/mytable.csv \
    'Number:INTEGER,Name:STRING,TookOffice:STRING,LeftOffice:STRING,Party:STRING'

Der Fehler in der Ausgabe sieht in etwa so aus:

Waiting on bqjob_r5268069f5f49c9bf_0000018632e903d7_1 ... (0s)
Current status: DONE
BigQuery error in load operation: Error processing job
'myproject:bqjob_r5268069f5f49c9bf_0000018632e903d7_1': Error while reading
data, error message: Error detected while parsing row starting at position: 1405.
Error: Data between close quote character (") and field separator.
File: gs://my-bucket/mytable.csv
Failure details:
- gs://my-bucket/mytable.csv: Error while reading data,
error message: Error detected while parsing row starting at
position: 1405. Error: Data between close quote character (") and
field separator. File: gs://my-bucket/mytable.csv
- Error while reading data, error message: CSV processing encountered
too many errors, giving up. Rows: 22; errors: 1; max bad: 0; error
percent: 0

Basierend auf dem vorherigen Fehler ist in der Datei ein Formatfehler aufgetreten. Führen Sie den Befehl gcloud storage cat aus, um den Inhalt der Datei aufzurufen:

gcloud storage cat 1405-1505 gs://my-bucket/mytable.csv --recursive

Die Ausgabe sieht in etwa so aus:

16,Abraham Lincoln,"March 4, 1861","April 15, "1865,Republican
18,Ulysses S. Grant,"March 4, 1869",
...

Basierend auf der Ausgabe der Datei ist das Problem ein falsch platziertes Zitat in "April 15, "1865.

Komprimierte CSV-Dateien

Das Debugging von Parsing-Fehlern ist für komprimierte CSV-Dateien schwieriger, da sich der gemeldete Byte-Offset auf den Speicherort in der unkomprimierten Datei bezieht. Mit dem folgenden gcloud storage cat-Befehl wird die Datei aus Cloud Storage gestreamt, dekomprimiert die Datei, identifiziert den entsprechenden Byte-Offset und gibt die Zeile mit dem Formatfehler aus:

gcloud storage cat gs://my-bucket/mytable.csv.gz | gunzip - | tail -c +1406 | head -n 1

Die Ausgabe sieht in etwa so aus:

16,Abraham Lincoln,"March 4, 1861","April 15, "1865,Republican

CSV-Optionen

Wenn Sie ändern möchten, wie BigQuery CSV-Daten parst, geben Sie in der Google Cloud Console, dem bq-Befehlszeilentool oder der API zusätzliche Optionen an.

Weitere Informationen zum CSV-Format finden Sie unter RFC 4180.

CSV-Option Console-Option bq-Tool-Flag BigQuery API-Attribut Beschreibung
Feldtrennzeichen Feldtrennzeichen: Komma, Tabulatorzeichen, senkrechter Strich, benutzerdefiniert -F oder --field_delimiter fieldDelimiter (Java, Python) (Optional) Das Trennzeichen für Felder in einer CSV-Datei. Das Trennzeichen kann ein beliebiges ISO-8859-1-Einzelbytezeichen sein. BigQuery konvertiert den String in ISO-8859-1-Codierung und verwendet das erste Byte des codierten Strings, um die Daten in ihrer binären Rohform aufzuteilen. BigQuery unterstützt auch die Escapesequenz "\t" zur Eingabe eines Tabulatortrennzeichens. Der Standardwert ist ein Komma (",").
Überschriftszeilen Zu überspringende Headerzeilen --skip_leading_rows skipLeadingRows (Java, Python) (Optional) Eine Ganzzahl, die die Anzahl der Kopfzeilen in den Quelldaten angibt.
Anzahl der zulässigen fehlerhaften Datensätze Anzahl zulässiger Fehler --max_bad_records maxBadRecords (Java, Python) (Optional) Die maximale Anzahl fehlerhafter Datensätze, die BigQuery beim Ausführen des Jobs ignorieren darf. Wenn die Anzahl fehlerhafter Datensätze diesen Wert überschreitet, wird im Jobergebnis ein Fehler wegen ungültiger Werte zurückgegeben. Der Standardwert ist 0, was erfordert, dass alle Datensätze gültig sind.
Zeilenumbruchzeichen Zeilenumbrüche in Abschnitten in Anführungszeichen zulassen --allow_quoted_newlines allowQuotedNewlines (Java, Python) (Optional) Gibt an, ob in Anführungszeichen eingeschlossene Datenabschnitte mit Zeilenumbruchzeichen in einer CSV-Datei zulässig sind. Der Standardwert ist "false".
Benutzerdefinierte Nullwerte Keine --null_marker nullMarker (Java, Python) Optional: Gibt einen String an, der einen Nullwert in einer CSV-Datei darstellt. Wenn Sie beispielsweise "\N" angeben, interpretiert BigQuery beim Laden einer CSV-Datei "\N" als Nullwert. Der Standardwert ist ein leerer String. Wenn Sie dieses Attribut auf einen benutzerdefinierten Wert setzen, gibt BigQuery einen Fehler aus, falls ein leerer String vorhanden ist. Dies gilt für alle Datentypen, mit Ausnahme von STRING und BYTE. Bei STRING- und BYTE-Spalten interpretiert BigQuery den leeren String als leeren Wert.
Optionale Spalten am Ende Unvollständige Zeilen zulassen --allow_jagged_rows allowJaggedRows (Java, Python) (Optional) Lässt Zeilen zu, in denen nachgestellte optionale Spalten fehlen. Die fehlenden Werte werden wie Nullen behandelt. Ist diese Option auf "false" gesetzt, werden Datensätze mit fehlenden nachgestellten Spalten wie fehlerhafte Datensätze behandelt. Wenn zu viele fehlerhafte Datensätze vorhanden sind, wird im Jobergebnis ein Fehler wegen ungültiger Werte zurückgegeben. Der Standardwert ist "false". Nur für CSV anwendbar, bei anderen Formaten wird die Option ignoriert.
Unbekannte Werte Unbekannte Werte ignorieren --ignore_unknown_values ignoreUnknownValues (Java, Python) (Optional) Gibt an, ob BigQuery zusätzliche Werte zulassen soll, die nicht im Tabellenschema enthalten sind. Wird diese Option auf "true" gesetzt, werden die zusätzlichen Werte ignoriert. Bei "false" werden Datensätze mit zusätzlichen Spalten wie fehlerhafte Datensätze behandelt. Wenn zu viele fehlerhafte Datensätze vorliegen, wird im Jobergebnis ein Fehler wegen ungültiger Werte zurückgegeben. Der Standardwert ist "false". Das Attribut sourceFormat bestimmt, was BigQuery als zusätzlichen Wert behandelt:
  • CSV: Nachgestellte Spalten
  • JSON: Benannte Werte, die keinem Spaltennamen entsprechen
Angebot Anführungszeichen: Doppelte Anführungszeichen, Einfache Anführungszeichen, Keine, Benutzerdefiniert --quote quote (Java, Python) (Optional) Der Wert, der zum Kennzeichnen von Datenabschnitten in einer CSV-Datei verwendet wird. BigQuery konvertiert den String in ISO-8859-1-Codierung und verwendet das erste Byte des codierten Strings, um die Daten in ihrer binären Rohform aufzuteilen. Der Standardwert ist ein Anführungszeichen ("). Legen Sie den Attributwert als leeren String fest, wenn die Daten keine in Anführungszeichen gesetzten Abschnitte enthalten. Wenn Ihre Daten Zeilenumbruchzeichen in Anführungszeichen enthalten, sollten Sie auch das Attribut allowQuotedNewlines auf true setzen. Wenn Sie das spezifische Anführungszeichen einem in Anführungszeichen gesetzten Wert hinzufügen möchten, stellen Sie ihm ein zusätzliches entsprechendes Anführungszeichen voran. Wenn Sie z. B. das Standardzeichen ' " ' maskieren möchten, verwenden Sie ' "" '.
Codierung -E oder --encoding encoding (Java, Python) (Optional) Die Zeichencodierung der Daten. Die unterstützten Werte sind UTF-8, ISO-8859-1, UTF-16BE, UTF-16LE, UTF-32BE und UTF-32LE. Der Standardwert ist UTF-8. BigQuery decodiert die Daten, nachdem die binären Rohdaten nach den Werten der Attribute quote und fieldDelimiter aufgeteilt wurden.
ASCII-Steuerzeichen Keine --preserve_ascii_control_characters Keine (Optional) Wenn Sie ASCII 0 und andere ASCII-Zeichen zulassen möchten, setzen Sie --preserve_ascii_control_characters auf true.