Tabellendaten exportieren

Auf dieser Seite wird gezeigt, wie Sie Daten aus BigQuery-Tabellen in Cloud Storage exportieren oder daraus extrahieren.

Nach dem Laden der Daten in BigQuery können Sie die Daten in verschiedene Formate exportieren. BigQuery kann bis zu 1 GB Daten in eine einzige Datei exportieren. Wenn Sie mehr als 1 GB Daten exportieren möchten, müssen Sie dafür mehrere Dateien verwenden. Beim Export in mehrere Dateien variiert die Größe der Dateien.

Anstatt Daten manuell zu exportieren, können Sie auch einen Dienst wie Dataflow verwenden, um Daten aus BigQuery zu lesen. Weitere Informationen dazu, wie Sie Dataflow zum Lesen und Schreiben in BigQuery verwenden, finden Sie in der Apache Beam-Dokumentation unter BigQuery-E/A.

Sie können die Ergebnisse einer Abfrage auch mit der Anweisung EXPORT DATA exportieren.

Exportbeschränkungen

Wenn Sie Daten aus BigQuery exportieren, sollten Sie Folgendes beachten:

  • Tabellendaten können nicht in eine lokale Datei, nicht in Tabellen und nicht in Drive exportiert werden. Der einzige unterstützte Exportspeicherort ist Cloud Storage. Informationen zum Speichern von Abfrageergebnissen finden Sie unter Abfrageergebnisse herunterladen und speichern.
  • Sie können bis zu 1 GB Tabellendaten in eine einzige Datei exportieren. Wenn Sie mehr als 1 GB Daten exportieren, verwenden Sie einen Platzhalter, um die Daten in mehrere Dateien zu exportieren. Wenn Sie Daten in mehrere Dateien exportieren, variiert die Größe der Dateien.
  • Verschachtelte und wiederkehrende Daten können nicht im CSV-Format exportiert werden. Verschachtelte und wiederkehrende Daten werden für Avro-, JSON- und Parquet-Exporte unterstützt.
  • Beim Exportieren von Daten in das JSON-Format werden INT64-Datentypen (Ganzzahl) als JSON-Strings codiert, um die 64-Bit-Genauigkeit beizubehalten, wenn die Daten von anderen Systemen gelesen werden.
  • Daten aus mehreren Tabellen können nicht mit einem einzelnen Exportjob exportiert werden.
  • Beim Exportieren von Daten mit der Cloud Console können Sie nur den Komprimierungstyp GZIP auswählen.
  • Wenn Sie Daten in einen Cloud Storage-Bucket exportieren, der mit einer Aufbewahrungsrichtlinie konfiguriert wurde, schreibt BigQuery möglicherweise keine Dateien in den Bucket. Erwägen Sie, die Aufbewahrungsrichtlinie für die Dauer der Exportjobs zu lockern.
  • Wenn Sie eine Tabelle im JSON-Format exportieren, werden die Symbole <, > und & mit der Unicode-Notation \uNNNN konvertiert, wobei N eine Hexadezimalzahl ist. Aus profit&loss wird beispielsweise profit\u0026loss. Diese Unicode-Konvertierung erfolgt, um Sicherheitslücken zu vermeiden.

Hinweis

Erteilen Sie IAM-Rollen (Identity and Access Management), die Nutzern die erforderlichen Berechtigungen zum Ausführen der einzelnen Aufgaben in diesem Dokument geben.

Erforderliche Berechtigungen

Zum Ausführen der Aufgaben in diesem Dokument benötigen Sie die folgenden Berechtigungen.

Berechtigungen für den Zugriff auf die BigQuery-Tabelle

Für den Zugriff auf die BigQuery-Tabelle, die die Daten enthält, die Sie exportieren möchten, benötigen Sie die IAM-Berechtigung bigquery.tables.export.

Jede der folgenden vordefinierten IAM-Rollen enthält die Berechtigungen, die Sie für den Zugriff auf eine BigQuery-Tabelle benötigen:

  • roles/bigquery.dataViewer
  • roles/bigquery.dataOwner
  • roles/bigquery.dataEditor
  • roles/bigquery.admin

Berechtigungen zum Ausführen eines Exportjobs

Zum Ausführen eines Exportjobs benötigen Sie die IAM-Berechtigung bigquery.jobs.create.

Jede der folgenden vordefinierten IAM-Rollen enthält die Berechtigungen, die Sie zum Ausführen eines Exportjobs benötigen:

  • roles/bigquery.user
  • roles/bigquery.jobUser
  • roles/bigquery.admin

Berechtigungen zum Schreiben der Daten in den Cloud Storage-Bucket

Zum Schreiben der Daten in einen vorhandenen Cloud Storage-Bucket benötigen Sie die folgenden IAM-Berechtigungen:

  • storage.objects.create
  • storage.objects.delete

Jede der folgenden vordefinierten IAM-Rollen enthält die Berechtigungen, die Sie benötigen, um die Daten in einen vorhandenen Cloud Storage-Bucket zu schreiben:

  • roles/storage.objectAdmin
  • roles/storage.admin

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

Überlegungen zum Standort

Bei der Auswahl eines Speicherorts für Ihre Daten sollten Sie Folgendes beachten:

  • Platzieren Sie die Cloud Storage-Buckets zum Exportieren von Daten am selben Standort wie das Dataset:
    • Wenn Sie Daten exportieren, muss sich der regionale oder multiregionale Cloud Storage-Bucket am selben Standort wie das BigQuery-Dataset befinden. Wenn sich Ihr BigQuery-Dataset zum Beispiel am multiregionalen Standort "EU" befindet, muss sich der Cloud Storage-Bucket mit den Daten, die Sie exportieren, an einem regionalen oder multiregionalen Standort in der EU befinden.
    • Wenn sich Ihr Dataset an einem regionalen Standort befindet, muss der Cloud Storage-Bucket ein regionaler Bucket am selben Standort sein. Wenn sich Ihr Dataset zum Beispiel in der Region "Tokio" befindet, muss der Cloud Storage-Bucket ein regionaler Bucket in Tokio sein.
    • Ausnahme: Wenn sich Ihr Dataset am multiregionalen Standort "US" befindet, können Sie Daten in einen Cloud Storage-Bucket exportieren, der sich an einem beliebigen regionalen oder multiregionalen Standort befindet.
  • Entwickeln Sie einen Plan zur Datenverwaltung:
    • Wenn Sie eine regionale Speicherressource wie ein BigQuery-Dataset oder einen Cloud Storage-Bucket auswählen, sollten Sie einen Plan für die geografische Verwaltung Ihrer Daten entwickeln.

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

BigQuery-Daten zwischen Standorten verschieben

Der Standort eines Datasets lässt sich nach seiner Erstellung nicht mehr ändern. Sie können aber eine Kopie des Datasets anlegen. Ein Dataset lässt sich auch nicht von einem Standort an einen anderen verschieben. Sie haben jedoch die Möglichkeit, ein Dataset manuell zu verschieben, d. h. neu zu erstellen.

Exportformate und Komprimierungstypen

BigQuery unterstützt die folgenden Datenformate und Komprimierungstypen für exportierte Daten.

Datenformat Unterstützte Komprimierungstypen Details
CSV GZIP

Sie können das CSV-Trennzeichen in Ihren exportierten Daten mithilfe des --field_delimiter-Befehlszeilentool-Flags bq oder des configuration.extract.fieldDelimiter-Extrahierungsjob-Attributs festlegen.

Verschachtelte und wiederkehrende Daten werden nicht unterstützt.
JSON GZIP Verschachtelte und wiederkehrende Daten werden unterstützt.
Avro DEFLATE, SNAPPY

GZIP wird für Avro-Exporte nicht unterstützt.

Verschachtelte und wiederkehrende Daten werden unterstützt. Siehe Avro-Exportdetails.
Parquet SNAPPY, GZIP

Verschachtelte und wiederkehrende Daten werden unterstützt. Weitere Informationen finden Sie unter Parquet-Exportdetails.

In BigQuery gespeicherte Daten exportieren

Sie können Tabellendaten mit den folgenden Methoden exportieren:

  • Mit der Cloud Console
  • Mit dem Befehl bq extract im bq-Befehlszeilentool
  • Durch Senden eines extract-Jobs über die API oder die Clientbibliotheken

Tabellendaten exportieren

So exportieren Sie Daten aus einer BigQuery-Tabelle:

Console

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

    Zur Seite "BigQuery"

  2. Maximieren Sie im Bereich Explorer Ihr Projekt und das Dataset und wählen Sie dann die Tabelle aus.

  3. Klicken Sie im Detailbereich auf Exportieren und wählen Sie Nach Cloud Storage exportieren aus.

  4. Gehen Sie im Dialogfeld Nach Google Cloud Storage exportieren folgendermaßen vor:

    • Wählen Sie für Google Cloud Storage-Speicherort auswählen den Bucket, Ordner oder die Datei aus, in den bzw. die Sie die Daten exportieren möchten.
    • Wählen Sie unter Exportformat das Format für die exportierten Daten aus: CSV, JSON (durch Zeilenumbruch getrennt), Avro oder Parquet.
    • Wählen Sie unter Komprimierung ein Komprimierungsformat aus oder wählen Sie None für keine Komprimierung aus.
    • Klicken Sie auf Exportieren, um die Tabelle zu exportieren.

Für einen Exportjob können Sie unter Jobverlauf oben in der Navigationsleiste den Status des Jobs prüfen.

bq

Führen Sie den Befehl bq extract mit dem Flag --destination_format aus.

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

Andere optionale Flags sind:

  • --compression: Der Komprimierungstyp, der für exportierte Dateien verwendet werden soll.
  • --field_delimiter: Das Zeichen, das die Begrenzung zwischen den Spalten in der Ausgabedatei für CSV-Exporte angibt. Es kann sowohl \t als auch tab als Tabulatortrennzeichen verwendet werden.
  • --print_header: Wenn dieses Flag angegeben ist, werden bei Formaten mit Headern wie CSV entsprechende Kopfzeilen ausgegeben.
bq --location=location extract \
--destination_format format \
--compression compression_type \
--field_delimiter delimiter \
--print_header=boolean \
project_id:dataset.table \
gs://bucket/filename.ext

Wobei:

  • location ist der Name Ihres Standorts. 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 lässt sich für den Standort ein Standardwert angeben.
  • format ist das Format für die exportierten Daten: CSV, NEWLINE_DELIMITED_JSON, AVRO oder PARQUET.
  • compression_type ist ein unterstützter Komprimierungstyp für das Datenformat. Weitere Informationen finden Sie unter Exportformate und Komprimierungstypen.
  • delimiter ist das Trennzeichen für Spalten in CSV-Exporten. \t und tab sind akzeptierte Namen für das Tabulatorzeichen.
  • boolean ist true oder false. Wenn true festgelegt ist, werden Header an die exportierten Daten ausgegeben, sofern das Datenformat Header unterstützt. Der Standardwert ist true.
  • project_id ist die Projekt-ID.
  • dataset ist der Name des Quell-Datasets.
  • table ist die Tabelle, die Sie exportieren.
  • bucket ist der Name des Cloud Storage-Buckets, in den Sie Daten exportieren. Das BigQuery-Dataset und der Cloud Storage-Bucket müssen sich am selben Standort befinden.
  • filename.ext ist der Name und die Erweiterung der exportierten Datendatei. Mit einem Platzhalter können Sie in mehrere Dateien exportieren.

Beispiele:

Mit dem folgenden Befehl wird beispielsweise mydataset.mytable in eine komprimierte GZIP-Datei mit dem Namen myfile.csv exportiert. Die Datei myfile.csv wird in einem Cloud Storage-Bucket namens example-bucket gespeichert.

bq extract \
--compression GZIP \
'mydataset.mytable' \
gs://example-bucket/myfile.csv

Das Standardzielformat ist CSV. Für Exporte in eine JSON- oder Avro-Datei verwenden Sie das Flag destination_format und legen dafür NEWLINE_DELIMITED_JSON oder AVRO fest.

bq extract \
--destination_format NEWLINE_DELIMITED_JSON \
'mydataset.mytable' \
gs://example-bucket/myfile.json

Mit dem folgenden Befehl wird mydataset.mytable in eine mit Snappy komprimierte Avro-Datei exportiert. Der Name der Datei lautet myfile.avro. myfile.avro wird in einen Cloud Storage-Bucket namens example-bucket exportiert.

bq extract \
--destination_format AVRO \
--compression SNAPPY \
'mydataset.mytable' \
gs://example-bucket/myfile.avro

API

Zum Exportieren von Daten erstellen Sie einen extract-Job und legen dafür die Jobkonfiguration fest.

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

  1. Erstellen Sie einen Extrahierungsjob, der auf die BigQuery-Quelldaten und auf das Cloud Storage-Ziel verweist.

  2. Geben Sie die Quelltabelle mithilfe des Konfigurationsobjekts sourceTable an, das die Projekt-ID, die Dataset-ID und die Tabellen-ID enthält.

  3. Das Attribut destination URI(s) muss vollständig qualifiziert sein und das Format gs://bucket/filename.ext haben. Jeder URI kann genau ein Platzhalterzeichen (*) enthalten, das nach dem Bucket-Namen stehen muss.

  4. Geben Sie das Datenformat an. Legen Sie dazu das Attribut configuration.extract.destinationFormat fest. Geben Sie beispielsweise für dieses Attribut für den Export einer JSON-Datei den Wert NEWLINE_DELIMITED_JSON an.

  5. Rufen Sie zur Prüfung des Jobstatus jobs.get(job_id) mit der ID des Jobs auf, die 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 status.errorResult nicht zurückgegeben wird, wurde der Job erfolgreich abgeschlossen. Es können aber nichtsdestotrotz einige nicht schwerwiegende Fehler aufgetreten sein. Nicht schwerwiegende Fehler werden im Attribut status.errors des Objekts des zurückgegebenen Jobs aufgeführt.

API-Hinweise:

  • Als Best Practice generieren Sie eine nur einmal vorkommende ID und übergeben sie als jobReference.jobId, wenn Sie jobs.insert zum Erstellen eines Ladejobs aufrufen. 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 eine bestimmte Job-ID beliebig oft wiederholen können. Maximal einer dieser Vorgänge wird erfolgreich sein.

C#

Bevor Sie dieses Beispiel ausprobieren, folgen Sie den Schritten zur Einrichtung von C# in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery C# API. 


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

public class BigQueryExtractTable
{
    public void ExtractTable(
        string projectId = "your-project-id",
        string bucketName = "your-bucket-name")
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Define a destination URI. Use a single wildcard URI if you think
        // your exported data will be larger than the 1 GB maximum value.
        string destinationUri = $"gs://{bucketName}/shakespeare-*.csv";
        BigQueryJob job = client.CreateExtractJob(
            projectId: "bigquery-public-data",
            datasetId: "samples",
            tableId: "shakespeare",
            destinationUri: destinationUri
        );
        job = job.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.
        Console.Write($"Exported table to {destinationUri}.");
    }
}

Go

Bevor Sie dieses Beispiel ausprobieren, 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. 

import (
	"context"
	"fmt"

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

// exportTableAsCompressedCSV demonstrates using an export job to
// write the contents of a table into Cloud Storage as CSV.
func exportTableAsCSV(projectID, gcsURI string) error {
	// projectID := "my-project-id"
	// gcsUri := "gs://mybucket/shakespeare.csv"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	srcProject := "bigquery-public-data"
	srcDataset := "samples"
	srcTable := "shakespeare"

	gcsRef := bigquery.NewGCSReference(gcsURI)
	gcsRef.FieldDelimiter = ","

	extractor := client.DatasetInProject(srcProject, srcDataset).Table(srcTable).ExtractorTo(gcsRef)
	extractor.DisableHeader = true
	// You can choose to run the job in a specific location for more complex data locality scenarios.
	// Ex: In this example, source dataset and GCS bucket are in the US.
	extractor.Location = "US"

	job, err := extractor.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 ausprobieren, folgen Sie den Schritten zur Einrichtung von Java in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery Java API. 

import com.google.cloud.RetryOption;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import org.threeten.bp.Duration;

public class ExtractTableToCsv {

  public static void runExtractTableToCsv() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "bigquery-public-data";
    String datasetName = "samples";
    String tableName = "shakespeare";
    String bucketName = "my-bucket";
    String destinationUri = "gs://" + bucketName + "/path/to/file";
    // For more information on export formats available see:
    // https://cloud.google.com/bigquery/docs/exporting-data#export_formats_and_compression_types
    // For more information on Job see:
    // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html

    String dataFormat = "CSV";
    extractTableToCsv(projectId, datasetName, tableName, destinationUri, dataFormat);
  }

  // Exports datasetName:tableName to destinationUri as raw CSV
  public static void extractTableToCsv(
      String projectId,
      String datasetName,
      String tableName,
      String destinationUri,
      String dataFormat) {
    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(projectId, datasetName, tableName);
      Table table = bigquery.getTable(tableId);

      Job job = table.extract(dataFormat, destinationUri);

      // Blocks until this job completes its execution, either failing or succeeding.
      Job completedJob =
          job.waitFor(
              RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
              RetryOption.totalTimeout(Duration.ofMinutes(3)));
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to extract due to an error: \n" + job.getStatus().getError());
        return;
      }
      System.out.println(
          "Table export successful. Check in GCS bucket for the " + dataFormat + " file.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \n" + e.toString());
    }
  }
}

Node.js

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

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

const bigquery = new BigQuery();
const storage = new Storage();

async function extractTableToGCS() {
  // Exports my_dataset:my_table to gcs://my-bucket/my-file as raw CSV.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  // const bucketName = "my-bucket";
  // const filename = "file.csv";

  // Location must match that of the source table.
  const options = {
    location: 'US',
  };

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

  console.log(`Job ${job.id} created.`);

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

PHP

Bevor Sie dieses Beispiel ausprobieren, folgen Sie den Schritten zur Einrichtung von PHP in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery PHP API. 

use Google\Cloud\BigQuery\BigQueryClient;

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

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
$destinationUri = "gs://{$bucketName}/{$tableId}.json";
// Define the format to use. If the format is not specified, 'CSV' will be used.
$format = 'NEWLINE_DELIMITED_JSON';
// Create the extract job
$extractConfig = $table->extract($destinationUri)->destinationFormat($format);
// Run the job
$job = $table->runJob($extractConfig);  // Waits for the job to complete
printf('Exported %s to %s' . PHP_EOL, $table->id(), $destinationUri);

Python

Bevor Sie dieses Beispiel ausprobieren, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur  Python API. 

# from google.cloud import bigquery
# client = bigquery.Client()
# bucket_name = 'my-bucket'
project = "bigquery-public-data"
dataset_id = "samples"
table_id = "shakespeare"

destination_uri = "gs://{}/{}".format(bucket_name, "shakespeare.csv")
dataset_ref = bigquery.DatasetReference(project, dataset_id)
table_ref = dataset_ref.table(table_id)

extract_job = client.extract_table(
    table_ref,
    destination_uri,
    # Location must match that of the source table.
    location="US",
)  # API request
extract_job.result()  # Waits for job to complete.

print(
    "Exported {}:{}.{} to {}".format(project, dataset_id, table_id, destination_uri)
)

Ruby

Bevor Sie dieses Beispiel ausprobieren, folgen Sie den Schritten zur Einrichtung von Ruby in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery Ruby API. 

require "google/cloud/bigquery"

def extract_table bucket_name = "my-bucket",
                  dataset_id  = "my_dataset_id",
                  table_id    = "my_table_id"

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table    = dataset.table    table_id

  # Define a destination URI. Use a single wildcard URI if you think
  # your exported data will be larger than the 1 GB maximum value.
  destination_uri = "gs://#{bucket_name}/output-*.csv"

  extract_job = table.extract_job destination_uri do |config|
    # Location must match that of the source table.
    config.location = "US"
  end
  extract_job.wait_until_done! # Waits for the job to complete

  puts "Exported #{table.id} to #{destination_uri}"
end

Avro-Exportdetails

BigQuery drückt Avro-formatierte Daten folgendermaßen aus:

  • Bei den resultierenden Exportdateien handelt es sich um Avro-Containerdateien.
  • Jede BigQuery-Zeile wird als Avro-Datensatz dargestellt. Verschachtelte Daten werden durch verschachtelte Datensatzobjekte dargestellt.
  • REQUIRED-Felder werden als äquivalente Avro-Typen dargestellt. Der Typ INTEGER in BigQuery wird beispielsweise dem Typ LONG in Avro zugeordnet.
  • NULLABLE-Felder werden als Avro-Union des entsprechenden Typs und als "null" dargestellt.
  • REPEATED-Felder werden als Avro-Arrays dargestellt.
  • TIMESTAMP-Datentypen werden als logische Avro-timestamp-micros-Typen dargestellt.
  • DATE-Datentypen werden standardmäßig als Avro-INT-Typen oder logische Avro-date-Typen dargestellt, wenn das Flag --use_avro_logical_types angegeben ist.
  • TIME-Datentypen werden standardmäßig als Avro-LONG-Typen oder logische Avro-time-micros-Typen dargestellt, wenn das Flag --use_avro_logical_types angegeben ist.
  • DATETIME-Datentypen werden als Avro-STRING-Typen dargestellt. Die Codierung folgt der Spezifikation RFC 3339 der Internet Engineering Task Force.
  • Die parametrisierten Datentypen NUMERIC(P[, S]) und BIGNUMERIC(P[, S]) übertragen ihre Genauigkeits- und Skalierungstypparameter an den logischen Avro-Dezimaltyp.

Das Avro-Format kann nicht in Verbindung mit der GZIP-Komprimierung verwendet werden. Komprimieren Sie Avro-Daten mit dem bq-Befehlszeilentool oder der API und geben Sie dabei einen der unterstützten Komprimierungstypen für Avro-Daten an: DEFLATE oder SNAPPY.

Parquet-Exportdetails

BigQuery konvertiert Standard-SQL-Datentypen in folgende Parquet-Datentypen:

BigQuery-Datentyp Einfacher Parquet-Typ Logischer Parquet-Typ
Integer INT64 NONE
Numerisch FIXED_LEN_BYTE_ARRAY DECIMAL (precision = 38, scale = 9)
Numeric(P[, S]) FIXED_LEN_BYTE_ARRAY DECIMAL (precision = P, scale = S)
BigNumeric FIXED_LEN_BYTE_ARRAY DECIMAL (precision = 76, scale = 38)
BigNumeric(P[, S]) FIXED_LEN_BYTE_ARRAY DECIMAL (precision = P, scale = S)
Gleitkomma FLOAT NONE
Boolesch BOOLEAN NONE
String BYTE_ARRAY STRING (UTF8)
Byte BYTE_ARRAY NONE
Datum INT32 DATE
Datum/Uhrzeit INT64 TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)
Zeit INT64 TIME (isAdjustedToUTC = false, unit = MICROS)
Zeitstempel INT64 TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)

Das Parquet-Schema stellt verschachtelte Daten als Gruppe und wiederkehrende Datensätze als wiederkehrende Gruppen dar. Weitere Informationen zur Verwendung verschachtelter und wiederkehrender Daten in BigQuery finden Sie unter Verschachtelte und wiederkehrende Spalten angeben.

Sie können die folgenden Problemumgehungen für DATETIME-Typen verwenden:

  • Laden Sie die Datei in eine Staging-Tabelle. Verwenden Sie dann eine SQL-Abfrage, um das Feld in DATETIME umzuwandeln und das Ergebnis in einer neuen Tabelle zu speichern. Weitere Informationen finden Sie unter Datentyp einer Spalte ändern.
  • Geben Sie im Ladejob das Flag --schema für die Tabelle an. Definieren Sie die Datum/Uhrzeit-Spalte als col:DATETIME.

Daten in eine oder mehrere Dateien exportieren

Das Attribut destinationUris gibt die Speicherorte der Dateinamen an, in die BigQuery die Dateien exportieren soll.

BigQuery unterstützt einen einzelnen Platzhalteroperator (*) in jedem URI. Der Platzhalter kann an jeder beliebigen Stelle im URI eingefügt werden, darf jedoch nicht Teil des Bucket-Namens sein. Durch Verwendung des Platzhalteroperators wird BigQuery angewiesen, mehrere fragmentierte Dateien gemäß dem bereitgestellten Musters zu erstellen. Der Platzhalteroperator wird durch eine Zahl (beginnend mit 0) ersetzt und nach links auf 12 Stellen aufgefüllt. Ein URI mit einem Platzhalter am Ende des Dateinamens würde Dateien erstellen, bei denen 000000000000 an den Namen der ersten Datei, 000000000001 an den Namen der zweiten Datei usw. angefügt wird.

In der folgenden Tabelle sind mehrere mögliche Optionen für das Attribut destinationUris beschrieben:

Optionen für "destinationUris"
Einzelner URI

Verwenden Sie einen einzelnen URI, wenn Sie Tabellendaten mit einer Größe von maximal 1 GB exportieren. Diese Option ist am gebräuchlichsten, da exportierte Daten im Allgemeinen unter dem Höchstwert von 1 GB liegen.

Attributdefinition:

['gs://my-bucket/file-name.json']

Erstellt:


gs://my-bucket/file-name.json
Einzelner Platzhalter-URI

Verwenden Sie einen einzelnen Platzhalter-URI, wenn Sie davon ausgehen, dass die exportierten Daten den Höchstwert von 1 GB überschreiten. BigQuery fragmentiert die Daten dann anhand des bereitgestellten Musters in mehrere Dateien. Die Größe der exportierten Dateien variiert.

Wenn Sie einen Platzhalter in einer anderen URI-Komponente als dem Dateinamen verwenden, achten Sie vor dem Export der Daten darauf, dass die Pfadkomponente nicht vorhanden ist.

Attributdefinition:

['gs://my-bucket/file-name-*.json']

Erstellt:


gs://my-bucket/file-name-000000000000.json
gs://my-bucket/file-name-000000000001.json
gs://my-bucket/file-name-000000000002.json
...
Mehrere Platzhalter-URIs

Verwenden Sie mehrere Platzhalter-URIs, wenn die Ausgabe des Exports partitioniert werden soll. Dies ist z. B. notwendig, wenn Sie einen parallelen Verarbeitungsjob mit einem Dienst wie Dataproc ausführen. Legen Sie fest, wie viele Worker für die Verarbeitung des Jobs verfügbar sein sollen, und erstellen Sie einen URI pro Worker. BigQuery behandelt jeden URI-Speicherort als eine Partition und nutzt die Parallelverarbeitung, um die Daten in mehrere Dateien pro Speicherort zu fragmentieren. Sie können jedes beliebige Muster im Dateinamen verwenden, solange nur ein Platzhalteroperator pro URI verwendet wird, alle URIs nur einmal vorkommen und die Anzahl der URIs die Kontingentrichtlinie nicht überschreitet.

Wenn Sie mehrere Platzhalter-URIs übergeben, erstellt BigQuery am Ende jeder Partition eine spezielle Datei, die die letzte Datei in der Gruppe darstellt. Dieser Dateiname gibt an, wie viele Shards von BigQuery erstellt wurden.

Wenn beispielsweise der Platzhalter-URI gs://my-bucket/file- name-<worker number>-*.json ist und BigQuery 80 fragmentierte Dateien erstellt, hat die Datei mit null Datensätzen den Namen gs://my-bucket/file-name-<worker number>-000000000080.json. An diesem Dateinamen können Sie ablesen, dass BigQuery 80 fragmentierte Dateien erstellt hat (namens 000000000000 bis 000000000079).

Beachten Sie, dass die Größe einer Datei mit null Datensätzen je nach Datenformat mehr als 0 Byte betragen kann, wie z. B. beim Export von Daten in das CSV-Format mit einer Spaltenüberschrift.

Stringmuster:

gs://my-bucket/file-name-<worker number>-*.json

Attributdefinition:


['gs://my-bucket/file-name-1-*.json',
'gs://my-bucket/file-name-2-*.json',
'gs://my-bucket/file-name-3-*.json']

Erstellt:

Bei diesem Beispiel wird davon ausgegangen, dass BigQuery 80 fragmentierte Dateien in jeder Partition erstellt.


gs://my-bucket/file-name-1-000000000000.json
gs://my-bucket/file-name-1-000000000001.json
...
gs://my-bucket/file-name-1-000000000080.json
gs://my-bucket/file-name-2-000000000000.json
gs://my-bucket/file-name-2-000000000001.json
...
gs://my-bucket/file-name-2-000000000080.json
gs://my-bucket/file-name-3-000000000000.json
gs://my-bucket/file-name-3-000000000001.json
...
gs://my-bucket/file-name-3-000000000080.json

Komprimierte Tabelle extrahieren

Go

Bevor Sie dieses Beispiel ausprobieren, 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. 

import (
	"context"
	"fmt"

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

// exportTableAsCompressedCSV demonstrates using an export job to
// write the contents of a table into Cloud Storage as compressed CSV.
func exportTableAsCompressedCSV(projectID, gcsURI string) error {
	// projectID := "my-project-id"
	// gcsUri := "gs://mybucket/shakespeare.csv"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	srcProject := "bigquery-public-data"
	srcDataset := "samples"
	srcTable := "shakespeare"

	gcsRef := bigquery.NewGCSReference(gcsURI)
	gcsRef.Compression = bigquery.Gzip

	extractor := client.DatasetInProject(srcProject, srcDataset).Table(srcTable).ExtractorTo(gcsRef)
	extractor.DisableHeader = true
	// You can choose to run the job in a specific location for more complex data locality scenarios.
	// Ex: In this example, source dataset and GCS bucket are in the US.
	extractor.Location = "US"

	job, err := extractor.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 ausprobieren, folgen Sie den Schritten zur Einrichtung von Java in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur BigQuery Java API. 

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.ExtractJobConfiguration;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.TableId;

// Sample to extract a compressed table
public class ExtractTableCompressed {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectName = "MY_PROJECT_NAME";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String bucketName = "MY-BUCKET-NAME";
    String destinationUri = "gs://" + bucketName + "/path/to/file";
    // For more information on export formats available see:
    // https://cloud.google.com/bigquery/docs/exporting-data#export_formats_and_compression_types
    String compressed = "gzip";
    // For more information on Job see:
    // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
    String dataFormat = "CSV";

    extractTableCompressed(
        projectName, datasetName, tableName, destinationUri, dataFormat, compressed);
  }

  public static void extractTableCompressed(
      String projectName,
      String datasetName,
      String tableName,
      String destinationUri,
      String dataFormat,
      String compressed) {
    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(projectName, datasetName, tableName);

      ExtractJobConfiguration extractConfig =
          ExtractJobConfiguration.newBuilder(tableId, destinationUri)
              .setCompression(compressed)
              .setFormat(dataFormat)
              .build();

      Job job = bigquery.create(JobInfo.of(extractConfig));

      // Blocks until this job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to extract due to an error: \n" + job.getStatus().getError());
        return;
      }
      System.out.println("Table extract compressed successful");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \n" + e.toString());
    }
  }
}

Node.js

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

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

const bigquery = new BigQuery();
const storage = new Storage();

async function extractTableCompressed() {
  // Exports my_dataset:my_table to gcs://my-bucket/my-file as a compressed file.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  // const bucketName = "my-bucket";
  // const filename = "file.csv";

  // Location must match that of the source table.
  const options = {
    location: 'US',
    gzip: true,
  };

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

  console.log(`Job ${job.id} created.`);

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

Python

Bevor Sie dieses Beispiel ausprobieren, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur  Python API. 

# from google.cloud import bigquery
# client = bigquery.Client()
# bucket_name = 'my-bucket'

destination_uri = "gs://{}/{}".format(bucket_name, "shakespeare.csv.gz")
dataset_ref = bigquery.DatasetReference(project, dataset_id)
table_ref = dataset_ref.table("shakespeare")
job_config = bigquery.job.ExtractJobConfig()
job_config.compression = bigquery.Compression.GZIP

extract_job = client.extract_table(
    table_ref,
    destination_uri,
    # Location must match that of the source table.
    location="US",
    job_config=job_config,
)  # API request
extract_job.result()  # Waits for job to complete.

Kontingentrichtlinie

Weitere Informationen zum Exportieren von Jobkontingenten finden Sie auf der Seite "Kontingente und Beschränkungen" unter Jobs exportieren.

Preise

Derzeit ist das Exportieren von BigQuery-Daten kostenlos. Die Exporte unterliegen jedoch den Kontingenten und Limits von BigQuery. Weitere Informationen zu den Preisen von BigQuery finden Sie auf der Seite BigQuery-Preise.

Nachdem die Daten exportiert wurden, wird das Speichern der Daten in Cloud Storage in Rechnung gestellt. Weitere Informationen zu den Preisen von Cloud Storage erhalten Sie auf der Seite Cloud Storage – Preise.

Tabellensicherheit

Informationen zum Steuern des Zugriffs auf Tabellen in BigQuery finden Sie unter Einführung in die Tabellenzugriffssteuerung.

Nächste Schritte