從 Cloud Storage 載入 Avro 資料

從 Cloud Storage 載入 Avro 檔案

Avro 是將序列化資料與資料結構定義結合於相同檔案的開放原始碼資料格式。

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

將資料從 Cloud Storage 載入 BigQuery 資料表時，該資料表所屬資料集必須位於和 Cloud Storage 值區相同的地區或多地區位置。

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

Avro 的優勢

Avro 是將資料載入至 BigQuery 的偏好格式。相較於 CSV 與 JSON (以換行符號分隔)，載入 Avro 檔案有以下優勢：

  • Avro 二進位格式：
    • 載入較快。即便資料區塊經過壓縮，還是能夠平行讀取。
    • 無需任何輸入或序列化作業。
    • 沒有 ASCII 等其他格式會有的編碼問題，所以剖析較容易。
  • 將 Avro 檔案載入 BigQuery 時，會從自述式來源資料自動擷取資料表結構定義。

Avro 結構定義

將 Avro 檔案載入 BigQuery 時，會使用來源資料自動擷取資料表結構定義。當 BigQuery 從來源資料擷取結構定義時，會按字母順序使用最後一個檔案。

舉例來說，Cloud Storage 中有下列 Avro 檔案：

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

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

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

匯入擁有不同 Avro 結構定義的多個 Avro 檔案時，所有結構定義都必須與 Avro 的結構定義解析相容。

當 BigQuery 偵測到結構定義時，部分 Avro 資料類型會轉換為 BigQuery 資料類型，確保與 BigQuery SQL 語法相容。如需更多資訊，請參閱 Avro 轉換。

Avro 壓縮

系統不支援壓縮的 Avro 檔案，但支援壓縮的資料區塊。 BigQuery 支援 DEFLATE 與 Snappy 轉碼器。

所需權限

將資料載入 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 權限。

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

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

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

如要將 Avro 資料從 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」(檔案格式) 中，選取 [Avro]。

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

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

      查看資料集

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

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

  6. 在「Schema」(結構定義) 區段中，不必執行任何操作。結構定義自述於 Avro 檔案中。

  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]，然後在「Source」(來源) 欄位中輸入 Cloud Storage URI。請注意，您無法在 BigQuery 網頁版 UI 中輸入多個 URI，但可以使用萬用字元。建立資料表時，Cloud Storage 值區的位置必須和資料表所在的資料集位置相同。
    • 在「File format」(檔案格式) 中，選取 [Avro]。

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

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

  5. 在「Schema」(結構定義) 區段中，不必執行任何操作。結構定義自述於 Avro 檔案中。

  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 標記指定 AVRO，並加入 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 金鑰。

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

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

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

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

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

其中：

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

範例：

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

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

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

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

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

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

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

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata*.avro

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

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

API

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

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

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

  4. 將 sourceFormat 屬性設為 AVRO，指定 Avro 資料格式。

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

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

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

將 Avro 資料附加或覆寫至資料表

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

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

如要使用 Avro 資料附加或覆寫資料表：

主控台

  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」(檔案格式) 中，選取 [Avro]。

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

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

      選取資料集

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

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

  6. 在「Schema」(結構定義) 區段中，不必執行任何操作。結構定義自述於 Avro 檔案中。

  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」(檔案格式) 中，選取 [Avro]。

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

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

  5. 在「Schema」(結構定義) 區段中，不必執行任何操作。結構定義資訊自述於 Avro 檔案中。

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

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

範例：

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

    bq load \
    --replace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

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

    bq load \
    --noreplace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

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

API

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

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

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

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

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

Python

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

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

Avro 轉換

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

原始類型

Avro 資料類型 BigQuery 資料類型 附註
null BigQuery 會略過這些值
boolean BOOLEAN
int INTEGER
long INTEGER
float FLOAT
double FLOAT
bytes BYTES
含有 decimal 邏輯類型的 bytes NUMERIC
string STRING 僅限 UTF-8

複合類型

Avro 資料類型 BigQuery 資料類型 附註
record RECORD
  • 別名會被略過
  • Doc 會轉換為欄位說明
  • 在讀取時間設定預設值
  • 順序會被略過
  • 會捨棄遞迴欄位 — 僅為遞迴欄位保留第一個巢狀層級
enum STRING
  • 字串為 enum 的符號值
  • 別名會被略過
  • Doc 會轉換為欄位說明
array 重複欄位 不支援陣列的陣列。只包含 NULL 類型的陣列會被略過。
map<T> RECORD BigQuery 會將 Avro map<T> 欄位轉換為包含兩個欄位 (鍵與值) 的重複 RECORD。BigQuery 會將鍵儲存為 STRING，並將其值轉換為 BigQuery 中相對應的資料類型。
union
  • 可為 null 的欄位
  • 清單欄位可為 null 的 RECORD
  • 當 union 僅有一個非 null 類型時，會轉換為可為 null 的欄位。
  • 否則會轉換為清單欄位可為 null 的 RECORD。這些欄位只有其中一個會在讀取時間設定。
fixed BYTES
  • 別名會被略過
  • 大小會被略過

邏輯類型

預設情況下，BigQuery 會忽略 logicalType 屬性並改用基本 Avro 類型。

Avro 邏輯類型 BigQuery 資料類型
date INTEGER
time-millis INTEGER
time-micros INTEGER (從 LONG 轉換)
timestamp-millis INTEGER (從 LONG 轉換)
timestamp-micros INTEGER (從 LONG 轉換)
duration BYTES (從大小為 12 的 fixed 類型轉換)
decimal NUMERIC (請參閱 Decimal 邏輯類型一節)

為了讓 Avro 邏輯類型能夠轉換成對應的 BigQuery 資料類型，請使用指令列工具將 --use_avro_logical_types 標記設為 True，或在呼叫 jobs.insert 方法建立載入工作時，於工作資源中設定 useAvroLogicalTypes 屬性。

下表顯示 Avro 邏輯類型到 BigQuery 資料類型的轉換。

Avro 邏輯類型 轉換後的 BigQuery 資料類型
date DATE
time-millis TIME
time-micros TIME
timestamp-millis TIMESTAMP
timestamp-micros TIMESTAMP
duration BYTES (從大小為 12 的 fixed 類型轉換)
decimal NUMERIC (請參閱 Decimal 邏輯類型一節)

如需進一步瞭解 Avro 資料類型，請參閱 Apache Avro™ 1.8.2 規格。

Decimal 邏輯類型

含有 decimal 邏輯類型的 Avro bytes 類型最多可將 precision 設為 38 (總位數)，且 scale 最多可設為 9 (小數點右邊的位數)。整數位數 (即 precision 減去 scale) 最多可以是 29。例如，系統支援 precision 為 38 且 scale 為 9 的 decimal，因為整數位數為 29；但系統不支援 precision 為 38 且 scale 為 5 的 decimal，因為整數位數為 33。

當您將 bytes 資料欄中含有 decimal 邏輯類型的 Avro 檔案載入現有的資料表時，這個資料欄的資料類型在資料表的結構定義中可能是 BYTES 或 NUMERIC。如果資料欄的資料類型是 BYTES，則系統會忽略 Avro 檔案中資料欄的 decimal 邏輯類型。

如要進一步瞭解 Avro decimal 邏輯類型，請參閱 Apache Avro™ 1.8.2 規格。

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

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

這個網頁
文件意見
BigQuery
產品意見