從 Cloud Storage 載入 Parquet 資料

本頁面提供將 Parquet 資料從 Cloud Storage 載入至 BigQuery 的總覽。

Parquet 是 Apache Hadoop 生態系統廣泛使用的開放來源資料欄導向式資料格式。

從 Cloud Storage 載入 Parquet 資料時，您可以將資料載入至新的資料表或分區，或是將資料附加至現有的資料表或分區，或是覆寫現有的資料表或分區。將資料載入至 BigQuery 時，資料會轉換為 Capacitor 資料欄格式 (BigQuery 的儲存格式)。

您將資料從 Cloud Storage 載入至 BigQuery 資料表時，含有該資料表的資料集必須位於與 Cloud Storage 值區相同的單一地區或多地區位置。

如需從本機檔案載入 Parquet 資料的相關資訊，請參閱 將資料從本機資料來源載入至 BigQuery。

Parquet 結構定義

您將 Parquet 檔案載入至 BigQuery 時，系統會從自述式來源資料自動擷取資料表結構定義。從來源資料擷取結構定義時，BigQuery 會按照字母順序使用最後一個檔案。

舉例來說，假設 Cloud Storage 中包含下列 Parquet 檔案：

gs://mybucket/00/
  a.parquet
  z.parquet
gs://mybucket/01/
  b.parquet

這個指令可透過單一 CLI 指令 (以逗號分隔的清單) 載入所有檔案，並從 mybucket/01/b.parquet 擷取結構定義：

bq load \
--source_format=PARQUET \
dataset.table \
"gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"

載入具有不同結構定義的多個 Parquet 檔案時，多個結構定義中所指定的相同資料欄必須在各個結構定義中採用相同的模式。

BigQuery 偵測到結構定義時，部分 Parquet 資料類型會轉換為 BigQuery 資料類型，確保與 BigQuery SQL 語法相容。詳情請參閱 Parquet 轉換。

Parquet 壓縮

壓縮的 Parquet 檔案未受支援，但壓縮的資料區塊有。以 Parquet 檔案中的壓縮資料區塊來說，BigQuery 支援 Snappy、GZip 與 LZO_1X 轉碼器。

必要權限

將資料載入 BigQuery 時，您必須具備相關權限，以便執行載入工作以及將資料載入新的或現有的 BigQuery 資料表和分區。如要載入 Cloud Storage 中的資料，您也要有權限存取包含資料的值區。

BigQuery 權限

您至少要具備下列權限，才能將資料載入 BigQuery。不管您要將資料載入或附加到資料表或分區，還是覆寫資料表或分區資料，都需要這些權限。

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.jobs.create

以下是具有 bigquery.tables.create 和 bigquery.tables.updateData 權限的預先定義 Cloud IAM 角色：

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

以下是具有 bigquery.jobs.create 權限的預先定義 Cloud IAM 角色：

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

此外，具備 bigquery.datasets.create 權限的使用者在建立資料集時，會獲得 bigquery.dataOwner 存取權。 bigquery.dataOwner 存取權可讓使用者透過載入工作建立及更新資料集中的資料表。

如要進一步瞭解 BigQuery 中的 Cloud IAM 角色和權限，請參閱存取權控管。

Cloud Storage 權限

您必須具備 storage.objects.get 權限，才能從 Cloud Storage 值區載入資料。如要使用 URI 萬用字元，您必須同時具備 storage.objects.list 權限。

授予預先定義的 Cloud IAM 角色 storage.objectViewer，即可提供 storage.objects.get 與 storage.objects.list 權限。

將 Parquet 資料載入至新的資料表

您可以透過以下方式將 ORC 資料載入至新的資料表：

  • 使用 GCP Console 或傳統網頁版 UI
  • 使用 CLI 的 bq load 指令
  • 呼叫 jobs.insert API 方法並設定 load 工作
  • 使用用戶端程式庫

如要將 Parquet 資料從 Cloud Storage 載入至新的 BigQuery 資料表，請按照下列指示操作：

主控台

  1. 在 GCP Console 中開啟 BigQuery 網頁版 UI。
    前往 GCP Console

  2. 在導覽面板的「Resources」(資源) 區段中，展開您的專案並選取資料集。

  3. 在視窗右側的詳細資料面板中，按一下 [Create table] (建立資料表)。載入資料的程序與建立空白資料表的程序相同。

    建立資料表

  4. 在「Create table」(建立資料表) 頁面的「Source」(來源) 專區中：

    • 針對「Create table from」(使用下列資料建立資料表)，選取 [Cloud Storage]。

    • 在「Source」(來源) 欄位中瀏覽或輸入 Cloud Storage URI。請注意，您無法在 GCP Console 中輸入多個 URI，但可以使用萬用字元。Cloud Storage 值區的位置必須與待建立資料表所在的資料集位置相同。

      選取檔案

    • 在「File format」(檔案格式) 中選取 [Parquet]。

  5. 在「Create table」(建立資料表) 頁面的「Destination」(目的地) 區段中：

    • 針對「Dataset name」(資料集名稱)，選擇適當的資料集。

      查看資料集

    • 確認「Table type」(資料表類型) 已設為 [Native table] (原生資料表)。

    • 在「Table name」(資料表名稱) 欄位中，輸入您在 BigQuery 中建立資料表時使用的資料表名稱。

  6. 您不需要調整「Schema」(結構定義) 專區中的任何設定。您可以在 Parquet 檔案中找到結構定義資訊。

  7. (選用) 如要對資料表進行分區，請在「Partition and cluster settings」(分區與叢集設定) 專區中選擇您要使用的選項：

    • 如要建立分區資料表，請按一下 [No partitioning] (無分區)，選取 [Partition by field] (依欄位分區)，然後選擇 DATE 或 TIMESTAMP 資料欄。如果您的結構定義未包含 DATE 或 TIMESTAMP 資料欄，就無法使用這個選項。
    • 如要建立擷取時間分區資料表，請按一下 [No partitioning] (無分區)，然後選取 [Partition by ingestion time] (依擷取時間分區)。

  8. (選用) 針對「Partitioning filter」(分區篩選器)，勾選 [Require partition filter] (需要分區篩選器) 方塊，要求使用者提供 WHERE 子句來指定要查詢的分區。使用分區篩選器可以降低成本並提升成效。詳情請參閱查詢分區資料表一文。如果選取了 [No partitioning] (無分區)，就無法使用這個選項。

  9. (選用) 如要將資料表分群，請在「Clustering order」(分群順序) 方塊中輸入一到四個欄位名稱。分群法目前僅支援分區資料表。

  10. (選用) 按一下 [Advanced options] (進階選項)。

    • 讓「Write preference」(寫入偏好設定) 的 [Write if empty] (空白時寫入) 選項維持在已選取狀態。這個選項能建立新的資料表，並將您的資料載入其中。
    • 針對「Number of errors allowed」(允許的錯誤數量)，接受預設值 0，或輸入可忽略的含錯列數上限。如果含錯的列數超過這個值，該項工作就會導致 invalid 訊息並失敗。
    • 「Unknown values」(不明的值) 部分請取消勾選 [Ignore unknown values] (略過不明的值)。這個選項僅用於 CSV 和 JSON 檔案。
    • 針對「Encryption」(加密)，點選 [Customer-managed key] (客戶管理的金鑰)，以使用 Cloud Key Management Service 金鑰。如果您保留「Google-managed key」(Google 代管的金鑰) 這項設定，則 BigQuery 會加密靜態資料。

  11. 按一下 [Create table] (建立資料表)。

傳統版 UI

  1. 前往 BigQuery 網頁版 UI。
    前往 BigQuery 網頁版 UI

  2. 在導覽面板中，將游標移至特定資料集上，按一下向下箭頭圖示 向下箭號圖示圖片，然後點選 [Create new table]。載入資料的程序與建立空白資料表的程序相同。

  3. 在「Create Table」(建立資料表) 頁面的「Source Data」(來源資料) 區段中：

    • 按一下 [Create from source] (透過來源建立)。
    • 針對「Location」選取 [Cloud Storage]，然後在來源欄位中輸入 Cloud Storage URI。請注意，您無法在 BigQuery 網頁版 UI 中輸入多個 URI，但可以使用萬用字元。Cloud Storage 值區的位置必須與待建立資料表所在的資料集位置相同。
    • 在「File format」(檔案格式) 中選取 [Parquet]。

  4. 在「Destination Table」(目標資料表) 專區中：

    • 針對「Table name」(資料表名稱) 選擇適當的資料集，並在「Table name」(資料表名稱) 欄位中，輸入您在 BigQuery 中建立資料表時使用的資料表名稱。
    • 確認「Table type」(資料表類型) 已設為「Native table」(原生資料表)。

  5. 您不需要調整「Schema」(結構定義) 專區中的任何設定。您可以在 Parquet 檔案中找到結構定義資訊。

  6. (選用) 在「Options」(選項) 專區中：

    • 針對「Number of errors allowed」，接受預設值 0，或輸入可忽略的含錯列數上限。如果含錯的列數超過這個值，該項工作就會導致 invalid 訊息並失敗。
    • 針對 [Write preference] (寫入偏好設定)，請將 [Write if empty] (空白時寫入) 保持為已選取狀態。這個選項能建立新的資料表，並將您的資料載入其中。
    • 如要將資料表分區：
      • 針對「Partitioning Type」(分區類型) 按一下 [None] (無)，接著選擇 [Day] (日)。
      • 針對「Partitioning Field」(分區欄位)：
      • 如要建立分區資料表，請選擇 DATE 或 TIMESTAMP 資料欄。如果您的結構定義未包含 DATE 或 TIMESTAMP 資料欄，就無法使用這個選項。
      • 如要建立擷取時間分區資料表，請保留預設值：_PARTITIONTIME。
      • 勾選 [Require partition filter] 方塊，要求使用者提供 WHERE 子句來指定要查詢的分區。使用分區篩選器可以降低成本並提升成效。詳情請參閱查詢分區資料表一文。如果「Partitioning type」(分區類型) 設為 [None] (無)，就無法使用這個選項。
    • 如要將資料表分群，請在「Clustering fields」方塊中輸入一至四個欄位名稱。
    • 在「Destination encryption」中，按一下 [Customer-managed encryption]，以使用 Cloud Key Management Service 金鑰加密資料表。如果您保留 Default 設定，BigQuery 會使用 Google 代管的金鑰加密靜態資料。

  7. 按一下 [Create Table] (建立資料表)。

CLI

請使用 bq load 指令，然後使用 --source_format 標記指定 PARQUET，再加入 Cloud Storage URI。您可以加入單一 URI、以逗號分隔的 URI 清單，或包含萬用字元的 URI。

(選用) 提供 --location 標記，並將值設為您的位置。

其他選用標記包括：

  • --max_bad_records：這是一個整數，用來指定整個工作失敗前可允許的錯誤記錄數量上限。預設值為 0。無論 --max_bad_records 的值為何，系統最多只會傳回五個任何類型的錯誤。
  • --time_partitioning_type：針對資料表啟用時間分區並設定分區類型。目前唯一可使用的值為 DAY，亦即每天產生一個分區。如果您依據 DATE 或 TIMESTAMP 資料欄建立分區資料表，則不一定要使用這個標記。
  • --time_partitioning_expiration：一個整數，用來指定系統應在經過多少時間後刪除時間分區 (以秒為單位)。到期時間為分區的世界標準時間日期加上整數值。
  • --time_partitioning_field：用來建立分區資料表的 DATE 或 TIMESTAMP 資料欄。如果您在啟用時間分區時未提供這個值，系統就會建立擷取時間分區資料表。
  • --require_partition_filter：如果有啟用，使用者必須提供 WHERE 子句來指定要查詢的分區。使用分區篩選器可以降低成本並提升成效。詳情請參閱查詢分區資料表一文。
  • --clustering_fields：以逗號分隔的資料欄名稱清單 (最多四個名稱)，可用來建立叢集資料表。這個標記只能和分區資料表搭配使用。

  • --destination_kms_key：用來加密資料表資料的 Cloud KMS 金鑰。

    如要進一步瞭解分區資料表，請參閱下列說明文章：

    如要進一步瞭解叢集資料表，請參閱下列說明文章：

    如要進一步瞭解資料表加密作業，請參閱下列說明文章：

如要將 ORC 資料載入至 BigQuery，請輸入下列指令：

bq --location=location load \
--source_format=format \
dataset.table \
path_to_source

在上方的指令中：

  • 「location」是您的位置。--location 是選用標記。舉例來說，如果您在東京地區使用 BigQuery，請將標記的值設為 asia-northeast1。您可以使用 .bigqueryrc 檔案設定位置的預設值。
  • 「format」是 PARQUET。
  • 「dataset」是現有資料集。
  • 「table」是資料表名稱，代表您要載入資料的目的地。
  • 「path_to_source」是完整的 Cloud Storage URI，或是以逗號分隔的 URI 清單。您也可以使用萬用字元。

範例：

下列指令會將 gs://mybucket/mydata.parquet 中的資料載入至 mydataset 中名為「mytable」的資料表。

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

下列指令會將 gs://mybucket/mydata.parquet 中的資料載入至 mydataset 中名為「mytable」的擷取時間分區資料表。

    bq load \
    --source_format=PARQUET \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

下列指令會將 gs://mybucket/mydata.parquet 中的資料載入至 mydataset 中名為「mytable」的分區資料表。資料表會依 mytimestamp 資料欄進行分區。

    bq load \
    --source_format=PARQUET \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

下列指令會將 gs://mybucket/ 中多個檔案的資料載入至 mydataset 中名為 mytable 的資料表。Cloud Storage URI 使用萬用字元。

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata*.parquet

下列指令會將 gs://mybucket/ 中多個檔案的資料載入至 mydataset 中名為 mytable 的資料表。指令包含以逗號分隔且帶有萬用字元的 Cloud Storage URI 清單。

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    "gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"

API

  1. 建立指向 Cloud Storage 中來源資料的 load 工作。

  2. (選用) 在工作資源的 jobReference 區段中，於 location 屬性指定您的位置。

  3. source URIs 屬性必須完整且符合下列格式：gs://bucket/object。每個 URI 可包含一個「*」萬用字元。

  4. 將 sourceFormat 屬性設為 PARQUET 來指定 Parquet 資料格式。

  5. 如要檢查工作狀態，請呼叫 jobs.get(job_id*)，其中 job_id 是初始要求傳回的工作 ID。

    • 如果出現 status.state = DONE，表示工作已順利完成。
    • 如果出現 status.errorResult 屬性，表示要求失敗，且該物件會包含描述問題的資訊。如果要求失敗，系統就不會建立任何資料表，也不會載入任何資料。
    • 如果未出現 status.errorResult，表示工作順利完成，但可能有一些不嚴重的錯誤，例如匯入一些資料列時發生問題。不嚴重的錯誤會列在傳回工作物件的 status.errors 屬性中。

API 注意事項：

  • 載入工作不可部分完成，且資料狀態具一致性。如果載入工作失敗，所有資料都無法使用；如果載入工作成功，則所有資料都可以使用。

  • 最佳做法是產生唯一識別碼，並在呼叫 jobs.insert 以建立載入工作時，將該識別碼當做 jobReference.jobId 傳送。這個方法較不受網路故障問題的影響，因為用戶端可對已知的工作 ID 進行輪詢或重試。

  • 對指定的工作 ID 呼叫 jobs.insert 是一種冪等運算。您可以對同一組工作 ID 重試無數次，最多會有一次作業成功。

Go

在試行這個範例之前，請按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Go 相關設定指示操作。詳情請參閱 BigQuery Go API 參考說明文件。 

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.parquet")
gcsRef.SourceFormat = bigquery.Parquet
gcsRef.AutoDetect = true
loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)

job, err := loader.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}

if status.Err() != nil {
	return fmt.Errorf("Job completed with error: %v", status.Err())
}

Java

在試行這個範例之前，請按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Java 相關設定指示操作。詳情請參閱 BigQuery Java API 參考說明文件。 

String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
TableId tableId = TableId.of(datasetName, "us_states");
LoadJobConfiguration configuration =
        LoadJobConfiguration.builder(tableId, sourceUri)
                .setFormatOptions(FormatOptions.parquet())
                .build();
// Load the table
Job loadJob = bigquery.create(JobInfo.of(configuration));
loadJob = loadJob.waitFor();
// Check the table
StandardTableDefinition destinationTable = bigquery.getTable(tableId).getDefinition();
System.out.println("State: " + loadJob.getStatus().getState());
System.out.printf("Loaded %d rows.\n", destinationTable.getNumRows());

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');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the Parquet file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.parquet
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

async function loadTableGCSParquet() {
  // Imports a GCS file into a table with Parquet source format.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'PARQUET',
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // 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;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET');
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

在嘗試此範例之前，請至 BigQuery 快速入門導覽課程：使用用戶端程式庫，按照 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。

使用 Client.load_table_from_uri() 方法，從 Cloud Storage 啟動載入工作。如要使用 Parquet，請將 LoadJobConfig.source_format 屬性設為 SourceFormat 常數 PARQUET，並將工作設定當做 job_config 引數傳送至 load_table_from_uri() 方法。

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.source_format = bigquery.SourceFormat.PARQUET
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"

load_job = client.load_table_from_uri(
    uri, dataset_ref.table("us_states"), job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(dataset_ref.table("us_states"))
print("Loaded {} rows.".format(destination_table.num_rows))

使用 Parquet 資料附加到資料表或覆寫資料表

如要將其他資料載入資料表，您可以指定來源檔案或附加查詢結果。

在主控台及傳統版 BigQuery 網頁版 UI 中，使用 [Write preference] (寫入偏好設定) 選項，指定從來源檔案或從查詢結果載入資料時採取的動作。

將額外資料載入資料表時，可以選擇下列選項：

主控台選項 傳統網頁版 UI 選項 CLI 標記 BigQuery API 屬性 說明
空白時寫入 空白時寫入 無 WRITE_EMPTY 資料表空白時才會寫入資料。
附加至資料表 附加至資料表 --noreplace 或 --replace=false。如果您未指定 --[no]replace，則預設動作為附加 WRITE_APPEND (預設值) 將資料附加至資料表尾端。
覆寫資料表 覆寫資料表 --replace 或 --replace=true WRITE_TRUNCATE 清除資料表中所有現有資料後再寫入新的資料。

如果您將資料載入至現有資料表，該載入工作可能會附加資料或覆寫資料表。

您可以透過下列方式附加或覆寫資料表：

  • 使用 GCP Console 或傳統網頁版 UI
  • 使用 CLI 的 bq load 指令
  • 呼叫 jobs.insert API 方法並設定 load 工作
  • 使用用戶端程式庫

如要使用 Parquet 資料附加或覆寫資料表，請按照下列指示操作：

主控台

  1. 在 GCP Console 中開啟 BigQuery 網頁版 UI。
    前往 GCP Console

  2. 在導覽面板的「Resources」(資源) 區段中，展開您的專案並選取資料集。

  3. 在視窗右側的詳細資料面板中，按一下 [Create table] (建立資料表)。附加和覆寫資料的程序與在載入工作中建立資料表的程序相同。

    建立資料表

  4. 在「Create table」(建立資料表) 頁面的「Source」(來源) 區段中：

    • 針對「Create table from」(使用下列資料建立資料表)，選取 [Cloud Storage]。

    • 在「Source」(來源) 欄位中瀏覽或輸入 Cloud Storage URI。請注意，您無法在 BigQuery 網頁版 UI 中輸入多個 URI，但可以使用萬用字元。Cloud Storage 值區的位置必須與待附加或待覆寫資料表所在的資料集位置相同。

      選取檔案

    • 在「File format」(檔案格式) 中選取 [Parquet]。

  5. 在「Create table」(建立資料表) 頁面的「Destination」(目的地) 區段中：

    • 針對「Dataset name」(資料集名稱)，選擇適當的資料集。

      選取資料集

    • 在「Table name」(資料表名稱) 欄位中，輸入您在 BigQuery 中附加或覆寫資料表時使用的名稱。

    • 確認「Table type」(資料表類型) 已設為「Native table」(原生資料表)。

  6. 您不需要調整「Schema」(結構定義) 專區中的任何設定。您可以在 Parquet 檔案中找到結構定義資訊。

  7. 保留「Partition and cluster settings」(分區與叢集設定) 中的預設值。您無法藉由附加或覆寫的方式，將資料表轉換為分區資料表或叢集資料表；GCP Console 不支援在載入工作中對分區或叢集資料表執行附加或覆寫作業。

  8. 按一下 [Advanced options] (進階選項)。

    • 針對「Write preference」(寫入偏好設定)，選擇 [Append to table] (附加到資料表中) 或 [Overwrite table] (覆寫資料表)。
    • 針對「Number of errors allowed」(允許的錯誤數量)，接受預設值 0，或輸入可忽略的含錯列數上限。如果含錯的列數超過這個值，該項工作就會導致 invalid 訊息並失敗。
    • 「Unknown values」(不明的值) 部分請取消勾選 [Ignore unknown values] (略過不明的值)。這個選項僅用於 CSV 和 JSON 檔案。

    • 針對「Encryption」(加密)，點選 [Customer-managed key] (客戶管理的金鑰)，以使用 Cloud Key Management Service 金鑰。如果您保留「Google-managed key」(Google 代管的金鑰) 這項設定，則 BigQuery 會加密靜態資料。

      覆寫資料表

  9. 按一下 [Create table] (建立資料表)。

傳統版 UI

  1. 前往 BigQuery 網頁版 UI。
    前往 BigQuery 網頁版 UI

  2. 在導覽面板中，將游標移至特定資料集上，按一下向下箭頭圖示 向下箭號圖示圖片，然後點選 [Create new table]。載入工作中的附加和覆寫資料程序與載入工作中建立資料表的程序相同。

  3. 在「Create Table」(建立資料表) 頁面的「Source Data」(來源資料) 區段中：

    • 針對「Location」選取 [Cloud Storage]，然後在來源欄位中輸入 Cloud Storage URI。請注意，您無法在 UI 中輸入多個 URI，但可以使用萬用字元。Cloud Storage 值區的位置必須與待附加或待覆寫資料表所在的資料集位置相同。
    • 在「File format」(檔案格式) 中選取 [Parquet]。

  4. 在「Create Table」(建立資料表) 頁面的「Destination Table」(目標資料表) 專區中：

    • 針對「Table name」(資料表名稱) 選擇適當的資料集，並在「Table name」(資料表名稱) 欄位中，輸入要附加或覆寫的資料表名稱。
    • 確認「Table type」(資料表類型) 已設為「Native table」(原生資料表)。

  5. 您不需要調整「Schema」(結構定義) 專區中的任何設定。您可以在 Parquet 檔案中找到結構定義資訊。

  6. 在「Options」(選項) 區段中：

    • 針對「Number of errors allowed」，接受預設值 0，或輸入可忽略的含錯列數上限。如果含錯的列數超過這個值，該項工作就會導致 invalid 訊息並失敗。
    • 針對「Write preference」(寫入偏好設定)，選擇 [Append to table] (附加到資料表中) 或 [Overwrite table] (覆寫資料表)。
    • 「Partitioning Type」(分區類型)、「Partitioning Field」(分區欄位)、「Require partition filter」(需要分區篩選器) 和「Clustering fields」(分群欄位) 等，請保留預設值。您無法藉由附加或覆寫的方式，將資料表轉換為分區資料表或叢集資料表；網頁版 UI 不支援在載入工作中對分區或叢集資料表執行附加或覆寫作業。
    • 在「Destination encryption」中，按一下 [Customer-managed encryption]，以使用 Cloud Key Management Service 金鑰加密資料表。如果您保留 Default 設定，BigQuery 會使用 Google 代管的金鑰加密靜態資料。

  7. 按一下 [Create Table] (建立資料表)。

CLI

輸入 bq load 指令並搭配使用 --replace 標記覆寫資料表。使用 --noreplace 標記將資料附加至資料表。如果您未指定任何標記，則預設動作為附加資料。提供 --source_format 標記並設為 PARQUET。系統會自動從自述來源資料中擷取 Parquet 結構定義，因此您不需要提供結構定義。

(選用) 提供 --location 標記，並將值設為您的位置。

其他選用標記包括：

  • --max_bad_records：這是一個整數，用來指定整個工作失敗前可允許的錯誤記錄數量上限。預設值為 0。無論 --max_bad_records 的值為何，系統最多只會傳回五個任何類型的錯誤。
  • --destination_kms_key：用來加密資料表資料的 Cloud KMS 金鑰。
bq --location=location load \
--[no]replace \
--source_format=format \
dataset.table \
path_to_source

其中：

  • 「location」是您的位置，--location 是選用標記。您可以使用 .bigqueryrc 檔案來設定位置的預設值。
  • 「format」是 PARQUET。
  • 「dataset」是現有資料集。
  • 「table」是資料表名稱，代表您要載入資料的目的地。
  • 「path_to_source」是完整的 Cloud Storage URI，或是以逗號分隔的 URI 清單。您也可以使用萬用字元。

範例：

下列指令會載入 gs://mybucket/mydata.parquet 中的資料，並覆寫 mydataset 中名為「mytable」的資料表。

    bq load \
    --replace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

下列指令會載入 gs://mybucket/mydata.parquet 中的資料，並將資料附加至 mydataset 中名為「mytable」的資料表。

    bq load \
    --noreplace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

如要進一步瞭解如何使用 CLI 附加及覆寫分區資料表，請參閱：對分區資料表中的資料執行附加或覆寫操作。

API

  1. 建立指向 Cloud Storage 中來源資料的 load 工作。

  2. (選用) 在工作資源的 jobReference 區段中，於 location 屬性指定您的位置。

  3. source URIs 屬性必須完整且符合下列格式：gs://bucket/object。您可以使用逗號分隔清單的形式包含多個 URI。不過請注意，您也可以使用萬用字元。

  4. 將 configuration.load.sourceFormat 屬性設為 PARQUET 來指定資料格式。

  5. 將 configuration.load.writeDisposition 屬性設為 WRITE_TRUNCATE 或 WRITE_APPEND 來指定寫入偏好設定。

Go

在試行這個範例之前，請按照 BigQuery 快速入門導覽課程：使用用戶端程式庫中的 Go 相關設定指示操作。詳情請參閱 BigQuery Go API 參考說明文件。 

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.parquet")
gcsRef.SourceFormat = bigquery.Parquet
gcsRef.AutoDetect = true
loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
loader.WriteDisposition = bigquery.WriteTruncate

job, err := loader.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}

if status.Err() != nil {
	return fmt.Errorf("Job completed with error: %v", status.Err())
}

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');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

async function loadParquetFromGCSTruncate() {
  /**
   * Imports a GCS file into a table and overwrites
   * table data if table already exists.
   */

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'PARQUET',
    // Set the write disposition to overwrite existing table data.
    writeDisposition: 'WRITE_TRUNCATE',
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);
  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // 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;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableID = 'The BigQuery table ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET')->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});

// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

在嘗試此範例之前，請至 BigQuery 快速入門導覽課程：使用用戶端程式庫，按照 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。

如要取代現有資料表中的資料列，請將 LoadJobConfig.write_disposition 屬性設為 WriteDisposition 常數 WRITE_TRUNCATE。

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
job_config.source_format = bigquery.SourceFormat.PARQUET
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"
load_job = client.load_table_from_uri(
    uri, table_ref, job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(table_ref)
print("Loaded {} rows.".format(destination_table.num_rows))

Parquet 轉換

BigQuery 會將 Parquet 資料類型轉換為下列 BigQuery 資料類型：

類型轉換

Parquet 類型 Parquet 轉換類型 BigQuery 資料類型
BOOLEAN NONE Boolean
INT32 NONE、UINT_8、UINT_16、UINT_32、INT_8、INT_16、INT_32 Integer
INT32 DECIMAL (請參閱 DECIMAL 註解) Numeric
INT32 DATE Date
INT64 NONE、UINT_64、INT_64 Integer
INT64 DECIMAL (請參閱 DECIMAL 註解) Numeric
INT64 TIMESTAMP_MILLIS Timestamp
INT64 TIMESTAMP_MICROS Timestamp
INT96 NONE Timestamp
FLOAT NONE Floating point
DOUBLE NONE Floating point
BYTE_ARRAY NONE Bytes
BYTE_ARRAY UTF8 String
FIXED_LEN_BYTE_ARRAY DECIMAL (請參閱 DECIMAL 註解) Numeric
FIXED_LEN_BYTE_ARRAY NONE Bytes

系統不支援其他 Parquet 類型與轉換類型的組合。

Decimal 註解

附有 DECIMAL 註解的 Parquet 類型準確度最高可達 38 (總位數)，且小數位數最多可以是 9 (小數點右邊的位數)。整數位數 (即總位數減去小數位數) 最多可以是 29。例如，系統支援 DECIMAL(38, 9)，因為總位數是 38 而小數位數是 9 (在本例中，整數位數的值是 29)。系統不支援 DECIMAL(38, 5)，因為總位數是 38 而小數位數是 5 (在本例中，整數位數的值是 33)。

資料欄名稱轉換

資料欄名稱僅可包含字母 (a-z、A-Z)、數字 (0-9) 或底線 (_)，且必須以字母或底線作為開頭。資料欄名稱的長度上限為 128 個字元。資料欄名稱不得使用以下任何一個前置字元：

  • _TABLE_
  • _FILE_
  • _PARTITION

資料欄名稱不得重複，即便其情況不同也是如此。例如，名為 Column1 的資料欄名稱會被視為與名為 column1 的資料欄相同。

就目前而言，您無法載入資料欄名稱帶有句號 (.) 之資料欄的 Parquet 檔案。

如果 Parquet 資料欄名稱包含其他字元 (句號除外)，則會以底線取代這些字元。可在資料欄名稱的結尾處加上底線以避免發生衝突。舉例來說，假設 Parquet 檔案中包含 Column1 與 column1 這 2 個資料欄，資料欄會分別以 Column1 和 column1_ 的形式載入。

本頁內容對您是否有任何幫助？請提供意見：

傳送您對下列選項的寶貴意見...

這個網頁
文件意見
BigQuery
產品意見
需要協助嗎？請前往我們的支援網頁。