テーブルデータを Cloud Storage にエクスポートする

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

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

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

また、EXPORT DATA ステートメントを使用して、クエリの結果をエクスポートすることもできます。EXPORT DATA OPTIONS を使用してビューを {storage_name} にエクスポートできます。

エクスポートの制限事項

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

テーブルデータをローカルファイル、Google スプレッドシート、Google ドライブにエクスポートすることはできません。可能なエクスポート先は Cloud Storage だけです。クエリ結果の保存については、クエリ結果のダウンロードと保存をご覧ください。
1 つのファイルに最大 1 GB のテーブルデータをエクスポートできます。1 GB を超えるデータをエクスポートする場合は、ワイルドカードを使用してデータを複数のファイルにエクスポートします。データを複数のファイルにエクスポートすると、さまざまなサイズのファイルになります。エクスポートするファイルサイズを制御するには、データをパーティショニングし、各パーティションをエクスポートします。
EXPORT DATA ステートメントの使用時に生成されるファイルのサイズは保証されません。
エクスポートジョブによって生成されるファイルの数はさまざまです。
ネストや繰り返しのあるデータを CSV 形式でエクスポートすることはできません。ネストされたデータと繰り返しデータは、Avro、JSON、Parquet のエクスポートでサポートされています。
データを JSON 形式でエクスポートするときは、INT64（整数）データ型が JSON 文字列としてエンコードされます。これは、そのデータが他のシステムで読み込まれるときに 64 ビットの精度を保持するためです。
単一のエクスポートジョブで複数のテーブルからデータをエクスポートすることはできません。
Google Cloud コンソールを使用してデータをエクスポートする場合、GZIP 以外の圧縮タイプを選択することはできません。
保持ポリシーを使用して構成された Cloud Storage バケットにデータをエクスポートすると、BigQuery からバケットへのファイルの書き込みが失敗する場合があります。エクスポートジョブの期間よりも長く保持期間を構成します。
JSON 形式でテーブルをエクスポートする場合、記号 <、>、& は Unicode 表記の \uNNNN に変換されます。ここで、N は 16 進数です。たとえば、profit&loss は profit\u0026loss になります。この Unicode 変換は、セキュリティの脆弱性を回避するために行われます。
EXPORT DATA ステートメントを使用して query_statement で ORDER BY 句を指定しない限り、エクスポートされるテーブルデータの順序は保証されません。
BigQuery では、最初のダブルスラッシュの後に複数の連続スラッシュが含まれる Cloud Storage リソースパスはサポートされていません。Cloud Storage オブジェクトの名前には複数の連続スラッシュ（"/"）文字を含めることができます。一方、BigQuery では、複数の連続スラッシュは単一のスラッシュに変換されます。たとえば、リソースパス gs://bucket/my//object//name は Cloud Storage では有効ですが、BigQuery では機能しません。

始める前に

このドキュメントの各タスクを実行するために必要な権限をユーザーに与える Identity and Access Management（IAM）のロールを付与します。

必要な権限

このドキュメントのタスクを実行するには、次の権限が必要です。

BigQuery テーブルからデータをエクスポートするための権限

BigQuery テーブルからデータをエクスポートするには、bigquery.tables.export IAM 権限が必要です。

次に示す各 IAM 事前定義ロールには bigquery.tables.export 権限が含まれています。

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

エクスポートジョブの実行に必要な権限

エクスポートジョブを実行するには、bigquery.jobs.create IAM 権限が必要です。

次の IAM 事前定義ロールには、エクスポートジョブの実行に必要な権限が含まれています。

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

Cloud Storage バケットにデータを書き込む権限

既存の Cloud Storage バケットにデータを書き込むには、次の IAM 権限が必要です。

storage.objects.create
storage.objects.delete

次の IAM 事前定義ロールには、既存の Cloud Storage バケットにデータを書き込むために必要な権限が含まれています。

roles/storage.objectAdmin
roles/storage.admin

BigQuery での IAM のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。

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

データのエクスポート用に Cloud Storage バケットを同じロケーションに配置します。

BigQuery データセットが EU マルチリージョンにある場合、エクスポート対象のデータが含まれている Cloud Storage バケットは、同じマルチリージョンか、マルチリージョンに含まれているロケーションに存在する必要があります。たとえば、BigQuery データセットが EU マルチリージョンにある場合、Cloud Storage バケットは EU 内の europe-west1 ベルギーリージョンに配置できます。
データセットが US マルチリージョンにある場合、任意のロケーションにある Cloud Storage バケットにデータをエクスポートできます。
データセットがリージョンにある場合、Cloud Storage バケットは同じリージョンに存在する必要があります。たとえば、データセットが asia-northeast1 の東京リージョンにある場合、Cloud Storage バケットを ASIA マルチリージョンに配置することはできません。

データマネジメント計画を作成する

BigQuery データセットや Cloud Storage バケットなどのリージョンストレージリソースを選択する場合は、データの地理的管理を行うための計画を作成します。

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

ロケーション間で BigQuery データを移動する

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

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

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

データ形式	サポートされている圧縮タイプ	詳細
CSV	GZIP	エクスポートされるデータの CSV 区切り文字を制御するには、`--field_delimiter` コマンドラインツールフラグまたは `configuration.extract.fieldDelimiter` 抽出ジョブプロパティを使用します。ネストされたデータや繰り返しデータは、サポートされていません。
JSON	GZIP	ネストされたデータと繰り返しデータはサポートされます。
Avro	DEFLATE、SNAPPY	Avro のエクスポートでは、GZIP はサポートされていません。ネストされたデータと繰り返しデータはサポートされます。Avro のエクスポートの詳細をご覧ください。
Parquet	SNAPPY、GZIP、ZSTD	ネストされたデータと繰り返しデータはサポートされます。Parquet エクスポートの詳細をご覧ください。

データのエクスポート

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

Google Cloud コンソールを使用する
bq コマンドラインツールの bq extract コマンドを使用する
API またはクライアントライブラリを介して extract ジョブを送信する

テーブルデータをエクスポートする

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

コンソール

Google Cloud コンソールで [BigQuery] ページを開きます。

[BigQuery] ページに移動
[エクスプローラ] パネルで、プロジェクトとデータセットを開いて、テーブルを選択します。
詳細パネルで、[エクスポート] をクリックして [Cloud Storage にエクスポート] を選択します。
[Google Cloud Storage へのテーブルのエクスポート] ダイアログで、次の操作を行います。
- [Google Cloud Storage のロケーション] で、データをエクスポートするバケット、フォルダ、またはファイルを参照します。
- [エクスポート形式] で、エクスポートするデータの形式を CSV、JSON（改行区切り）、Avro、または Parquet から選択します。
- [圧縮] で、圧縮形式を選択するか、None を選択して圧縮なしにします。
- [エクスポート] をクリックしてテーブルをエクスポートします。

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

ビューを Cloud Storage にエクスポートするには、EXPORT DATA OPTIONS ステートメントを使用します。

SQL

EXPORT DATA ステートメントを使用します。次の例では、mydataset.table1 という名前のテーブルから選択したフィールドをエクスポートします。

Google Cloud コンソールで [BigQuery] ページに移動します。

[BigQuery] に移動

クエリエディタで次のステートメントを入力します。

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

[実行] をクリックします。

クエリの実行方法については、インタラクティブクエリを実行するをご覧ください。

bq

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

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

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

--compression: エクスポートされるファイルに使用する圧縮タイプ。
--field_delimiter: CSV エクスポートの出力ファイル内での列間の境界を示す文字。タブ区切り文字には \t と tab の両方を使用できます。
--print_header: 指定すると、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

ここで

location はロケーションの名前です。--location フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値を asia-northeast1 に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
format は、エクスポートされるデータの形式です（CSV、NEWLINE_DELIMITED_JSON、AVRO、または PARQUET）。
compression_type は、データ形式に対してサポートされる圧縮タイプです。エクスポート形式と圧縮形式をご覧ください。
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

次のコマンドは、mydataset.my_partitioned_table の単一パーティションを Cloud Storage の CSV ファイルにエクスポートします。

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

API

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

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

抽出ジョブを作成し、抽出元の BigQuery データと抽出先の Cloud Storage を指定します。
プロジェクト ID、データセット ID、テーブル ID を含む sourceTable 構成オブジェクトを使用して、ソーステーブルを指定します。
destination URI(s) プロパティは、gs://bucket/filename.ext の形式で完全修飾する必要があります。各 URI に '*' ワイルドカード文字を 1 つ含めることができますが、このワイルドカードはバケット名より後にある必要があります。
configuration.extract.destinationFormat プロパティを設定して、データ形式を指定します。たとえば、JSON ファイルとしてエクスポートするには、このプロパティの値を NEWLINE_DELIMITED_JSON に設定します。
ジョブステータスを確認するには、最初のリクエストで返されるジョブの 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 のリファレンスドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証を設定するをご覧ください。

GitHub で表示フィードバック


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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

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 のリファレンスドキュメントをご覧ください。

GitHub で表示フィードバック

// Import the Google Cloud client libraries

テーブルデータを Cloud Storage にエクスポートする

エクスポートの制限事項

始める前に

必要な権限

BigQuery テーブルからデータをエクスポートするための権限

エクスポート ジョブの実行に必要な権限

Cloud Storage バケットにデータを書き込む権限

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

ロケーション間で BigQuery データを移動する

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

データのエクスポート

テーブルデータをエクスポートする

コンソール

SQL

bq

API

C#

Go

Java

Node.js

エクスポートジョブの実行に必要な権限