從 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 值區載入資料所需的權限，請要求管理員為您授予值區的儲存空間管理員 (roles/storage.admin) 身分與存取權管理角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

這個預先定義的角色具備從 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」(逐步引導)：

逐步引導

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往 BigQuery

  2. 在「Explorer」窗格中展開專案，然後選取資料集。
  3. 在「資料集資訊」部分中，按一下 「建立資料表」。
  4. 在「建立資料表」面板中，指定下列詳細資料：
    1. 在「來源」部分中，從「建立資料表來源」清單中選取「Google Cloud Storage」。 接著，按照下列步驟操作：
      1. 從 Cloud Storage 值區選取檔案，或輸入 Cloud Storage URI。 您無法在 Google Cloud 控制台中加入多個 URI，但支援使用萬用字元。Cloud Storage 值區的位置必須與要建立、附加或覆寫的表格所在的資料集位置相同。 選取來源檔案，建立 BigQuery 資料表
      2. 在「File format」(檔案格式) 部分，選取「CSV」。
    2. 在「目的地」部分，指定下列詳細資料：
      1. 在「Dataset」(資料集) 部分，選取要建立資料表的資料集。
      2. 在「Table」(資料表) 欄位中，輸入要建立的資料表名稱。
      3. 確認「Table type」(資料表類型) 欄位已設為「Native table」(原生資料表)。
    3. 在「Schema」(結構定義) 區段中，輸入結構定義。如要啟用結構定義自動偵測功能，請選取「Auto detect」(自動偵測)。 你可以使用下列其中一種方法，手動輸入結構定義資訊：
      • 選項 1：按一下「以文字形式編輯」，然後以 JSON 陣列的形式貼上結構定義。如果您使用 JSON 陣列，可透過與建立 JSON 結構定義檔一樣的程序產生結構定義。您可以輸入下列指令，查看現有資料表的 JSON 格式結構定義：
            bq show --format=prettyjson dataset.table
      • 選項 2：按一下 「新增欄位」，然後輸入表格結構定義。指定每個欄位的「Name」(名稱)、「Type」(類型) 和「Mode」(模式)。
    4. 選用：指定「分區與叢集設定」。詳情請參閱「建立分區資料表」和「建立及使用叢集資料表」。
    5. 按一下「進階選項」，然後執行下列操作：
      • 讓「Write preference」(寫入偏好設定) 的 [Write if empty] (空白時寫入) 選項維持在已選取狀態。這個選項能建立新的資料表，並將您的資料載入其中。
      • 針對「Number of errors allowed」(允許的錯誤數量)，請接受預設值 0，或輸入可忽略的含錯列數上限。如果含有錯誤的列數超過這個值，該項工作就會產生 invalid 訊息並發生失敗。這個選項僅適用於 CSV 和 JSON 檔案。
      • 在「時區」中，輸入剖析時間戳記值時要採用的預設時區，如果時間戳記值沒有特定時區，就會採用這個預設時區。如要查看更多有效的時區名稱，請按這裡。如果沒有這個值，系統會使用預設時區 UTC 剖析沒有特定時區的時間戳記值。(「預覽」)。
      • 在「Date Format」(日期格式) 輸入格式元素，定義輸入檔案中的 DATE 值格式。這個欄位應採用 SQL 樣式，例如 MM/DD/YYYY。如果這個值存在，則只有這個格式是相容的 DATE 格式。結構定義自動偵測功能也會根據這個格式，而非現有格式，決定 DATE 欄類型。如果沒有這個值，系統會使用預設格式剖析 DATE 欄位。(「預覽」)。
      • 在「日期時間格式」中，輸入 格式元素，定義輸入檔案中的 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 欄位會以預設格式剖析。 (「預覽」)。
      • 如要忽略不在資料表結構定義中的資料列值，請選取「Unknown values」(不明的值)。
      • 針對「Field delimiter」(欄位分隔符號)，選擇在 CSV 檔案中分隔儲存格的字元：[Comma] (半形逗號)、[Tab] (定位點符號)、[Pipe] (管線符號) 或 [Custom] (自訂)。如果選擇「自訂」，請在「自訂欄位分隔符號」方塊中輸入分隔符號。預設值為 [Comma] (半形逗號)。
      • 針對「Header rows to skip」(要略過的標題列)，在 CSV 檔案頂端輸入要略過的標題列數。預設值為 0。
      • 針對「Quoted newlines」(引用換行符號)，勾選「Allow quoted newlines」(允許引用換行符號)，以允許在 CSV 檔案中使用包含換行符號字元的引用資料區段。預設值為 false。
      • 針對「不規則資料列」，勾選「允許不規則資料列」，以接受在 CSV 檔案中使用缺少結尾自選欄的資料列。系統會將缺少的值視為空值。如果取消勾選，系統會將缺少結尾資料欄的記錄視為損壞記錄；如果損壞記錄過多，工作結果中就會出現無效錯誤。預設值為 false。
      • 針對「Encryption」(加密)，請按一下「Customer-managed key」(客戶管理的金鑰)，以使用 Cloud Key Management Service 金鑰。如果您保留 Google-managed key 設定，BigQuery 會加密靜態資料。
    6. 點選「建立資料表」。

SQL

使用 LOAD DATA DDL 陳述式。以下範例會將 CSV 檔案載入新資料表 mytable：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往 BigQuery

  2. 在查詢編輯器中輸入下列陳述式：

    LOAD DATA OVERWRITE mydataset.mytable
(x INT64,y STRING)
FROM FILES (
  format = 'CSV',
  uris = ['gs://bucket/path/file.csv']);

  3. 按一下「執行」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

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 資料中 DATE 值的格式。
  • --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

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

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

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

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

  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 參考說明文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。


using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsCsv
{
    public void LoadTableGcsCsv(
        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.csv";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        var destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            // The source format defaults to CSV; line below is optional.
            SourceFormat = FileFormat.Csv,
            SkipLeadingRows = 1
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob = loadJob.PollUntilCompleted().ThrowOnAnyError();  // 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 參考說明文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importCSVExplicitSchema demonstrates loading CSV data from Cloud Storage into a BigQuery
// table and providing an explicit schema for the data.
func importCSVExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
	}
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteEmpty

	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())
	}
	return nil
}

Java

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

// Sample to load CSV data from Cloud Storage into a new BigQuery table
public class LoadCsvFromGcs {

  public static void runLoadCsvFromGcs() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadCsvFromGcs(datasetName, tableName, sourceUri, schema);
  }

  public static void loadCsvFromGcs(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Skip header row in the file.
      CsvOptions csvOptions = CsvOptions.newBuilder().setSkipLeadingRows(1).build();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri, csvOptions).setSchema(schema).build();

      // Load data from a GCS CSV file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("CSV from GCS successfully added during load append job");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

// 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 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.csv';

async function loadCSVFromGCS() {
  // Imports a GCS file into a table with manually defined schema.

  /**
   * 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: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    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 參考說明文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

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.csv';
$schema = [
    'fields' => [
        ['name' => 'name', 'type' => 'string'],
        ['name' => 'post_abbr', 'type' => 'string']
    ]
];
$loadConfig = $table->loadFromStorage($gcsUri)->schema($schema)->skipLeadingRows(1);
$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 參考說明文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

使用 Client.load_table_from_uri() 方法，從 Cloud Storage 的 CSV 檔案載入資料。將 LoadJobConfig.schema 屬性設為 SchemaField 物件清單，以提供明確的結構定義。

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
    skip_leading_rows=1,
    # The source format defaults to CSV, so the line below is optional.
    source_format=bigquery.SourceFormat.CSV,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)  # Make an API request.
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

require "google/cloud/bigquery"

def load_table_gcs_csv 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.csv"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, skip_leading: 1 do |schema|
    schema.string "name"
    schema.string "post_abbr"
  end
  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

將 CSV 資料載入以資料欄為基礎的時間分區資料表

如要將 Cloud Storage 中的 CSV 資料載入至使用以資料欄為準的時間分區 BigQuery 資料表，請按照下列步驟操作：

Go

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。


import (
	"context"
	"fmt"
	"time"

	"cloud.google.com/go/bigquery"
)

// importPartitionedTable demonstrates specifing time partitioning for a BigQuery table when loading
// CSV data from Cloud Storage.
func importPartitionedTable(projectID, destDatasetID, destTableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states-by-date.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
		{Name: "date", Type: bigquery.DateFieldType},
	}
	loader := client.Dataset(destDatasetID).Table(destTableID).LoaderFrom(gcsRef)
	loader.TimePartitioning = &bigquery.TimePartitioning{
		Field:      "date",
		Expiration: 90 * 24 * time.Hour,
	}
	loader.WriteDisposition = bigquery.WriteEmpty

	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())
	}
	return nil
}

Java

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobId;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TimePartitioning;
import java.time.Duration;
import java.time.temporal.ChronoUnit;
import java.util.UUID;

public class LoadPartitionedTable {

  public static void runLoadPartitionedTable() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "/path/to/file.csv";
    loadPartitionedTable(datasetName, tableName, sourceUri);
  }

  public static void loadPartitionedTable(String datasetName, String tableName, String sourceUri)
      throws Exception {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      // Configure time partitioning. For full list of options, see:
      // https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#TimePartitioning
      TimePartitioning partitioning =
          TimePartitioning.newBuilder(TimePartitioning.Type.DAY)
              .setField("date")
              .setExpirationMs(Duration.of(90, ChronoUnit.DAYS).toMillis())
              .build();

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .build();

      // Create a job ID so that we can safely retry.
      JobId jobId = JobId.of(UUID.randomUUID().toString());
      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).setJobId(jobId).build());

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Data successfully loaded into time partitioned table during load job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println(
          "Data not loaded into time partitioned table during load job \n" + e.toString());
    }
  }
}

Node.js

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

// 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 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-by-date.csv';

async function loadTablePartitioned() {
  // Load data into a table that uses column-based time partitioning.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_new_table';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const partitionConfig = {
    type: 'DAY',
    expirationMs: '7776000000', // 90 days
    field: 'date',
  };

  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
        {name: 'date', type: 'DATE'},
      ],
    },
    location: 'US',
    timePartitioning: partitionConfig,
  };

  // 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.`);
}

Python

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
        bigquery.SchemaField("date", "DATE"),
    ],
    skip_leading_rows=1,
    time_partitioning=bigquery.TimePartitioning(
        type_=bigquery.TimePartitioningType.DAY,
        field="date",  # Name of the column to use for partitioning.
        expiration_ms=7776000000,  # 90 days.
    ),
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states-by-date.csv"

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Wait for the job to complete.

table = client.get_table(table_id)
print("Loaded {} rows to table {}".format(table.num_rows, table_id))

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

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

在 Google Cloud 主控台中，使用「寫入偏好設定」選項，指定從來源檔案或查詢結果載入資料時採取的動作。

將額外資料載入資料表時，可以選擇下列選項：

主控台選項 bq 工具標記 BigQuery API 屬性 說明
空白時寫入 不支援 WRITE_EMPTY 資料表空白時才會寫入資料。
附加到資料表中 --noreplace 或 --replace=false；如果未指定 --[no]replace，則預設動作為附加 WRITE_APPEND (預設) 將資料附加至資料表尾端。
覆寫資料表 --replace或--replace=true WRITE_TRUNCATE 先清除資料表中所有現有資料，再寫入新的資料。 這項操作也會刪除資料表結構定義、資料列層級安全性，並移除所有 Cloud KMS 金鑰。

如果您將資料載入現有資料表，該載入工作可附加資料，或覆寫資料表。

主控台

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往 BigQuery

  2. 在「Explorer」窗格中展開專案，然後選取資料集。
  3. 在「資料集資訊」部分中，按一下 「建立資料表」。
  4. 在「建立資料表」面板中，指定下列詳細資料：
    1. 在「來源」部分中，從「建立資料表來源」清單中選取「Google Cloud Storage」。 接著，按照下列步驟操作：
      1. 從 Cloud Storage 值區選取檔案，或輸入 Cloud Storage URI。 您無法在 Google Cloud 控制台中加入多個 URI，但支援使用萬用字元。Cloud Storage 值區的位置必須與要建立、附加或覆寫的表格所在的資料集位置相同。 選取來源檔案，建立 BigQuery 資料表
      2. 在「File format」(檔案格式) 部分，選取「CSV」。
    2. 在「目的地」部分，指定下列詳細資料：
      1. 在「Dataset」(資料集) 部分，選取要建立資料表的資料集。
      2. 在「Table」(資料表) 欄位中，輸入要建立的資料表名稱。
      3. 確認「Table type」(資料表類型) 欄位已設為「Native table」(原生資料表)。
    3. 在「Schema」(結構定義) 區段中，輸入結構定義。如要啟用結構定義自動偵測功能，請選取「Auto detect」(自動偵測)。 你可以使用下列其中一種方法，手動輸入結構定義資訊：
      • 選項 1：按一下「以文字形式編輯」，然後以 JSON 陣列的形式貼上結構定義。如果您使用 JSON 陣列，可透過與建立 JSON 結構定義檔一樣的程序產生結構定義。您可以輸入下列指令，查看現有資料表的 JSON 格式結構定義：
            bq show --format=prettyjson dataset.table
      • 選項 2：按一下 「新增欄位」，然後輸入表格結構定義。指定每個欄位的「Name」(名稱)、「Type」(類型) 和「Mode」(模式)。
    4. 選用：指定「分區與叢集設定」。詳情請參閱「建立分區資料表」和「建立及使用叢集資料表」。您無法藉由附加或覆寫的方式，將資料表轉換為分區資料表或叢集資料表。 Google Cloud 主控台不支援在載入工作中附加資料到分區或叢集資料表，也不支援覆寫這類資料表。
    5. 按一下「進階選項」，然後執行下列操作：
      • 針對「Write preference」(寫入偏好設定)，請選擇「Append to table」(附加到資料表中) 或「Overwrite table」(覆寫資料表)。
      • 針對「Number of errors allowed」(允許的錯誤數量)，請接受預設值 0，或輸入可忽略的含錯列數上限。如果含有錯誤的列數超過這個值，該項工作就會產生 invalid 訊息並發生失敗。這個選項僅適用於 CSV 和 JSON 檔案。
      • 在「時區」中，輸入剖析時間戳記值時要採用的預設時區，如果時間戳記值沒有特定時區，就會採用這個預設時區。如要查看更多有效的時區名稱，請按這裡。如果沒有這個值，系統會使用預設時區 UTC 剖析沒有特定時區的時間戳記值。(「預覽」)。
      • 在「Date Format」(日期格式) 輸入格式元素，定義輸入檔案中的 DATE 值格式。這個欄位應採用 SQL 樣式，例如 MM/DD/YYYY。如果這個值存在，則只有這個格式是相容的 DATE 格式。結構定義自動偵測功能也會根據這個格式，而非現有格式，決定 DATE 欄類型。如果沒有這個值，系統會使用預設格式剖析 DATE 欄位。(「預覽」)。
      • 在「日期時間格式」中，輸入 格式元素，定義輸入檔案中的 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 欄位會以預設格式剖析。 (「預覽」)。
      • 如要忽略不在資料表結構定義中的資料列值，請選取「Unknown values」(不明的值)。
      • 針對「Field delimiter」(欄位分隔符號)，選擇在 CSV 檔案中分隔儲存格的字元：[Comma] (半形逗號)、[Tab] (定位點符號)、[Pipe] (管線符號) 或 [Custom] (自訂)。如果選擇「自訂」，請在「自訂欄位分隔符號」方塊中輸入分隔符號。預設值為 [Comma] (半形逗號)。
      • 針對「Header rows to skip」(要略過的標題列)，在 CSV 檔案頂端輸入要略過的標題列數。預設值為 0。
      • 針對「Quoted newlines」(引用換行符號)，勾選「Allow quoted newlines」(允許引用換行符號)，以允許在 CSV 檔案中使用包含換行符號字元的引用資料區段。預設值為 false。
      • 針對「不規則資料列」，勾選「允許不規則資料列」，以接受在 CSV 檔案中使用缺少結尾自選欄的資料列。系統會將缺少的值視為空值。如果取消勾選，系統會將缺少結尾資料欄的記錄視為損壞記錄；如果損壞記錄過多，工作結果中就會出現無效錯誤。預設值為 false。
      • 針對「Encryption」(加密)，請按一下「Customer-managed key」(客戶管理的金鑰)，以使用 Cloud Key Management Service 金鑰。如果您保留 Google-managed key 設定，BigQuery 會加密靜態資料。
    6. 點選「建立資料表」。

SQL

使用 LOAD DATA DDL 陳述式。以下範例會將 CSV 檔案附加至 mytable 資料表：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往 BigQuery

  2. 在查詢編輯器中輸入下列陳述式：

    LOAD DATA INTO mydataset.mytable
FROM FILES (
  format = 'CSV',
  uris = ['gs://bucket/path/file.csv']);

  3. 按一下「執行」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」。

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 資料中 DATE 值的格式。
  • --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

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

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

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

  4. 藉由將 configuration.load.sourceFormat 屬性設為 CSV，以指定資料格式。

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

Go

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importCSVTruncate demonstrates loading data from CSV data in Cloud Storage and overwriting/truncating
// data in the existing table.
func importCSVTruncate(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.csv")
	gcsRef.SourceFormat = bigquery.CSV
	gcsRef.AutoDetect = true
	gcsRef.SkipLeadingRows = 1
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	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())
	}
	return nil
}

Java

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to overwrite the BigQuery table data by loading a CSV file from GCS
public class LoadCsvFromGcsTruncate {

  public static void runLoadCsvFromGcsTruncate() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    loadCsvFromGcsTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadCsvFromGcsTruncate(String datasetName, String tableName, String sourceUri)
      throws Exception {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);

      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(WriteDisposition.WRITE_TRUNCATE)
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job loadJob = bigquery.create(JobInfo.of(configuration));

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Table is successfully overwritten by CSV file loaded from GCS");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

如要取代現有資料表中的資料列，請將 metadata 參數中的 writeDisposition 值設為 'WRITE_TRUNCATE'。

// 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 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.csv';

async function loadCSVFromGCSTruncate() {
  /**
   * 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: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    // 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;
  }
}

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

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

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.csv';
$loadConfig = $table->loadFromStorage($gcsUri)->skipLeadingRows(1)->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 參考說明文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。 詳情請參閱「設定用戶端程式庫的驗證機制」。

如要取代現有資料表中的資料列，請將 LoadJobConfig.write_disposition 屬性設為 SourceFormat 常數 WRITE_TRUNCATE。

import six

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

body = six.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    source_format=bigquery.SourceFormat.CSV,
    skip_leading_rows=1,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

載入 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 Little Endian)
  • UTF-32BE (UTF-32 大端序)
  • UTF-32LE (UTF-32 Little Endian)

如果您未指定編碼格式，或指定 UTF-8 編碼格式，但 CSV 檔案並非以 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 會正確解讀。不過，如果使用多位元組字元做為分隔符號，系統可能會將部分位元組誤解為欄位值的一部分。

一般來說，建議您使用標準的分隔符號，例如定位點、直立線或逗號。預設值為半形逗號。

資料類型

Boolean。BigQuery 可以剖析下列任一組布林資料：1 或 0、true 或 false、t 或 f、yes 或 no，或是 y 或 n (所有大小寫不分)。結構定義自動偵測功能會自動偵測 0 和 1 以外的任何值。

位元組。BYTES 類型的資料欄必須採用 Base64 編碼。

Date。DATE 類型的資料欄必須採用 YYYY-MM-DD 格式。

日期時間。DATETIME 類型的資料欄必須採用 YYYY-MM-DD HH:MM:SS[.SSSSSS] 格式。

地理位置。GEOGRAPHY 類型的資料欄必須包含下列任一格式的字串：

  • Well-known text (WKT)
  • Well-known binary (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 - TIME 類型的資料欄必須採用 HH:MM:SS[.SSSSSS] 格式。

時間戳記。BigQuery 接受各種時間戳記格式。時間戳記必須包含日期和時間。

  • 日期部分可格式化為 YYYY-MM-DD 或 YYYY/MM/DD。

  • 時間戳記部分必須採用 HH:MM[:SS[.SSSSSS]] 格式 (秒數和秒數的小數部分為選填)。

  • 日期和時間之間必須以空格或「T」分隔。

  • 日期和時間後面可以加上 UTC 偏移或 UTC 區域指定元 (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

範圍。以 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 將何種內容視為其他值：
  • CSV：結尾資料欄
  • JSON：與任何資料欄名稱均不相符的具名值
引述 引用字元：雙引號、單引號、無、自訂 --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 格式。 結構定義自動偵測功能也會根據這個格式，而非現有格式，決定 DATE 資料欄類型。如果沒有這個值，系統會使用預設格式剖析 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 欄位。