從 Cloud Storage 載入 Parquet 資料
本頁概要說明如何將 Parquet 資料從 Cloud Storage 載入 BigQuery。
Parquet 是 Apache Hadoop 生態系統廣泛使用的開放原始碼資料欄導向資料格式。
從 Cloud Storage 載入 Parquet 資料時,可將資料載入新的資料表或分區、或對現有資料表或分區進行附加或覆寫作業。將資料載入 BigQuery 時,資料會轉換為 Capacitor 資料欄格式 (BigQuery 的儲存格式)。
將資料從 Cloud Storage 載入至 BigQuery 資料表時,包含該資料表的資料集必須位於與 Cloud Storage 值區相同的地區或多地區位置。
如要瞭解如何從本機檔案載入 Parquet 資料,請參閱「從本機檔案載入資料」。
限制
將資料從 Cloud Storage 值區載入 BigQuery 時有下列限制:
- BigQuery 不保證外部資料來源的資料一致性。如果基礎資料在查詢執行期間遭到變更,可能會導致非預期的行為。
BigQuery 不支援 Cloud Storage 物件版本控制。如果在 Cloud Storage URI 中加入世代號碼,載入作業就會失敗。
如果要載入的任何檔案具有不同的結構定義,您就無法在 Cloud Storage URI 中使用萬用字元。任何資料欄位置的差異都會視為不同的結構定義。
輸入檔案相關規定
如要避免在將 Parquet 檔案載入 BigQuery 時發生 resourcesExceeded
錯誤,請遵循下列規範:
- 列大小不得超過 50 MB。
- 如果輸入資料含有超過 100 個欄,建議您將頁面大小縮減為小於預設頁面大小 (1 * 1024 * 1024 個位元組)。如果您使用的是大量壓縮功能,這項功能就特別實用。
- 為求最佳效能,請將資料列群組大小設為至少 16 MiB。資料列群組越小,I/O 就會增加,載入和查詢速度也會變慢。
事前準備
授予身分與存取權管理 (IAM) 角色,讓使用者取得執行本文件中各項工作的必要權限,並建立資料集來儲存資料。
所需權限
如要將資料載入 BigQuery,您必須具備 IAM 權限,才能執行載入工作,並將資料載入 BigQuery 資料表和分區。如要從 Cloud Storage 載入資料,您也需要 IAM 權限存取包含資料的值區。
將資料載入 BigQuery 的權限
如要將資料載入新的 BigQuery 資料表或分區,或是附加或覆寫現有資料表或分區,您需要具備下列 IAM 權限:
bigquery.tables.create
bigquery.tables.updateData
bigquery.tables.update
bigquery.jobs.create
以下每個預先定義的 IAM 角色都包含將資料載入 BigQuery 資料表或分區所需的權限:
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin
(包含bigquery.jobs.create
權限)bigquery.user
(包含bigquery.jobs.create
權限)bigquery.jobUser
(包含bigquery.jobs.create
權限)
此外,如果您具備 bigquery.datasets.create
權限,就可以在您建立的資料集中使用載入工作建立及更新資料表。
如要進一步瞭解 BigQuery 中的 IAM 角色和權限,請參閱「預先定義的角色與權限」一文。
從 Cloud Storage 載入資料的權限
如要取得從 Cloud Storage 值區載入資料所需的權限,請要求管理員為您授予該值區的 Storage 管理員 (roles/storage.admin
) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。
這個預先定義的角色包含從 Cloud Storage 值區載入資料所需的權限。如要查看確切的必要權限,請展開「必要權限」部分:
所需權限
您必須具備下列權限,才能從 Cloud Storage 值區載入資料:
-
storage.buckets.get
-
storage.objects.get
-
storage.objects.list (required if you are using a URI wildcard)
建立資料集
建立 BigQuery 資料集來儲存資料。
Parquet 結構定義
將 Parquet 檔案載入 BigQuery 時,系統會從自述式來源資料自動擷取資料表結構定義。從來源資料擷取結構定義時,BigQuery 會按照字母順序使用最後一個檔案。
舉例來說,Cloud Storage 中有下列 Parquet 檔案:
gs://mybucket/00/ a.parquet z.parquet gs://mybucket/01/ b.parquet
在 bq 指令列工具中執行這項指令可載入所有檔案 (以逗號分隔的清單),且結構定義衍生自 mybucket/01/b.parquet
:
bq load \ --source_format=PARQUET \ dataset.table \ "gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"
載入具有不同結構定義的多個 Parquet 檔案時,不同結構定義中指定的相同資料欄必須在各個結構定義中採用相同的模式。
BigQuery 偵測結構定義時,部分 Parquet 資料類型會轉換為 BigQuery 資料類型,確保與 GoogleSQL 語法相容。詳情請參閱 Parquet 轉換。
如要提供建立外部資料表的資料表結構定義,請將 BigQuery API 中的referenceFileSchemaUri
屬性或 bq 指令列工具中的 --reference_file_schema_uri
參數設為參考檔案的網址。例如 --reference_file_schema_uri="gs://mybucket/schema.parquet"
。
Parquet 壓縮
BigQuery 支援下列 Parquet 檔案內容的壓縮轉碼器:
GZip
LZO_1C
LZO_1X
LZ4_RAW
Snappy
ZSTD
將 Parquet 資料載入至新的資料表
您可以使用下列任一方法,將 Parquet 資料載入新的資料表:
- Google Cloud 控制台
- bq 指令列工具的
bq load
指令 jobs.insert
API 方法和設定load
工作- 用戶端程式庫
如要將 Parquet 資料從 Cloud Storage 載入新的 BigQuery 資料表,請執行下列操作:
主控台
前往 Google Cloud 控制台的「BigQuery」頁面。
- 在「Explorer」窗格中展開專案,然後選取資料集。
- 在「資料集資訊」部分,按一下 「建立資料表」。
- 在「Create table」面板中,指定下列詳細資料:
- 在「Source」部分,選取「Create table from」清單中的「Google Cloud Storage」。接著,按照下列步驟操作:
- 從 Cloud Storage 值區選取檔案,或輸入 Cloud Storage URI。您無法在 Google Cloud 控制台中輸入多個 URI,但支援使用萬用字元。Cloud Storage 值區的位置必須與要建立、附加或覆寫的表格所屬的資料集位置相同。
- 在「File format」(檔案格式) 部分,選取「Parquet」。
- 從 Cloud Storage 值區選取檔案,或輸入 Cloud Storage URI。您無法在 Google Cloud 控制台中輸入多個 URI,但支援使用萬用字元。Cloud Storage 值區的位置必須與要建立、附加或覆寫的表格所屬的資料集位置相同。
- 在「Destination」(目的地) 部分中,指定下列詳細資料:
- 在「Dataset」(資料集) 部分,選取要建立資料表的資料集。
- 在「Table」(資料表) 欄位中,輸入要建立的資料表名稱。
- 確認「Table type」欄位已設為「Native table」。
- 在「Schema」(結構定義) 區段中,無需採取任何行動。Parquet 檔案的結構定義為自述式。
- 選用步驟:指定「分區與叢集設定」。如需更多資訊,請參閱「建立分區資料表」和「建立及使用叢集資料表」。
- 按一下「進階選項」,然後執行下列操作:
- 讓「Write preference」(寫入偏好設定) 的 [Write if empty] (空白時寫入) 選項維持在已選取狀態。這個選項能建立新的資料表,並將您的資料載入其中。
- 如果您想忽略資料列中不在資料表結構定義中的值,請選取「不明的值」。
- 針對「Encryption」(加密),請按一下「Customer-managed key」(客戶管理的金鑰),以使用 Cloud Key Management Service 金鑰。如果您保留 Google-managed key 設定,BigQuery 會加密靜態資料。
- 點選「建立資料表」。
SQL
使用 LOAD DATA
DDL 陳述式。以下範例會將 Parquet 檔案載入新的資料表 mytable
:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入以下陳述式:
LOAD DATA OVERWRITE mydataset.mytable FROM FILES ( format = 'PARQUET', uris = ['gs://bucket/path/file.parquet']);
按一下
「Run」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」一文。
bq
請使用 bq load
指令,然後使用 --source_format
旗標指定 PARQUET
,並加入 Cloud Storage URI。您可以加入單一 URI、以逗號分隔的 URI 清單,或包含萬用字元的 URI。
(選用) 提供 --location
旗標,並將值設為您的位置。
其他選用標記包括:
--time_partitioning_type
:針對資料表啟用時間分區功能並設定分區類型。可能的值為HOUR
、DAY
、MONTH
和YEAR
。如果您在DATE
、DATETIME
或TIMESTAMP
資料欄建立分區資料表,則不一定要使用這個標記。時間分區的預設分區類型為DAY
。您無法變更現有資料表的分區規格。--time_partitioning_expiration
:這是一個整數,用來指定系統應在何時刪除時間分區 (以秒為單位)。到期時間為分區的世界標準時間日期加上整數值。--time_partitioning_field
:用於建立分區資料表的DATE
或TIMESTAMP
資料欄。如果您在啟用時間分區功能時未提供這個值,系統就會建立擷取時間分區資料表。--require_partition_filter
:這個選項啟用後,系統會要求使用者加入WHERE
子句,以指定要查詢的分區。使用分區篩選器可以降低成本並提升效能。詳情請參閱「在查詢中要求分區篩選器」。--clustering_fields
:以逗號分隔的資料欄名稱清單 (最多四個名稱),可用來建立叢集資料表。--destination_kms_key
:用來加密資料表資料的 Cloud KMS 金鑰。--column_name_character_map
:定義資料欄名稱字元的範圍和處理方式,並提供啟用彈性資料欄名稱的選項。詳情請參閱load_option_list
。如要進一步瞭解支援和不支援的字元,請參閱靈活的資料欄名稱。如要進一步瞭解分區資料表,請參閱:
如要進一步瞭解叢集資料表,請參閱下列說明:
如要進一步瞭解資料表加密作業,請參閱下列說明文章:
如要將 Parquet 資料載入 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
建立指向 Cloud Storage 中來源資料的
load
工作。source URIs
屬性必須完整且符合下列格式:gs://BUCKET/OBJECT
。每個 URI 可包含一個「*」萬用字元。將
sourceFormat
屬性設為PARQUET
,以指定 Parquet 資料格式。如要檢查工作狀態,請呼叫
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 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Node.js
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
PHP
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 PHP 設定說明進行操作。詳情請參閱 BigQuery PHP API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Python
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
使用 Client.load_table_from_uri() 方法,從 Cloud Storage 啟動載入工作。如要使用 Parquet,請將 LoadJobConfig.source_format 屬性設為PARQUET
字串,並將工作設定當做 job_config
引數傳送至 load_table_from_uri()
方法。
使用 Parquet 資料附加到資料表或覆寫資料表
如要將其他資料載入資料表,您可以指定來源檔案或附加查詢結果。
在 Google Cloud 主控台中,使用「寫入偏好設定」選項,指定從來源檔案或從查詢結果載入資料時採取的動作。
將額外資料載入資料表時,可以選擇下列選項:
主控台選項 | bq 工具標記 | BigQuery API 屬性 | 說明 |
---|---|---|---|
空白時寫入 | 不支援 | WRITE_EMPTY |
資料表空白時才會寫入資料。 |
附加到資料表中 | --noreplace 或 --replace=false ;如果未指定 --[no]replace ,則預設動作為附加 |
WRITE_APPEND |
(預設) 將資料附加至資料表尾端。 |
覆寫資料表 | --replace 或--replace=true |
WRITE_TRUNCATE |
先清除資料表中所有現有資料,再寫入新的資料。這項操作也會刪除資料表結構定義、資料列層級安全性,並移除任何 Cloud KMS 金鑰。 |
如果您將資料載入現有資料表,該載入工作可附加資料,或覆寫資料表。
您可以使用下列任一方法來對資料表進行附加或覆寫作業:
- Google Cloud 控制台
- bq 指令列工具的
bq load
指令 jobs.insert
API 方法和設定load
工作- 用戶端程式庫
如要使用 Parquet 資料對資料表進行附加或覆寫,請執行下列操作:
主控台
前往 Google Cloud 控制台的「BigQuery」頁面。
- 在「Explorer」窗格中展開專案,然後選取資料集。
- 在「資料集資訊」部分,按一下 「建立資料表」。
- 在「Create table」面板中,指定下列詳細資料:
- 在「Source」部分,選取「Create table from」清單中的「Google Cloud Storage」。接著,按照下列步驟操作:
- 從 Cloud Storage 值區選取檔案,或輸入 Cloud Storage URI。您無法在 Google Cloud 控制台中輸入多個 URI,但支援使用萬用字元。Cloud Storage 值區的位置必須與要建立、附加或覆寫的表格所屬的資料集位置相同。
- 在「File format」(檔案格式) 部分,選取「Parquet」。
- 從 Cloud Storage 值區選取檔案,或輸入 Cloud Storage URI。您無法在 Google Cloud 控制台中輸入多個 URI,但支援使用萬用字元。Cloud Storage 值區的位置必須與要建立、附加或覆寫的表格所屬的資料集位置相同。
- 在「Destination」(目的地) 部分中,指定下列詳細資料:
- 在「Dataset」(資料集) 部分,選取要建立資料表的資料集。
- 在「Table」(資料表) 欄位中,輸入要建立的資料表名稱。
- 確認「Table type」欄位已設為「Native table」。
- 在「Schema」(結構定義) 區段中,無需採取任何行動。Parquet 檔案的結構定義為自述式。
- 選用步驟:指定「分區與叢集設定」。如需更多資訊,請參閱「建立分區資料表」和「建立及使用叢集資料表」。您無法藉由附加或覆寫的方式,將資料表轉換為分區資料表或叢集資料表。 Google Cloud 主控台不支援在載入工作中附加或覆寫分區資料表或叢集資料表。
- 按一下「進階選項」,然後執行下列操作:
- 針對「Write preference」(寫入偏好設定),請選擇「Append to table」(附加到資料表中) 或「Overwrite table」(覆寫資料表)。
- 如果您想忽略資料列中不在資料表結構定義中的值,請選取「不明的值」。
- 針對「Encryption」(加密),請按一下「Customer-managed key」(客戶管理的金鑰),以使用 Cloud Key Management Service 金鑰。如果您保留 Google-managed key 設定,BigQuery 會加密靜態資料。
- 點選「建立資料表」。
SQL
使用 LOAD DATA
DDL 陳述式。以下範例會將 Parquet 檔案附加至資料表 mytable
:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入以下陳述式:
LOAD DATA INTO mydataset.mytable FROM FILES ( format = 'PARQUET', uris = ['gs://bucket/path/file.parquet']);
按一下
「Run」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」一文。
bq
如要覆寫資料表,請輸入 bq load
指令並加上 --replace
旗標。如要附加資料至資料表,使用 --noreplace
旗標。若未指定任何旗標,預設動作為附加資料。提供 --source_format
旗標,並將其設為 PARQUET
。系統會自動從自述來源資料中擷取 Parquet 結構定義,因此您不需要提供結構定義。
(選用) 提供 --location
旗標,並將值設為您的位置。
其他選用標記包括:
--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
如要進一步瞭解如何使用 bq 指令列工具對分區資料表進行附加和覆寫作業,請參閱「對分區資料表中的資料執行附加或覆寫操作」一文。
API
建立指向 Cloud Storage 中來源資料的
load
工作。source URIs
屬性必須完整且符合下列格式:gs://BUCKET/OBJECT
。您可以使用以逗號分隔清單的形式包含多個 URI。請注意,系統也支援使用萬用字元。藉由將
configuration.load.sourceFormat
屬性設為PARQUET
,以指定資料格式。藉由將
configuration.load.writeDisposition
屬性設為WRITE_TRUNCATE
或WRITE_APPEND
,以指定寫入偏好設定。
Go
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Node.js
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
PHP
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 PHP 設定說明進行操作。詳情請參閱 BigQuery PHP API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Python
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
如要將資料列附加到現有資料表,請將LoadJobConfig.write_disposition
屬性設為 WRITE_APPEND
。
如要取代現有資料表中的資料列,請將 LoadJobConfig.write_disposition
屬性設為 WRITE_TRUNCATE
。
載入 Hive 分區的 Parquet 資料
BigQuery 支援載入儲存在 Cloud Storage 的 Hive 分區 Parquet 資料,並且會將目標 BigQuery 代管資料表中的資料欄,填入 Hive 分區的資料欄。詳情請參閱「載入外部分區資料」。
Parquet 轉換
本節說明 BigQuery 在載入 Parquet 資料時,如何剖析各種資料類型。
部分 Parquet 資料類型 (例如 INT32
、INT64
、BYTE_ARRAY
和 FIXED_LEN_BYTE_ARRAY
) 可轉換為多種 BigQuery 資料類型。為確保 BigQuery 正確轉換 Parquet 資料類型,請在 Parquet 檔案中指定適當的資料類型。
例如,如要將 Parquet INT32
資料類型轉換為 BigQuery DATE
資料類型,請指定下列內容:
optional int32 date_col (DATE);
BigQuery 會將 Parquet 資料類型轉換為下列各節所述的 BigQuery 資料類型。
類型轉換
BigQuery 資料類型 | ||
---|---|---|
BOOLEAN |
無 | BOOLEAN |
INT32 | None、INTEGER (UINT_8 、UINT_16 、UINT_32 、INT_8 、INT_16 、INT_32 )
|
INT64 |
INT32 | 十進位 | NUMERIC、BIGNUMERIC 或 STRING |
INT32 |
DATE |
DATE |
INT64 |
None、INTEGER (UINT_64 、INT_64 )
|
INT64 |
INT64 | 十進位 | NUMERIC、BIGNUMERIC 或 STRING |
INT64 |
TIMESTAMP ,precision=MILLIS
(TIMESTAMP_MILLIS )
|
TIMESTAMP |
INT64 |
TIMESTAMP ,precision=MICROS
(TIMESTAMP_MICROS )
|
TIMESTAMP |
INT96 |
無 | TIMESTAMP |
FLOAT |
無 | FLOAT64 |
DOUBLE |
無 | FLOAT64 |
BYTE_ARRAY |
無 | BYTES |
BYTE_ARRAY |
STRING (UTF8 ) |
STRING |
FIXED_LEN_BYTE_ARRAY | 十進位 | NUMERIC、BIGNUMERIC 或 STRING |
FIXED_LEN_BYTE_ARRAY |
無 | BYTES |
巢狀群組會轉換為 STRUCT
類型。系統不支援其他 Parquet 類型與轉換類型的組合。
無號邏輯型別
Parquet UINT_8
、UINT_16
、UINT_32
和 UINT_64
型別未簽署。當 BigQuery 將這些類型的值載入 BigQuery 已簽署的 INTEGER
欄時,會將這些值視為未簽署。在 UINT_64
的情況下,如果未簽署的值超過 INTEGER
的最大值 9,223,372,036,854,775,807,系統會傳回錯誤。
Decimal 邏輯類型
Decimal
邏輯類型可轉換為 NUMERIC
、BIGNUMERIC
或 STRING
類型。轉換的類型取決於 decimal
邏輯型別的精確度和比例參數,以及指定的小數目標類型。請按照下列方式指定小數目標類型:
- 使用
jobs.insert
API 的載入工作:使用JobConfigurationLoad.decimalTargetTypes
欄位。 - 在 bq 指令列工具中使用
bq load
指令的載入工作:使用--decimal_target_types
標記。 - 針對含有外部來源的資料表執行查詢:使用
ExternalDataConfiguration.decimalTargetTypes
欄位。 - 對於使用 DDL 建立的永久性外部資料表:請使用
decimal_target_types
選項。
列舉邏輯類型
Enum
邏輯型別可轉換為 STRING
或 BYTES
。請按照下列方式指定轉換的目標類型:
- 使用
jobs.insert
API 的載入工作:使用JobConfigurationLoad.parquetOptions
欄位。 - 在 bq 指令列工具中使用
bq load
指令的載入工作:使用--parquet_enum_as_string
旗標。 - 如要使用
bq mk
建立永久外部資料表:請使用--parquet_enum_as_string
旗標。
清單邏輯類型
您可以為 Parquet LIST
邏輯型別啟用結構定義推論功能。BigQuery 會檢查 LIST
節點是否採用標準格式,或採用向後相容性規則所述的其中一種格式:
// standard form
<optional | required> group <name> (LIST) {
repeated group list {
<optional | required> <element-type> element;
}
}
如果是的話,系統會將轉換後結構定義中 LIST
節點的對應欄位視為節點具有下列結構定義:
repeated <element-type> <name>
節點「list」和「element」已省略。
- 如果是使用
jobs.insert
API 的載入工作,請使用JobConfigurationLoad.parquetOptions
欄位。 - 如果在 bq 指令列工具中使用
bq load
指令執行載入工作,請使用--parquet_enable_list_inference
標記。 - 如要使用
bq mk
建立永久外部資料表,請使用--parquet_enable_list_inference
旗標。 - 如果是使用
CREATE EXTERNAL TABLE
陳述式建立的永久外部資料表,請使用enable_list_inference
選項。
地理空間資料
您可以指定類型為 GEOGRAPHY
的 BigQuery 結構定義,載入包含 WKT、十六進位編碼的 WKB 或 GeoJSON 的 Parquet 檔案,或是載入 STRING
資料欄中的 WKB,BYTE_ARRAY
詳情請參閱「載入地理空間資料」。
您也可以載入 GeoParquet 檔案。在這種情況下,GeoParquet 中繼資料所描述的資料欄會預設解讀為 GEOGRAPHY
類型。您也可以提供明確的結構定義,將原始 WKB 資料載入 BYTES
資料欄。詳情請參閱「載入 GeoParquet 檔案」。
資料欄名稱轉換
欄名稱可以包含英文字母 (a-z、A-Z)、數字 (0-9) 或底線 (_),且開頭必須為英文字母或底線。如果您使用彈性資料欄名稱,BigQuery 會支援以數字開頭的資料欄名稱。請謹慎使用以數字開頭的資料欄,因為在 BigQuery Storage Read API 或 BigQuery Storage Write API 中使用彈性欄名需要特殊處理。如要進一步瞭解靈活的資料欄名稱支援功能,請參閱「靈活的資料欄名稱」。
資料欄名稱的長度上限為 300 個半形字元。資料欄名稱不得使用以下任何一個前置字串:
_TABLE_
_FILE_
_PARTITION
_ROW_TIMESTAMP
__ROOT__
_COLIDENTIFIER
資料欄名稱不得重複,即使大小寫不同也是如此。舉例來說,系統會將 Column1
和 column1
這兩個資料欄名稱視為相同。如要進一步瞭解資料欄命名規則,請參閱 GoogleSQL 參考資料中的「資料欄名稱」。
如果資料表名稱 (例如 test
) 與其中一個資料欄名稱 (例如 test
) 相同,SELECT
運算式會將 test
資料欄解讀為包含所有其他資料表欄的 STRUCT
。如要避免這類衝突,請使用下列任一方法:
避免為資料表和資料欄使用相同的名稱。
為表格指派其他別名。舉例來說,以下查詢會將資料表別名
t
指派給資料表project1.dataset.test
:SELECT test FROM project1.dataset.test AS t;
參照資料欄時,請一併提供資料表名稱。例如:
SELECT test.test FROM project1.dataset.test;
彈性設定資料欄名稱
您可以更靈活地命名資料欄,包括擴充對英文字元以外的字元存取權,以及其他符號。
靈活的資料欄名稱支援下列字元:
- 任何語言的任何字母,由 Unicode 規則運算式
\p{L}
表示。 - 任何語言的任何數字字元,由萬國碼規則運算式
\p{N}
表示。 - 任何連接符號字元 (包括底線),以 Unicode 規則運算式
\p{Pc}
表示。 - 以 Unicode 規則運算式
\p{Pd}
表示的分號或破折號。 - 任何標記,旨在搭配另一個字元,以 Unicode 規則運算式
\p{M}
表示。例如重音符號、變音符號或外框。 - 下列特殊字元:
- 以 Unicode 規則運算式
\u0026
表示的 & 號 (&
)。 - 百分比符號 (
%
),由 Unicode 規則運算式\u0025
表示。 - 等號 (
=
),由 Unicode 規則運算式\u003D
表示。 - 加號 (
+
),由 Unicode 規則運算式\u002B
表示。 - 以 Unicode 規則運算式
\u003A
表示的冒號 (:
)。 - 萬國碼規則運算式
\u0027
所代表的單引號 ('
)。 - 小於符號 (
<
),由 Unicode 規則運算式\u003C
表示。 - 大於符號 (
>
),由 Unicode 規則運算式\u003E
表示。 - 由 Unicode 規則運算式
\u0023
表示的數字符號 (#
)。 - 以 Unicode 規則運算式
\u007c
表示的垂直線 (|
)。 - 空格字元。
- 以 Unicode 規則運算式
靈活的資料欄名稱不支援下列特殊字元:
- 由 Unicode 規則運算式
\u0021
表示的驚嘆號 (!
)。 - 由 Unicode 規則運算式
\u0022
表示的引號 ("
)。 - 萬國碼規則運算式
\u0024
所代表的美元符號 ($
)。 - 左括號 (
(
),由 Unicode 規則運算式\u0028
表示。 - 由 Unicode 規則運算式
\u0029
所代表的右括號 ()
)。 - 以 Unicode 規則運算式
\u002A
表示的星號 (*
)。 - 以 Unicode 規則運算式
\u002C
表示的逗號 (,
)。 - 以 Unicode 規則運算式
\u002E
表示的句點 (.
)。使用資料欄名稱字元對照表時,系統不會在 Parquet 檔案資料欄名稱中將句號替換為底線。詳情請參閱彈性資料欄限制。 - 以 Unicode 規則運算式
\u002F
表示的斜線 (/
)。 - 以 Unicode 規則運算式
\u003B
表示的分號 (;
)。 - 由 Unicode 規則運算式
\u003F
表示的問號 (?
)。 - 以 Unicode 規則運算式
\u0040
表示的 @ 符號 (@
)。 - 左方括號 (
[
),由 Unicode 規則運算式\u005B
表示。 - 以 Unicode 規則運算式
\u005C
表示的反斜線 (\
)。 - 由 Unicode 規則運算式
\u005D
表示的右方括號 (]
)。 - 以 Unicode 規則運算式
\u005E
表示的揚抑符號 (^
)。 - 重音符號 (
`
),由 Unicode 規則運算式\u0060
表示。 - 左大括號 {
{
),由 Unicode 規則運算式\u007B
表示。 - 由 Unicode 規則運算式
\u007D
表示的右大括號 (}
)。 - 以 Unicode 規則運算式
\u007E
表示的波浪號 (~
)。
如需其他規範,請參閱「資料欄名稱」。
BigQuery Storage Read API 和 BigQuery Storage Write API 都支援展開的資料欄字元。如要搭配 BigQuery Storage Read API 使用擴充的萬國碼字元清單,您必須設定標記。您可以使用 displayName
屬性擷取欄名稱。以下範例說明如何使用 Python 用戶端設定標記:
from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()
#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options
如要在 BigQuery Storage Write API 中使用擴充的萬國碼字元清單,您必須使用 column_name
符號提供結構定義,除非您使用 JsonStreamWriter
寫入器物件。以下範例說明如何提供結構定義:
syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";
message FlexibleSchema {
optional string item_name_column = 1
[(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
optional string item_description_column = 2
[(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}
在這個範例中,item_name_column
和 item_description_column
是預留位置名稱,需要符合Protocol Buffers 命名慣例。請注意,column_name
註解一律優先於預留位置名稱。
限制
外部資料表不支援彈性資料欄名稱。
您無法載入資料欄名稱中含有半形句號 (.) 的 Parquet 檔案。
將 Parquet 檔案中的資料欄名稱載入至 BigQuery 時,系統會將其視為不區分大小寫。不區分大小寫的相同名稱會造成衝突。為避免這種情況,請在重複的資料欄名稱中加上底線,或是在載入前重新命名資料欄。
對 Parquet 檔案進行偵錯
如果載入工作因資料錯誤而失敗,您可以使用 PyArrow 確認 Parquet 資料檔案是否已損毀。如果 PyArrow 無法讀取檔案,BigQuery 載入工作可能會拒絕這些檔案。以下範例說明如何使用 PyArrow 讀取 Parquet 檔案的內容:
from pyarrow import parquet as pq
# Read the entire file
pq.read_table('your_sample_file.parquet')
# Read specific columns
pq.read_table('your_sample_file.parquet',columns=['some_column', 'another_column'])
# Read the metadata of specific columns
file_metadata=pq.read_metadata('your_sample_file.parquet')
for col in file_metadata.row_group(0).to_dict()['columns']:
print col['column_path_in_schema']
print col['num_values']
詳情請參閱 PyArrow 說明文件。