從 Cloud Storage 載入 CSV 資料
從 Cloud Storage 載入 CSV 資料時,可將資料載入至新的資料表或分區、將資料附加到現有資料表或分區或覆寫現有資料表或分區。將資料載入至 BigQuery 時,資料會轉換為 Capacitor 資料欄格式 (BigQuery 的儲存格式)。
將資料從 Cloud Storage 載入至 BigQuery 資料表時,包含該資料表的資料集必須位於與 Cloud Storage 值區相同的地區或多地區位置。
如需從本機檔案載入 CSV 資料的相關資訊,請參閱將資料從本機資料來源載入至 BigQuery。
歡迎試用
如果您未曾使用過 Google Cloud,歡迎建立帳戶,親自體驗實際使用 BigQuery 的成效。新客戶可以獲得價值 $300 美元的免費抵免額,可用於執行、測試及部署工作負載。
免費試用 BigQuery限制
將資料從 Cloud Storage 值區載入 BigQuery 時有下列限制:
- BigQuery 不保證外部資料來源的資料一致性。如果基礎資料在查詢執行期間遭到變更,可能會導致非預期的行為。
- BigQuery 不支援 Cloud Storage 物件版本控制。如果在 Cloud Storage URI 中加入世代號碼,載入作業就會失敗。
將 CSV 檔案載入 BigQuery 時,請注意下列事項:
- CSV 檔案不支援巢狀和重複的資料。
- 移除位元組順序標示 (BOM) 字元。可能會導致意外問題。
- 如果您使用 gzip 壓縮,BigQuery 無法同時讀取資料。將壓縮的 CSV 資料載入至 BigQuery 會比載入未壓縮的資料還慢。請參閱「載入壓縮與未壓縮資料」。
- 您無法在同一個載入工作中同時包含壓縮和未壓縮的檔案。
- gzip 檔案的大小上限為 4 GB。
- 如果所有欄都是字串類型,則使用結構定義自動偵測功能載入 CSV 資料時,系統不會自動偵測標題。在這種情況下,請在輸入內容中新增數值欄或明確宣告架構。
- 載入 CSV 或 JSON 資料時,
DATE
資料欄中的值必須使用連字號 (-
) 分隔符,且必須採用下列日期格式:YYYY-MM-DD
(年-月-日)。 - 載入 JSON 或 CSV 資料時,
TIMESTAMP
資料欄中的值必須使用連字號 (-
) 或斜線 (/
) 分隔符來區隔時間戳記的日期部分,且日期必須採用下列格式之一:YYYY-MM-DD
(年-月-日) 或YYYY/MM/DD
(年/月/日)。時間戳記的hh:mm:ss
(時-分-秒) 部分必須使用冒號 (:
) 分隔符。 - 檔案必須符合 負載工作限制中所述的 CSV 檔案大小限制。
事前準備
授予身分與存取權管理 (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 資料集來儲存資料。
CSV 壓縮
您可以使用 gzip
公用程式壓縮 CSV 檔案。請注意,gzip
會執行完整的檔案壓縮作業,這與其他檔案格式 (例如 Avro) 的壓縮轉碼器執行的檔案內容壓縮作業不同。使用 gzip
壓縮 CSV 檔案可能會影響效能;如要進一步瞭解取捨之處,請參閱「載入壓縮與未壓縮資料」。
將 CSV 資料載入資料表
如要將 CSV 資料從 Cloud Storage 載入至新的 BigQuery 資料表,請選取下列任一選項:
主控台
如要直接在 Cloud Shell 編輯器中按照逐步指南操作,請按一下「Guide me」:
前往 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」(檔案格式) 部分,選取「CSV」。
- 從 Cloud Storage 值區選取檔案,或輸入 Cloud Storage URI。您無法在 Google Cloud 控制台中輸入多個 URI,但支援使用萬用字元。Cloud Storage 值區的位置必須與要建立、附加或覆寫的表格所屬的資料集位置相同。
- 在「Destination」(目的地) 部分中,指定下列詳細資料:
- 在「Dataset」(資料集) 部分,選取要建立資料表的資料集。
- 在「Table」(資料表) 欄位中,輸入要建立的資料表名稱。
- 確認「Table type」欄位已設為「Native table」。
- 在「Schema」(結構定義) 部分輸入結構定義。如要啟用結構定義的自動偵測功能,請選取「自動偵測」。您可以使用下列任一方法,手動輸入結構定義資訊:
- 選項 1:按一下「Edit as Text」(以文字形式編輯),然後以 JSON 陣列的形式貼上結構定義。如果您使用 JSON 陣列,可透過與建立 JSON 結構定義檔一樣的程序產生結構定義。您可以輸入下列指令,查看現有資料表的 JSON 格式結構定義:
bq show --format=prettyjson dataset.table
- 選項 2:按一下「新增欄位」,然後輸入表格結構定義。 和「Mode」。 指定每個欄位的「Name」、「Type」
- 選項 1:按一下「Edit as Text」(以文字形式編輯),然後以 JSON 陣列的形式貼上結構定義。如果您使用 JSON 陣列,可透過與建立 JSON 結構定義檔一樣的程序產生結構定義。您可以輸入下列指令,查看現有資料表的 JSON 格式結構定義:
- 選用步驟:指定「分區與叢集設定」。如需更多資訊,請參閱「建立分區資料表」和「建立及使用叢集資料表」。
- 按一下「進階選項」,然後執行下列操作:
- 讓「Write preference」(寫入偏好設定) 的 [Write if empty] (空白時寫入) 選項維持在已選取狀態。這個選項能建立新的資料表,並將您的資料載入其中。
- 針對「Number of errors allowed」(允許的錯誤數量),請接受預設值
0
,或輸入可忽略的含錯列數上限。如果含錯誤的列數超過這個值,該項工作就會產生invalid
訊息並失敗。這個選項僅適用於 CSV 和 JSON 檔案。 - 針對「時區」,請輸入剖析沒有特定時區的時間戳記值時要使用的預設時區。如要查看更多有效的時區名稱,請按這裡。如果沒有這個值,則會使用預設時區 (UTC) 剖析沒有特定時區的時間戳記值。(預覽)。
- 在「Date Format」(日期格式) 中,輸入 格式元素,定義輸入檔案中的 DATE 值格式。這個欄位應採用 SQL 樣式格式 (例如
MM/DD/YYYY
)。如果這個值存在,則這個格式是唯一相容的日期格式。結構定義自動偵測功能也會根據這個格式,而非現有格式,決定日期欄的類型。如果沒有這個值,系統會使用預設格式剖析日期欄位。(預覽)。 - 針對「日期時間格式」,請輸入 格式元素,定義輸入檔案中的 DATETIME 值格式。這個欄位應採用 SQL 樣式,例如
MM/DD/YYYY HH24:MI:SS.FF3
。如果有這個值,這個格式是唯一相容的 DATETIME 格式。結構定義自動偵測功能也會根據這個格式,而非現有格式,決定 DATETIME 資料欄類型。如果沒有這個值,系統會使用預設格式剖析 DATETIME 欄位。(預覽)。 - 針對「時間格式」,請輸入 格式元素,定義輸入檔案中的 TIME 值格式。這個欄位應採用 SQL 樣式,例如
HH24:MI:SS.FF3
。如果這個值存在,這個格式是唯一相容的 TIME 格式。結構定義自動偵測功能也會根據這個格式,而非現有格式,決定 TIME 欄的類型。如果沒有這個值,系統會使用預設格式剖析 TIME 欄位。(預覽)。 - 針對「時間戳記格式」,請輸入 格式元素,定義輸入檔案中的 TIMESTAMP 值格式。這個欄位應採用 SQL 樣式格式 (例如
MM/DD/YYYY HH24:MI:SS.FF3
)。如果有這個值,這個格式是唯一相容的 TIMESTAMP 格式。結構定義自動偵測功能也會根據這個格式,而非現有格式,決定 TIMESTAMP 欄類型。如果沒有這個值,系統會使用預設格式剖析 TIMESTAMP 欄位。(預覽)。 - 如果您想忽略資料列中不在資料表結構定義中的值,請選取「不明的值」。
- 針對「Field delimiter」(欄位分隔符號),選擇在 CSV 檔案中分隔儲存格的字元:半形逗號、定位點符號、管線符號或自訂。如果選擇「Custom」(自訂),請在「Custom field delimiter」(自訂欄位分隔符號) 方塊中輸入分隔符號。預設值為 [Comma] (半形逗號)。
- 針對「Header rows to skip」(要略過的標題列),在 CSV 檔案頂端輸入要略過的標題列數。預設值為
0
。 - 針對「Quoted newlines」(引用換行符號),勾選「Allow quoted newlines」(允許引用換行符號),以允許在 CSV 檔案中使用包含換行符號字元的引用資料區段。預設值為
false
。 - 針對「Jagged rows」(不規則資料列),勾選「Allow jagged rows」(允許不規則資料列),以接受在 CSV 檔案中使用缺少結尾自選欄的資料列。系統會將缺少的值視為空值。如果取消勾選,系統會將缺少結尾資料欄的記錄視為損壞記錄;如果損壞記錄過多,工作結果中就會出現無效錯誤。預設值為
false
。 - 針對「Encryption」(加密),請按一下「Customer-managed key」(客戶管理的金鑰),以使用 Cloud Key Management Service 金鑰。如果您保留 Google-managed key 設定,BigQuery 會加密靜態資料。
- 點選「建立資料表」。
SQL
使用 LOAD DATA
DDL 陳述式。以下範例會將 CSV 檔案載入至新資料表 mytable
:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入以下陳述式:
LOAD DATA OVERWRITE mydataset.mytable (x INT64,y STRING) FROM FILES ( format = 'CSV', uris = ['gs://bucket/path/file.csv']);
按一下
「Run」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」一文。
bq
請使用 bq load
指令,然後使用 --source_format
旗標指定 CSV
,並加入 Cloud Storage URI。您可以加入單一 URI、以逗號分隔的 URI 清單,或包含萬用字元的 URI。在結構定義檔中以內嵌方式提供結構定義,或使用結構定義自動偵測功能。如果您未指定結構定義,且 --autodetect
為 false
,且目的地表格已存在,則會使用目的地表格的結構定義。
(選用) 提供 --location
旗標,並將值設為您的位置。
其他選用標記包括:
--allow_jagged_rows
:如果有指定,系統會接受在 CSV 檔案中缺少結尾自選欄的資料列。系統會將缺少的值視為空值。如果取消勾選,系統會將缺少結尾資料欄的記錄視為損壞記錄;如果損壞記錄過多,工作結果中就會出現無效錯誤。預設值為false
。--allow_quoted_newlines
:如果有指定,系統會允許在 CSV 檔案中使用包含換行符號字元的引用資料區段。預設值為false
。--field_delimiter
:用來表示資料中資料欄間界線的字元,\t
和tab
都可用來表示 Tab 字元分隔。預設值為,
。--null_marker
:選用的自訂字串,代表 CSV 資料中的 NULL 值。--skip_leading_rows
:指定在 CSV 檔案頂端要略過的標題列數。預設值為0
。--quote
:用來括住記錄的引號字元。預設值為"
。如要表示沒有引號字元,請使用空白字串。--max_bad_records
:這是一個整數,用來指定整個工作失敗前可允許的錯誤記錄數量上限。預設值為0
。無論--max_bad_records
的值為何,系統最多只會傳回五個任何類型的錯誤。--ignore_unknown_values
:如果指定,CSV 或 JSON 資料中就可以含有其他無法辨識的值 (但系統會予以忽略)。--time_zone
:(預先發布) 選用的預設時區,會在剖析 CSV 或 JSON 資料中沒有特定時區的時間戳記值時套用。--date_format
:(預覽) 選用的自訂字串,定義 CSV 或 JSON 資料中日期值的格式。--datetime_format
:(預覽) 選用的自訂字串,可定義 CSV 或 JSON 資料中 DATETIME 值的格式。--time_format
:(預覽) 選用的自訂字串,定義 CSV 或 JSON 資料中 TIME 值的格式。--timestamp_format
:(預覽) 選用的自訂字串,可定義 CSV 或 JSON 資料中 TIMESTAMP 值的格式。--autodetect
:如果指定,系統就會針對 CSV 和 JSON 資料啟用結構定義自動偵測功能。--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
:定義資料欄名稱字元的範圍和處理方式,並提供啟用彈性資料欄名稱的選項。需要 CSV 檔案的--autodetect
選項。詳情請參閱load_option_list
。如要進一步瞭解
bq load
指令,請參閱:如要進一步瞭解分區資料表,請參閱:
如要進一步瞭解叢集資料表,請參閱下列說明:
如要進一步瞭解資料表加密作業,請參閱下列說明文章:
如要將 CSV 資料載入 BigQuery,請輸入下列指令:
bq --location=location load \ --source_format=format \ dataset.table \ path_to_source \ schema
其中:
- location 是您的位置。
--location
是選用旗標。舉例來說,如果您在東京地區使用 BigQuery,就可以將該旗標的值設定為asia-northeast1
。您可以使用 .bigqueryrc 檔案來設定位置的預設值。 - format為
CSV
。 - dataset 是現有資料集。
- table 是您正在載入資料的資料表名稱。
- path_to_source 是完整的 Cloud Storage URI,或是以逗號分隔的 URI 清單。您也可以使用萬用字元。
- schema 是有效的結構定義。結構定義可以是本機 JSON 檔案,或以內嵌的方式在指令中輸入。您也可以改用
--autodetect
旗標,而非提供結構定義。
範例:
下列指令會將 gs://mybucket/mydata.csv
中的資料載入 mydataset
中名為 mytable
的資料表。結構定義是在名為 myschema.json
的本機結構定義檔中定義。
bq load \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
下列指令會將 gs://mybucket/mydata.csv
中的資料載入 mydataset
中名為 mytable
的資料表。結構定義是在名為 myschema.json
的本機結構定義檔中定義。CSV 檔案中包含兩個標頭列。如果未指定 --skip_leading_rows
,則預設行為會假設檔案中不含標頭。
bq load \
--source_format=CSV \
--skip_leading_rows=2
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
下列指令會將 gs://mybucket/mydata.csv
中的資料載入 mydataset
中名為 mytable
的擷取時間分區資料表。結構定義是在名為 myschema.json
的本機結構定義檔中定義。
bq load \
--source_format=CSV \
--time_partitioning_type=DAY \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
下列指令會將資料從 gs://mybucket/mydata.csv
載入到 mydataset
中名為 mytable
的新分區資料表。資料表會依 mytimestamp
資料欄進行分區。結構定義是在名為 myschema.json
的本機結構定義檔中定義。
bq load \
--source_format=CSV \
--time_partitioning_field mytimestamp \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
下列指令會將 gs://mybucket/mydata.csv
中的資料載入 mydataset
中名為 mytable
的資料表。結構定義是由系統自動偵測。
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv
下列指令會將 gs://mybucket/mydata.csv
中的資料載入 mydataset
中名為 mytable
的資料表。結構定義是以內嵌的方式定義,格式為 field:data_type,field:data_type
。
bq load \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
qtr:STRING,sales:FLOAT,year:STRING
下列指令會將 gs://mybucket/
中多個檔案的資料載入 mydataset
中名為 mytable
的資料表。Cloud Storage URI 使用萬用字元。結構定義是由系統自動偵測。
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata*.csv
下列指令會將 gs://mybucket/
中多個檔案的資料載入 mydataset
中名為 mytable
的資料表。指令包含以逗號分隔且帶有萬用字元的 Cloud Storage URI 清單。結構定義是在名為 myschema.json
的本機結構定義檔中定義。
bq load \
--source_format=CSV \
mydataset.mytable \
"gs://mybucket/00/*.csv","gs://mybucket/01/*.csv" \
./myschema.json
API
建立指向 Cloud Storage 中來源資料的
load
工作。source URIs
屬性必須是完整的,且必須符合下列格式:gs://bucket/object
。每個 URI 可包含一個「*」萬用字元。藉由將
sourceFormat
屬性設為CSV
,以指定 CSV 資料格式。如要檢查工作狀態,請呼叫
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 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
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 的 CSV 檔案載入資料。將 LoadJobConfig.schema 屬性設為 SchemaField 物件清單,以提供明確的結構定義。
Ruby
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Ruby 設定說明進行操作。詳情請參閱 BigQuery Ruby API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
將 CSV 資料載入至使用以資料欄為基礎的時間分區資料表
如要將 CSV 資料從 Cloud Storage 載入至使用資料欄時間區隔的 BigQuery 資料表,請按照下列步驟操作:
將 CSV 資料附加或覆寫至資料表
如要將其他資料載入資料表,您可以指定來源檔案或附加查詢結果。
在 Google Cloud 主控台中,使用「寫入偏好設定」選項,指定從來源檔案或查詢結果載入資料時採取的動作。
將額外資料載入資料表時,可以選擇下列選項:
主控台選項 | bq 工具標記 | BigQuery API 屬性 | 說明 |
---|---|---|---|
空白時寫入 | 不支援 | WRITE_EMPTY | 資料表空白時才會寫入資料。 |
附加到資料表中 | --noreplace 或 --replace=false ;如果未指定 --[no]replace ,則預設動作為附加 | WRITE_APPEND | (預設) 將資料附加至資料表尾端。 |
覆寫資料表 | --replace 或--replace=true | WRITE_TRUNCATE | 先清除資料表中所有現有資料,再寫入新的資料。這項操作也會刪除資料表結構定義、資料列層級安全性,並移除任何 Cloud KMS 金鑰。 |
如果您將資料載入現有資料表,該載入工作可附加資料,或覆寫資料表。
主控台
前往 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」(檔案格式) 部分,選取「CSV」。
- 從 Cloud Storage 值區選取檔案,或輸入 Cloud Storage URI。您無法在 Google Cloud 控制台中輸入多個 URI,但支援使用萬用字元。Cloud Storage 值區的位置必須與要建立、附加或覆寫的表格所屬的資料集位置相同。
- 在「Destination」(目的地) 部分中,指定下列詳細資料:
- 在「Dataset」(資料集) 部分,選取要建立資料表的資料集。
- 在「Table」(資料表) 欄位中,輸入要建立的資料表名稱。
- 確認「Table type」欄位已設為「Native table」。
- 在「Schema」(結構定義) 部分輸入結構定義。如要啟用結構定義的自動偵測功能,請選取「自動偵測」。您可以使用下列任一方法,手動輸入結構定義資訊:
- 選項 1:按一下「Edit as Text」(以文字形式編輯),然後以 JSON 陣列的形式貼上結構定義。如果您使用 JSON 陣列,可透過與建立 JSON 結構定義檔一樣的程序產生結構定義。您可以輸入下列指令,查看現有資料表的 JSON 格式結構定義:
bq show --format=prettyjson dataset.table
- 選項 2:按一下「新增欄位」,然後輸入表格結構定義。 和「Mode」。 指定每個欄位的「Name」、「Type」
- 選項 1:按一下「Edit as Text」(以文字形式編輯),然後以 JSON 陣列的形式貼上結構定義。如果您使用 JSON 陣列,可透過與建立 JSON 結構定義檔一樣的程序產生結構定義。您可以輸入下列指令,查看現有資料表的 JSON 格式結構定義:
- 選用步驟:指定「分區與叢集設定」。如需更多資訊,請參閱「建立分區資料表」和「建立及使用叢集資料表」。您無法藉由附加或覆寫的方式,將資料表轉換為分區資料表或叢集資料表。 Google Cloud 主控台不支援在載入工作中附加或覆寫分區資料表或叢集資料表。
- 按一下「進階選項」,然後執行下列操作:
- 針對「Write preference」(寫入偏好設定),請選擇「Append to table」(附加到資料表中) 或「Overwrite table」(覆寫資料表)。
- 針對「Number of errors allowed」(允許的錯誤數量),請接受預設值
0
,或輸入可忽略的含錯列數上限。如果含錯誤的列數超過這個值,該項工作就會產生invalid
訊息並失敗。這個選項僅適用於 CSV 和 JSON 檔案。 - 針對「時區」,請輸入剖析沒有特定時區的時間戳記值時要使用的預設時區。如要查看更多有效的時區名稱,請按這裡。如果沒有這個值,則會使用預設時區 (UTC) 剖析沒有特定時區的時間戳記值。(預覽)。
- 在「Date Format」(日期格式) 中,輸入 格式元素,定義輸入檔案中的 DATE 值格式。這個欄位應採用 SQL 樣式格式 (例如
MM/DD/YYYY
)。如果這個值存在,則這個格式是唯一相容的日期格式。結構定義自動偵測功能也會根據這個格式,而非現有格式,決定日期欄的類型。如果沒有這個值,系統會使用預設格式剖析日期欄位。(預覽)。 - 針對「日期時間格式」,請輸入 格式元素,定義輸入檔案中的 DATETIME 值格式。這個欄位應採用 SQL 樣式,例如
MM/DD/YYYY HH24:MI:SS.FF3
。如果有這個值,這個格式是唯一相容的 DATETIME 格式。結構定義自動偵測功能也會根據這個格式,而非現有格式,決定 DATETIME 資料欄類型。如果沒有這個值,系統會使用預設格式剖析 DATETIME 欄位。(預覽)。 - 針對「時間格式」,請輸入 格式元素,定義輸入檔案中的 TIME 值格式。這個欄位應採用 SQL 樣式,例如
HH24:MI:SS.FF3
。如果這個值存在,這個格式是唯一相容的 TIME 格式。結構定義自動偵測功能也會根據這個格式,而非現有格式,決定 TIME 欄的類型。如果沒有這個值,系統會使用預設格式剖析 TIME 欄位。(預覽)。 - 針對「時間戳記格式」,請輸入 格式元素,定義輸入檔案中的 TIMESTAMP 值格式。這個欄位應採用 SQL 樣式格式 (例如
MM/DD/YYYY HH24:MI:SS.FF3
)。如果有這個值,這個格式是唯一相容的 TIMESTAMP 格式。結構定義自動偵測功能也會根據這個格式,而非現有格式,決定 TIMESTAMP 欄類型。如果沒有這個值,系統會使用預設格式剖析 TIMESTAMP 欄位。(預覽)。 - 如果您想忽略資料列中不在資料表結構定義中的值,請選取「不明的值」。
- 針對「Field delimiter」(欄位分隔符號),選擇在 CSV 檔案中分隔儲存格的字元:半形逗號、定位點符號、管線符號或自訂。如果選擇「Custom」(自訂),請在「Custom field delimiter」(自訂欄位分隔符號) 方塊中輸入分隔符號。預設值為 [Comma] (半形逗號)。
- 針對「Header rows to skip」(要略過的標題列),在 CSV 檔案頂端輸入要略過的標題列數。預設值為
0
。 - 針對「Quoted newlines」(引用換行符號),勾選「Allow quoted newlines」(允許引用換行符號),以允許在 CSV 檔案中使用包含換行符號字元的引用資料區段。預設值為
false
。 - 針對「Jagged rows」(不規則資料列),勾選「Allow jagged rows」(允許不規則資料列),以接受在 CSV 檔案中使用缺少結尾自選欄的資料列。系統會將缺少的值視為空值。如果取消勾選,系統會將缺少結尾資料欄的記錄視為損壞記錄;如果損壞記錄過多,工作結果中就會出現無效錯誤。預設值為
false
。 - 針對「Encryption」(加密),請按一下「Customer-managed key」(客戶管理的金鑰),以使用 Cloud Key Management Service 金鑰。如果您保留 Google-managed key 設定,BigQuery 會加密靜態資料。
- 點選「建立資料表」。
SQL
使用 LOAD DATA
DDL 陳述式。以下範例會將 CSV 檔案附加至資料表 mytable
:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入以下陳述式:
LOAD DATA INTO mydataset.mytable FROM FILES ( format = 'CSV', uris = ['gs://bucket/path/file.csv']);
按一下
「Run」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」一文。
bq
請使用 bq load
指令,然後使用 --source_format
旗標指定 CSV
,並加入 Cloud Storage URI。您可以加入單一 URI、以逗號分隔的 URI 清單,或包含萬用字元的 URI。
在結構定義檔中以內嵌方式提供結構定義,或使用結構定義自動偵測功能。如果您未指定結構定義,且 --autodetect
為 false
,且目的地表格已存在,則會使用目的地表格的結構定義。
指定 --replace
旗標來覆寫資料表。使用 --noreplace
旗標將資料附加至資料表。未指定任何標記時,預設為附加資料。
您可以在附加或覆寫資料表時,修改資料表的結構定義。如要進一步瞭解載入作業期間支援的結構定義變更,請參閱修改資料表結構定義一文。
(選用) 提供 --location
旗標,並將值設為您的位置。
其他選用標記包括:
--allow_jagged_rows
:如果有指定,系統會接受在 CSV 檔案中缺少結尾自選欄的資料列。系統會將缺少的值視為空值。如果取消勾選,系統會將缺少結尾資料欄的記錄視為損壞記錄;如果損壞記錄過多,工作結果中就會出現無效錯誤。預設值為false
。--allow_quoted_newlines
:如果有指定,系統會允許在 CSV 檔案中使用包含換行符號字元的引用資料區段。預設值為false
。--field_delimiter
:用來表示資料中資料欄間界線的字元,\t
和tab
都可用來表示 Tab 字元分隔。預設值為,
。--null_marker
:選用的自訂字串,代表 CSV 資料中的 NULL 值。--skip_leading_rows
:指定在 CSV 檔案頂端要略過的標題列數。預設值為0
。--quote
:用來括住記錄的引號字元。預設值為"
。如要表示沒有引號字元,請使用空白字串。--max_bad_records
:這是一個整數,用來指定整個工作失敗前可允許的錯誤記錄數量上限。預設值為0
。無論--max_bad_records
的值為何,系統最多只會傳回五個任何類型的錯誤。--ignore_unknown_values
:如果指定,CSV 或 JSON 資料中就可以含有其他無法辨識的值 (但系統會予以忽略)。--time_zone
:(預先發布) 選用的預設時區,會在剖析 CSV 或 JSON 資料中沒有特定時區的時間戳記值時套用。--date_format
:(預覽) 選用的自訂字串,定義 CSV 或 JSON 資料中日期值的格式。--datetime_format
:(預覽) 選用的自訂字串,可定義 CSV 或 JSON 資料中 DATETIME 值的格式。--time_format
:(預覽) 選用的自訂字串,定義 CSV 或 JSON 資料中 TIME 值的格式。--timestamp_format
:(預覽) 選用的自訂字串,可定義 CSV 或 JSON 資料中 TIMESTAMP 值的格式。--autodetect
:如果指定,系統就會針對 CSV 和 JSON 資料啟用結構定義自動偵測功能。--destination_kms_key
:用來加密資料表資料的 Cloud KMS 金鑰。
bq --location=location load \ --[no]replace \ --source_format=format \ dataset.table \ path_to_source \ schema
其中:
- location 是您的位置。
--location
是選用旗標。您可以使用 .bigqueryrc 檔案設定位置的預設值。 - format為
CSV
。 - dataset 是現有資料集。
- table 是您正在載入資料的資料表名稱。
- path_to_source 是完整的 Cloud Storage URI,或是以逗號分隔的 URI 清單。您也可以使用萬用字元。
- schema 是有效的結構定義。結構定義可以是本機 JSON 檔案,或以內嵌的方式在指令中輸入。您也可以改用
--autodetect
旗標,而非提供結構定義。
範例:
下列指令會載入 gs://mybucket/mydata.csv
中的資料,並覆寫 mydataset
中名為 mytable
的資料表。這個結構定義是使用結構定義自動偵測功能定義的。
bq load \
--autodetect \
--replace \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv
下列指令會載入 gs://mybucket/mydata.csv
中的資料,並將資料附加至 mydataset
中名為 mytable
的資料表。結構定義是使用 JSON 結構定義檔 (即 myschema.json
) 定義的。
bq load \
--noreplace \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
API
建立指向 Cloud Storage 中來源資料的
load
工作。source URIs
屬性必須是完整的,且必須符合下列格式:gs://bucket/object
。您可以使用逗號分隔清單的形式加入多個 URI。請注意,系統也支援使用萬用字元。藉由將
configuration.load.sourceFormat
屬性設為CSV
,以指定資料格式。藉由將
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 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
如要取代現有資料表中的資料列,請將 metadata
參數中的 writeDisposition
值設為 'WRITE_TRUNCATE'
。
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 PHP 設定說明進行操作。詳情請參閱 BigQuery PHP API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Python
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
如要取代現有資料表中的資料列,請將 LoadJobConfig.write_disposition 屬性設為 SourceFormat 常數 WRITE_TRUNCATE
。
載入 Hive 分區的 CSV 資料
BigQuery 支援載入儲存在 Cloud Storage 的 Hive 分區 CSV 資料,並且會在目的地 BigQuery 代管資料表中的資料欄,填入 Hive 分區的資料欄。詳情請參閱從 Cloud Storage 載入外部分區資料。
載入 CSV 資料的詳細資料
本節說明 BigQuery 如何處理各種 CSV 格式選項。
編碼
BigQuery 需要的 CSV 資料格式為 UTF-8 編碼。如果您的 CSV 檔案使用其他支援的編碼類型,請明確指定編碼,這樣 BigQuery 才能將資料正確轉換為 UTF-8。
BigQuery 支援下列 CSV 檔案的編碼類型:
- UTF-8
- ISO-8859-1
- UTF-16BE (UTF-16 大端序)
- UTF-16LE (UTF-16 小端)
- UTF-32BE (UTF-32 大端序)
- UTF-32LE (UTF-32 Little Endian)
如果您未指定編碼,或是在 CSV 檔案未以 UTF-8 編碼時指定 UTF-8 編碼,BigQuery 會嘗試將資料轉換為 UTF-8。一般來說,如果 CSV 檔案是以 ISO-8859-1 格式編碼,系統會成功載入資料,但資料可能不完全符合預期。如果 CSV 檔案採用 UTF-16BE、UTF-16LE、UTF-32BE 或 UTF-32LE 編碼,載入作業可能會失敗。為避免發生非預期的失敗情形,請使用 --encoding
標記指定正確的編碼。
如果 BigQuery 無法轉換 ASCII 0
字元以外的字元,就會將該字元轉換為標準的 Unicode 替換字元:�。
欄位分隔符號
CSV 檔案中的分隔符號可以是任何半形字元。如果來源檔案使用 ISO-8859-1 編碼,任何字元都可以做為分隔符。如果來源檔案使用 UTF-8 編碼,則可直接使用 1 到 127 的十進位範圍 (U+0001 到 U+007F) 中的任何字元,無須修改。您可以插入這個範圍以外的 ISO-8859-1 字元做為分隔符,BigQuery 會正確解讀這類字元。不過,如果您使用多位元字元做為分隔符,部分位元會誤解為欄位值的一部分。
一般來說,建議您使用標準的分隔符號,例如 tab、直立線或逗號。預設為半形逗號。
資料類型
布林值。BigQuery 可剖析下列任何一組布林值資料:1 或 0、true 或 false、t 或 f、是或否、y 或 n (所有大小寫皆可)。結構定義autodetection功能會自動偵測 0 和 1 以外的任何值。Bytes。BYTES 類型的資料欄必須採用 Base64 編碼。
Date。日期欄的格式必須為 YYYY-MM-DD
。
日期時間。使用 DATETIME 類型的欄必須採用 YYYY-MM-DD HH:MM:SS[.SSSSSS]
格式。
地理區域。使用 GEOGRAPHY 類型的資料欄必須包含下列其中一種格式的字串:
- 熟知的文字 (WKT)
- 熟知的二進位檔 (WKB)
- GeoJSON
如果您使用 WKB,則值應為十六進位編碼。
以下清單列出有效資料的範例:
- WKT:
POINT(1 2)
- GeoJSON:
{ "type": "Point", "coordinates": [1, 2] }
- 十六進位編碼的 WKB:
0101000000feffffffffffef3f0000000000000040
在載入 GEOGRAPHY 資料前,請參閱載入地理空間資料。
間隔。INTERVAL
類型的資料欄必須採用 Y-M D H:M:S[.F]
格式,其中:
- Y = 年。支援的範圍為 0 到 10,000。
- M = 月份。支援的範圍為 1 到 12。
- D = 天。支援的範圍為 1 到 [指定月份的最後一天]。
- H = 小時。
- M = 分鐘。
- S = 秒。
- [.F] = 秒數的小數,最多六位數,精確度為微秒。
您可以透過在前面加上破折號 (-) 來表示負值。
以下清單列出有效資料的範例:
10-6 0 0:0:0
0-0 -5 0:0:0
0-0 0 0:0:1.25
如要載入 INTERVAL 資料,您必須使用 bq load
指令,並使用 --schema
標記指定結構定義。您無法使用控制台上傳 INTERVAL 資料。
JSON。您可以使用兩個字元序列 ""
逸出引號。如需更多資訊,請參閱從 CSV 檔案載入 JSON 資料的範例
Time - 時間類型的資料欄必須採用 HH:MM:SS[.SSSSSS]
格式。
時間戳記。BigQuery 接受各種時間戳記格式。時間戳記必須包含日期和時間部分。
日期部分的格式可以是
YYYY-MM-DD
或YYYY/MM/DD
。時間戳記部分必須採用
HH:MM[:SS[.SSSSSS]]
格式 (秒數和秒數小數為選用項目)。日期和時間必須以空格或「T」分隔。
日期和時間後方可選加上世界標準時間偏移或世界標準時間區域指定元 (
Z
)。詳情請參閱「時區」一文。
舉例來說,下列任何一個值都是有效的時間戳記值:
- 2018-08-19 12:11
- 2018-08-19 12:11:35
- 2018-08-19 12:11:35.22
- 2018/08/19 12:11
- 2018-07-05 12:54:00 UTC
- 2018-08-19 07:11:35.220 -05:00
- 2018-08-19T12:11:35.220Z
如果您提供結構定義,BigQuery 也會接受 Unix 紀元時間做為時間戳記值。不過,結構定義自動偵測功能不會偵測這種情況,而是將值視為數值或字串類型。
以下是 Unix Epoch 紀元時間戳記值的範例:
- 1534680695
- 1.534680695e12
RANGE。在 CSV 檔案中以 [LOWER_BOUND, UPPER_BOUND)
格式表示,其中 LOWER_BOUND
和 UPPER_BOUND
為有效的 DATE
、DATETIME
或 TIMESTAMP
字串。NULL
和 UNBOUNDED
代表無限的起始或結束值。
以下是 RANGE<DATE>
的 CSV 值範例:
"[2020-01-01, 2021-01-01)"
"[UNBOUNDED, 2021-01-01)"
"[2020-03-01, NULL)"
"[UNBOUNDED, UNBOUNDED)"
結構定義自動偵測
本節將說明載入 CSV 檔案時,結構定義自動偵測功能的行為。
CSV 分隔符號
BigQuery 可偵測以下分隔符號:
- 半形逗號 ( , )
- 管線符號 ( | )
- 定位點 ( \t )
CSV 標頭
BigQuery 會將檔案的第一個資料列與檔案中的其他資料列做比較,藉此推測出標題。如果第一行只包含字串,而其他行包含其他資料類型,BigQuery 會假設第一行是標題資料列。BigQuery 會根據標題列中的欄位名稱指派資料欄名稱。名稱可能會經過修改,以符合 BigQuery 資料欄的命名規則。例如,空格會替換成底線。
否則,BigQuery 會假設第一列是資料列,並指派 string_field_1
等通用欄名稱。請注意,資料表建立後,雖然您可以在資料表建立後手動變更名稱,但無法在結構定義中更新資料欄名稱。另一個選項是提供明確的結構定義,而非使用自動偵測功能。
您可能會使用含有標題列的 CSV 檔案,其中所有資料欄位都是字串。在這種情況下,BigQuery 不會自動偵測第一列是標題。使用 --skip_leading_rows
選項略過標題列。否則,系統會將標頭匯入為資料。在這種情況下,您也可以考慮提供明確的結構定義,以便指派資料欄名稱。
CSV 引用的新行
BigQuery 會偵測 CSV 欄位內引用的新行字元,但不會將引用的新行字元解讀為資料列邊界。
排解剖析錯誤
如果剖析 CSV 檔案時發生問題,系統會在載入工作的工作 errors
資源中填入錯誤詳細資料。
一般來說,這些錯誤會使用位元組偏移量來指出問題行開始的位置。對於未壓縮的檔案,您可以使用 gcloud storage
搭配 --recursive
引數,存取相關的程式碼行。
舉例來說,您執行 bq load
指令時,會收到錯誤訊息:
bq load --skip_leading_rows=1 \ --source_format=CSV \ mydataset.mytable \ gs://my-bucket/mytable.csv \ 'Number:INTEGER,Name:STRING,TookOffice:STRING,LeftOffice:STRING,Party:STRING'
輸出內容中的錯誤會與以下內容類似:
Waiting on bqjob_r5268069f5f49c9bf_0000018632e903d7_1 ... (0s) Current status: DONE BigQuery error in load operation: Error processing job 'myproject:bqjob_r5268069f5f49c9bf_0000018632e903d7_1': Error while reading data, error message: Error detected while parsing row starting at position: 1405. Error: Data between close quote character (") and field separator. File: gs://my-bucket/mytable.csv Failure details: - gs://my-bucket/mytable.csv: Error while reading data, error message: Error detected while parsing row starting at position: 1405. Error: Data between close quote character (") and field separator. File: gs://my-bucket/mytable.csv - Error while reading data, error message: CSV processing encountered too many errors, giving up. Rows: 22; errors: 1; max bad: 0; error percent: 0
根據上述錯誤,檔案中有格式錯誤。如要查看檔案內容,請執行 gcloud storage cat
指令:
gcloud storage cat 1405-1505 gs://my-bucket/mytable.csv --recursive
輸出結果會與下列內容相似:
16,Abraham Lincoln,"March 4, 1861","April 15, "1865,Republican 18,Ulysses S. Grant,"March 4, 1869", ...
根據檔案的輸出內容,問題出在 "April 15, "1865
中不當的位置有引號。
壓縮 CSV 檔案
對於壓縮 CSV 檔案,剖析錯誤的偵錯作業會更加困難,因為所回報的位元組偏移量是指 未壓縮檔案中的位置。下列 gcloud storage cat
指令會從 Cloud Storage 串流檔案、解壓縮檔案、找出適當的位元組偏移量,並列印格式錯誤的資料行:
gcloud storage cat gs://my-bucket/mytable.csv.gz | gunzip - | tail -c +1406 | head -n 1
輸出結果會與下列內容相似:
16,Abraham Lincoln,"March 4, 1861","April 15, "1865,Republican
CSV 選項
如要變更 BigQuery 剖析 CSV 資料的方式,請在 Google Cloud 主控台、bq 指令列工具或 API 中指定額外選項。
如要進一步瞭解 CSV 格式,請參閱 RFC 4180。
CSV 選項 | 主控台選項 | bq 工具標記 | BigQuery API 屬性 | 說明 |
---|---|---|---|---|
欄位分隔符號 | 欄位分隔符號:逗號、定位點符號、管線符號及自訂符號 | -F 或--field_delimiter | fieldDelimiter (Java、Python) | (選用) CSV 檔案中的欄位分隔符。分隔符可以是任何 ISO-8859-1 半形字元。BigQuery 會將字串轉換成 ISO-8859-1 編碼格式,並使用已編碼字串的第一個位元組來分割原始的二進位資料。BigQuery 也支援使用逸出序列 "\t" 來指定定位點分隔符。預設值為逗號 (`,`)。 |
標題列 | 要略過的標題列 | --skip_leading_rows | skipLeadingRows (Java、Python) | (選用) 表示來源資料標題列數量的整數。 |
允許的損壞記錄數量 | 允許的錯誤數量 | --max_bad_records | maxBadRecords (Java、Python) | (選用) BigQuery 在執行工作時可忽略的損壞記錄數量上限。如果損壞記錄的數量超過這個值,工作結果中就會出現無效錯誤。預設值為 0,表示所有記錄都必須有效。 |
換行符號字元 | 允許引用換行符號 | --allow_quoted_newlines | allowQuotedNewlines (Java、Python) | (選用) 表示 CSV 檔案中是否允許包含換行符號字元的引用資料區段。預設值為 false。 |
自訂空值 | 無 | --null_marker | nullMarker (Java、Python) | (選用) 指定代表 CSV 檔案中空值的字串。例如,如果指定 "\N",載入 CSV 檔案時,BigQuery 會將 "\N" 解譯為空值。預設值為空字串。如果將這個屬性設為自訂值,當 STRING 與 BYTE 以外的所有資料類型出現空字串時,BigQuery 會擲回錯誤。BigQuery 會將 STRING 與 BYTE 資料欄的空字串解譯為空值。 |
結尾自選欄 | 允許不規則資料列 | --allow_jagged_rows | allowJaggedRows (Java、Python) | (選用) 接受缺少結尾自選欄的資料列。系統會將缺少的值視為空值。如為 false,系統會將缺少結尾資料欄的記錄視為損壞記錄;如果損壞記錄過多,工作結果中就會出現無效錯誤。預設值為 false。僅適用於 CSV,其他格式會忽略此選項。 |
不明的值 | 略過不明的值 | --ignore_unknown_values | ignoreUnknownValues (Java、Python) | (選用) 表示 BigQuery 是否應允許不在資料表結構定義中的其他值。如為 true,即會忽略其他值。如為 false,系統會將包含其他欄位的記錄視為損壞記錄;如果損壞記錄過多,工作結果中就會出現無效錯誤。預設值為 false。sourceFormat 屬性決定 BigQuery 將何種內容視為其他值:
|
引述 | 引號字元:雙引號、單引號、無、自訂 | --quote | quote (Java、Python) | (選用) 在 CSV 檔案中用來引用資料區段的值。BigQuery 會將字串轉換成 ISO-8859-1 編碼格式,並使用已編碼字串的第一個位元組來分割原始的二進位資料。預設值為雙引號 ('"')。如果資料未包含引用區段,請將這個屬性值設為空字串。如果資料包含引用的換行符號字元,您也必須將 allowQuotedNewlines 屬性設為 true 。如要在引號值中加入特定引號字元,請在引號前方加上額外的對應引號字元。舉例來說,如果您想逸出預設字元 ' " ',請使用 ' "" '。 |
編碼 | 無 | -E 或--encoding | encoding (Java、Python) | (選用) 資料的字元編碼。支援的值為 UTF-8、ISO-8859-1、UTF-16BE、UTF-16LE、UTF-32BE 或 UTF-32LE。預設值為 UTF-8。使用 quote 和 fieldDelimiter 屬性的值分割原始的二進位資料後,BigQuery 會將資料解碼。 |
ASCII 控制字元 | 無 | --preserve_ascii_control_characters | 無 | (選用) 如要允許 ASCII 0 和其他 ASCII 控制字元,請將 --preserve_ascii_control_characters 設為 true ,以便載入工作。 |
時區 | 時區 | --time_zone | 無 | (預覽) (選用) 剖析沒有特定時區的時間戳記值時,會採用的預設時區。查看有效的時區名稱。如果沒有這個值,則會使用預設時區 (UTC) 剖析沒有特定時區的時間戳記值。 |
日期格式 | 日期格式 | --date_format | 無 | (預覽) (選用) 格式元素,可定義輸入檔案中的 DATE 值格式 (例如 MM/DD/YYYY )。如果有這個值,這個格式就是唯一相容的 DATE 格式。結構定義自動偵測功能也會根據這個格式,而非現有格式,決定日期欄的類型。如果沒有這個值,系統會使用預設格式剖析日期欄位。 |
日期時間格式 | 日期時間格式 | --datetime_format | 無 | (預覽) (選用) 格式元素,可定義輸入檔案中的 DATETIME 值格式 (例如 MM/DD/YYYY HH24:MI:SS.FF3 )。如果有這個值,這個格式就是唯一相容的 DATETIME 格式。結構定義自動偵測功能也會根據這個格式,而非現有格式,決定 DATETIME 欄的類型。如果沒有這個值,系統會使用預設格式剖析 DATETIME 欄位。 |
時間格式 | 時間格式 | --time_format | 無 | (預覽) (選用) 格式元素,可定義輸入檔案中的 TIME 值格式 (例如 HH24:MI:SS.FF3 )。如果有這個值,這個格式是唯一相容的 TIME 格式。結構定義自動偵測功能也會根據這個格式,而非現有格式,決定 TIME 資料欄類型。如果沒有這個值,系統會使用預設格式剖析 TIME 欄位。 |
時間戳記格式 | 時間戳記格式 | --timestamp_format | 無 | (預覽) (選用) 格式元素,可定義輸入檔案中的 TIMESTAMP 值格式 (例如 MM/DD/YYYY HH24:MI:SS.FF3 )。如果有這個值,這個格式就是唯一相容的 TIMESTAMP 格式。結構定義自動偵測功能也會根據這個格式,而非現有格式,決定 TIMESTAMP 欄類型。如果沒有這個值,系統會使用預設格式剖析 TIMESTAMP 欄位。 |