テーブルデータのエクスポート

このページでは、BigQuery テーブルからデータをエクスポートまたは抽出する方法について説明します。

BigQuery にデータを読み込んだ後、さまざまな形式でデータをエクスポートできます。BigQuery は最大 1 GB のデータを 1 つのファイルにエクスポートできます。1 GB を超えるデータをエクスポートする場合は、データを複数のファイルにエクスポートする必要があります。データを複数のファイルにエクスポートすると、さまざまなサイズのファイルになります。

Dataflow などのサービスを使用すると、データを手動でエクスポートする代わりに、BigQuery から直接読み取ることができます。Dataflow を使用した BigQuery の読み取りと書き込みの詳細については、Apache Beam ドキュメントの BigQuery I/O をご覧ください。

必要な権限

Cloud Storage にデータをエクスポートするには、データを含む BigQuery テーブルにアクセスするための権限、エクスポート ジョブの実行権限、Cloud Storage バケットにデータを書き込むための権限が必要です。

BigQuery の権限

  • データをエクスポートするには、少なくとも bigquery.tables.export 権限が付与されている必要があります。事前定義された以下の IAM のロールには bigquery.tables.export 権限が含まれています。

    • bigquery.dataViewer
    • bigquery.dataOwner
    • bigquery.dataEditor
    • bigquery.admin

  • エクスポート ジョブを実行するには、少なくとも bigquery.jobs.create 権限が付与されている必要があります。事前定義された以下の IAM のロールには bigquery.jobs.create 権限が含まれています。

    • bigquery.user
    • bigquery.jobUser
    • bigquery.admin

Cloud Storage の権限

  • 既存の Cloud Storage バケットにデータを書き込むには、storage.objects.create 権限と storage.objects.delete 権限が付与されている必要があります。これら 2 つの権限は、事前定義された以下の IAM のロールによって付与されます。

    • storage.objectAdmin
    • storage.admin

エクスポートの制限事項

BigQuery からデータをエクスポートするときは、次の点に注意してください。

  • テーブルデータをローカル ファイル、スプレッドシート、ドライブにエクスポートすることはできません。可能なエクスポート先は Cloud Storage だけです。クエリ結果の保存については、クエリ結果のダウンロードと保存をご覧ください。
  • 1 つのファイルに最大 1 GB のテーブルデータをエクスポートできます。1 GB を超えるデータをエクスポートする場合は、ワイルドカードを使用してデータを複数のファイルにエクスポートします。データを複数のファイルにエクスポートすると、さまざまなサイズのファイルになります。
  • ネストや繰り返しのあるデータを CSV 形式でエクスポートすることはできません。ネストや繰り返しのあるデータは、Avro および JSON のエクスポートでサポートされています。
  • データを JSON 形式でエクスポートするときは、INT64（整数）データ型が JSON 文字列としてエンコードされます。これは、そのデータが他のシステムで読み込まれるときに 64 ビットの精度を保持するためです。
  • 単一のエクスポート ジョブで複数のテーブルからデータをエクスポートすることはできません。
  • Cloud Console または従来の BigQuery ウェブ UI を使用してデータをエクスポートする場合、GZIP 以外の圧縮タイプを選択することはできません。

ロケーションに関する留意事項

データのロケーションを選択するときは、次の点を考慮してください。

  • データをエクスポートするには Cloud Storage バケットを同じリージョンに配置する
    • データをエクスポートする場合、リージョンまたはマルチリージョンの Cloud Storage バケットを BigQuery データセットと同じロケーションに配置する必要があります。たとえば、BigQuery データセットが EU のマルチリージョン ロケーションにある場合、エクスポート対象のデータが含まれている Cloud Storage バケットは EU のリージョンまたはマルチリージョン ロケーションに存在する必要があります。
    • データセットがリージョン ロケーションにある場合、Cloud Storage バケットは同じロケーションのリージョン バケットに存在する必要があります。たとえば、データセットが東京リージョンにある場合、Cloud Storage バケットは東京のリージョン バケットである必要があります。
    • 例外: データセットが米国のマルチリージョン ロケーションにある場合、任意のリージョンまたはマルチリージョン ロケーションにある Cloud Storage バケットにデータをエクスポートできます。
  • データ管理計画を作成する
    • BigQuery データセットや Cloud Storage バケットなどのリージョン ストレージ リソースを選択する場合は、データの地理的管理を行うための計画を作成します。

Cloud Storage のロケーションの詳細については、Cloud Storage のドキュメントのバケットのロケーションをご覧ください。

ロケーション間での BigQuery データの移動

データセットの作成後にそのロケーションを変更することはできませんが、データセットのコピーを作成することはできます。また、データセットをあるロケーションから別のロケーションに移動することはできませんが、手動でデータセットを移動（再作成）することはできます。

データセットのコピー

データセットをコピーする手順（リージョン間でのコピーを含む）については、データセットのコピーをご覧ください。

データセットの移動

データセットをあるロケーションから別のロケーションに手動で移動するには、次の手順に従います。

  1. BigQuery テーブルから、データセットと同じロケーションにあるリージョンまたはマルチリージョンの Cloud Storage バケットにデータをエクスポートします。たとえば、データセットが EU のマルチリージョン ロケーションにある場合は、EU のリージョン バケットまたはマルチリージョン バケットにデータをエクスポートします。

    BigQuery からのデータのエクスポートに対しては課金されませんが、エクスポートしたデータを Cloud Storage へ保存することについては課金の対象になります。BigQuery からのエクスポートには、エクスポート ジョブの制限が適用されます。

  2. Cloud Storage バケットから新しいロケーションのリージョン バケットまたはマルチリージョン バケットに、データをコピーするか移動します。たとえば、米国のマルチリージョン ロケーションから東京のリージョン ロケーションにデータを移動すると、データは東京のリージョン バケットに転送されます。Cloud Storage オブジェクトの転送について詳しくは、Cloud Storage ドキュメントのオブジェクトの名前変更、コピー、移動をご覧ください。

    リージョン間でデータを転送すると、Cloud Storage でネットワークの下り（外向きのトラフィック）料金が発生することに注意してください。

  3. 新しいロケーションの Cloud Storage バケットにデータを転送した後、新しい BigQuery データセットを（新しいロケーションに）作成します。次に、Cloud Storage バケットから BigQuery にデータを読み込みます。

    BigQuery へのデータの読み込みについて請求は発生しませんが、Cloud Storage にデータを保存することについては請求が発生し、データまたはバケットを削除するまで請求が行われます。読み込まれたデータを BigQuery に保存することについても、請求の対象になります。BigQuery へのデータの読み込みには、読み込みジョブの制限が適用されます。

また、Cloud Composer を使用して、大規模なデータセットをプログラムで移動し、コピーすることもできます。

Cloud Storage を使用した大量のデータセットの保存や移動に関する詳細は、Cloud Storage とビッグデータの使用をご覧ください。

エクスポート形式と圧縮形式

BigQuery は、エクスポートされるデータに対して次のデータ形式と圧縮形式をサポートしています。

データ形式 サポートされている圧縮タイプ 詳細
CSV GZIP

エクスポートされるデータの CSV 区切り文字を制御するには、--field_delimiter bq コマンドライン ツールフラグまたは configuration.extract.fieldDelimiter を使用します。抽出ジョブ プロパティを使用します。

ネストされたデータや繰り返しデータは、サポートされていません。
JSON GZIP ネストされたデータや繰り返しデータはサポートされます。
Avro DEFLATE、SNAPPY

Avro のエクスポートでは、GZIP はサポートされていません。

ネストされたデータや繰り返しデータはサポートされます。

BigQuery に保存されているデータのエクスポート

テーブルデータは次の方法でエクスポートできます。

  • Cloud Console または従来の BigQuery ウェブ UI を使用する
  • bq コマンドライン ツールで bq extract コマンドを使用する
  • API またはクライアント ライブラリを介した extract ジョブを送信する

テーブルデータのエクスポート

BigQuery テーブルからデータをエクスポートするには:

コンソール

  1. Cloud Console で [BigQuery] ページを開きます。

    BigQuery ページに移動

  2. ナビゲーション パネルの [リソース] セクションでプロジェクトを展開し、目的のデータセットをクリックして展開します。エクスポートするデータを含むテーブルに移動しクリックします。

  3. ウィンドウの右側で [エクスポート] を選択し、[Google Cloud Storage へのエクスポート] を選択します。

    データのエクスポート

  4. [Google Cloud Storage へのテーブルのエクスポート] ダイアログで、次の操作を行います。

    • [Google Cloud Storage のロケーション] で、データをエクスポートするバケット、フォルダ、またはファイルを参照します。
    • [エクスポート形式] で、エクスポートするデータの形式を [CSV]、[JSON]（改行区切り）、[Avro] から選択します。
    • [Compression] では、デフォルト値の None を受け入れるか、GZIP を選択します。Avro 形式を GZIP 圧縮とともに使用することはできません。Avro データを圧縮するには、bq コマンドライン ツールまたは API を使用して、Avro データでサポートされている圧縮タイプのいずれか（DEFLATE または SNAPPY）を指定します。
    • [エクスポート] をクリックしてテーブルをエクスポートします。

ジョブの進行状況を確認するには、ナビゲーションの上部にある [エクスポート] ジョブの [ジョブ履歴] を確認します。

従来の UI

  1. BigQuery ウェブ UI に移動します。
    BigQuery ウェブ UI に移動

  2. ナビゲーションで、データセットをクリックして展開します。

  3. エクスポートするデータを含むテーブルの横にある下矢印アイコン 下矢印アイコンの画像 をクリックします。

  4. [Export table] を選択して [Export to Google Cloud Storage] ダイアログを表示します。

  5. [Export to Google Cloud Storage] ダイアログで、次の操作を行います。

    • [Export Format] で、エクスポートするデータの形式を [CSV]、[JSON]（改行区切り）、[Avro] から選択します。
    • [Compression] では、デフォルト値の None を受け入れるか、GZIP を選択します。Avro 形式を GZIP 圧縮とともに使用することはできません。Avro データを圧縮するには、bq コマンドライン ツールまたは API を使用して、Avro データでサポートされている圧縮タイプのいずれか（DEFLATE または SNAPPY）を指定します。
    • [Google Cloud Storage URI] テキスト ボックスに、gs://bucket_name/filename.ext の形式で有効な URI を入力します。bucket_name は Cloud Storage バケット名、filename.ext は宛先ファイルの名前と拡張子です。BigQuery データセットと Cloud Storage バケットは同じロケーションに存在する必要があります。
    • [OK] をクリックしてテーブルをエクスポートします。

ジョブが実行されている間、（extracting）というメッセージがナビゲーション領域のテーブル名の横に表示されます。ジョブの進行状況をチェックするには、ナビゲーション領域の上の方にある [Job History] で [Extract] ジョブを確認します。

bq

bq extract コマンドを使用し、--destination_format フラグを指定します。

（省略可）--location フラグを指定して、その値をロケーションに設定します。

次のフラグを使用することもできます。

  • --compression: エクスポートされるファイルに使用する圧縮タイプ。
  • --field_delimiter: CSV エクスポートの出力ファイル内での列間の境界を示す文字。タブ区切り文字には \t と tab の両方を使用できます。
  • --print_header: 指定すると、CSV などのヘッダーを持つ形式でヘッダー行が出力されます。
bq --location=location extract \
--destination_format format \
--compression compression_type \
--field_delimiter delimiter \
--print_header=boolean \
project_id:dataset.table \
gs://bucket/filename.ext

ここで

  • location は、ロケーションの名前です。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
  • format は、エクスポートされるデータの形式です（CSV、NEWLINE_DELIMITED_JSON、または AVRO）。
  • compression_type は、データ形式に対してサポートされる圧縮タイプです。CSV と NEWLINE_DELIMITED_JSON は、GZIP をサポートします。AVRO は、DEFLATE と SNAPPY をサポートします。
  • delimiter は、CSV エクスポートの列間の境界を示す文字です。タブの名前として受け入れられるのは \t と tab です。
  • boolean は true または false です。true に設定すると、データ形式がヘッダーをサポートする場合に、エクスポートされるデータにヘッダー行が出力されます。デフォルト値は true です。
  • project_id はプロジェクト ID です。
  • dataset はソース データセットの名前です。
  • table は、エクスポートするテーブルです。
  • bucket は、データのエクスポート先の Cloud Storage バケットの名前です。BigQuery データセットと Cloud Storage バケットは同じロケーションに存在する必要があります。
  • filename.ext は、エクスポートされるデータファイルの名前と拡張子です。ワイルドカードを使用して複数のファイルにエクスポートできます。

例:

たとえば、次のコマンドは、mydataset.mytable を myfile.csv という名前の gzip 圧縮ファイルにエクスポートします。myfile.csv は、example-bucket という名前の Cloud Storage バケットに保存されます。

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

デフォルトの出力形式は CSV です。JSON または Avro 形式でエクスポートするには、destination_format フラグを NEWLINE_DELIMITED_JSON または AVRO に設定します。次に例を示します。

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

次のコマンドは、mydataset.mytable を、Snappy を使用して圧縮された Avro ファイルにエクスポートします。ファイル名は、myfile.avro になります。myfile.avro は、example-bucket という名前の Cloud Storage バケットにエクスポートされます。

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

API

データをエクスポートするには、extract ジョブを作成し、ジョブ構成に入力します。

（省略可）ジョブリソースの jobReference セクションにある location プロパティでロケーションを指定します。

  1. 抽出ジョブを作成し、抽出元の BigQuery データと抽出先の Cloud Storage を指定します。

  2. プロジェクト ID、データセット ID、テーブル ID を含む sourceTable 構成オブジェクトを使用して、ソーステーブルを指定します。

  3. destination URI(s) プロパティは、gs://bucket/filename.ext の形式で完全修飾する必要があります。各 URI に '*' ワイルドカード文字を 1 つ含めることができますが、このワイルドカードはバケット名より後にある必要があります。

  4. configuration.extract.destinationFormat プロパティを設定して、データ形式を指定します。たとえば、JSON ファイルとしてエクスポートするには、このプロパティの値を NEWLINE_DELIMITED_JSON に設定します。

  5. ジョブ ステータスを確認するには、最初のリクエストで返されるジョブの ID を指定して jobs.get(job_id) を呼び出します。

    • status.state = DONE である場合、ジョブは正常に完了しています。
    • status.errorResult プロパティが存在する場合は、リクエストが失敗したことを意味し、該当するオブジェクトにエラーを説明する情報が格納されます。
    • status.errorResult が存在しない場合、ジョブは正常に完了しましたが、致命的でないエラーが発生した可能性があります。致命的でないエラーは、返されたジョブ オブジェクトの status.errors プロパティに格納されています。

API に関する注:

  • おすすめの方法として、jobs.insert を呼び出して読み込みジョブを作成する際に、一意の ID を生成して、その ID を jobReference.jobId として渡します。この手法を使用すると、ネットワーク障害時にクライアントは既知のジョブ ID を使ってポーリングまたは再試行できるので、頑健性が向上します。

  • 特定のジョブ ID で jobs.insert を呼び出す操作は「べき等」です。つまり、同じジョブ ID で何回でも再試行できますが、成功するオペレーションはそのうちの 1 回だけです。

C#

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用にある PHP 向けの手順に従って設定を行ってください。詳細については、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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery 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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用で説明している Ruby 向けの手順に沿って設定を行ってください。詳細については、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 エクスポートの詳細

BigQuery は次の方法で Avro 形式のデータを表現します。

  • エクスポートされたファイルは Avro コンテナ ファイルになります。
  • 各 BigQuery 行は 1 つの Avro レコードとして表されます。ネストされたデータは、ネストされたレコード オブジェクトによって表されます。
  • REQUIRED フィールドは、対応する Avro 型として表されます。たとえば、BigQuery の INTEGER 型は Avro の LONG 型に対応しています。
  • NULLABLE フィールドは、対応する型と "null" の Avro ユニオンとして表されます。
  • REPEATED フィールドは Avro 配列として表されます。
  • TIMESTAMP データ型は Avro の timestamp-micros 論理型として表されます。
  • DATE データ型はデフォルトで Avro の INT 型として表されますが、--use_avro_logical_types フラグが指定されている場合は Avro の date 論理型として表されます。
  • TIME データ型はデフォルトで Avro の LONG 型として表されますが、--use_avro_logical_types フラグが指定されている場合は Avro の time-micros 論理型として表されます。
  • DATETIME データ型は Avro の STRING 型として表されます。エンコードは Internet Engineering Task Force RFC 3339 仕様に従います。

Avro 形式を GZIP 圧縮とともに使用することはできません。Avro データを圧縮するには、bq コマンドライン ツールまたは API を使用して、Avro データでサポートされている圧縮タイプの 1 つ（DEFLATE または SNAPPY）を指定します。

1 つまたは複数のファイルへのデータのエクスポート

destinationUris プロパティには、BigQuery によるファイルの 1 つ以上のエクスポート先とファイル名を指定します。

BigQuery は URI ごとに 1 つのワイルドカード演算子（*）をサポートします。ワイルドカードは、バケット名の中を除いて URI のどこでも使用できます。ワイルドカード演算子を使用すると、指定したパターンに基づいて複数の分割ファイルが作成されます。ワイルドカード演算子は、左側に 0 が埋められた 12 桁の数値（0 から始まるシーケンス番号）に置き換えられます。たとえば、ファイル名の最後にワイルドカードがある URI の場合、最初のファイルに 000000000000 が追加され、2 番目のファイルに 000000000001 が追加されます。

destinationUris プロパティで使用できるオプションを次の表に示します。

destinationUris のオプション
単一の URI

1 GB 以下のテーブルデータをエクスポートする場合は、単一の URI を使用します。ほとんどの場合、エクスポートされるデータは最大値の 1 GB に満たないため、このオプションは最も一般的なユースケースとなります。

プロパティの定義:

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

作成されるファイル:


gs://my-bucket/file-name.json
単一のワイルドカード URI

エクスポートされるデータが最大値の 1 GB を超えそうな場合は、単一のワイルドカード URI を使用します。データは、指定したパターンに基づいて複数のファイルに分割されます。エクスポートされたファイルのサイズは一定ではありません。

ファイル名以外の URI コンポーネントでワイルドカードを使用する場合、データをエクスポートする前に、そのパス コンポーネントが存在していないことを確認してください。

プロパティの定義:

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

作成されるファイル:


gs://my-bucket/file-name-000000000000.json
gs://my-bucket/file-name-000000000001.json
gs://my-bucket/file-name-000000000002.json
...
複数のワイルドカード URI

複数のワイルドカード URI は、エクスポート出力をパーティショニングする場合に使用します。Dataproc などのサービスを使用して並列処理ジョブを実行している場合は、このオプションを使用します。ジョブの処理に使用できるワーカーの数を判断し、ワーカーごとに 1 つの URI を作成します。BigQuery は各 URI の場所をパーティションとして扱い、並行処理を使用してそれぞれの場所でデータを複数のファイルにシャーディングします。各 URI に単一のワイルドカード演算子が含まれていて、各 URI が重複しておらず、URI の数が割り当てのポリシーの上限を超えていない限り、ファイル名でどのようなパターンでも使用できます。

複数のワイルドカード URI を渡すと、BigQuery は各パーティションの最後に特別なファイルを作成し、セット内に最終ファイルであることを示します。このファイル名は、作成された分割ファイルの数を示しています。

たとえば、ワイルドカード URI が gs://my-bucket/file- name-<worker number>-*.json で、80 個の分割ファイルが作成された場合、ゼロレコード ファイルの名前は gs://my-bucket/file-name-<worker number>-000000000080.json になります。このファイル名から、000000000000～000000000079 という名前の 80 個の分割ファイルを BigQuery が作成したことがわかります。

列ヘッダーのある CSV 形式など、エクスポートしたデータ形式によっては、ゼロレコード ファイルのサイズが 0 バイトより大きくなる場合があります。

文字列パターン:

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

プロパティの定義:


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

作成されるファイル:

この例は各パーティションで 80 個の分割ファイルが作成された場合を示します。


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

圧縮されたテーブルの抽出

Go

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、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

このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery 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.

割り当てポリシー

エクスポート ジョブの割り当てについては、「割り当てと上限」のページのエクスポート ジョブをご覧ください。

料金

現時点では、BigQuery からのデータのエクスポートについて請求は発生しませんが、エクスポートは BigQuery の割り当てと上限の対象となります。BigQuery の料金設定の詳細については、料金設定のページをご覧ください。

データのエクスポート後は、Cloud Storage にデータを保存することで料金が発生します。Cloud Storage の料金設定の詳細については、クラウドの料金設定のページをご覧ください。

次のステップ