從 Cloud Storage 載入 ORC 資料

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

ORC 是 Apache Hadoop 生態系統廣泛使用的開放原始碼欄導向式資料格式。

從 Cloud Storage 載入 ORC 資料時,可將資料載入至新的資料表或分區,或將資料附加到現有資料表或分區,或覆寫現有資料表或分區。資料載入 BigQuery 後,會轉換為 Capacitor 列表型格式 (BigQuery 的儲存格式)。

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

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

ORC 結構定義

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

舉例來說,Cloud Storage 中有下列 ORC 檔案:

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

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

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

當 BigQuery 偵測到結構定義時,部分 ORC 資料類型會轉換為 BigQuery 資料類型,確保與 BigQuery SQL 語法相容。在偵測到的結構定義中,所有欄位均為 NULLABLE。詳情請參閱 ORC 轉換一節。

載入具有不同結構定義的多個 ORC 檔案時,多個結構定義中所指定的相同欄位 (具有相同名稱與相同巢狀層級) 必須對應至各個結構定義中相同的已轉換 BigQuery 資料類型。

ORC 壓縮

壓縮的 ORC 檔案未受支援,但壓縮的頁尾和等量區有。支援的壓縮類型有 Zlib、Snappy、LZO 與 LZ4。

所需權限

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

BigQuery 權限

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

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

以下是具有 bigquery.tables.createbigquery.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.getstorage.objects.list 權限。

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

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

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

如要將 ORC 資料從 Google 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」(檔案格式) 部分選取 [ORC]

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

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

      查看資料集

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

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

  6. 在「Schema」(結構定義) 區段中,無需採取任何行動。結構定義自述於 ORC 檔案中。

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

    • 如要建立分區資料表,請按一下 [No partitioning] (無分區),選取 [Partition by field] (依欄位分區),然後選擇 DATETIMESTAMP 資料欄。如果您的結構定義未包含 DATETIMESTAMP 資料欄,就無法使用這個選項。
    • 如要建立擷取時間分區資料表,請按一下 [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],然後在「Source」(來源) 欄位中輸入 Cloud Storage URI。請注意,您無法在 BigQuery 網頁版 UI 中輸入多個 URI,但可以使用萬用字元。Cloud Storage 值區的位置必須與要建立的資料表所在的資料集位置相同。
    • 在「File format」(檔案格式) 部分選取 [ORC]
  4. 在「Destination Table」(目的地資料表) 區段中:

    • 針對「Table name」(資料表名稱) 選擇適當的資料集,並在「Table name」(資料表名稱) 欄位中,輸入您在 BigQuery 中建立資料表時使用的資料表名稱。
    • 確認「Table type」(資料表類型) 已設為「Native table」(原生資料表)
  5. 在「Schema」(結構定義) 區段中,無需採取任何行動。結構定義自述於 ORC 檔案中。

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

    • 針對「Number of errors allowed」(允許的錯誤數量),接受預設值 0,或輸入可忽略的含錯列數上限。如果含錯的列數超過這個值,該項工作就會導致 invalid 訊息並失敗。
    • 讓「Write preference」(寫入偏好設定) 的 [Write if empty] (空白時寫入) 選項維持在已選取狀態。這個選項能建立新的資料表,並將您的資料載入其中。
    • 如要將資料表分區:
      • 針對「Partitioning Type」(分區類型) 按一下 [None] (無),接著選擇 [Day] (日)
      • 針對「Partitioning Field」(分區欄位)
      • 如要建立分區資料表,請選擇 DATETIMESTAMP 資料欄。如果您的結構定義未包含 DATETIMESTAMP 資料欄,就無法使用這個選項。
      • 如要建立擷取時間分區資料表,請保留預設值:_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 指令將 ORC 指定為 source_format,並納入 Cloud Storage URI。您可以納入單一 URI、以逗號分隔的 URI 清單,或含有萬用字元的 URI。

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

其他選用標記包括:

  • --max_bad_records:這是一個整數,用來指定整個工作失敗前可允許的錯誤記錄數量上限。預設值為 0。無論 --max_bad_records 的值為何,系統最多只會傳回五個任何類型的錯誤。
  • --time_partitioning_type:針對資料表啟用時間分區並設定分區類型。目前唯一可使用的值為 DAY,亦即每天產生一個分區。如果您依據 DATETIMESTAMP 資料欄建立分區資料表,則不一定要使用這個標記。
  • --time_partitioning_expiration:一個整數,用來指定系統應在經過多少時間後刪除時間分區 (以秒為單位)。到期時間為分區的世界標準時間日期加上整數值。
  • --time_partitioning_field:用來建立分區資料表DATETIMESTAMP 資料欄。如果您在啟用時間分區時未提供這個值,系統就會建立擷取時間分區資料表
  • --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」ORC
  • 「dataset」是現有資料集。
  • 「table」是資料表名稱,代表您要載入資料的目的地。
  • 「path_to_source」是完整的 Cloud Storage URI,或是以逗號分隔的 URI 清單。您也可以使用萬用字元

範例:

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

    bq load \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

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

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

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

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

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

    bq load \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata*.orc

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

    bq load --autodetect \
    --source_format=ORC \
    mydataset.mytable \
    "gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"

API

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

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

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

  4. sourceFormat 屬性設為 ORC,以指定 ORC 資料格式。

  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 重試無數次,最多會有一個作業成功。

C#

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 C# 設定說明進行操作。詳情請參閱 BigQuery C# API 參考說明文件


using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsOrc
{
    public void LoadTableGcsOrc(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null,
            options: jobOptions
        );
        loadJob.PollUntilCompleted();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

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.orc")
gcsRef.SourceFormat = bigquery.ORC
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())
}

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 ORC file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.orc
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.orc';

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

  /**
   * TODO(developer): Uncomment the following line 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: 'ORC',
    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.orc';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC');
$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 參考說明文件

# 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.ORC
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

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

Ruby

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

require "google/cloud/bigquery"

def load_table_gcs_orc dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, format: "orc"
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done!  # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table(table_id)
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

將 ORC 資料附加到資料表或使用 ORC 資料覆寫資料表

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

在主控台及傳統版 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 工作
  • 使用用戶端程式庫

使用 ORC 資料附加或覆寫資料表的方式如下:

主控台

  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」(檔案格式) 部分選取 [ORC]

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

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

      選取資料集

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

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

  6. 在「Schema」(結構定義) 區段中,無需採取任何行動。結構定義自述於 ORC 檔案中。

  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],然後在「Source」(來源) 欄位中輸入 Cloud Storage URI。請注意,您無法在 UI 中輸入多個 URI,但可以使用萬用字元。Cloud Storage 值區的位置必須與您要附加或覆寫的資料表所在的資料集位置相同。
    • 在「File format」(檔案格式) 部分選取 [ORC]
  4. 在「Create Table」(建立資料表) 頁面的「Destination Table」(目的地資料表) 區段中:

    • 針對「Table name」(資料表名稱) 選擇適當的資料集,並在「Table name」(資料表名稱) 欄位中,輸入要附加或覆寫的資料表名稱。
    • 確認「Table type」(資料表類型) 已設為「Native table」(原生資料表)
  5. 在「Schema」(結構定義) 區段中,無需採取任何行動。結構定義資訊自述於 ORC 檔案中。

  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 標記並將其設為 ORC。由於系統會自動從自述來源資料中擷取 ORC 結構定義,所以您不需要提供結構定義。

(選用) 提供 --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」ORC
  • 「dataset」是現有資料集。
  • 「table」是資料表名稱,代表您要載入資料的目的地。
  • 「path_to_source」是完整的 Cloud Storage URI,或是以逗號分隔的 URI 清單。您也可以使用萬用字元

範例:

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

    bq load \
    --replace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

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

    bq load \
    --noreplace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

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

API

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

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

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

  4. configuration.load.sourceFormat 屬性設為 ORC,以指定資料格式。

  5. configuration.load.writeDisposition 屬性設為 WRITE_TRUNCATEWRITE_APPEND,以指定寫入偏好設定。

C#

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 C# 設定說明進行操作。詳情請參閱 BigQuery C# API 參考說明文件


using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsOrcTruncate
{
    public void LoadTableGcsOrcTruncate(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc,
            WriteDisposition = WriteDisposition.WriteTruncate
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null, options: jobOptions);
        loadJob.PollUntilCompleted();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

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.orc")
gcsRef.SourceFormat = bigquery.ORC
loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
// Default for import jobs is to append data to a table.  WriteTruncate
// specifies that existing data should instead be replaced/overwritten.
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 the 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.orc';

async function loadORCFromGCSTruncate() {
  /**
   * 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: 'ORC',
    // 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.orc';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC')->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 屬性設為 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.ORC
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"
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))

Ruby

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

require "google/cloud/bigquery"

def load_table_gcs_orc_truncate(
    dataset_id = "your_dataset_id",
    table_id   = "your_table_id"
  )
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

  load_job = dataset.load_job table_id,
                              gcs_uri,
                              format: "orc",
                              write:  "truncate"
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done!  # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table(table_id)
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

ORC 轉換

BigQuery 會將 ORC 資料類型轉換為下列 BigQuery 資料類型:

原始類型

ORC 資料類型 BigQuery 資料類型 附註
boolean BOOLEAN
byte INTEGER
short INTEGER
int INTEGER
long INTEGER
float FLOAT
double FLOAT
string STRING 僅限 UTF-8
varchar STRING 僅限 UTF-8
char STRING 僅限 UTF-8
binary BYTES
date DATE
timestamp TIMESTAMP ORC 支援奈秒精確度,但系統讀取資料時,BigQuery 會將小於微秒的值轉換為微秒。
decimal NUMERIC 或 STRING NUMERIC 類型為總位數 38 位數及小數位數 9 位數的精確數值。詳情請參閱 NUMERIC 類型。如果 ORC 結構定義中 decimal 類型的小數位數不超過 9 位數,且總位數 (包含小數位數) 不超過 29 位數,系統會將其轉換為 NUMERIC,否則會轉換為 STRING。若 decimal 類型轉換為 STRING,系統將傳回警告訊息。

複合類型

ORC 資料類型 BigQuery 資料類型 附註
struct RECORD
  • 所有欄位均為 NULLABLE。
  • 系統會忽略欄位順序。
  • 欄位名稱必須為有效的欄名稱
map<K,V> RECORD ORC map<K,V> 欄位會轉換為重複的 RECORD,其中包含兩個欄位:相同資料類型的鍵為 K,以及相同資料類型的值為 V。這兩個欄位都是 NULLABLE。
list 重複欄位 不支援巢狀清單與對應清單。
union RECORD
  • 當 union 只有一個變因時,系統會將其轉換為 NULLABLE 欄位。
  • 否則,會將 union 轉換為含有 NULLABLE 欄位清單的 RECORD。NULLABLE 欄位的後置字串為 field_0、field_1,依此類推。系統讀取資料時,只會為其中一個欄位指派值。

欄名稱

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

  • _TABLE_
  • _FILE_
  • _PARTITION

資料欄名稱不得重複,即便其情況不同也是如此。舉例來說,系統會將名為 Column1 的欄視為與 column1 欄的名稱相同。

NULL

請注意,目前 BigQuery 會忽略 list 複合類型的 NULL 元素。

如要進一步瞭解 ORC 資料類型,請參閱 Apache ORC™ 規格 v1

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

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

這個網頁
需要協助嗎?請前往我們的支援網頁