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

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

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

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

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

エクスポートの制限事項

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

  • テーブルデータをローカル ファイル、スプレッドシート、ドライブにエクスポートすることはできません。可能なエクスポート先は Cloud Storage だけです。クエリ結果の保存については、クエリ結果のダウンロードと保存をご覧ください。
  • 1 つのファイルに最大 1 GB のテーブルデータをエクスポートできます。1 GB を超えるデータをエクスポートする場合は、ワイルドカードを使用してデータを複数のファイルにエクスポートします。データを複数のファイルにエクスポートすると、さまざまなサイズのファイルになります。
  • ネストや繰り返しのあるデータを CSV 形式でエクスポートすることはできません。ネストされたデータと繰り返しデータは、Avro、JSON、Parquet のエクスポートでサポートされています。
  • データを JSON 形式でエクスポートするときは、INT64(整数)データ型が JSON 文字列としてエンコードされます。これは、そのデータが他のシステムで読み込まれるときに 64 ビットの精度を保持するためです。
  • 単一のエクスポート ジョブで複数のテーブルからデータをエクスポートすることはできません。
  • Cloud Console を使用してデータをエクスポートする場合、GZIP 以外の圧縮タイプを選択することはできません。
  • 保持ポリシーを使用して構成された Cloud Storage バケットにデータをエクスポートすると、BigQuery からバケットへのファイルの書き込みが失敗する場合があります。エクスポート ジョブの期間の保持ポリシーを緩和することを検討してください。
  • JSON 形式でテーブルをエクスポートする場合、記号 <>& は Unicode 表記の \uNNNN に変換されます。ここで、N は 16 進数です。たとえば、profit&lossprofit\u0026loss になります。この Unicode 変換は、セキュリティの脆弱性を回避するために行われます。

始める前に

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

必要な権限

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

BigQuery テーブルへのアクセス権限

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

次の IAM 事前定義ロールには、BigQuery テーブルにアクセスするために必要な権限が含まれています。

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

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

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

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

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

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

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

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

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

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

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

ネストされたデータと繰り返しデータはサポートされます。Avro のエクスポートの詳細をご覧ください。

Parquet SNAPPY、GZIP

ネストされたデータと繰り返しデータはサポートされます。Parquet エクスポートの詳細をご覧ください。

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

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

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

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

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

Console

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

    BigQuery ページに移動

  2. [エクスプローラ] パネルで、プロジェクトとデータセットを開いて、テーブルを選択します。

  3. 詳細パネルで、[エクスポート] をクリックして [Cloud Storage にエクスポート] を選択します。

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

    • [Google Cloud Storage のロケーション] で、データをエクスポートするバケット、フォルダ、またはファイルを参照します。
    • [エクスポート形式] で、エクスポートするデータの形式を CSV、JSON(改行区切り)、Avro、または Parquet から選択します。
    • [圧縮] で、圧縮形式を選択するか、None を選択して圧縮なしにします。
    • [エクスポート] をクリックしてテーブルをエクスポートします。

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

bq

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

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

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

  • --compression: エクスポートされるファイルに使用する圧縮タイプ。
  • --field_delimiter: CSV エクスポートの出力ファイル内での列間の境界を示す文字。タブ区切り文字には \ttab の両方を使用できます。
  • --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 は、エクスポートされるデータの形式です(CSVNEWLINE_DELIMITED_JSONAVRO、または PARQUET)。
  • compression_type は、データ形式に対してサポートされる圧縮タイプです。エクスポート形式と圧縮形式をご覧ください。
  • delimiter は、CSV エクスポートの列間の境界を示す文字です。タブの名前として受け入れられるのは \ttab です。
  • booleantrue または false です。true に設定すると、データ形式がヘッダーをサポートする場合に、エクスポートされるデータにヘッダー行が出力されます。デフォルト値は true です。
  • project_id はプロジェクト ID です。
  • dataset はソース データセットの名前です。
  • table は、エクスポートするテーブルです。
  • bucket は、データのエクスポート先の Cloud Storage バケットの名前です。BigQuery データセットと Cloud Storage バケットは同じロケーションに存在する必要があります。
  • filename.ext は、エクスポートされるデータファイルの名前と拡張子です。ワイルドカードを使用して複数のファイルにエクスポートできます。

例:

たとえば、次のコマンドは、mydataset.mytablemyfile.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 仕様に従います。
  • パラメータ化された NUMERIC(P[, S]) データ型と BIGNUMERIC(P[, S]) データ型では、精度とスケール型のパラメータが Avro の decimal 論理型に移転されます。

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

Parquet エクスポートの詳細

BigQuery は、標準 SQL のデータ型を次の Parquet データ型に変換します。

BigQuery のデータ型 Parquet のプリミティブ型 Parquet の論理型
整数 INT64 NONE
数値 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)
浮動小数点数 FLOAT NONE
ブール値 BOOLEAN NONE
文字列 BYTE_ARRAY STRING (UTF8)
バイト BYTE_ARRAY NONE
日付 INT32 DATE
日時 INT64 TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)
時間 INT64 TIME (isAdjustedToUTC = false, unit = MICROS)
タイムスタンプ INT64 TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)

Parquet スキーマでは、ネストされたデータをグループとして表し、繰り返しレコードを繰り返しグループとして表します。BigQuery でネストされた繰り返しデータを使用する詳しい方法については、ネストされた繰り返し列の指定をご覧ください。

DATETIME 型には、次の回避策を使用できます。

  • ステージング テーブルにファイルを読み込みます。その後、SQL クエリを使用してフィールドを DATETIME にキャストし、結果を新しいテーブルに保存します。詳細については、列のデータ型の変更をご覧ください。
  • 読み込みジョブで --schema フラグを使用してテーブルのスキーマを指定します。日時列を col:DATETIME として定義します。

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 の料金設定の詳細については、クラウドの料金設定のページをご覧ください。

テーブルのセキュリティ

BigQuery でテーブルへのアクセスを制御するには、テーブルのアクセス制御の概要をご覧ください。

次のステップ