Daten im Batch laden

Sie können Daten aus Cloud Storage oder aus einer lokalen Datei als Batchvorgang in BigQuery laden. Die Quelldaten können folgende Formate haben:

  • Avro
  • Kommagetrennte Werte (CSV)
  • JSON (durch Zeilenumbruch getrennt)
  • ORC
  • Parquet
  • In Cloud Storage gespeicherte Datastore-Exporte.
  • Firestore, die in Cloud Storage gespeichert sind

Sie können auch den BigQuery Data Transfer Service verwenden, um wiederkehrende Ladevorgänge von Cloud Storage in BigQuery einzurichten.

Überzeugen Sie sich selbst

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

Vorbereitung

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 auf Projekte, Ordner und Organisationen 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.

Daten aus Cloud Storage laden

BigQuery unterstützt das Laden von Daten aus den folgenden Cloud Storage-Speicherklassen:

  • Standard
  • Nearline
  • Coldline
  • Archivieren

Mehr zum Laden von Daten in BigQuery finden Sie auf der Seite zu Ihrem Datenformat:

Informationen zum Konfigurieren eines wiederkehrenden Ladevorgangs aus Cloud Storage in BigQuery finden Sie unter Cloud Storage-Übertragungen.

Überlegungen zum Standort

Wenn Sie Daten aus Cloud Storage laden, müssen sich die Daten am selben Ort wie Ihr BigQuery-Dataset befinden.

  • Sie können Daten aus einem Cloud Storage-Bucket laden, der sich an einem beliebigen Standort befindet, wenn sich Ihr BigQuery-Dataset in der Multiregion US befindet.

  • Multiregionaler Bucket: Wenn sich der Cloud Storage-Bucket, aus dem Sie laden möchten, in einem multiregionalen Bucket befindet, kann sich Ihr BigQuery-Dataset im selben multiregionalen Bucket oder in einer einzelnen Region befinden, die im selben multiregionalen Bucket enthalten ist. Befindet sich der Cloud Storage-Bucket beispielsweise in der Region EU, kann sich das BigQuery-Dataset in der Multiregion EU oder in einer einzelnen Region in der EU befinden.

  • Biregionaler Bucket: Wenn sich der Cloud Storage-Bucket, aus dem Sie laden möchten, in einem biregionalen Bucket befindet, kann sich Ihr BigQuery-Dataset in Regionen befinden, die in einem biregionalen Bucket oder in einer Multiregion enthalten sind, die die duale Region enthält. Beispiel: Wenn sich Ihr Cloud Storage-Bucket in der Region EUR4 befindet, kann sich das BigQuery-Dataset entweder in der einzelnen Region Finnland (europe-north1), in der einzelnen Region Niederlande (europe-west4) oder in der Multiregion EU befinden.

  • Bucket mit einzelner Region: Wenn sich der Cloud Storage-Bucket, aus dem Sie laden möchten, in einer einzelnen Region befindet, kann sich Ihr BigQuery-Dataset in derselben einzelnen Region oder in der Multiregion befinden, die die einzelne Region enthält. Wenn sich Ihr Cloud Storage-Bucket beispielsweise in der Region Finnland (europe-north1) befindet, kann sich das BigQuery-Dataset in der Region Finnland oder in der Multiregion EU befinden.

  • Eine Ausnahme besteht, wenn sich Ihr BigQuery-Dataset in der Region asia-northeast1 befindet. Dann kann sich Ihr Cloud Storage-Bucket in der Multiregion EU befinden.

Weitere Informationen zu Cloud Storage-Standorten finden Sie in der Cloud Storage-Dokumentation unter Bucket-Standorte.

Der Standort eines Datasets lässt sich nach seiner Erstellung nicht mehr ändern. Sie können aber eine Kopie des Datasets erstellen oder es manuell verschieben. Weitere Informationen finden Sie unter:

Cloud Storage-URI abrufen

Wenn Sie Daten aus einer Cloud Storage-Datenquelle laden möchten, müssen Sie den Cloud Storage-URI angeben.

Der Cloud Storage-Ressourcenpfad enthält den Bucket-Namen und das Objekt (Dateiname). Wenn der Cloud Storage-Bucket beispielsweise den Namen mybucket hat und die Datendatei den Namen myfile.csv hat, lautet der Bucket-URI gs://mybucket/myfile.csv.

BigQuery unterstützt keine Cloud Storage-Ressourcenpfade, die nach dem anfänglichen doppelten Schrägstrich weitere, aufeinanderfolgende Schrägstriche enthalten. Cloud Storage-Objektnamen können mehrere aufeinanderfolgende Schrägstriche ("/") enthalten. BigQuery wandelt diese jedoch in einen einzelnen Schrägstrich um. Der folgende Ressourcenpfad ist beispielsweise in Cloud Storage gültig, funktioniert aber nicht in BigQuery: gs://bucket/my//object//name

So rufen Sie den Cloud Storage-Ressourcenpfad ab:

  1. Öffnen Sie die Cloud Storage-Konsole.

    Cloud Storage-Konsole

  2. Gehen Sie zum Standort des Objekts (Datei), das die Quelldaten enthält.

  3. Klicken Sie auf den Namen des gewünschten Objekts.

    Die Seite Objektdetails wird geöffnet.

  4. Kopieren Sie den Wert im Feld gsutil URI, der mit gs:// beginnt.

Bei Google Datastore-Exporten kann nur ein URI angegeben werden, der außerdem auf .backup_info oder .export_metadata enden muss.

Unterstützung von Platzhaltern für Cloud Storage-URIs

Wenn Ihre Daten auf mehrere Dateien verteilt sind, können Sie mehrere Dateien mit einem Sternchenplatzhalter (*) auswählen. Die Verwendung des Sternchenplatzhalters muss folgenden Regeln entsprechen:

  • Das Sternchen kann innerhalb oder am Ende des Objektnamens stehen.
  • Die Verwendung mehrerer Sternchen wird nicht unterstützt. Beispiel: Der Pfad gs://mybucket/fed-*/temp/*.csv ist ungültig.
  • Die Verwendung eines Sternchens mit dem Bucket-Namen wird nicht unterstützt.

Beispiele:

  • Im folgenden Beispiel wird gezeigt, wie Sie alle Dateien in allen Ordnern auswählen, die mit dem Präfix gs://mybucket/fed-samples/fed-sample beginnen:

    gs://mybucket/fed-samples/fed-sample*

  • Im folgenden Beispiel wird gezeigt, wie nur Dateien mit der .csv-Erweiterung im Ordner mit dem Namen fed-samples und allen Unterordnern von fed-samples ausgewählt werden:

    gs://mybucket/fed-samples/*.csv

  • Das folgende Beispiel zeigt, wie Sie Dateien mit dem Benennungsmuster fed-sample*.csv im Ordner fed-samples auswählen. In diesem Beispiel werden keine Dateien in Unterordnern von fed-samples ausgewählt.

    gs://mybucket/fed-samples/fed-sample*.csv

Bei der Verwendung des bq-Befehlszeilentools müssen Sie das Sternchen auf einigen Plattformen unter Umständen mit einem Escape-Zeichen versehen.

Sie können Sternchenplatzhalter nicht verwenden, wenn Sie Datastore- oder Firestore-Exportdaten aus Cloud Storage laden.

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.

Je nach Format Ihrer Cloud Storage-Quelldaten sind weitere Beschränkungen möglich. Weitere Informationen finden Sie unter:

Daten aus lokalen Dateien laden

Sie können mit einer der folgenden Methoden Daten aus einer lesbaren Datenquelle (z. B. von Ihrem lokalen Rechner) laden:

  • Die Google Cloud Console
  • Der Befehl bq load des bq-Befehlszeilentools
  • Mit der API
  • Mit den Clientbibliotheken

Beim Laden von Daten über die Google Cloud Console oder das bq-Befehlszeilentool wird automatisch ein Ladejob erstellt.

So laden Sie Daten aus einer lokalen Datenquelle:

Console

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

    Zur Seite "BigQuery"

  2. Maximieren Sie im Bereich Explorer Ihr Projekt und wählen Sie ein Dataset aus.

  3. Maximieren Sie die Option Aktionen und klicken Sie auf Öffnen.

  4. Klicken Sie im Detailfeld auf Tabelle erstellen.

  5. Gehen Sie auf der Seite Create table (Tabelle erstellen) im Bereich Source (Quelle) wie folgt vor:

    • Wählen Sie unter Tabelle erstellen aus die Option Hochladen aus.
    • Klicken Sie unter Datei auswählen auf Browse.
    • Gehen Sie dann zur gewünschten Datei und klicken Sie auf Öffnen. Beachten Sie, dass Platzhalter und durch Kommas getrennte Listen in lokalen Dateien nicht unterstützt werden.
    • Wählen Sie für File format (Dateiformat) die Option CSV, JSON (newline delimited) (JSON (durch Zeilenumbruch getrennt)), Avro, Parquet oder ORC aus.

  6. Gehen Sie auf der Seite Tabelle erstellen im Abschnitt Ziel folgendermaßen vor:

    • Wählen Sie als Projekt das entsprechende Projekt aus.
    • Wählen Sie für Dataset das entsprechende Dataset aus.
    • Geben Sie im Feld Tabelle den Namen der Tabelle ein, die Sie in BigQuery erstellen.
    • Achten Sie darauf, dass für Tabellentyp die Option Native Tabelle ausgewählt ist.

  7. Geben Sie im Abschnitt Schema die Schemadefinition ein.

    • Für CSV- und JSON-Dateien können Sie die Option Auto-detect (Automatisch erkennen) anklicken, um die automatische Schemaerkennung zu aktivieren. Die Schemainformationen sind in den Quelldaten für andere unterstützte Dateitypen selbstbeschreibend.

    • Sie können Schemainformationen auch manuell eingeben:

      • Klicken Sie dazu auf Edit as text (Als Text bearbeiten) und geben Sie das Tabellenschema als JSON-Array ein:

      • Geben Sie das Schema mit Feld hinzufügen manuell ein.

  8. Wählen Sie die entsprechenden Elemente im Abschnitt Erweiterte Optionen aus. Informationen zu den verfügbaren Optionen finden Sie unter CSV-Optionen und JSON-Optionen.

  9. Optional: Wählen Sie unter Erweiterte Optionen die Schreibanordnung aus:

    • Schreiben, wenn leer: Die Daten werden nur geschrieben, wenn die Tabelle leer ist.
    • An Tabelle anfügen: Die Daten werden an das Ende der Tabelle angefügt. Dies ist die Standardeinstellung.
    • Tabelle überschreiben: Alle vorhandenen Daten in der Tabelle werden gelöscht, bevor die neuen Daten geschrieben werden.

  10. Klicken Sie auf Tabelle erstellen.

bq

Verwenden Sie den Befehl bq load und geben Sie das source_format sowie den Pfad zur lokalen Datei an.

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

Wenn Sie Daten in ein anderes Projekt als Ihr Standardprojekt laden, fügen Sie die Projekt-ID im folgenden Format dem Dataset hinzu: PROJECT_ID:DATASET.

bq --location=LOCATION load \
--source_format=FORMAT \
PROJECT_ID:DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

Ersetzen Sie dabei Folgendes:

  • LOCATION: Ihr Standort. Das Flag --location ist optional. Wenn Sie beispielsweise BigQuery in der Region Tokio verwenden, legen Sie den Wert des Flags auf asia-northeast1 fest. Mit der Datei ".bigqueryrc" können Sie für den Standort einen Standardwert festlegen.
  • FORMAT: CSV, AVRO, PARQUET, ORC oder NEWLINE_DELIMITED_JSON.
  • project_id: Ihre Projekt-ID.
  • dataset: ein vorhandenes Dataset.
  • table: der Name der Tabelle, in die Sie Daten laden.
  • path_to_source: der Pfad zur lokalen Datei.
  • schema: 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.

Darüber hinaus haben Sie die Möglichkeit, Flags für Optionen einzufügen, mit denen sich steuern lässt, wie BigQuery Ihre Daten parst. Sie können beispielsweise mit dem Flag --skip_leading_rows festlegen, dass Header-Zeilen in einer CSV-Datei ignoriert werden. Weitere Informationen finden Sie unter CSV-Optionen und JSON-Optionen.

Beispiele:

Mit dem folgenden Befehl wird eine lokale durch Zeilenumbruch getrennte JSON-Datei (mydata.json) in eine Tabelle namens mytable in mydataset in Ihrem Standardprojekt geladen. Das Schema ist in einer lokalen Schemadatei namens myschema.json definiert.

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    ./mydata.json \
    ./myschema.json

Mit dem folgenden Befehl wird eine lokale CSV-Datei (mydata.csv) in eine Tabelle namens mytable inmydataset in myotherproject geladen. Das Schema ist inline im Format FIELD:DATA_TYPE, FIELD:DATA_TYPE definiert.

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

Mit dem folgenden Befehl wird eine lokale CSV-Datei (mydata.csv) in eine Tabelle namens mytable in mydataset in Ihrem Standardprojekt geladen. Das Schema wird mithilfe der automatischen Schemaerkennung definiert.

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

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.

Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Für lokale Dateien anderer Formate verwenden Sie anstelle von UploadCsvOptions die Klasse "UploadOptions" für das entsprechende Format aus der Basisklasse JobCreationOptions.


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

public class BigQueryLoadFromFile
{
    public void LoadFromFile(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id",
        string filePath = "path/to/file.csv"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Create job configuration
        var uploadCsvOptions = new UploadCsvOptions()
        {
            SkipLeadingRows = 1,  // Skips the file headers
            Autodetect = true
        };
        using (FileStream stream = File.Open(filePath, FileMode.Open))
        {
            // Create and run job
            // Note that there are methods available for formats other than CSV
            BigQueryJob job = client.UploadCsv(
                datasetId, tableId, null, stream, uploadCsvOptions);
            job = job.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.

            // Display the number of rows uploaded
            BigQueryTable table = client.GetTable(datasetId, tableId);
            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.

Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Zum Laden lokaler Dateien anderer Formate legen Sie das entsprechende Format mit dem Attribut DataFormat von NewReaderSource fest.

import (
	"context"
	"fmt"
	"os"

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

// importCSVFromFile demonstrates loading data into a BigQuery table using a file on the local filesystem.
func importCSVFromFile(projectID, datasetID, tableID, filename 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()

	f, err := os.Open(filename)
	if err != nil {
		return err
	}
	source := bigquery.NewReaderSource(f)
	source.AutoDetect = true   // Allow BigQuery to determine schema.
	source.SkipLeadingRows = 1 // CSV has a single header line.

	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return 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.

Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Zum Laden lokaler Dateien anderer Formate legen Sie für FormatOptions das entsprechende Format fest.

TableId tableId = TableId.of(datasetName, tableName);
WriteChannelConfiguration writeChannelConfiguration =
    WriteChannelConfiguration.newBuilder(tableId).setFormatOptions(FormatOptions.csv()).build();
// The location must be specified; other fields can be auto-detected.
JobId jobId = JobId.newBuilder().setLocation(location).build();
TableDataWriteChannel writer = bigquery.writer(jobId, writeChannelConfiguration);
// Write data to writer
try (OutputStream stream = Channels.newOutputStream(writer)) {
  Files.copy(csvPath, stream);
}
// Get load job
Job job = writer.getJob();
job = job.waitFor();
LoadStatistics stats = job.getStatistics();
return stats.getOutputRows();

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.

Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Zum Laden lokaler Dateien anderer Formate legen Sie für den Parameter metadata der load-Funktion das entsprechende Format fest.

// Imports the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function loadLocalFile() {
  // Imports a local file into a table.

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

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(filename);

  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.

Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Für lokale Dateien anderer Formate geben Sie für sourceFormat das entsprechende Format an.

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';
// $source     = 'The path to the CSV source file to import';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
// create the import job
$loadConfig = $table->load(fopen($source, 'r'))->sourceFormat('CSV');

$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    printf('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.

Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Für lokale Dateien anderer Formate legen Sie für das Attribut LoadJobConfig.source_format das entsprechende Format 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(
    source_format=bigquery.SourceFormat.CSV, skip_leading_rows=1, autodetect=True,
)

with open(file_path, "rb") as source_file:
    job = client.load_table_from_file(source_file, table_id, job_config=job_config)

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

table = client.get_table(table_id)  # Make an API request.
print(
    "Loaded {} rows and {} columns to {}".format(
        table.num_rows, len(table.schema), table_id
    )
)

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.

Im folgenden Codebeispiel wird gezeigt, wie Sie eine lokale CSV-Datei in eine neue BigQuery-Tabelle laden. Zum Laden lokaler Dateien anderer Formate legen Sie für den Parameter format der Methode Table#load_job das entsprechende Format fest.

require "google/cloud/bigquery"

def load_from_file dataset_id = "your_dataset_id",
                   file_path  = "path/to/file.csv"

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "new_table_id"

  # Infer the config.location based on the location of the referenced dataset.
  load_job = dataset.load_job table_id, file_path do |config|
    config.skip_leading = 1
    config.autodetect   = true
  end
  load_job.wait_until_done! # Waits for table load to complete.

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

Beschränkungen

Das Laden von Daten aus einer lokalen Datenquelle unterliegt folgenden Beschränkungen:

  • Platzhalter und durch Kommas getrennte Listen werden nicht unterstützt. Dateien müssen einzeln geladen werden.
  • Wenn Sie die Google Cloud Console verwenden, dürfen Dateien, die aus einer lokalen Datenquelle geladen werden, nicht größer als 100 MB sein. Bei größeren Dateien laden Sie die Datei aus Cloud Storage.
  • Für Ladejobs wird standardmäßig ein gemeinsam genutzter Pool von Slots verwendet. BigQuery übernimmt keine Garantie für die verfügbaren Kapazitäten dieses gemeinsamen Pools oder den angezeigten Durchsatz. Alternativ können Sie dedizierte Slots erwerben, um Ladejobs auszuführen. Weitere Informationen finden Sie unter Datenaufnahme – Preise.

Komprimierte und unkomprimierte Daten laden

Für Avro-, Parquet- und ORC-Formate unterstützt BigQuery das Laden von Dateien, bei denen die Dateidaten mit einem unterstützten Codec komprimiert wurden. BigQuery unterstützt jedoch kein Laden von Dateien in diesen Formaten, die selbst komprimiert wurden, z. B. mit dem Dienstprogramm gzip.

Das Avro-Binärformat ist das bevorzugte Format zum Laden komprimierter und unkomprimierter Daten. Avro-Daten können schneller geladen werden, da die Daten parallel gelesen werden können, selbst wenn die Datenblöcke komprimiert sind. Eine Liste der unterstützten Komprimierungscodecs finden Sie unter Avro-Komprimierung.

Das binäre Parquet-Format ist auch eine gute Wahl, da die effiziente Spaltencodierung von Parquet in der Regel zu einer besseren Komprimierungsrate und kleineren Dateien führt. Parquet-Dateien nutzen auch Komprimierungstechniken, mit denen Dateien parallel geladen werden können. Eine Liste der unterstützten Komprimierungscodecs finden Sie unter Parquet-Komprimierung.

Das ORC-Binärformat bietet ähnliche Vorteile wie das Parquet-Format. Daten in ORC-Dateien können durch das parallele Lesen von Datenstreifen schnell geladen werden. Die in jedem Datenstreifen enthaltenen Zeilen werden nacheinander geladen. Verwenden Sie zum Optimieren der Ladezeit Datenstreifen mit maximal rund 256 MB. Eine Liste der unterstützten Komprimierungscodecs finden Sie unter ORC-Komprimierung.

Bei anderen Datenformaten wie CSV und JSON kann BigQuery unkomprimierte Dateien aufgrund der parallelen Lesevorgänge wesentlich schneller laden als komprimierte Dateien. Da unkomprimierte Dateien größer sind, kann ihre Verwendung zu Bandbreitenbeschränkungen und höheren Kosten für Daten führen, die in Cloud Storage bereitgestellt sind, bevor sie in BigQuery geladen werden. Beachten Sie außerdem, dass die Zeilenreihenfolge bei komprimierten und unkomprimierten Dateien nicht sichergestellt ist. Je nach Anwendungsfall müssen Sie die Vor- und Nachteile unbedingt abwägen.

Allgemein gilt: Wenn die Bandbreite begrenzt ist, sollten Sie Ihre CSV- und JSON-Dateien mit gzip komprimieren, bevor Sie sie in Cloud Storage hochladen. gzip ist der einzige unterstützte Dateikomprimierungstyp für CSV- und JSON-Dateien beim Laden von Daten in BigQuery. Wenn die Ladegeschwindigkeit für Ihre Anwendung wichtig ist und Sie viel Bandbreite zum Laden Ihrer Daten haben, lassen Sie die Dateien unkomprimiert.

An eine Tabelle anfügen oder eine Tabelle überschreiben

Zusätzliche Daten können entweder aus Quelldateien oder durch das Anfügen von Abfrageergebnissen in eine Tabelle geladen werden. Sollte das Schema der Daten nicht mit dem Schema der Zieltabelle oder -partition übereinstimmen, können Sie das Schema aktualisieren, wenn Sie Daten an das Ziel anfügen oder das Ziel überschreiben.

Wenn Sie das Schema beim Anfügen von Daten aktualisieren, können Sie in BigQuery folgende Vorgänge ausführen:

  • Neue Felder hinzufügen
  • Felder vom Typ REQUIRED in den Typ NULLABLE ändern (herunterstufen)

Beim Überschreiben einer Tabelle wird immer auch das Schema überschrieben. Schemaaktualisierungen sind beim Überschreiben einer Tabelle nicht eingeschränkt.

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. Das bq-Befehlszeilentool und die API umfassen die folgenden Optionen:

Console-Option bq-Tool-Flag BigQuery API-Attribut Beschreibung
Schreiben, wenn leer Ohne WRITE_EMPTY Daten werden nur geschrieben, wenn die Tabelle leer ist.
An Tabelle anfügen --noreplace oder --replace=false. Wenn --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.

Kontingentrichtlinie

Informationen zu den Kontingentrichtlinien für das Laden von Daten im Batch finden Sie unter Ladejobs auf der Seite „Kontingente und Limits“.

Aktuelle Kontingentnutzung ansehen

Sie können Ihre aktuelle Nutzung von Abfrage-, Lade-, Extrahierungs- oder Kopierjobs aufrufen, indem Sie eine INFORMATION_SCHEMA-Abfrage ausführen, um Metadaten zu den Jobs aufzurufen, die in einem bestimmten Zeitraum ausgeführt wurden. Sie können Ihre aktuelle Nutzung mit dem Kontingentlimit vergleichen, um die Kontingentnutzung für eine bestimmte Art von Job zu ermitteln. Die folgende Beispielabfrage verwendet die Ansicht INFORMATION_SCHEMA.JOBS, um die Anzahl der Abfrage-, Lade-, Extrahierungs- und Kopierjobs nach Projekt aufzulisten:

SELECT
  sum(case  when job_type="QUERY" then 1 else 0 end) as QRY_CNT,
  sum(case  when job_type="LOAD" then 1 else 0 end) as LOAD_CNT,
  sum(case  when job_type="EXTRACT" then 1 else 0 end) as EXT_CNT,
  sum(case  when job_type="COPY" then 1 else 0 end) as CPY_CNT
FROM `region-eu`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE date(creation_time)= CURRENT_DATE()

Preise

Das Laden von Daten im Batch in BigQuery ist kostenlos. Weitere Informationen finden Sie unter BigQuery-Datenaufnahmepreise.

Anwendungsbeispiel

Angenommen, es gibt eine nächtliche Batchverarbeitungspipeline, die bis zu einer festen Frist abgeschlossen werden muss. Daten müssen innerhalb dieser Frist zur weiteren Verarbeitung durch einen anderen Batchprozess verfügbar sein, um Berichte zu generieren, die an eine Aufsichtsbehörde gesendet werden. Dieser Anwendungsfall ist in regulierten Branchen wie der Finanzbranche üblich.

Für diesen Anwendungsfall ist das Batch-Laden von Daten mit Ladejobs der richtige Ansatz, da die Latenz kein Problem darstellt, wenn die Frist eingehalten werden kann. Achten Sie darauf, dass Ihre Cloud Storage-Buckets die Standortanforderungen zum Laden von Daten in das BigQuery-Dataset erfüllen.

Das Ergebnis eines BigQuery-Ladejobs ist atomar. Entweder werden alle Datensätze eingefügt oder keiner. Als Best Practice sollten Sie beim Einfügen aller Daten in einen einzelnen Ladejob mithilfe der WRITE_TRUNCATE-Disposition der JobConfigurationLoad-Ressource eine neue Tabelle erstellen. Dies ist wichtig, wenn ein fehlgeschlagener Ladejob wiederholt werden soll, da der Client möglicherweise nicht zwischen fehlgeschlagenen Jobs und dem unterscheiden kann, wenn der Fehler beispielsweise bei der Kommunikation des Erfolgsstatus an den Client verursacht wurde.

Wenn Daten, die aufgenommen werden sollen, bereits in Cloud Storage kopiert wurden, reicht der Versuch mit exponentiellem Backoff aus, um Aufnahmefehler zu beheben.

Es wird empfohlen, dass ein nächtlicher Batchjob nicht das Standardkontingent von 1.500 Ladevorgängen pro Tabelle und Tag überschreitet, selbst mit Wiederholungsversuchen. Wenn die Daten inkrementell geladen werden, reicht das Standardkontingent aus, um alle 5 Minuten einen Ladejob auszuführen und dabei noch über genügend unverbrauchte Kontingente für durchschnittlich mindestens 1 Wiederholungsversuch pro Job zu verfügen.