從 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 時，會從自述式來源資料自動擷取資料表結構定義。

所需權限

如果您要將資料載入至 BigQuery，您必須擁有專案或資料集層級的權限，才能將資料載入至新的或現有的 BigQuery 資料表與分區。如果是從 Cloud Storage 載入檔案，您還需要擁有包含您的資料的值區存取權。

BigQuery 權限

如果您要將資料從 Cloud Storage 載入至 BigQuery，您必須獲得專案層級或資料集層級的 bigquery.dataOwner 或 bigquery.dataEditor 角色授權。這兩種角色授予使用者與群組將資料載入至新資料表或將資料附加至現有資料表或覆寫現有資料表的權限。

授予專案層級的角色可讓使用者或群組有權將資料載入至專案中任何資料集的資料表。授予資料集層級的角色可讓使用者或群組只能將資料載入至該資料集的資料表。

如需設定資料集存取權的詳細資訊，請參閱控管資料集存取權。如要進一步瞭解 BigQuery 中的身分與存取權管理 (IAM) 角色，請參閱存取權控管。

Cloud Storage 權限

若要從 Cloud Storage 值區載入資料，您必須被授予專案層級的 storage.objects.get 授權或該個別值區的授權。如要使用 URI 萬用字元，您也必須擁有 storage.objects.list 權限。

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

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 --location=US load --source_format=AVRO [DATASET].[TABLE_NAME] "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

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

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

Avro 壓縮

壓縮的 Avro 檔案未受支援，但壓縮的資料區塊有。 BigQuery 支援 DEFLATE 與 Snappy 轉碼器。

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

如何將 Avro 資料從 Cloud Storage 載入至新的 BigQuery 表格，或將 Avro 資料附加至現有資料表：

主控台

  1. 在 GCP 主控台中開啟 BigQuery 網頁版 UI。
    前往 BigQuery 網頁版 UI

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

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

    建立資料表

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

    • 在「Create table from」(使用下列資料建立資料表) 區段，選取您要採用的來源類型。

      建立資料表來源

    • 在「Source」(來源) 欄位中，瀏覽檔案/Cloud Storage 值區，或輸入 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. 按一下 [Create table] (建立資料表)。

傳統版 UI

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

  2. 在導覽面板中，將滑鼠游標懸停在某個資料集上，按一下向下箭頭圖示 向下箭號圖示圖片，然後點選 [Create new table] (建立新資料表)。載入資料的程序與建立空白資料表的程序相同。

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

    • 在「Location」(位置) 中，選取 [Cloud Storage]，然後在「Source」(來源) 欄位輸入 Cloud Storage URI。請注意，您無法在 BigQuery 網頁版 UI 中輸入多個 URI，但可以使用萬用字元。Cloud Storage 值區的位置必須與要建立的資料表所在的資料集位置相同。
    • 在「File format」中，選取 [Avro]。

  4. 在「Create Table」頁面的「Destination Table」區段中：

    • 在「Table name」(表格名稱) 部分選擇適當的資料集，然後在表格名稱欄位中，輸入要在 BigQuery 中建立的表格名稱。
    • 確認「Table type」(資料表類型) 設為 [Native table] (原生資料表)。

  5. 在「Schema」區段中，無需採取任何行動。結構定義是透過 Avro 檔案推測得出。

  6. 按一下 [Create Table]。

指令列

使用 bq load 指令將 AVRO 指定為 source_format，並加入 Cloud Storage URI。您可以加入單一 URI、以逗號分隔的 URI 清單或含有萬用字元的 URI。

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

bq --location=[LOCATION] load --source_format=[FORMAT] [DATASET].[TABLE] [PATH_TO_SOURCE]

其中：

  • [LOCATION] 是您的位置。如果您的資料位於 US 或 EU 多地區位置，則 --location 是選用標記。舉例來說，假設您是在東京地區使用 BigQuery，請將標記的值設為 asia-northeast1。您可以使用 .bigqueryrc 檔案設定位置的預設值。
  • [FORMAT] 是 AVRO。
  • [DATASET] 是現有資料集。
  • [TABLE] 是您正在載入資料的資料表名稱。
  • [PATH_TO_SOURCE] 是完整的 Cloud Storage URI，或是以逗號分隔的 URI 清單。您也可以使用萬用字元。

範例：

  • 下列指令會將 gs://mybucket/mydata.avro 中的資料載入至 mydataset 中名為 mytable 的資料表。mybucket 與 mydataset 建立於 US 多區域位置。

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

  • 下列指令會將 gs://mybucket/ 中多個檔案的資料載入至 mydataset 中名為 mytable 的資料表。Cloud Storage URI 使用萬用字元。 mybucket 與 mydataset 建立於 US 多地區位置。

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

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

    bq --location=asia-northeast1 load --autodetect --source_format=AVRO mydataset.mytable "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

API

設定下列屬性以使用 API 載入 Avro 資料。

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

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

  3. sourceUris 必須完整且符合下列格式：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 清除資料表中所有現有的資料後再寫入新資料。

根據預設，載入工作會將資料附加至資料表。如要使用載入工作來覆寫資料表的資料，請如下操作：

主控台

  1. 在 GCP 主控台中開啟 BigQuery 網頁版 UI。
    前往 BigQuery 網頁版 UI

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

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

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

    • 在「Create table from」(使用下列資料建立資料表) 區段，選取您要採用的來源類型，然後在來源欄位中，瀏覽檔案/Cloud Storage 值區，或輸入 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. 在「Advance options」(進階選項) 部分的「Write preference」(寫入偏好設定)，選擇 [Write if empty] (空白時寫入)、[Append to table] (附加到表格中) 或是 [Overwrite table] (覆寫資料表)。

  8. 按一下 [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 type」(資料表類型) 設為 [Native table] (原生資料表)。

  5. 在「Schema」區段中，無需採取任何行動。結構定義資訊是透過 Avro 檔案推測得出。

  6. 在「Options」區段的「Write preference」中，選擇 [Write if empty]、[Append to table] 或 [Overwrite table]。

    使用新增欄位新增結構定義

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

指令列

輸入帶有 --replace 標記的 bq load 指令以覆寫資料表。提供 --location 標記，並將值設為您的位置。使用 --noreplace 標記將資料附加至資料表。未指定任何標記時，預設為附加資料。

bq --location=[LOCATION] load --[no]replace [DATASET].[TABLE] [PATH_TO_SOURCE]

其中：

  • [LOCATION] 是您的位置。如果您的資料位於 --location 或 US 多地區位置，則 EU 標記為選用。您可以使用 .bigqueryrc 檔案設定位置的預設值。
  • [DATASET] 是現有資料集。
  • [TABLE] 是您正在載入資料的資料表名稱。
  • [PATH_TO_SOURCE] 是完整的 Cloud Storage URI，或是以逗號分隔的 URI 清單。您也可以使用萬用字元。

範例：

  • 下列指令會從 gs://mybucket/mydata.avro 載入資料並覆寫在 mydataset 中名為 mytable 的資料表。mybucket 與 mydataset 建立於 US 多區域位置。

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

  • 下列指令會從 gs://mybucket/mydata.avro 載入資料並將資料附加至 mydataset 中名為 mytable 的資料表。mybucket 與 mydataset 建立於 asia-northeast1 區域。

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

API

設定下列屬性以使用 API 載入 CSV 資料。

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

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

  3. sourceUris 必須完整且符合下列格式：gs://[BUCKET]/[OBJECT]。您可以使用以逗號分隔清單的形式包含多個 URI。請注意，從 Cloud Storage 載入 CSV 資料時，也可以使用萬用字元。

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

  5. 將 writeDisposition 屬性設為 WRITE_TRUNCATE、WRITE_APPEND 或 WRITE_EMPTY，以指定寫入偏好設定。

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
產品意見