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

BigQuery テーブルデータを CSV、JSON、Avro、Parquet 形式で Cloud Storage にエクスポートして、バックアップ、アーカイブ、または他のツールでの処理を行うことができます。BigQuery にデータを読み込んだ後、 Cloud de Confiance コンソール、bq コマンドライン ツール、API、クライアント ライブラリ、または代替のエクスポート方法を使用してデータをエクスポートできます。

エクスポートの制限事項

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

• テーブルデータをローカル ファイル、Google スプレッドシート、Google ドライブにエクスポートすることはできません。可能なエクスポート先は Cloud Storage だけです。クエリ結果の保存については、クエリ結果のダウンロードと保存をご覧ください。
• 最大 1 GB のサイズの論理テーブルデータを 1 つのファイルにエクスポートできます。1 GB を超えるデータをエクスポートする場合は、ワイルドカードを使用してデータを複数のファイルにエクスポートします。データを複数のファイルにエクスポートすると、さまざまなサイズのファイルになります。エクスポートするファイルサイズを制御するには、データをパーティショニングし、各パーティションをエクスポートします。大規模なテーブルのエクスポートに関する詳細と推奨事項については、大規模なテーブルのエクスポートに関する考慮事項をご覧ください。
• EXPORT DATA ステートメントの使用時に生成されるファイルのサイズは保証されません。
• 抽出ジョブによって生成されるファイルの数はさまざまです。
• ネストや繰り返しのあるデータを CSV 形式でエクスポートすることはできません。ネストされたデータと繰り返しデータは、Avro、JSON、Parquet のエクスポートでサポートされています。
• データを JSON 形式でエクスポートするときは、INT64（整数）データ型が JSON 文字列としてエンコードされます。これは、そのデータが他のシステムで読み込まれるときに 64 ビットの精度を保持するためです。
• 単一の抽出ジョブで複数のテーブルからデータをエクスポートすることはできません。
• Cloud de Confiance コンソールを使用してデータをエクスポートする場合、GZIP 以外の圧縮タイプを選択することはできません。
• 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 では機能しません。
• 抽出ジョブの実行中に BigQuery に読み込まれた新しいデータは、その抽出ジョブには含まれません。新しいデータを抽出するには、新しいエクスポート ジョブを作成する必要があります。
• Cloud Storage の世代番号は、エクスポート プロセス中に 1 回以上変更されることがあります。エクスポート直後に新しい Cloud Storage オブジェクトでジョブを実行する場合は、世代番号を指定しないでください。

始める前に

このドキュメントの各タスクを実行するために必要な権限をユーザーに与える 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 のロールと権限について詳しくは、事前定義ロールと権限をご覧ください。

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

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

データのエクスポート

次のセクションでは、テーブルデータ、テーブル メタデータ、クエリ結果を Cloud Storage にエクスポートする方法について説明します。

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

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

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

次のいずれかを選択します。

bq extract --location=location \
--destination_format format \
--compression compression_type \
--field_delimiter delimiter \
--print_header=boolean \
project_id:dataset.table \
gs://bucket/filename.ext

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

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

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

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

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}.");
    }
}

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
}

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

// 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;
  }
}

use Google\Cloud\BigQuery\BigQueryClient;

/**
 * Extracts the given table as json to given GCS bucket.
 *
 * @param string $projectId The project Id of your Google Cloud Project.
 * @param string $datasetId The BigQuery dataset ID.
 * @param string $tableId The BigQuery table ID.
 * @param string $bucketName Bucket name in Google Cloud Storage
 */
function extract_table(
    string $projectId,
    string $datasetId,
    string $tableId,
    string $bucketName
): void {
    $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);
}

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

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

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

Iceberg テーブルからテーブル メタデータをエクスポートするには、次の SQL ステートメントを使用します。

EXPORT TABLE METADATA FROM `[[PROJECT_NAME.]DATASET_NAME.]TABLE_NAME`;

次のように置き換えます。

• PROJECT_NAME: テーブルのプロジェクトの名前。値はこのクエリを実行するプロジェクトにデフォルトで設定されます。
• DATASET_NAME: テーブルのデータセットの名前。
• TABLE_NAME: テーブルの名前。

エクスポートされたメタデータは STORAGE_URI/metadata フォルダにあります。ここで、STORAGE_URI はオプションで設定されたテーブルのストレージ ロケーションです。

クエリ結果をエクスポートする

次の手順により、 Cloud de Confiance コンソールでクエリ結果を Cloud Storage にエクスポートできます。

1. Cloud de Confiance コンソールで [BigQuery] ページを開きます。

   [BigQuery] ページに移動

2. [add_box SQL クエリ] をクリックします。

3. [クエリエディタ] テキスト領域に有効な GoogleSQL クエリを入力します。

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

5. 結果が返されたら、[結果を保存] > [Cloud Storage] をクリックします。

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

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

7. [保存] をクリックしてクエリ結果をエクスポートします。

ジョブの進行状況を確認するには、[ジョブ履歴] ペインを開き、EXTRACT タイプのジョブを探します。

その他のデータ エクスポート方法

また、EXPORT DATA ステートメントを使用して、クエリの結果をエクスポートすることもできます。EXPORT DATA OPTIONS を使用して、エクスポートされるデータの形式を指定できます。

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

Avro エクスポートの詳細

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

• エクスポートされたファイルは Avro コンテナ ファイルになります。
• 各 BigQuery 行は 1 つの Avro レコードとして表されます。ネストされたデータは、ネストされたレコード オブジェクトによって表されます。
• REQUIRED フィールドは、対応する Avro 型として表されます。たとえば、BigQuery の INTEGER 型は Avro の LONG 型に対応しています。
• NULLABLE フィールドは、対応する型と "null" の Avro ユニオンとして表されます。
• REPEATED フィールドは Avro 配列として表されます。
• TIMESTAMP データ型は、抽出ジョブとエクスポート データ SQL の両方のデフォルトで timestamp-micros 論理型（Avro の LONG 型にアノテーションが追加されます）として表されます。（注意: use_avro_logical_types=False を Export Data Options に追加して論理型を無効にし、タイムスタンプ列ではなく string 型を使用できますが、抽出ジョブでは常に Avro の論理型を使用します。）
• DATE データ型はエクスポート データ SQL のデフォルトで date 論理型（Avro の INT 型にアノテーションが追加されます）として表されますが、抽出ジョブのデフォルトでは string 型として表されます。（注: use_avro_logical_types=False を Export Data Options に追加して論理型を無効にしたり、フラグ --use_avro_logical_types=True を使用して抽出ジョブの論理型を有効にしたりできます）。
• TIME データ型はエクスポート データ SQL のデフォルトで timestamp-micro 論理型（Avro の LONG 型にアノテーションが追加されます）として表されますが、抽出ジョブのデフォルトでは string 型として表されます。（注: use_avro_logical_types=False を Export Data Options に追加して論理型を無効にしたり、フラグ --use_avro_logical_types=True を使用して抽出ジョブの論理型を有効にしたりできます）。
• DATETIME データ型はデフォルトではエクスポート データ SQL のデフォルトで Avro の STRING 型（カスタムの名前付き論理型 datetime の文字列型）として表されますが、抽出ジョブのデフォルトでは string 型として表されます。（注: use_avro_logical_types=False を Export Data Options に追加して論理型を無効にしたり、フラグ --use_avro_logical_types=True を使用して抽出ジョブの論理型を有効にしたりできます）。
• RANGE タイプは Avro エクスポートではサポートされていません。

パラメータ化された NUMERIC(P[, S]) データ型と BIGNUMERIC(P[, S]) データ型の場合、精度とスケール型のパラメータが Avro の decimal 論理型に変換されます。

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

Parquet エクスポートの詳細

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

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

JSON 列を Parquet 形式にエクスポートすると、STRING フィールドとしてエクスポートされます。この Parquet ファイルを BigQuery の JSON 列に読み込むには、読み込みジョブでスキーマを指定する必要があります（たとえば、--schema フラグを使用します）。Parquet を使用したスキーマの自動検出では、列が STRING 型として推測されます。

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

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

GEOGRAPHY 論理型は、エクスポートされたファイルに追加された GeoParquet メタデータで表されます。

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

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

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

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

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
...

gs://my-bucket/000000000000
gs://my-bucket/000000000001
gs://my-bucket/000000000002
...

エクスポートするファイルのサイズを制限する

1 回に 1 GB を超えるデータをエクスポートする場合は、ワイルドカードを使用して複数のファイルにデータをエクスポートする必要があります。また、ファイルサイズは異なります。エクスポートする各ファイルの最大サイズを制限する必要がある場合は、データをランダムに分割してから各パーティションをファイルにエクスポートするという方法があります。

1. 必要なパーティションの数を決定します。これは、データの合計サイズを選択したエクスポート ファイルのサイズで割った値です。たとえば、8,000 MB のデータがあり、各エクスポート ファイルを約 20 MB にする場合、400 パーティションが必要です。

2. export_id というランダムに生成された新しい列でパーティション分割およびクラスタ化される、新しいテーブルを作成します。 次の例は、選択したファイルサイズにするために n パーティションを必要とする既存のテーブル source_table から新しい processed_table を作成する方法を示しています。

   CREATE TABLE my_dataset.processed_table
   PARTITION BY RANGE_BUCKET(export_id, GENERATE_ARRAY(0, n, 1))
   CLUSTER BY export_id
   AS (
     SELECT *, CAST(FLOOR(n*RAND()) AS INT64) AS export_id
     FROM my_dataset.source_table
   );

3. 0 から n-1 までの整数 i ごとに、次のクエリで EXPORT DATA ステートメントを実行します。

   SELECT * EXCEPT(export_id)
   FROM my_dataset.processed_table
   WHERE export_id = i;

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

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: %w", 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
}

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

// 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;
  }
}

# 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.

使用例

この例は、Cloud Storage にデータをエクスポートする方法を示しています。

エンドポイント ログから Cloud Storage に継続的にデータをストリーミングしているとします。バックアップとアーカイブの目的で、毎日のスナップショットが Cloud Storage にエクスポートされます。最適な選択は、特定の割り当てと制限に従う必要がある抽出ジョブです。

jobReference.jobId として一意の ID を渡し、API またはクライアント ライブラリを使用して抽出ジョブを送信します。抽出ジョブは非同期です。ジョブの作成に使用された一意のジョブ ID を使用して、ジョブのステータスを確認します。status.status が DONE の場合、ジョブは正常に完了しています。status.errorResult が存在する場合は、ジョブが失敗するため、再試行する必要があります。

バッチデータ処理

決められた期限までにデータを読み込むために、夜間のバッチジョブを使用するとします。この読み込みジョブが完了すると、前のセクションで説明したように、統計情報を含むテーブルがクエリから実体化されます。このテーブルのデータは、取得して PDF レポートにコンパイルし、規制機関に送信されます。

読み取る必要があるデータの量は少ないため、tabledata.list API を使用して、テーブルのすべての行を JSON 辞書形式で取得します。データページが複数ある場合は、結果に pageToken プロパティが設定されます。次のページの結果を取得するには、別の tabledata.list 呼び出しを行い、トークン値を pageToken パラメータとして指定します。API 呼び出しが 5xx エラーで失敗した場合は、指数バックオフで再試行します。ほとんどの 4xx エラーは再試行できません。BigQuery エクスポートとレポート生成をより適切に分離するには、結果をディスクに保存する必要があります。

割り当てポリシー

抽出ジョブの割り当てについては、「割り当てと上限」のページの抽出ジョブをご覧ください。

抽出の使用状況は INFORMATION_SCHEMA で確認できます。抽出ジョブの JOBS_BY_* システム テーブルのジョブエントリには、合計使用量をモニタリングして、1 日あたり 50 TiB 未満にするために使用できる total_bytes_processed 値が含まれます。INFORMATION_SCHEMA.JOBS ビューに対してクエリを実行して total_bytes_processed 値を取得する方法については、INFORMATION_SCHEMA.JOBS スキーマをご覧ください。

現在の割り当て使用量を確認する

クエリ、読み込み、抽出、コピージョブの現在の使用状況を確認するには、INFORMATION_SCHEMA クエリを実行して、指定した期間に実行されたジョブに関するメタデータを表示します。現在の使用量と割り当て上限を比較することで、特定の種類のジョブの割り当て使用量を確認できます。次のクエリの例では、INFORMATION_SCHEMA.JOBS ビューを使用して、プロジェクトごとにクエリ、読み込み、抽出、コピーの各ジョブの数を一覧表示します。

SELECT
  sum(case  when job_type="QUERY" then 1 else 0 end) as QRY_CNT,
  sum(case  when job_type="LOAD" then 1 else 0 end) as LOAD_CNT,
  sum(case  when job_type="EXTRACT" then 1 else 0 end) as EXT_CNT,
  sum(case  when job_type="COPY" then 1 else 0 end) as CPY_CNT
FROM `region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE date(creation_time)= CURRENT_DATE()

エクスポートされたバイト数をモニタリングする Cloud Monitoring アラート ポリシーを設定できます。

1. Cloud de Confiance コンソールで、[notifications アラート] ページに移動します。

   [アラート] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが [Monitoring] の結果を選択します。

2. [アラート] ページで、[ポリシーを作成] をクリックします。

3. [ポリシー構成モード] で、[コードエディタ（MQL または PromQL）] を選択します。

4. PromQL クエリエディタで、次のクエリを入力します。

   (
     sum by (project_id, quota_metric, location) (increase({"serviceruntime.googleapis.com/quota/rate/net_usage", monitored_resource="consumer_quota", service="bigquery.googleapis.com"}[1m]))
     /
     max by (project_id, quota_metric, location) ({"serviceruntime.googleapis.com/quota/limit", monitored_resource="consumer_quota", service="bigquery.googleapis.com", limit_name="ExtractBytesPerDay"})
   ) > 0.01
   

   [自動実行] が有効になっていない場合は、[クエリを実行] をクリックします。

5. アラートの残りの部分を構成して、[ポリシーを作成] をクリックします。

PromQL ベースのアラート ポリシーを作成する手順の詳細については、PromQL ベースのアラート ポリシーを作成する（コンソール）をご覧ください。

トラブルシューティング

抽出ジョブの問題を診断し、トラブルシューティングします。

ログ エクスプローラを使用して問題を診断する

抽出ジョブの問題を診断するには、ログ エクスプローラを使用して特定の抽出ジョブのログを確認し、考えられるエラーを特定します。次のログ エクスプローラ フィルタは、抽出ジョブに関する情報を返します。

resource.type="bigquery_resource"
protoPayload.methodName="jobservice.insert"
(protoPayload.serviceData.jobInsertRequest.resource.jobConfiguration.query.query=~"EXPORT" OR
protoPayload.serviceData.jobCompletedEvent.eventName="extract_job_completed" OR
protoPayload.serviceData.jobCompletedEvent.job.jobConfiguration.query.query=~"EXPORT")

1 日あたりの抽出バイト数の割り当て超過エラー

抽出がプロジェクトのデフォルトの 1 日あたりの上限（50 TiB）を超えると、BigQuery はこのエラーを返します。抽出ジョブの上限の詳細については、抽出ジョブをご覧ください。

エラー メッセージ

Your usage exceeded quota for ExtractBytesPerDay

診断

50 TiB を超えるテーブルをエクスポートすると、抽出の上限を超えるため、エクスポートは失敗します。特定のテーブル パーティションのテーブルデータをエクスポートする場合は、パーティション デコレータを使用して、エクスポートするパーティションを指定できます。

直近数日間のエクスポート データの使用状況を収集するには、次の方法を試してください。

• Name: Extract bytes per day、Metric: bigquery.googleapis.com/quota/extract/bytes などのフィルタ条件を使用してプロジェクトの割り当てを表示し、[使用状況を表示] グラフで数日間の使用状況の傾向を確認します。

• または、INFORMATION_SCHEMA.JOBS_BY_PROJECT をクエリして、数日間の抽出バイト数の合計を確認することもできます。たとえば、次のクエリは、過去 7 日間に EXTRACT ジョブによって処理された 1 日あたりの合計バイト数を返します。

  SELECT
  TIMESTAMP_TRUNC(creation_time, DAY) AS day,
  SUM ( total_bytes_processed ) / POW(1024, 3) AS total_gibibytes_processed
  FROM
  `region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
  WHERE
  creation_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY) AND CURRENT_TIMESTAMP()
  AND job_type = "EXTRACT"
  GROUP BY 1
  ORDER BY 2 DESC

• 想定よりも多くのバイト数を使用している特定のジョブを明確にすることで、結果をさらに絞り込むことができます。次の例では、過去 7 日間に処理された 100 GB を超える EXTRACT ジョブの上位 100 件を返します。

  SELECT
  creation_time,
  job_id,
  total_bytes_processed/POW(1024, 3) AS total_gigabytes_processed
  FROM
  `region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
  WHERE
  creation_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY) AND CURRENT_TIMESTAMP()
  AND job_type="EXTRACT"
  AND total_bytes_processed > (POW(1024, 3) * 100)
  ORDER BY
  total_bytes_processed DESC
  LIMIT 100

または、Bytes processed more than などのフィルタとともにジョブ エクスプローラを使用して、指定した期間の処理負荷の高いジョブをフィルタ処理することもできます。

解決策

この割り当てエラーを解決する方法の 1 つは、スロット予約を作成し、PIPELINE ジョブタイプを使用して、プロジェクトを予約に割り当てることです。ここでは、無料の共有スロットプールではなく専用の予約を使用するため、上限チェックを回避できます。必要に応じて、後で共有スロットプールを使用する場合は予約を削除できます。

50 TiB を超えるエクスポートを可能にする別の方法については、抽出ジョブの注記セクションをご覧ください。

ネストされたスキーマのエラーでエクスポートに失敗する

このエラーは、STRUCT や ARRAY などのネストされたフィールドや繰り返しフィールドを含むテーブルを、CSV や改行区切りの JSON などのフラット ファイル形式にエクスポートしようとしたときに発生します。

エラー メッセージ

Failed to export: Operation cannot be performed on a nested schema. Field: [COLUMN_NAME]

このエラーは、CSV などのフラット ファイル形式では階層データや多値データを表現できないために発生します。BigQuery Export では、この複雑なデータをフラット ファイル形式で書き込む前に、フラット化するか、表形式に変換する必要があります。この場合、COLUMN_NAME は、データをエクスポートする前にフラット化または変換する必要があるネストされたフィールドまたは繰り返しフィールドを含む列を指します。

解決策

ソーススキーマに応じて、スキーマをフラット化してエクスポートの準備を行う方法がいくつかあります。

次の例は、ネストされた STRUCT フィールドを含むスキーマと、エクスポート用にそれらをフラット化するクエリを示しています。この例では、user_details 列のネストされたフィールドが原因でエクスポート クエリが失敗します。推奨される修正を使用して、ファイル構造を user_details.name と user_details.email の 2 つの列にフラット化できます。

  -- Schema example:
  root
    ├── id (INTEGER)
    ├── user_details (RECORD / STRUCT, NULLABLE)
    │   ├── name (STRING)
    │   └── email (STRING)
    └── created_at (TIMESTAMP)

  -- Export query:
  SELECT * FROM my_dataset.my_table;

  -- Suggested fix:
  SELECT
      id,
      user_details.name AS user_name,
      user_details.email AS user_email,
      created_at
  FROM
      my_dataset.my_table;

次の例は、繰り返し ARRAY フィールドを含むスキーマと、エクスポート用にそれらをフラット化するクエリを示しています。この例では、line_items 列に繰り返しフィールドがあるため、エクスポート クエリが失敗します。提案された修正を使用できます。この修正では、UNNEST() 演算子を使用して配列要素を個々の行に変換します。

  -- Schema example:
  root
    ├── order_id (STRING)
    ├── customer_name (STRING)
    └── line_items (REPEATED / ARRAY of RECORD/STRUCT, NULLABLE)
        ├── product_id (STRING)
        └── quantity (INTEGER)


  -- Export query:
  SELECT * FROM my_dataset.my_orders_table;

  -- Suggested fix:
  SELECT
      t.order_id,
      t.customer_name,
      item.product_id,
      item.quantity
  FROM
      my_dataset.my_orders_table AS t
  LEFT JOIN
      UNNEST(t.line_items) AS item
  ;

また、CSV ファイルで ARRAY<STRING> などの配列を単一の文字列列として表すだけでよい場合は、ARRAY_TO_STRING() を使用できます。

ARRAY_TO_STRING() は、interests 配列のすべての要素をカンマを区切り文字として使用して 1 つの文字列に連結します。この変換は、各配列要素の正確な構造がエクスポートに重要でない場合に役立ちます。

  -- Schema example:
  root
    ├── user_id (STRING)
    └── interests (REPEATED / ARRAY of STRING, NULLABLE)

  -- Suggested fix:
  SELECT
      user_id,
      ARRAY_TO_STRING(interests, ', ') AS user_interests
  FROM
      my_dataset.my_users_table;

料金

データ エクスポートの料金については、BigQuery の料金ページをご覧ください。

データのエクスポート後は、Cloud Storage にデータを保存することで料金が発生します。詳しくは、Cloud Storage の料金をご覧ください。

テーブルのセキュリティ

BigQuery でテーブルへのアクセスを制御するには、IAM を使用してリソースへのアクセスを制御するをご覧ください。

次のステップ

• Cloud de Confiance コンソールの詳細については、 Cloud de Confiance コンソールの使用をご覧ください。
• bq コマンドライン ツールの詳細については、bq コマンドライン ツールの使用をご覧ください。
• BigQuery API クライアント ライブラリを使ってアプリケーションを作成する方法を学習するには、クライアント ライブラリ クイックスタート ガイドをご覧ください。