Ekspor data tabel ke Cloud Storage.

Halaman ini menjelaskan cara mengekspor atau mengekstrak data dari tabel BigQuery ke Cloud Storage.

Setelah memuat data ke BigQuery, Anda dapat mengekspor data tersebut dalam beberapa format. BigQuery dapat mengekspor hingga 1 GB data ke satu file. Jika mengekspor lebih dari 1 GB data, Anda harus mengekspor data ke beberapa file. Saat Anda mengekspor data ke beberapa file, ukuran file akan bervariasi.

Anda dapat menggunakan layanan seperti Dataflow untuk membaca data dari BigQuery, alih-alih mengekspornya secara manual. Untuk mengetahui informasi lebih lanjut tentang cara menggunakan Dataflow untuk membaca dan menulis ke BigQuery, lihat BigQuery I/O di dokumentasi Apache Beam.

Anda juga dapat mengekspor hasil kueri menggunakan pernyataan EXPORT DATA. Anda dapat menggunakan EXPORT DATA OPTIONS untuk mengekspor tampilan ke Cloud Storage.

Batasan ekspor

Saat Anda mengekspor data dari BigQuery, perhatikan hal-hal berikut:

• Anda tidak dapat mengekspor data tabel ke file lokal, ke Google Spreadsheet, atau Google Drive. Satu-satunya lokasi ekspor yang didukung adalah Cloud Storage. Untuk mengetahui informasi tentang cara menyimpan hasil kueri, lihat Mendownload dan menyimpan hasil kueri.
• Anda dapat mengekspor hingga 1 GB data tabel ke satu file. Jika Anda mengekspor lebih dari 1 GB data, gunakan karakter pengganti untuk mengekspor data ke beberapa file. Saat Anda mengekspor data ke beberapa file, ukuran file akan bervariasi. Untuk membatasi ukuran file yang diekspor, Anda dapat mempartisi data dan mengekspor setiap partisi.
• Ukuran file yang dihasilkan saat menggunakan pernyataan EXPORT DATA tidak dijamin.
• Jumlah file yang dihasilkan oleh tugas ekspor dapat bervariasi.
• Anda tidak dapat mengekspor data bertingkat dan berulang dalam format CSV. Data bertingkat dan berulang didukung untuk ekspor Avro, JSON, dan Parquet.
• Saat Anda mengekspor data dalam format JSON, jenis data INT64 (bilangan bulat) dienkode sebagai string JSON untuk mempertahankan presisi 64-bit saat data tersebut dibaca oleh sistem lain.
• Anda tidak dapat mengekspor data dari beberapa tabel dalam satu tugas ekspor.
• Anda tidak dapat memilih jenis kompresi selain GZIP saat mengekspor data menggunakan Konsol Google Cloud.
• Saat Anda mengekspor data ke bucket Cloud Storage yang dikonfigurasi dengan kebijakan retensi, BigQuery mungkin gagal menulis file ke bucket. Konfigurasi periode retensi data agar lebih lama daripada durasi tugas ekspor.
• Saat Anda mengekspor tabel dalam format JSON, simbol <, >, dan & akan dikonversi menggunakan notasi unicode \uNNNN, dengan N adalah digit heksadesimal. Misalnya, profit&loss menjadi profit\u0026loss. Konversi unicode ini dilakukan untuk menghindari kerentanan keamanan.
• Urutan data tabel yang diekspor tidak dijamin kecuali jika Anda menggunakan pernyataan EXPORT DATA dan menentukan klausa ORDER BY di query_statement.
• BigQuery tidak mendukung jalur resource Cloud Storage yang mencakup beberapa garis miring berturut-turut setelah garis miring ganda di awal. Nama objek Cloud Storage dapat berisi beberapa karakter garis miring ("/") berturut-turut. Namun, BigQuery mengonversi beberapa garis miring berturut-turut menjadi satu garis miring. Misalnya, jalur resource berikut, meskipun valid di Cloud Storage, tidak berfungsi di BigQuery: gs://bucket/my//object//name.
• Anda tidak dapat mengekspor data dari snapshot tabel.

Sebelum memulai

Berikan peran Identity and Access Management (IAM) yang akan memberikan izin yang diperlukan pengguna untuk melakukan setiap tugas dalam dokumen ini.

Izin yang diperlukan

Untuk melakukan tugas dalam dokumen ini, Anda memerlukan izin berikut.

Izin untuk mengekspor data dari tabel BigQuery

Untuk mengekspor data dari tabel BigQuery, Anda memerlukan izin IAM bigquery.tables.export.

Setiap peran IAM yang telah ditetapkan berikut menyertakan izin bigquery.tables.export:

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

Izin untuk menjalankan tugas ekspor

Untuk menjalankan tugas ekspor, Anda memerlukan izin IAM bigquery.jobs.create.

Setiap peran IAM yang telah ditetapkan berikut menyertakan izin yang diperlukan untuk menjalankan tugas ekspor:

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

Izin untuk menulis data ke bucket Cloud Storage

Untuk menulis data ke bucket Cloud Storage yang ada, Anda memerlukan izin IAM berikut:

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

Masing-masing peran IAM yang telah ditetapkan berikut menyertakan izin yang Anda perlukan untuk menulis data ke bucket Cloud Storage yang ada:

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

Untuk mengetahui informasi lebih lanjut tentang peran dan izin IAM di BigQuery, lihat Peran dan izin yang telah ditetapkan.

Pertimbangan lokasi

Alokasikan bucket Cloud Storage Anda untuk mengekspor data:

• Jika set data BigQuery Anda berada di multi-region EU, bucket Cloud Storage yang berisi data yang Anda ekspor harus berada di multi-region yang sama atau di lokasi yang terdapat dalam multi-region tersebut. Misalnya, jika set data BigQuery Anda berada di multi-region EU, bucket Cloud Storage dapat berada di region Belgia europe-west1, yang berada di Uni Eropa.

  Jika set data Anda berada di multi-region US, Anda dapat mengekspor data ke bucket Cloud Storage di lokasi mana pun.

• Jika set data Anda berada di suatu region, bucket Cloud Storage Anda harus berada di region yang sama. Misalnya, jika set data Anda berada di region Tokyo asia-northeast1, bucket Cloud Storage Anda tidak boleh berada di multi-region ASIA.

Kembangkan rencana pengelolaan data:

• Jika Anda memilih resource penyimpanan regional seperti set data BigQuery atau bucket Cloud Storage, kembangkan rencana untuk mengelola data Anda secara geografis.

Untuk mengetahui informasi selengkapnya tentang lokasi Cloud Storage, lihat Lokasi Bucket dalam dokumentasi Cloud Storage.

Memindahkan data BigQuery antarlokasi

Anda tidak dapat mengubah lokasi set data setelah dibuat, tetapi Anda dapat membuat salinan set data. Anda tidak dapat memindahkan set data dari satu lokasi ke lokasi lain, tetapi Anda dapat memindahkan (membuat ulang) set data secara manual.

Mengekspor format dan jenis kompresi

BigQuery mendukung format data dan jenis kompresi berikut untuk data yang diekspor.

Format data	Jenis kompresi yang didukung	Detail
CSV	GZIP	Anda dapat mengontrol delimiter CSV dalam data yang diekspor menggunakan flag alat command line bq --field_delimiter atau configuration.extract.fieldDelimiter properti tugas mengekstrak. Data bertingkat dan berulang tidak didukung.
JSON	GZIP	Data bertingkat dan berulang didukung.
Avro	DEFLATE, SNAPPY	GZIP tidak didukung untuk ekspor Avro. Data bertingkat dan berulang didukung. Lihat detail ekspor Avro.
Parquet	SNAPPY, GZIP, ZSTD	Data bertingkat dan berulang didukung. Lihat Detail ekspor Parquet.

Mengekspor data

Anda dapat mengekspor data tabel dengan:

• Menggunakan konsol Google Cloud
• Menggunakan perintah bq extract di alat command line bq
• Mengirimkan extracttugas ekstrak melalui API atau library klien.

Ekspor data tabel

Untuk mengekspor data dari tabel BigQuery:

Konsol

1. Buka halaman BigQuery di konsol Google Cloud.

   Buka halaman BigQuery

2. Di panel Penjelajah, luaskan project dan set data Anda, lalu pilih tabel.

3. Di panel detail, klik Ekspor dan pilih Ekspor ke Cloud Storage.

4. Pada dialog Ekspor tabel ke Google Cloud Storage:

   • Untuk bagian Pilih lokasi Google Cloud Storage, cari bucket, folder, atau file tempat Anda ingin mengekspor data.
   • Untuk Format ekspor, pilih format untuk data yang diekspor: CSV, JSON (Newline Dibatasi), Avro, atau Parquet.
   • Untuk Kompresi, pilih format kompresi atau pilih None jika tidak ada kompresi.
   • Klik Ekspor untuk mengekspor tabel.

Untuk memeriksa progres tugas, lihat di dekat bagian atas navigasi untuk Histori tugas untuk tugas Ekspor.

Untuk mengekspor tampilan ke Cloud Storage, gunakan pernyataan EXPORT DATA OPTIONS.

SQL

Gunakan pernyataan EXPORT DATA. Contoh berikut mengekspor kolom yang dipilih dari tabel bernama mydataset.table1:

1. Di konsol Google Cloud, buka halaman BigQuery.

   Buka BigQuery

2. Di editor kueri, masukkan pernyataan berikut:

   EXPORT DATA
     OPTIONS (
       uri = 'gs://bucket/folder/*.csv',
       format = 'CSV',
       overwrite = true,
       header = true,
       field_delimiter = ';')
   AS (
     SELECT field1, field2
     FROM mydataset.table1
     ORDER BY field1
   );
   

3. Klik Run.

Untuk informasi selengkapnya tentang cara menjalankan kueri, lihat Menjalankan kueri interaktif.

bq

Gunakan perintah bq extract dengan flag --destination_format.

(Opsional) Berikan flag --location dan tetapkan nilainya ke lokasi Anda.

Flag opsional lainnya meliputi:

• --compression: Jenis kompresi yang akan digunakan untuk file yang diekspor.
• --field_delimiter: Karakter yang menunjukkan batas antar-kolom dalam file output untuk ekspor CSV. Baik \t maupun tab diizinkan untuk pembatas tab.
• --print_header: Jika ditentukan, cetak baris header untuk format yang memiliki header seperti CSV.

bq extract --location=location \
--destination_format format \
--compression compression_type \
--field_delimiter delimiter \
--print_header=boolean \
project_id:dataset.table \
gs://bucket/filename.ext

Dengan keterangan:

• location adalah nama lokasi Anda. Flag --location bersifat opsional. Misalnya, jika menggunakan BigQuery di region Tokyo, Anda dapat menetapkan nilai flag ke asia-northeast1. Anda dapat menetapkan nilai default untuk lokasi menggunakan file.bigqueryrc.
• format adalah format untuk data yang diekspor: CSV, NEWLINE_DELIMITED_JSON, AVRO, atau PARQUET.
• compression_type adalah jenis kompresi yang didukung untuk format data Anda. Lihat Mengekspor format dan jenis kompresi.
• delimiter adalah karakter yang menunjukkan batas antar-kolom dalam ekspor CSV. \t dan tab adalah nama yang diterima untuk tab.
• boolean adalah true atau false. Jika ditetapkan ke true, baris header akan dicetak ke data yang diekspor jika format data mendukung header. Nilai defaultnya adalah true.
• project_id adalah project ID Anda.
• dataset adalah nama set data sumber.
• table adalah tabel yang Anda ekspor. Jika menggunakan dekorator partisi, Anda harus mengapit jalur tabel dengan tanda kutip tunggal atau meng-escape karakter $.
• bucket adalah nama bucket Cloud Storage tempat Anda mengekspor data. Set data BigQuery dan bucket Cloud Storage harus berada di lokasi yang sama.
• filename.ext adalah nama dan ekstensi file data yang diekspor. Anda dapat mengekspor ke beberapa file menggunakan karakter pengganti.

Contoh:

Misalnya, perintah berikut mengekspor mydataset.mytable ke file terkompresi gzip yang bernama myfile.csv. myfile.csv disimpan di bucket Cloud Storage bernama example-bucket.

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

Format tujuan default adalah CSV. Untuk mengekspor ke JSON atau Avro, gunakan flag destination_format dan tetapkan ke NEWLINE_DELIMITED_JSON atau AVRO. Contoh:

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

Perintah berikut mengekspor mydataset.mytable ke dalam file Avro yang dikompresi menggunakan Snappy. Nama filenya adalah myfile.avro. myfile.avro diekspor ke bucket Cloud Storage bernama example-bucket.

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

Perintah berikut mengekspor satu partisi mydataset.my_partitioned_table ke file CSV di Cloud Storage:

bq extract \
--destination_format CSV \
'mydataset.my_partitioned_table$0' \
gs://example-bucket/single_partition.csv

API

Untuk mengekspor data, buat tugas extract dan isi konfigurasi tugas.

Catatan: Jika Anda mengekspor data ke format Parquet, mungkin akan lebih cepat jika Anda menggunakan template BigQuery Export ke Parquet (melalui BigQuery Storage API) , bukan menulis solusi kustom.

(Opsional) Tentukan lokasi Anda di properti location di bagian jobReference pada resource tugas.

1. Buat tugas ekstrak yang mengarah ke data sumber BigQuery dan tujuan Cloud Storage.

2. Tentukan tabel sumber menggunakan objek konfigurasi sourceTable yang berisi project ID, ID set data, dan ID tabel.

3. Properti destination URI(s) harus sepenuhnya memenuhi syarat, dalam format gs://bucket/filename.ext. Setiap URI dapat berisi satu karakter pengganti '*' dan harus muncul setelah nama bucket.

4. Tentukan format data dengan menetapkan properti configuration.extract.destinationFormat. Misalnya, untuk mengekspor file JSON, tetapkan properti ini ke nilai NEWLINE_DELIMITED_JSON.

5. Untuk memeriksa status tugas, panggil jobs.get(job_id) dengan ID tugas yang ditampilkan oleh permintaan awal.

   • Jika status.state = DONE, tugas berhasil diselesaikan.
   • Jika properti status.errorResult ada, permintaan gagal, dan objek tersebut akan menyertakan informasi yang menjelaskan penyebabnya.
   • Jika status.errorResult tidak ada, tugas berhasil diselesaikan, meskipun mungkin ada beberapa error non-fatal. Error non-fatal tercantum dalam properti status.errors objek tugas yang ditampilkan.

Catatan API:

• Sebagai praktik terbaik, buat ID unik dan teruskan sebagai jobReference.jobId saat memanggil jobs.insert untuk membuat tugas. Pendekatan ini lebih tangguh untuk kegagalan jaringan karena klien dapat melakukan polling atau mencoba ulang ID tugas yang diketahui.

• Memanggil jobs.insert pada ID pekerjaan tertentu bersifat idempoten; dengan kata lain, Anda dapat mencoba sebanyak yang Anda inginkan pada ID tugas yang sama, dan maksimal satu dari operasi tersebut akan berhasil.

C#

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery C# API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Go API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Node.js API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

// 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan PHP di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery PHP API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

use Google\Cloud\BigQuery\BigQueryClient;

/**
 * Extracts the given table as json to given GCS bucket.
 *
 * @param string $projectId The project Id of your Google Cloud Project.
 * @param string $datasetId The BigQuery dataset ID.
 * @param string $tableId The BigQuery table ID.
 * @param string $bucketName Bucket name in Google Cloud Storage
 */
function extract_table(
    string $projectId,
    string $datasetId,
    string $tableId,
    string $bucketName
): void {
    $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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Python API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

# 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Ruby di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Ruby API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Detail ekspor Avro

BigQuery mengekspresikan data berformat Avro dengan cara berikut:

• File ekspor yang dihasilkan adalah file kontainer Avro.
• Setiap baris BigQuery direpresentasikan sebagai data Avro. Data bertingkat direpresentasikan oleh objek data bertingkat.
• Kolom REQUIRED direpresentasikan sebagai jenis Avro yang sesuai. Misalnya, jenis INTEGER BigQuery dipetakan ke jenis LONG Avro.
• Kolom NULLABLE direpresentasikan sebagai union Avro dari jenis yang sesuai dan "null".
• Kolom REPEATED direpresentasikan sebagai array Avro.
• Jenis data TIMESTAMP direpresentasikan sebagai jenis logika timestamp-micros (menganotasi jenis LONG Avro) secara default di tugas Ekstrak dan Ekspor Data SQL. (Perhatian: Anda dapat menambahkanuse_avro_logical_types=False hingga Export Data Options menonaktifkan tipe logika sehingga menggunakanstring sebagai gantinya di kolom stempel waktu, tetapi dalam Tugas Ekstraksi, selalu menggunakan jenis logika Avro.)
• Jenis data DATE direpresentasikan sebagai jenis logika date (menganotasi jenis INT Avro) secara default di Export Data SQL, tetapi direpresentasikan sebagai jenis string secara default di tugas Ekstraksi. (Catatan: Anda dapat menambahkan use_avro_logical_types=False ke Export Data Options untuk menonaktifkan jenis logika, atau menggunakan flag --use_avro_logical_types=True untuk mengaktifkan jenis logika dalam tugas Ekstrak.)
• Jenis data TIME direpresentasikan sebagai jenis logika timestamp-micro (menganotasi jenis LONG Avro) secara default di Export Data SQL, tetapi direpresentasikan sebagai jenis string secara default di tugas Ekstraksi. (Catatan: Anda dapat menambahkan use_avro_logical_types=False ke Export Data Options untuk menonaktifkan jenis logika, atau menggunakan flag --use_avro_logical_types=True untuk mengaktifkan jenis logika dalam tugas Ekstraksi.)
• Jenis data DATETIME direpresentasikan sebagai jenis STRING Avro (jenis string dengan jenis logika bernama kustom datetime) secara default dalam Export Data SQL, tetapi direpresentasikan sebagai string secara default di tugas Ekstrak. (Catatan: Anda dapat menambahkan use_avro_logical_types=False ke Export Data Options untuk menonaktifkan jenis logika, atau menggunakan flag --use_avro_logical_types=True untuk mengaktifkan jenis logis dalam tugas Ekstraksi.)

Catatan: Encoding jenis string mengikuti spesifikasi RFC 3339 Internet Engineering Task Force.

Jenis data NUMERIC(P[, S]) dan BIGNUMERIC(P[, S]) yang berparameter akan mentransfer parameter jenis skala dan presisi keduanya ke jenis logika desimal Avro.

Perhatian:

• Jika mengekspor jenis DATETIME ke Avro, Anda tidak dapat memuat file Avro langsung kembali ke skema tabel yang sama, karena STRING yang dikonversi tidak akan cocok dengan skema. Sebagai solusinya, muat file ke dalam tabel staging. Kemudian, gunakan kueri SQL untuk mentransmisikan kolom ke jenis DATETIME dan menyimpan hasilnya ke tabel baru. Untuk mengetahui informasi selengkapnya, lihat Mengubah jenis data kolom .
• Opsi Data Ekspor use_avro_logical_types dan flag Tugas Ekstraksi --use_avro_logical_types diterapkan ke semua jenis logika secara bersamaan setelah ditentukan.

Format Avro tidak dapat digunakan bersama dengan kompresi GZIP. Untuk mengompresi data Avro, gunakan alat command line bq atau API dan tentukan salah satu jenis kompresi yang didukung untuk data Avro: DEFLATE atau SNAPPY.

Detail ekspor Parquet

BigQuery mengonversi jenis data GoogleSQL ke jenis data Parquet berikut:

Jenis data BigQuery	Jenis primitif Parquet	Jenis logika Parquet
Bilangan bulat	INT64	NONE
Angka	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)
Titik mengambang	FLOAT	NONE
Boolean	BOOLEAN	NONE
String	BYTE_ARRAY	STRING (UTF8)
Byte	BYTE_ARRAY	NONE
Tanggal	INT32	DATE
Datetime	INT64	TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)
Waktu	INT64	TIME (isAdjustedToUTC = true, unit = MICROS)
Stempel waktu	INT64	TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)

Skema Parquet mewakili data bertingkat sebagai grup dan data berulang sebagai grup berulang. Untuk mengetahui informasi selengkapnya tentang penggunaan data bertingkat dan berulang di BigQuery, lihat Menentukan kolom bertingkat dan berulang.

Perhatian: Jika mengekspor jenis DATETIME ke Parquet, Anda tidak dapat memuat fileParquet secara langsung kembali ke skema tabel yang sama, karena file yang dikonversi tidak akan cocok dengan skema.

Anda dapat menggunakan solusi berikut untuk jenis DATETIME:

• Muat file ke tabel staging. Kemudian, gunakan kueri SQL untuk mentransmisikan kolom ke DATETIME dan menyimpan hasilnya ke tabel baru. Untuk mengetahui informasi selengkapnya, lihat Mengubah jenis data kolom.
• Berikan skema untuk tabel menggunakan flag --schema dalam tugas pemuatan. Tentukan kolom tanggal dan waktu sebagai col:DATETIME.

Mengekspor data ke satu atau beberapa file

Properti destinationUris menunjukkan satu atau beberapa lokasi dan nama file tempat BigQuery harus mengekspor file Anda.

BigQuery mendukung operator karakter pengganti tunggal (*) di setiap URI. Karakter pengganti dapat muncul di mana saja dalam URI kecuali sebagai bagian dari nama bucket. Penggunaan operator karakter pengganti menginstruksikan BigQuery untuk membuat beberapa file shard berdasarkan pola yang diberikan. Operator karakter pengganti diganti dengan angka (dimulai dari 0), dengan padding kiri hingga 12 digit. Misalnya, URI dengan karakter pengganti di akhir nama file akan membuat file dengan000000000000 ditambahkan ke file pertama, 000000000001 ditambahkan ke file kedua, dan selanjutnya.

Tabel berikut menjelaskan beberapa kemungkinan opsi untuk properti destinationUris:

Opsi destinationUris
URI tunggal	Gunakan URI tunggal jika Anda mengekspor data tabel yang berukuran 1 GB atau kurang. Opsi ini adalah kasus penggunaan yang paling umum, karena data yang diekspor umumnya kurang dari nilai maksimum 1 GB. Opsi ini tidak didukung untuk pernyataan EXPORT DATA; Anda harus menggunakan satu URI karakter pengganti. Definisi properti: ['gs://my-bucket/file-name.json'] Membuat: gs://my-bucket/file-name.json
URI karakter pengganti tunggal	Gunakan URI karakter pengganti tunggal jika menurut Anda data yang diekspor akan lebih besar dari nilai maksimum 1 GB. BigQuery melakukan sharding data menjadi beberapa file berdasarkan pola yang diberikan. Ukuran file yang diekspor akan bervariasi. Jika Anda menggunakan karakter pengganti di komponen URI selain nama file, pastikan komponen jalur tidak ada sebelum mengekspor data Anda. Definisi properti: ['gs://my-bucket/file-name-*.json'] Membuat: gs://my-bucket/file-name-000000000000.json gs://my-bucket/file-name-000000000001.json gs://my-bucket/file-name-000000000002.json ...

Membatasi ukuran file yang diekspor

Jika Anda mengekspor lebih dari 1 GB data dalam sekali ekspor, Anda harus menggunakan karakter pengganti untuk mengekspor data ke beberapa file, dan ukuran file dapat bervariasi. Jika Anda perlu membatasi ukuran maksimum setiap file yang diekspor, salah satu opsinya adalah mempartisi data Anda secara acak, lalu mengekspor setiap partisi ke file:

1. Tentukan jumlah partisi yang Anda perlukan, yang sama dengan ukuran total data dibagi dengan ukuran file hasil ekspor yang diinginkan. Misalnya, jika Anda memiliki data sebesar 8.000 MB dan ingin setiap file yang diekspor berukuran sekitar 20 MB, maka Anda memerlukan 400 partisi.

2. Buat tabel baru yang dipartisi dan dikelompokkan oleh kolom baru yang dibuat secara acak yang disebut export_id. Contoh berikut menunjukkan cara membuat processed_table baru dari tabel yang ada bernama source_table yang memerlukan partisi n untuk mencapai ukuran file yang diinginkan:

   CREATE TABLE my_dataset.processed_table
   PARTITION BY RANGE_BUCKET(export_id, GENERATE_ARRAY(0, n, 1))
   CLUSTER BY export_id
   AS (
     SELECT *, CAST(FLOOR(n*RAND()) AS INT64) AS export_id
     FROM my_dataset.source_table
   );
   

3. Untuk setiap bilangan bulat i antara 0 dan n-1, jalankan pernyataan EXPORT DATA pada kueri berikut:

   SELECT * EXCEPT(export_id)
   FROM my_dataset.processed_table
   WHERE export_id = i;
   

Mengekstrak tabel terkompresi

Go

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Go API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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: %w", 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Node.js API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

// 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Python API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien.

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

Contoh kasus penggunaan

Contoh ini menunjukkan cara mengekspor data ke Cloud Storage.

Misalkan Anda melakukan streaming data ke Cloud Storage dari log endpoint secara kontinu. Snapshot harian akan diekspor ke Cloud Storage untuk tujuan pencadangan dan pengarsipan. Pilihan terbaik adalah tugas ekstraksi yang tunduk pada quotas dan batasan tertentu.

Kirim tugas ekstraksi dengan API atau library klien, dengan meneruskan ID unik sebagai jobReference.jobId. Tugas Ekstraksi bersifat asinkron. Periksa status tugas menggunakan ID tugas unik yang digunakan untuk membuat tugas. Tugas berhasil diselesaikan jika status.status adalah DONE. Jika status.errorResult ada, tugas gagal dan perlu dicoba lagi.

Pemrosesan data batch

Misalnya tugas batch per malam digunakan untuk memuat data berdasarkan batas waktu tetap. Setelah tugas pemuatan ini selesai, tabel dengan statistik akan terwujud dari sebuah kueri seperti yang dijelaskan di bagian sebelumnya. Data dari tabel ini diambil dan dikompilasi ke dalam laporan PDF lalu dikirim ke badan pengatur.

Karena jumlah data yang perlu dibaca kecil, gunakan tabledata.list API untuk mengambil semua baris tabel dalam format kamus JSON. Jika ada lebih dari satu halaman data, hasilnya akan menetapkan properti pageToken. Untuk mengambil halaman hasil berikutnya, lakukan panggilan tabledata.list lain dan sertakan nilai token sebagai parameter pageToken. Jika panggilan API gagal dengan error 5xx, coba lagi dengan backoff eksponensial. Sebagian besar error 4xx tidak dapat dicoba lagi. Untuk pemisahan yang lebih baik antara ekspor BigQuery dan pembuatan laporan, hasil harus disimpan ke disk.

Kebijakan kuota

Untuk mengetahui informasi tentang kuota tugas ekspor, lihat Tugas Ekspor di halaman Kuota dan batas.

Penggunaan untuk tugas ekspor tersedia di INFORMATION_SCHEMA. Entri tugas di tabel sistem JOBS_BY_* untuk tugas ekspor berisi nilai total_processed_bytes yang dapat digunakan untuk memantau penggunaan agregat untuk memastikannya tetap di bawah 50 TB per hari. Untuk mempelajari cara membuat kueri tampilan INFORMATION_SCHEMA.JOBS guna mendapatkan nilai total_processed_bytes, lihat Mendapatkan byte yang diproses oleh tugas ekspor

Melihat penggunaan kuota saat ini

Anda dapat melihat penggunaan tugas kueri, pemuatan, ekstrak, atau penyalinan saat ini dengan menjalankan kueri INFORMATION_SCHEMA untuk melihat metadata tentang tugas yang dijalankan selama jangka waktu yang ditentukan. Anda dapat membandingkan penggunaan saat ini dengan batas kuota untuk menentukan penggunaan kuota jenis tugas tertentu. Contoh kueri berikut menggunakan tampilan INFORMATION_SCHEMA.JOBS untuk mencantumkan jumlah tugas kueri, pemuatan, ekstraksi, dan penyalinan menurut project:

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()

Anda dapat menyiapkan kebijakan pemberitahuan Cloud Monitoring yang memberikan notifikasi tentang jumlah byte yang diekspor.

1. Di konsol Google Cloud, buka halaman Monitoring.

   Buka Monitoring

2. Di panel navigasi, pilih Metrics Explorer.

3. Di editor kueri MQL, siapkan pemberitahuan untuk memantau byte yang diekspor per hari, seperti yang terlihat pada contoh berikut:

   fetch consumer_quota
     | filter resource.service == 'bigquery.googleapis.com'
     | { metric serviceruntime.googleapis.com/quota/rate/net_usage
         | align delta_gauge(1m)
         | group_by [resource.project_id, metric.quota_metric, resource.location],
             sum(value.net_usage)
       ; metric serviceruntime.googleapis.com/quota/limit
         | filter metric.limit_name == 'ExtractBytesPerDay'
         | group_by [resource.project_id, metric.quota_metric, resource.location],
             sliding(1m), max(val()) }
     | ratio
     | every 1m
     | condition gt(val(), 0.01 '1')
   

4. Untuk menyiapkan pemberitahuan, klik Jalankan kueri.

Untuk informasi selengkapnya, lihat Kebijakan pemberitahuan dengan MQL.

Harga

Untuk mengetahui informasi tentang harga ekspor data, lihat halaman Harga BigQuery.

Setelah data diekspor, Anda akan dikenai biaya penyimpanan data di Cloud Storage. Untuk mengetahui informasi lebih lanjut, lihat Harga Cloud Storage.

Keamanan tabel

Untuk mengontrol akses ke tabel di BigQuery, lihat Pengantar kontrol akses tabel.

Langkah selanjutnya

• Untuk mempelajari konsol Google Cloud lebih lanjut, lihat Menggunakan Konsol Google Cloud.
• Untuk mempelajari alat command line bq lebih lanjut, lihat Menggunakan alat command line bq.
• Untuk mempelajari cara membuat aplikasi menggunakan library klien BigQuery API, lihat Panduan memulai library klien.