このページでは、BigQuery のテーブルからデータをエクスポートする方法について説明します。
BigQuery にデータを読み込んだ後、さまざまな形式でデータをエクスポートできます。BigQuery は最大 1 GB のデータを 1 つのファイルにエクスポートできます。1 GB を超えるデータをエクスポートする場合は、データを複数のファイルにエクスポートする必要があります。データを複数のファイルにエクスポートすると、ファイルのサイズは変動します。
Google Cloud Dataflow などのサービスを使用すると、データを手動でエクスポートする代わりに BigQuery からデータを読み取ることができます。Cloud Dataflow を使用して BigQuery からデータを読み取る方法、または BigQuery にデータを書き込む方法については、Cloud Dataflow ドキュメントの BigQuery I/O をご覧ください。
必要な権限
- エクスポートするデータが保存されているデータセットへの
READER
アクセス権があることを確認します。または、事前定義されているプロジェクト レベルの BigQuery IAM 役割のうち、bigquery.tables.export
権限が含まれているものを使用することもできます。たとえば、bigquery.dataViewer
、bigquery.dataOwner
、bigquery.dataEditor
、bigquery.admin
です。プロジェクト レベルで IAM 役割を割り当てると、そのユーザーまたはグループにはそのプロジェクト内のすべてのテーブルに対するbigquery.tables.export
権限が与えられます。 - Google Cloud Storage バケットに対する
WRITER
権限が付与されていることを確認します。または、事前定義されている IAM 役割のうち、バケットへのオブジェクト書き込みの権限が付与されるものが割り当てられていることを確認します。BigQuery からのエクスポートの出力先は、Cloud Storage バケットのみです。Cloud Storage の IAM 役割については、Cloud Storage の IAM 役割をご覧ください。
エクスポートの制限事項
BigQuery からデータをエクスポートするときは、次の点に注意してください。
- データをローカル ファイルまたは Google ドライブにエクスポートすることはできませんが、クエリ結果をローカル ファイルに保存することはできます。使用できるエクスポート先は Google Cloud Storage だけです。
- 1 つのファイルに最大 1 GB のテーブルデータをエクスポートできます。1 GB を超えるデータをエクスポートする場合は、ワイルドカードを使用してデータを複数のファイルにエクスポートします。データを複数のファイルにエクスポートすると、ファイルのサイズは変動します。
- ネストや繰り返しのあるデータを CSV 形式でエクスポートすることはできません。ネストや繰り返しのあるデータは、Avro および JSON のエクスポートでサポートされています。
- データを JSON 形式でエクスポートするときは、INT64(整数)データ型が JSON 文字列としてエンコードされます。これは、そのデータが他のシステムで読み込まれるときに 64 ビットの精度を保持するためです。
- 単一のエクスポート ジョブで複数のテーブルからデータをエクスポートすることはできません。
- 分割テーブルからデータをエクスポートする場合は、個々のパーティションをエクスポートすることはできません。
- 従来の BigQuery ウェブ UI を使用してデータをエクスポートする場合、
GZIP
以外の圧縮タイプは選択できません。
ロケーションに関する留意事項
データのロケーションを選択するときは、次の点を考慮してください。- BigQuery データセットと外部データソースを同じロケーションに配置する
- Cloud Storage などの外部データソースのデータをクエリする場合、クエリするデータは BigQuery データと同じロケーションに存在する必要があります。たとえば、BigQuery データセットが EU のマルチリージョン ロケーションにある場合、クエリ対象のデータが含まれている Cloud Storage バケットは、EU のマルチリージョン バケットに存在する必要があります。データセットが米国のマルチリージョン ロケーションにある場合、Cloud Storage バケットは米国のマルチリージョン バケットに存在する必要があります。
- データセットがリージョン ロケーションにある場合、クエリ対象のデータが含まれている Cloud Storage バケットは、同じロケーションのリージョン バケットに存在する必要があります。たとえば、データセットが東京リージョンにある場合、Cloud Storage バケットは東京のリージョン バケットである必要があります。
- 外部データセットが Cloud Bigtable にある場合、データセットは米国または EU のマルチリージョン ロケーションに存在する必要があります。Cloud Bigtable データは、サポートされている Cloud Bigtable のロケーションのいずれかに存在する必要があります。
- ロケーションに関する考慮事項は、Google ドライブの外部データソースには適用されません。
- データを読み込む場合は、Cloud Storage バケットを同じリージョンに配置する
- BigQuery データセットがマルチリージョン ロケーションにある場合、読み込み対象のデータが含まれている Cloud Storage バケットは、同じロケーションのリージョンまたはマルチリージョン バケットに存在する必要があります。たとえば、BigQuery データセットが EU にある場合、Cloud Storage バケットは EU のリージョンまたはマルチリージョン バケットに存在する必要があります。
- データセットがリージョン ロケーションにある場合、Cloud Storage バケットは同じロケーションのリージョン バケットに存在する必要があります。たとえば、データセットが東京リージョンにある場合、Cloud Storage バケットは東京のリージョン バケットである必要があります。
- 例外: データセットが米国のマルチリージョン ロケーションにある場合、任意のリージョンまたはマルチリージョン ロケーションにある Cloud Storage バケットからデータを読み込むことができます。
- データをエクスポートする場合は、Cloud Storage バケットを同じリージョンに配置する
- データをエクスポートする場合、リージョンまたはマルチリージョンの Cloud Storage バケットを BigQuery データセットと同じロケーションに配置する必要があります。たとえば、BigQuery データセットが EU のマルチリージョン ロケーションにある場合、エクスポート対象のデータが含まれている Cloud Storage バケットは EU のマルチリージョン バケットに存在する必要があります。
- データセットがリージョン ロケーションにある場合、Cloud Storage バケットは同じロケーションのリージョン バケットに存在する必要があります。たとえば、データセットが東京リージョンにある場合、Cloud Storage バケットは東京のリージョン バケットである必要があります。
- 例外: データセットが米国のマルチリージョン ロケーションにある場合、任意のリージョンまたはマルチリージョン ロケーションにある Cloud Storage バケットにデータをエクスポートできます。
- データ管理計画を作成する
- BigQuery データセットや 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 Storage を使用して大量のデータセットを保存し、移動させる方法の詳細については、Google Cloud Storage とビッグデータの使用をご覧ください。
エクスポート形式と圧縮形式
BigQuery は、エクスポートされるデータに対して次のデータ形式と圧縮形式をサポートしています。
データ形式 | サポートされている圧縮タイプ | 詳細 |
---|---|---|
CSV | GZIP | エクスポートされるデータの CSV 区切り文字は、 ネストされたデータや繰り返しデータは、サポートされていません。 |
JSON | GZIP | ネストされたデータや繰り返しデータはサポートされます。 |
Avro | DEFLATE、SNAPPY | Avro のエクスポートでは、GZIP はサポートされていません。 ネストされたデータや繰り返しデータはサポートされます。 |
BigQuery に保存されているデータのエクスポート
テーブルデータをエクスポートするには、BigQuery ウェブ UI を使用するか、bq extract
CLI コマンドを使用するか、API またはクライアント ライブラリを使用して抽出ジョブを送信します。
テーブルデータのエクスポート
BigQuery テーブルからデータをエクスポートするには:
ウェブ UI
BigQuery ウェブ UI に移動します。
BigQuery ウェブ UI に移動ナビゲーション領域で、データセットの横の展開アイコンをクリックして、その内容を表示します。
エクスポートするデータを含むテーブルの横にある下矢印アイコン
をクリックします。
[Export table] を選択して [Export to Google Cloud Storage] ダイアログを表示します。
[Export to Google Cloud Storage] ダイアログで、次の操作を行います。
- [Export format] でエクスポートするデータの形式を、[CSV]、[JSON](改行区切り)、[Avro] から選択します。
- [Compression] では、デフォルト値
None
を受け入れるか、GZIP
を選択します。Avro 形式は GZIP 圧縮と組み合わせて使用することはできません。Avro データを圧縮するには、bq
コマンドライン ツールまたは API を使用して、Avro データでサポートされている圧縮タイプの 1 つ(DEFLATE
またはSNAPPY
)を指定します。 - [Google Cloud Storage URI] テキスト ボックスに、有効な URI を
gs://[BUCKET_NAME]/[FILENAME.CSV]
の形式で入力します。[BUCKET_NAME]
は Cloud Storage バケットの名前、[FILENAME]
はエクスポート先のファイル名です。BigQuery データセットと Cloud Storage バケットは同じロケーションに存在する必要があります。 - [OK] をクリックしてテーブルをエクスポートします。
ジョブが実行されている間、(extracting)というメッセージがナビゲーション領域のテーブル名の横に表示されます。ジョブの進行状況をチェックするには、ナビゲーション領域の上の方にある [Job History] で [Extract] ジョブを確認します。
コマンドライン
bq extract
コマンドを使用します。
bq --location=[LOCATION] extract --destination_format [FORMAT] --compression [COMPRESSION_TYPE] --field_delimiter [DELIMITER] --print_header [BOOLEAN] [PROJECT_ID]:[DATASET].[TABLE] gs://[BUCKET]/[FILENAME]
ここで
[LOCATION]
はロケーションの名前です。データがUS
またはEU
のマルチリージョン ロケーションにある場合は、--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]
は、エクスポートされるデータファイルの名前です。ワイルドカードを使用して複数のファイルにエクスポートできます。
例:
たとえば、次のコマンドは、mydataset.mytable
を myfile.csv
という名前の gzip 圧縮ファイルにエクスポートします。myfile.csv
は example-bucket
という Cloud Storage バケットに保存されます。
bq --location=US extract --compression GZIP 'mydataset.mytable' gs://example-bucket/myfile.csv
デフォルトの出力形式は CSV です。JSON または Avro 形式でエクスポートするには、destination_format
フラグを NEWLINE_DELIMITED_JSON
または AVRO
に設定します。次に例を示します。
bq --location=US 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 --location=US extract --destination_format AVRO --compression SNAPPY 'mydataset.mytable' gs://example-bucket/myfile.avro
API
データをエクスポートするには、ジョブを作成して configuration.extract
オブジェクトの内容を設定します。
ジョブリソースの jobReference
セクションにある location
プロパティにロケーションを指定します。
抽出ジョブを作成し、抽出元の BigQuery データと抽出先の Cloud Storage を指定します。ジョブの作成について詳しくは、ジョブ、データセット、プロジェクトの管理をご覧ください。
sourceTable 設定オブジェクトを使用してソーステーブルを指定します。このオブジェクトはプロジェクト ID、データセット ID、テーブル ID で構成されています。
宛先 URI は gs://[BUCKET_NAME]/[FILENAME.CSV] の形式で完全修飾されている必要があります。各 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#
Go
Java
Node.js
PHP
Python
Ruby
Avro エクスポートの詳細
BigQuery は次の方法で Avro 形式のデータを表現します。
- エクスポートされたファイルは Avro コンテナ ファイルになります。
- 各 BigQuery の行は Avro レコードとして表されます。ネストされたデータは、ネストされた Record オブジェクトによって表されます。
REQUIRED
フィールドは、対応する Avro の型として表されます。たとえば、BigQuery のINTEGER
型は Avro のLONG
型に対応しています。NULLABLE
フィールドは、対応する型と "null" の Avro Union として表されます。REPEATED
フィールドは Avro の配列として表されます。TIMESTAMP
データ型は Avro のLONG
型として表されます。
Avro 形式を GZIP 圧縮とともに使用することはできません。Avro データを圧縮するには、bq
コマンドライン ツールまたは API を使用して、Avro データでサポートされている圧縮タイプの 1 つ(DEFLATE
または SNAPPY
)を指定します。
1 つまたは複数のファイルへのデータのエクスポート
destinationUris
プロパティはファイルのエクスポート先の場所とファイル名を示します。
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 ... プロパティの定義:
作成されるファイル: gs://my-bucket/path-component-000000000000/file-name.json gs://my-bucket/path-component-000000000001/file-name.json gs://my-bucket/path-component-000000000002/file-name.json ... |
複数のワイルドカード URI |
複数のワイルドカード URI は、エクスポート出力をパーティショニングする場合に使用します。Cloud Dataproc のようなサービスで並列処理ジョブを実行している場合は、このオプションを使用します。ジョブの処理に使用できるワーカーの数を判断し、ワーカーごとに 1 つの URI を作成します。BigQuery は各 URI の場所をパーティションとして扱い、並行処理を使用してそれぞれの場所でデータを複数のファイルに分割します。各 URI に単一のワイルドカード演算子が含まれていて、各 URI が重複しておらず、URI の数が割り当てのポリシーの上限を超えていない限り、ファイル名でどのようなパターンでも使用できます。 複数のワイルドカード URI を渡すと、一連のファイルの「最後」のファイルであることを示す特別なファイルが各パーティションの最後に作成されます。このファイルの名前は、作成された分割ファイルの数を示しています。 たとえば、ワイルドカード 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 |
割り当てポリシー
エクスポート ジョブの割り当てについては、「割り当てと制限」のページのエクスポート ジョブをご覧ください。
料金
現時点では、BigQuery からのデータのエクスポートについて請求は発生しませんが、エクスポートは BigQuery の割り当てと制限の対象となります。
BigQuery の料金設定の詳細については、料金のページをご覧ください。
データをエクスポートした後は、Google Cloud Storage 内でのデータの保管に関して請求が発生します。
Cloud Storage の料金設定の詳細については、Cloud Storage の料金体系をご覧ください。
次のステップ
- BigQuery ウェブ UI について学習するには、BigQuery ウェブ UI をご覧ください。
bq
コマンドライン ツールについて学習するには、bq コマンドライン ツールをご覧ください。- Google BigQuery API を使用してアプリケーションを作成する方法を学習するには、API による簡単なアプリケーションの作成をご覧ください。