將資料表資料匯出至 Cloud Storage

您可以將 BigQuery 資料表資料匯出至 Cloud Storage，格式為 CSV、JSON、Avro 或 Parquet，以便備份、封存或在其他工具中處理。將資料載入 BigQuery 後，您可以使用 Cloud de Confiance 控制台、bq 指令列工具、API、用戶端程式庫或其他匯出方法匯出資料。

匯出限制

當您從 BigQuery 匯出資料時，請注意以下幾點：

• 您無法將資料表資料匯出至本機檔案、Google 試算表或 Google 雲端硬碟。唯一支援的匯出位置是 Cloud Storage。如要瞭解如何儲存查詢結果，請參閱「下載及儲存查詢結果」。
• 最多可將 1 GB 的邏輯資料表資料匯出至單一檔案。如果您匯出的資料超過 1 GB，請使用萬用字元將資料匯出到多個檔案。將資料匯出至多個檔案時，檔案大小會有所不同。如要限制匯出檔案的大小，可以將資料分區，並匯出各個分區。如要進一步瞭解匯出大型資料表的相關資訊和建議，請參閱「大型資料表匯出注意事項」。
• 使用 EXPORT DATA 陳述式時，無法保證產生的檔案大小。
• 擷取工作產生的檔案數量可能不盡相同。
• 您無法將巢狀與重複資料匯出成 CSV 格式。Avro、JSON 和 Parquet 匯出作業支援巢狀和重複資料。
• 以 JSON 格式匯出資料時，INT64 (整數) 資料類型會編碼為 JSON 字串，以便在其他系統讀取資料時保留 64 位元精確度。
• 您無法在單一擷取工作中匯出多個資料表的資料。
• 使用 Cloud de Confiance 控制台匯出資料時，只能選擇 GZIP 壓縮類型。
• 以 JSON 格式匯出資料表時，系統會使用 Unicode 標記 \uNNNN 轉換符號 <、> 和 &，其中 N 是十六進位數字。舉例來說，profit&loss 會變為 profit\u0026loss。這項 Unicode 轉換作業是為了避免安全漏洞。
• 除非您使用 EXPORT DATA 陳述式，並在 query_statement 中指定 ORDER BY 子句，否則無法保證匯出的資料表資料順序。匯出至多個檔案時，所有產生的檔案都會保留排序序列。
• BigQuery 不支援在初始雙斜線後方包含多個連續斜線的 Cloud Storage 資源路徑。Cloud Storage 物件名稱可以包含多個連續斜線 (「/」) 字元。不過，BigQuery 會將多個連續斜線轉換為單一斜線。舉例來說，下列資源路徑雖然在 Cloud Storage 中有效，但在 BigQuery 中無法運作：gs://bucket/my//object//name。
• 擷取工作執行期間，載入 BigQuery 的任何新資料都不會納入該擷取工作。您必須建立新的擷取工作，才能匯出新資料。
• 在匯出過程中，Cloud Storage 世代編號可能會變更一或多次。如果要在匯出後立即對新的 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 bucket 的權限

如要將資料寫入現有的 Cloud Storage bucket，您必須具備下列 IAM 權限：

• storage.objects.create
• storage.objects.delete

下列各項預先定義的 IAM 角色，都包含將資料寫入現有 Cloud Storage bucket 所需的權限：

• 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. 在「Export to Google Storage」(匯出至 Google Cloud Storage) 對話方塊中：

   • 在「GCS Location」(GCS 位置)，瀏覽要匯出資料的值區、資料夾或檔案。
   • 在「Export format」(匯出格式)，選擇匯出資料的格式：CSV、JSON (以換行符號分隔)、Avro 或 Parquet。
   • 在「Compression」(壓縮) 部分，選取壓縮格式，或選取 None 表示不壓縮。

7. 按一下「儲存」，匯出查詢結果。

如要查看工作進度，請展開「Job history」(工作記錄) 窗格，然後尋找類型為 EXTRACT 的工作。

其他匯出資料的方式

您也可以使用 EXPORT DATA 陳述式匯出查詢結果。您可以使用 EXPORT DATA OPTIONS 指定匯出資料的格式。

最後，您可以使用 Dataflow 等服務從 BigQuery 讀取資料，而非從 BigLake 匯出資料。如要進一步瞭解如何使用 Dataflow 讀取及寫入 BigQuery，請參閱 BigQuery I/O 說明文件。

Avro 匯出詳細資料

BigQuery 可以透過以下方式表示 Avro 格式的資料：

• 結果匯出檔案是 Avro 容器檔案。
• 每個 BigQuery 資料列都會表示為一筆 Avro 記錄。巢狀資料會以巢狀記錄物件來表示。
• REQUIRED 欄位會表示為對應 Avro 類型。舉例來說，BigQuery 的 INTEGER 類型就會對應到 Avro 的 LONG 類型。
• NULLABLE 欄位會表示為對應類型的 Avro Union 與「空值」。
• REPEATED 欄位會表示為 Avro 陣列。
• 在擷取工作和匯出資料 SQL 中，TIMESTAMP 資料類型預設會以 timestamp-micros 邏輯類型表示 (會為 Avro LONG 類型加上註解)。(注意：您可以將 use_avro_logical_types=False 新增至 Export Data Options，停用邏輯類型，改為在時間戳記資料欄使用 string 類型，但在擷取工作中，一律會使用 Avro 邏輯類型)。
• 在匯出資料 SQL 中，DATE 資料類型預設會以 date 邏輯類型表示 (會為 Avro INT 類型加上註解)，但在擷取工作中，預設會以 string 類型表示。(注意：您可以在 Export Data Options 中加入 use_avro_logical_types=False 來停用邏輯類型，或使用 --use_avro_logical_types=True 旗標在擷取工作中啟用邏輯類型)。
• 在匯出資料 SQL 中，TIME 資料類型預設會以 timestamp-micro 邏輯類型表示 (會為 Avro LONG 類型加上註解)，但在擷取工作中，預設會以 string 類型表示。(注意：您可以將 use_avro_logical_types=False 新增至 Export Data Options 來停用邏輯類型，或使用 --use_avro_logical_types=True 旗標在擷取工作中啟用邏輯類型)。
• 在匯出資料 SQL 中，DATETIME 資料類型預設會以 Avro STRING 類型 (具有自訂命名邏輯類型 datetime 的字串類型) 表示，但在擷取工作中，預設會以 string 類型表示。(注意：您可以將 use_avro_logical_types=False 新增至 Export Data Options，停用邏輯類型，或使用 --use_avro_logical_types=True 旗標，在擷取工作中啟用邏輯類型)。
• Avro 匯出作業不支援 RANGE 類型。

參數化 NUMERIC(P[, S]) 和 BIGNUMERIC(P[, S]) 資料類型會將其有效位數和小數位數類型參數，轉移至 Avro 十進位邏輯類型。

Avro 格式無法與 GZIP 壓縮搭配使用。如要壓縮 Avro 資料，請使用 bq 指令列工具或 API，並指定 Avro 資料支援的壓縮類型：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 中繼資料表示。

將資料匯出為一或多個檔案

destinationUris 屬性會指出 BigQuery 應將檔案匯出至一或多個位置和檔案名稱。

BigQuery 支援在每個 URI 中使用一個萬用字元運算子 (*)。萬用字元可以出現在檔案名稱元件中的任何位置。使用萬用字元運算子就會指示 BigQuery 根據提供的模式建立多個資料分割檔案。萬用字元運算子會以數字取代 (從 0 開始)，向左填補到到 12 位數。舉例來說，如果 URI 的檔案名稱結尾有萬用字元，系統會建立檔案，並在第一個檔案附加 000000000000，在第二個檔案附加 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 GB 的資料時，必須使用萬用字元將資料匯出至多個檔案，檔案大小不一。如需限制每個匯出檔案的大小上限，可以隨機分割資料，然後將每個分區匯出至檔案：

1. 決定所需的分區數量，也就是資料總大小除以所選匯出檔案大小。舉例來說，如果您有 8,000 MB 的資料，且希望每個匯出的檔案約為 20 MB，則需要 400 個分區。

2. 建立新的資料表，並依隨機產生的新資料欄 export_id 進行分區和分群。以下範例說明如何從名為 source_table 的現有資料表建立新的 processed_table，該資料表需要 n 個分區才能達到所選檔案大小：

   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，用於備份和封存。最佳選擇是擷取工作，但須遵守特定配額和限制。

使用 API 或用戶端程式庫提交擷取工作，並傳入專屬 ID 做為 jobReference.jobId。擷取工作是非同步的。使用建立工作時所用的不重複工作 ID 檢查工作狀態。如果 status.status 為 DONE，代表工作已順利完成。如果出現 status.errorResult，表示工作失敗，需要重試。

批次資料處理

假設您使用夜間批次工作，在固定期限前載入資料。這項載入工作完成後，系統會根據查詢具體化含有統計資料的資料表，如上一節所述。系統會擷取這個資料表中的資料，並彙整成 PDF 報表，然後傳送給監管機構。

由於需要讀取的資料量很小，請使用 tabledata.list API，以 JSON 字典格式擷取資料表的所有資料列。如果資料不只一頁，結果會設定 pageToken 屬性。如要擷取下一頁結果，請再次發出 tabledata.list 呼叫，並將權杖值做為 pageToken 參數。如果 API 呼叫失敗並傳回 5xx 錯誤，請以指數輪詢方式重試。大多數 4xx 錯誤都無法重試。為進一步分離 BigQuery Export 和報表產生作業，應將結果保存至磁碟。

配額政策

如要瞭解擷取工作的配額，請參閱「配額與限制」頁面的「擷取工作」一節。

INFORMATION_SCHEMA提供擷取工作的用量。擷取工作的 JOBS_BY_* 系統資料表中的工作項目包含 total_bytes_processed 值，可用於監控匯總用量，確保用量維持在每天 50 TiB 以下。如要瞭解如何查詢 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「Alerting」(警告) 頁面：

   前往「Alerting」(警告)

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。

2. 在「Alerting」(快訊) 頁面中，按一下「Create Policy」(建立政策)。

3. 在「Policy configuration mode」(政策設定模式) 下方，選取「Code editor (MQL or PromQL)」(程式碼編輯器 (MQL 或 PromQL))。

4. 在「PromQL」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 警告政策 (控制台)」。

疑難排解

診斷及排解擷取工作的問題。

使用 Logs Explorer 診斷問題

如要診斷擷取工作的問題，您可以使用 Logs Explorer 查看特定擷取工作的記錄，並找出可能發生的錯誤。下列 Logs Explorer 篩選器會傳回擷取工作的相關資訊：

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

超出每日擷取位元組配額錯誤

如果擷取作業超出專案預設的每日 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，查看幾天內的擷取位元組總數。舉例來說，下列查詢會傳回過去七天內 EXTRACT 工作每日處理的總位元組數。

  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

• 接著，您可以找出耗用位元組數超出預期的特定工作，進一步縮小結果範圍。以下範例會傳回過去七天內，處理超過 100 GB 的前 100 個 EXTRACT 工作。

  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 等篩選器，篩選出指定時間範圍內處理量較高的工作。

解析度

如要解決這項配額錯誤，其中一種方法是建立運算單元預留項目，並將專案指派至具有 PIPELINE 工作類型的預留項目。這種方法會使用專屬預留項目，而非免費的共用運算單元集區，因此可以略過限制檢查。如有需要，您可以刪除預留項目，以便日後使用共用運算單元集區。

如要瞭解如何匯出超過 50 TiB 的資料，請參閱「擷取工作」中的附註部分。

巢狀結構定義錯誤，無法匯出

如果嘗試將含有巢狀或重複欄位 (例如 STRUCT 或 ARRAY 資料類型) 的資料表匯出為平面檔案格式 (例如 CSV 或以換行符號分隔的 JSON)，就會發生這項錯誤。

錯誤訊息

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

發生這項錯誤的原因是 CSV 等平面檔格式無法代表階層式或多值資料。BigQuery 匯出作業需要您先扁平化或轉換這類複雜資料，將其轉換為表格結構，才能以平面檔格式寫入。在這種情況下，COLUMN_NAME 是指含有巢狀或重複欄位的資料欄，必須先扁平化或轉換，才能匯出資料。

解決方式

視來源結構定義而定，您可以透過多種方法簡化結構定義，為匯出作業做好準備。

以下範例顯示含有巢狀 STRUCT 欄位的結構定義，以及將這些欄位扁平化以便匯出的查詢。在範例中，匯出查詢失敗，因為 user_details 欄中有巢狀欄位。您可以按照建議修正方式，將檔案結構簡化為 user_details.name 和 user_details.email 兩欄。

  -- 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() 會將興趣陣列的所有元素串連成單一字串，並以半形逗號分隔。如果每個陣列元素的確切結構對匯出作業不重要，這項轉換就非常實用。

  -- 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 指令列工具」。
• 如要瞭解如何使用 Google BigQuery API 用戶端程式庫來建立應用程式，請參閱用戶端程式庫快速入門導覽課程。