このページでは、BigQuery テーブルからデータをエクスポートまたは抽出する方法について説明します。
BigQuery にデータを読み込んだ後、さまざまな形式でデータをエクスポートできます。BigQuery は最大 1 GB のデータを 1 つのファイルにエクスポートできます。1 GB を超えるデータをエクスポートする場合は、データを複数のファイルにエクスポートする必要があります。データを複数のファイルにエクスポートすると、さまざまなサイズのファイルになります。
Dataflow などのサービスを使用すると、データを手動でエクスポートする代わりに、BigQuery から直接読み取ることができます。Dataflow を使用した BigQuery の読み取りと書き込みの詳細については、Apache Beam ドキュメントの BigQuery I/O をご覧ください。
また、EXPORT DATA
ステートメントを使用してクエリの結果をエクスポートすることもできます。
必要な権限
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 を使用してデータをエクスポートする場合、
GZIP
以外の圧縮タイプを選択することはできません。 - 保持ポリシーを使用して構成された Cloud Storage バケットにデータをエクスポートすると、BigQuery からバケットへのファイルの書き込みが失敗する場合があります。エクスポート ジョブの期間の保持ポリシーを緩和することを検討してください。
ロケーションに関する留意事項
データのロケーションを選択するときは、次の点を考慮してください。
- データをエクスポートするには Cloud Storage バケットを同じリージョンに配置する
- データをエクスポートする場合、リージョンまたはマルチリージョンの Cloud Storage バケットを BigQuery データセットと同じロケーションに配置する必要があります。たとえば、BigQuery データセットが EU のマルチリージョン ロケーションにある場合、エクスポート対象のデータが含まれている Cloud Storage バケットは EU のリージョンまたはマルチリージョン ロケーションに存在する必要があります。
- データセットがリージョン ロケーションにある場合、Cloud Storage バケットは同じロケーションのリージョン バケットに存在する必要があります。たとえば、データセットが東京リージョンにある場合、Cloud Storage バケットは東京のリージョン バケットである必要があります。
- 例外: データセットが米国のマルチリージョン ロケーションにある場合、任意のリージョンまたはマルチリージョン ロケーションにある Cloud Storage バケットにデータをエクスポートできます。
- データ管理計画を作成する
- BigQuery データセットや Cloud Storage バケットなどのリージョン ストレージ リソースを選択する場合は、データの地理的管理を行うための計画を作成します。
Cloud Storage のロケーションの詳細については、Cloud Storage のドキュメントのバケットのロケーションをご覧ください。
ロケーション間での BigQuery データの移動
データセットの作成後にそのロケーションを変更することはできませんが、データセットのコピーを作成することはできます。また、データセットをあるロケーションから別のロケーションに移動することはできませんが、手動でデータセットを移動(再作成)することはできます。
データセットのコピー
データセットをコピーする手順(リージョン間でのコピーを含む)については、データセットのコピーをご覧ください。
データセットの移動
データセットをあるロケーションから別のロケーションに手動で移動するには、次の手順に従います。
-
BigQuery テーブルから、データセットと同じロケーションにあるリージョンまたはマルチリージョンの Cloud Storage バケットにデータをエクスポートします。たとえば、データセットが EU のマルチリージョン ロケーションにある場合は、EU のリージョン バケットまたはマルチリージョン バケットにデータをエクスポートします。
BigQuery からのデータのエクスポートに対しては課金されませんが、エクスポートしたデータを Cloud Storage に保存する場合は課金の対象になります。BigQuery からのエクスポートには、エクスポート ジョブの上限が適用されます。
-
Cloud Storage バケットから新しいロケーションのリージョン バケットまたはマルチリージョン バケットに、データをコピーするか移動します。たとえば、米国のマルチリージョン ロケーションから東京のリージョン ロケーションにデータを移動すると、データは東京のリージョン バケットに転送されます。Cloud Storage オブジェクトの転送について詳しくは、Cloud Storage ドキュメントのオブジェクトのコピー、名前変更、移動をご覧ください。
リージョン間でデータを転送すると、Cloud Storage でネットワークの下り(外向き)料金が発生することに注意してください。
-
新しいロケーションの Cloud Storage バケットにデータを転送した後、新しい BigQuery データセットを(新しいロケーションに)作成します。次に、Cloud Storage バケットから BigQuery にデータを読み込みます。
BigQuery へのデータの読み込みに対しては課金されませんが、Cloud Storage にデータを保存した場合は課金の対象となり、データまたはバケットを削除するまで料金が請求されます。読み込まれたデータを BigQuery に保存することについても、請求の対象になります。BigQuery へのデータの読み込みには、読み込みジョブの上限が適用されます。
また、Cloud Composer を使用して、大規模なデータセットをプログラムで移動し、コピーすることもできます。
Cloud Storage を使用した大量のデータセットの保存や移動に関する詳細は、Cloud Storage とビッグデータの使用をご覧ください。
エクスポート形式と圧縮形式
BigQuery は、エクスポートされるデータに対して次のデータ形式と圧縮形式をサポートしています。
データ形式 | サポートされている圧縮タイプ | 詳細 |
---|---|---|
CSV | GZIP | エクスポートされるデータの CSV 区切り文字を制御するには、 ネストされたデータや繰り返しデータは、サポートされていません。 |
JSON | GZIP | ネストされたデータや繰り返しデータはサポートされます。 |
Avro | DEFLATE、SNAPPY | Avro のエクスポートでは、GZIP はサポートされていません。 ネストされたデータや繰り返しデータはサポートされます。 |
BigQuery に保存されているデータのエクスポート
テーブルデータは次の方法でエクスポートできます。
- Cloud Console を使用する
bq
コマンドライン ツールでbq extract
コマンドを使用する- API またはクライアント ライブラリを介した
extract
ジョブを送信する
テーブルデータのエクスポート
BigQuery テーブルからデータをエクスポートするには:
Console
Cloud Console で [BigQuery] ページを開きます。
[エクスプローラ] パネルで、プロジェクトとデータセットを展開し、テーブルを選択します。
詳細パネルで、[エクスポート] をクリックして [GCS にエクスポート] を選択します。
[Google Cloud Storage へのテーブルのエクスポート] ダイアログで、次の操作を行います。
- [Google Cloud Storage のロケーション] で、データをエクスポートするバケット、フォルダ、またはファイルを参照します。
- [エクスポート形式] で、エクスポートするデータの形式を [CSV]、[JSON](改行区切り)、[Avro] から選択します。
- [Compression] では、デフォルト値の
None
を受け入れるか、GZIP
を選択します。Avro 形式を GZIP 圧縮とともに使用することはできません。Avro データを圧縮するには、bq
コマンドライン ツールまたは API を使用して、Avro データでサポートされている圧縮タイプのいずれか(DEFLATE
またはSNAPPY
)を指定します。 - [エクスポート] をクリックしてテーブルをエクスポートします。
ジョブの進行状況を確認するには、ナビゲーションの上部にある [エクスポート] ジョブの [ジョブ履歴] を確認します。
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
プロパティでロケーションを指定します。
抽出ジョブを作成し、抽出元の 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 のリファレンス ドキュメントをご覧ください。
Go
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
Java
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Node.js
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
PHP
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用にある PHP 向けの手順に従って設定を行ってください。詳細については、BigQuery PHP API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
Ruby
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用で説明している Ruby 向けの手順に沿って設定を行ってください。詳細については、BigQuery Ruby API のリファレンス ドキュメントをご覧ください。
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 データでサポートされている圧縮タイプのいずれか(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 |
単一のワイルドカード URI |
エクスポートされるデータが最大値の 1 GB を超えそうな場合は、単一のワイルドカード URI を使用します。データは、指定したパターンに基づいて複数のファイルに分割されます。エクスポートされたファイルのサイズは一定ではありません。 ファイル名以外の URI コンポーネントでワイルドカードを使用する場合、データをエクスポートする前に、そのパス コンポーネントが存在していないことを確認してください。 プロパティの定義:
作成されるファイル: 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 が 列ヘッダーのある CSV 形式など、エクスポートしたデータ形式によっては、ゼロレコード ファイルのサイズが 0 バイトより大きくなる場合があります。 文字列パターン:
プロパティの定義: ['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 のリファレンス ドキュメントをご覧ください。
Java
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Node.js
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
割り当てポリシー
エクスポート ジョブの割り当てについては、「割り当てと制限」のページのエクスポート ジョブをご覧ください。
料金
現時点では、BigQuery からのデータのエクスポートについて請求は発生しませんが、エクスポートは BigQuery の割り当てと上限の対象となります。BigQuery の料金設定の詳細については、料金設定のページをご覧ください。
データのエクスポート後は、Cloud Storage にデータを保存することで料金が発生します。Cloud Storage の料金設定の詳細については、クラウドの料金設定のページをご覧ください。
次のステップ
- Cloud Console の詳細については、Cloud Console の使用をご覧ください。
bq
コマンドライン ツールの詳細については、bq
コマンドライン ツールの使用をご覧ください。- BigQuery API クライアント ライブラリを使ってアプリケーションを作成する方法を学習するには、クライアント ライブラリ クイックスタート ガイドをご覧ください。