從 Cloud Storage 載入 CSV 資料

從 Cloud Storage 載入 CSV 檔案

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

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

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

限制

若要將 CSV 資料從 Cloud Storage 載入至 BigQuery 資料表,請注意以下事項:

  • CSV 檔案不支援巢狀和重複的資料。
  • 如果您使用 gzip 壓縮,BigQuery 無法同時讀取資料。已壓縮的 CSV 資料載入至 BigQuery 的速度較未壓縮的資料慢。
  • 您無法在同一個載入工作中同時包含壓縮和未壓縮的檔案。
  • 載入 CSV 或 JSON 資料時,DATE 資料欄中的值必須使用連字號 (-) 分隔符,且必須採用下列日期格式:YYYY-MM-DD (年-月-日)。
  • 載入 JSON 或 CSV 資料時,TIMESTAMP 資料欄中的值必須使用連字號 (-) 分隔符來區隔時間戳記的日期部分,且必須採用下列日期格式:YYYY-MM-DD (年-月-日)。時間戳記的 hh:mm:ss (時-分-秒) 部分必須使用冒號 (:) 分隔符。

CSV 編碼

BigQuery 需要的 CSV 資料格式為 UTF-8 編碼。如果您的 CSV 檔案包含以 ISO-8859-1 (也稱為 Latin-1) 格式編碼的資料,載入資料時必須確實指定編碼,資料才能轉換成 UTF-8。

CSV 檔案中的分隔符號可以是任何 ISO-8859-1 半形字元。如果要使用 128-255 範圍內的字元,必須將字元編碼為 UTF-8。 BigQuery 會將字串轉換成 ISO-8859-1 編碼格式,並使用已編碼字串的第一個位元組來分割原始的二進位狀態資料。

所需權限

將資料載入 BigQuery 時,您必須具備相關權限,以便執行載入工作以及將資料載入新的或現有的 BigQuery 資料表和分區。如要從 Cloud Storage 載入資料,您也需要權限存取包含資料的值區。

BigQuery 權限

您至少要具備下列權限,才能將資料載入 BigQuery。不管您要將資料載入或附加到新的資料表或分區,還是覆寫資料表或分區資料,都需要這些權限。

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.jobs.create

以下是同時具有 bigquery.tables.createbigquery.tables.updateData 權限的預先定義 Cloud IAM 角色:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

以下是具有 bigquery.jobs.create 權限的預先定義 Cloud IAM 角色:

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

此外,當具備 bigquery.datasets.create 權限的使用者建立資料集時,會獲得該資料集的 bigquery.dataOwner 存取權。bigquery.dataOwner 存取權可讓使用者透過載入工作建立及更新資料集中的資料表。

如要進一步瞭解 BigQuery 中的 Cloud IAM 角色和權限,請參閱存取權控管

Cloud Storage 權限

您必須具備 storage.objects.get 權限,才能從 Cloud Storage 值區載入資料。如要使用 URI 萬用字元,您還必須具備 storage.objects.list 權限。

可以授予預先定義的 Cloud IAM 角色 storage.objectViewer,以提供 storage.objects.getstorage.objects.list 權限。

將 CSV 資料載入資料表

您可以透過下列方式將 CSV 資料從 Cloud Storage 載入至新的 BigQuery 資料表:

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

如要將 CSV 資料從 Cloud Storage 載入至新的 BigQuery 資料表:

主控台

  1. 在 Cloud Console 中開啟 BigQuery 網頁版 UI。
    前往 Cloud Console

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

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

    建立資料表

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

    • 針對「Create table from」(使用下列資料建立資料表),選取 [Cloud Storage]。

    • 在「source」(來源) 欄位中,瀏覽或輸入 Cloud Storage URI。請注意,在 Cloud Console 中不可包含多個 URI,但支援萬用字元。Cloud Storage 值區的位置必須與待建立資料表所在的資料集位置相同。

      選取檔案

    • 針對「File format」(檔案格式) 選取 [CSV]。

  5. 在「Create table」(建立資料表) 頁面的「Destination」(目的地) 部分:

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

      查看資料集

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

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

  6. 在「Schema」(結構定義) 區段的「Auto-detect」(自動偵測) 底下,勾選 [Schema and input parameters] (結構定義和輸入參數),以啟用結構定義自動偵測功能。您也可以透過下列方式手動輸入結構定義

    • 啟用 [Edit as text] (以文字形式編輯),然後以 JSON 陣列的形式輸入資料表結構定義。

      以 JSON 陣列新增結構定義

    • 使用 [Add Field] (新增欄位) 手動輸入結構定義。

      使用 [Add Field] (新增欄位) 按鈕加入結構定義

  7. (選用) 如要對資料表進行分區,請在「Partition and cluster settings」(分區與叢集設定) 區段中選擇您要使用的選項:

    • 如要建立分區資料表,請按一下 [No partitioning] (無分區),選取 [Partition by field] (依欄位分區),然後選擇 DATETIMESTAMP 資料欄。如果您的結構定義未包含 DATETIMESTAMP 資料欄,就無法使用這個選項。
    • 如要建立擷取時間分區資料表,請按一下 [No partitioning] (無分區),然後選取 [Partition by ingestion time] (依擷取時間分區)
  8. (選用) 在「Partitioning filter」(分區篩選器) 部分,勾選 [Require partition filter] (需要分區篩選器) 方塊,藉此要求使用者加入指定了待查詢分區的 WHERE 子句。使用分區篩選器可以降低成本並提升效能。詳情請參閱查詢分區資料表。如果選取了 [No partitioning] (無分區),就無法使用這個選項。

  9. (選用) 如要將資料表分群,請在「Clustering order」(分群順序) 方塊中輸入一到四個欄位名稱。分群法目前僅支援分區資料表。

  10. (選用) 按一下 [Advanced options] (進階選項)

    • 讓「Write preference」(寫入偏好設定) 的 [Write if empty] (空白時寫入) 選項維持在已選取狀態。這個選項能建立新的資料表,並將您的資料載入其中。
    • 針對「Number of errors allowed」(允許的錯誤數量),接受預設值 0,或輸入可忽略的含錯列數上限。如果含錯的列數超過這個值,該項工作就會導致 invalid 訊息並失敗。
    • 針對「Unknown values」(不明的值),勾選 [Ignore unknown values] (略過不明的值),這樣一來,當資料列不在資料表的結構定義中,系統就會忽略該資料列中的值。
    • 針對「Field delimiter」(欄位分隔符號),選擇在 CSV 檔案中分隔儲存格的字元:[Comma] (半形逗號)、[Tab] (定位點符號)、[Pipe] (管線符號) 或 [Custom] (自訂)。如果選擇 [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] (客戶代管的金鑰),以使用金鑰管理服務金鑰。如果您保留「Google-managed key」(Google 代管的金鑰) 設定,BigQuery 會加密靜態資料
  11. 按一下 [Create table] (建立資料表)

傳統版 UI

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

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

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

    • 按一下 [Create from source] (透過來源建立)
    • 對於「Location」(位置),選取 [Cloud Storage],並在來源欄位中,輸入 Cloud Storage URI。請注意,您無法在 BigQuery 網頁版 UI 中輸入多個 URI,但可以使用萬用字元。Cloud Storage 值區的位置必須與待建立資料表所在的資料集位置相同。
    • 針對「File format」(檔案格式) 選取 [CSV]。
  4. 在「Destination Table」(目標資料表) 區段中:

    • 在「Table name」(資料表名稱) 部分選擇合適的資料集,並在資料表名稱欄位中輸入要在 BigQuery 中建立的資料表名稱。
    • 確認「Table type」(資料表類型) 已設為「Native table」(原生資料表)。
  5. 在「Schema」(結構定義) 區段的「Auto-detect」(自動偵測) 底下,勾選 [Schema and input parameters] (結構定義和輸入參數),以啟用結構定義自動偵測功能。您也可以透過下列方式手動輸入結構定義

    • 按一下 [Edit as text] (以文字形式編輯),然後以 JSON 陣列的形式輸入資料表結構定義:

      以 JSON 陣列新增結構定義

    • 使用 [Add Field] (新增欄位) 手動輸入結構定義:

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

  6. (選用) 在「Options」(選項) 區段中:

    • 針對「Field delimiter」(欄位分隔符號),選擇在 CSV 檔案中分隔儲存格的字元:[Comma] (半形逗號)、[Tab] (定位點符號)、[Pipe] (管線符號) 或 [Other] (其他)。如果選擇 [Other] (其他),請在「Custom field delimiter」(自訂欄位分隔符號) 方塊中輸入分隔符號。預設值為 [Comma] (半形逗號)
    • 針對「Header rows to skip」(要略過的標題列),在 CSV 檔案頂端輸入要略過的標題列數。預設值為 0
    • 針對「Number of errors allowed」(允許的錯誤數量),接受預設值 0,或輸入可忽略的含錯列數上限。如果含錯的列數超過這個值,該項工作就會導致 invalid 訊息並失敗。
    • 針對「Allow quoted newlines」(允許引用換行符號),勾選核取方塊,以允許在 CSV 檔案中使用包含換行符號字元的引用資料區段。預設值為 false
    • 針對「Allow jagged rows」(允許不規則資料列),勾選核取方塊,以接受在 CSV 檔案中使用缺少結尾自選欄的資料列。系統會將缺少的值視為空值。如果取消勾選,系統會將缺少結尾資料欄的記錄視為損壞記錄;如果損壞記錄過多,工作結果中就會出現無效錯誤。預設值為 false
    • 針對「Ignore unknown values」(略過不明的值),勾選核取方塊,這樣一來,當資料列不在資料表的結構定義中,系統就會忽略該資料列中的值。
    • 讓「Write preference」(寫入偏好設定) 的 [Write if empty] (空白時寫入) 選項維持在已選取狀態。這個選項能建立新的資料表,並將您的資料載入其中。
    • 如要將資料表分區:
      • 對於 [Partitioning Type] (分區類型),按一下 [None] (無),並選擇 [Day] (日)。
      • 對於 [Partitioning Field] (分區欄位)
      • 如要建立分區資料表,請選擇 DATETIMESTAMP 資料欄。如果您的結構定義未包含 DATETIMESTAMP 資料欄,就無法使用這個選項。
      • 如要建立擷取時間分區資料表,請保留預設值:_PARTITIONTIME
      • 勾選 [Require partition filter] (需要分區篩選器) 方塊,要求使用者加入 WHERE 子句來指定要查詢的分區。使用分區篩選器可以降低成本並提升效能。詳情請參閱查詢分區資料表。如果 [Partitioning type] (分區類型) 設為 [None] (無),就無法使用這個選項。
    • 若要將資料表分群,請在「Clustering fields」(分群欄位) 方塊中,輸入一至四個欄位名稱。
    • 在「Destination encryption」(目的地加密) 中,按一下 [Customer-managed encryption] (客戶管理的加密),以便使用金鑰管理服務金鑰來加密資料表。如果您保留 Default 設定,BigQuery 會使用 Google 代管的金鑰加密靜態資料
  7. 按一下 [Create Table] (建立資料表)

CLI

請使用 bq load 指令,然後使用 --source_format 旗標指定 CSV,並加入 Cloud Storage URI。您可以加入單一 URI、以逗號分隔的 URI 清單,或包含萬用字元的 URI。在結構定義檔中以內嵌方式提供結構定義,或使用結構定義自動偵測功能。

(選用) 提供 --location 旗標,並將值設定為您的位置

其他選用的旗標包括:

  • --allow_jagged_rows:如果有指定,系統會接受在 CSV 檔案中缺少結尾自選欄的資料列。系統會將缺少的值視為空值。如果取消勾選,系統會將缺少結尾資料欄的記錄視為損壞記錄;如果損壞記錄過多,工作結果中就會出現無效錯誤。預設值為 false
  • --allow_quoted_newlines:如果有指定,系統會允許在 CSV 檔案中使用包含換行符號字元的引用資料區段。預設值為 false
  • --field_delimiter:用來表示資料中資料欄間界線的字元,\ttab 都可用來表示 Tab 字元分隔。預設值為 ,
  • --null_marker:選用的自訂字串,代表 CSV 資料中的 NULL 值。
  • --skip_leading_rows:指定在 CSV 檔案頂端要略過的標題列數。預設值為 0
  • --quote:用來括住記錄的引號字元。預設值為 "。如要表示沒有引號字元,請使用空白字串。
  • --max_bad_records:這是一個整數,用來指定整個工作失敗前可允許的錯誤記錄數量上限。預設值為 0。無論 --max_bad_records 的值為何,系統最多只會傳回五個任何類型的錯誤。
  • --ignore_unknown_values:如果指定,CSV 或 JSON 資料中就可以含有其他無法辨識的值 (但系統會予以忽略)。
  • --autodetect:如果指定,系統就會針對 CSV 和 JSON 資料啟用結構定義自動偵測功能。
  • --time_partitioning_type:針對資料表啟用時間分區並設定分區類型。目前唯一可使用的值為 DAY,亦即每天產生一個分區。如果您在 DATETIMESTAMP 資料欄建立分區資料表,則不一定要使用這個旗標。
  • --time_partitioning_expiration:這是一個整數,用來指定系統應在經過多少時間後刪除時間分區 (以秒為單位)。到期時間為分區的世界標準時間日期加上整數值。
  • --time_partitioning_field:用於建立分區資料表DATETIMESTAMP 資料欄。如果您在啟用時間分區時未提供這個值,系統就會建立擷取時間分區資料表
  • --require_partition_filter:啟用這個選項時,會要求使用者加入 WHERE 子句,以指定要查詢的分區。使用分區篩選器可以降低成本並提升效能。詳情請參閱查詢分區資料表
  • --clustering_fields:以逗號分隔的資料欄名稱清單 (最多四個名稱),可用來建立叢集資料表。這個旗標只能和分區資料表搭配使用。
  • --destination_kms_key:用於加密資料表資料的 KMS 金鑰。

    如要進一步瞭解分區資料表,請參閱:

    如要進一步瞭解叢集資料表,請參閱:

    如要進一步瞭解資料表加密作業,請參閱:

如要將 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 附註:

  • 載入工作不可部分完成,且資料狀態具一致性。如果載入工作失敗,所有資料都無法使用;如果載入工作成功,則所有資料都可以使用。

  • 最佳做法就是產生唯一識別碼,並在呼叫 jobReference.jobId 來建立載入工作時,將該唯一識別碼當做 jobs.insert 傳送。這個方法較不受網路故障問題的影響,因為用戶端可對已知的工作 ID 進行輪詢或重試。

  • 對指定的工作 ID 呼叫 jobs.insert 是一種冪等運算。也就是說,您可以對同一個工作 ID 重試無數次,最多會有一個作業成功。

C#

在嘗試這個範例之前,請至 BigQuery 快速入門:使用用戶端程式庫,按照 C# 設定說明進行操作。詳情請參閱 BigQuery C# API 參考說明文件


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.PollUntilCompleted();  // 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 參考資料說明文件

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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())
}

Java

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

Job job = table.load(FormatOptions.csv(), sourceUri);
// Wait for the job to complete
try {
  Job completedJob =
      job.waitFor(
          RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
          RetryOption.totalTimeout(Duration.ofMinutes(3)));
  if (completedJob != null && completedJob.getStatus().getError() == null) {
    // Job completed successfully
  } else {
    // Handle error case
  }
} catch (InterruptedException e) {
  // Handle interrupted wait
}

Node.js

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

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

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

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

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

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

load_job = client.load_table_from_uri(
    uri, dataset_ref.table("us_states"), job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(dataset_ref.table("us_states"))
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

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

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 資料附加或覆寫至資料表

如要將額外的資料載入至資料表,您可以指定來源檔案或附加查詢結果。

在主控台及傳統版 BigQuery 網頁版 UI 中,使用 [Write preference] (寫入偏好設定) 選項,指定從來源檔案或從查詢結果載入資料時採取的動作。

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

主控台選項 傳統網頁版 UI 選項 CLI 旗標 BigQuery API 屬性 說明
空白時寫入 空白時寫入 WRITE_EMPTY 資料表空白時才會寫入資料。
附加至資料表 附加至資料表 --noreplace--replace=false;如果未指定 --[no]replace,則預設動作為附加 WRITE_APPEND (預設值) 將資料附加至資料表尾端。
覆寫資料表 覆寫資料表 --replace--replace=true WRITE_TRUNCATE 清除資料表中所有現有資料後再寫入新的資料。

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

您可以透過下列方式附加或覆寫資料表:

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

主控台

  1. 在 Cloud Console 中開啟 BigQuery 網頁版 UI。
    前往 Cloud Console

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

  3. 在視窗右側的詳細資料面板中,按一下 [Create table] (建立資料表)。載入工作中的附加和覆寫資料程序與載入工作中建立資料表的程序相同。

    建立資料表

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

    • 針對「Create table from」(使用下列資料建立資料表),選取 [Cloud Storage]。

    • 在「source」(來源) 欄位中,瀏覽或輸入 Cloud Storage URI。請注意,您無法在 BigQuery 網頁版 UI 中輸入多個 URI,但可以使用萬用字元。Cloud Storage 值區的位置必須與待附加或待覆寫資料表所在的資料集位置相同。

      選取檔案

    • 針對「File format」(檔案格式) 選取 [CSV]。

  5. 在「Create table」(建立資料表) 頁面的「Destination」(目的地) 部分:

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

      選取資料集

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

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

  6. 在「Schema」(結構定義) 區段的「Auto-detect」(自動偵測) 底下,勾選 [Schema and input parameters] (結構定義和輸入參數),以啟用結構定義自動偵測功能。您也可以透過下列方式手動輸入結構定義

    • 啟用 [Edit as text] (以文字形式編輯),然後以 JSON 陣列的形式輸入資料表結構定義。

      以 JSON 陣列新增結構定義

    • 使用 [Add Field] (新增欄位) 手動輸入結構定義。

      使用 [Add Field] (新增欄位) 按鈕加入結構定義

  7. 保留「Partition and cluster settings」(分區與叢集設定) 中的預設值。您無法藉由附加或覆寫的方式,將資料表轉換為分區資料表或叢集資料表;Cloud Console 不支援在載入工作中對分區或叢集資料表執行附加或覆寫作業。

  8. 按一下 [Advanced options] (進階選項)

    • 針對「Write preference」(寫入偏好設定),選擇 [Append to table] (附加到資料表中) 或 [Overwrite table] (覆寫資料表)。
    • 針對「Number of errors allowed」(允許的錯誤數量),接受預設值 0,或輸入可忽略的含錯列數上限。如果含錯的列數超過這個值,該項工作就會導致 invalid 訊息並失敗。
    • 針對「Unknown values」(不明的值),勾選 [Ignore unknown values] (略過不明的值),這樣一來,當資料列不在資料表的結構定義中,系統就會忽略該資料列中的值。
    • 針對「Field delimiter」(欄位分隔符號),選擇在 CSV 檔案中分隔儲存格的字元:[Comma] (半形逗號)、[Tab] (定位點符號)、[Pipe] (管線符號) 或 [Custom] (自訂)。如果選擇 [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] (客戶代管的金鑰),以使用金鑰管理服務金鑰。如果您保留「Google-managed key」(Google 代管的金鑰) 設定,BigQuery 會加密靜態資料

      覆寫資料表

  9. 按一下 [Create table] (建立資料表)

傳統版 UI

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

  2. 在導覽面板中,將游標懸停在資料集上,按一下向下箭頭圖示 向下箭號圖示圖片,再按一下 [Create new table] (建立新資料表)。附加和覆寫資料的程序與在載入工作中建立資料表的程序相同。

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

    • 對於「Location」(位置),選取 [Cloud Storage],並在來源欄位中,輸入 Cloud Storage URI。請注意,您無法在 UI 中輸入多個 URI,但可以使用萬用字元。Cloud Storage 值區的位置必須與您要附加或覆寫的資料表所在的資料集位置相同。
    • 針對「File format」(檔案格式) 選取 [CSV]。
  4. 在「Create Table」(建立資料表) 頁面的「Destination Table」(目標資料表) 部分:

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

    • 如為 CSV 檔案,您可以勾選 [Auto-detect] (自動偵測) 選項以啟用結構定義自動偵測功能。

      自動偵測連結

    • 您也可以使用下列任一個方式手動輸入結構定義資訊:

      • 按一下 [Edit as text] (以文字形式編輯),然後以 JSON 陣列的形式輸入資料表結構定義:

        以 JSON 陣列新增結構定義

      • 使用 [Add Field] (新增欄位) 手動輸入結構定義:

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

  6. 在「Options」(選項) 區段中:

    • 針對「Field delimiter」(欄位分隔符號),選擇在 CSV 檔案中分隔儲存格的字元:[Comma] (半形逗號)、[Tab] (定位點符號)、[Pipe] (管線符號) 或 [Other] (其他)。如果選擇 [Other] (其他),請在「Custom field delimiter」(自訂欄位分隔符號) 方塊中輸入分隔符號。預設值為 [Comma] (半形逗號)
    • 針對「Header rows to skip」(要略過的標題列),在 CSV 檔案頂端輸入要略過的標題列數。預設值為 0
    • 針對「Number of errors allowed」(允許的錯誤數量),接受預設值 0,或輸入可忽略的含錯列數上限。如果含錯的列數超過這個值,該項工作就會導致 invalid 訊息並失敗。
    • 針對「Allow quoted newlines」(允許引用換行符號),勾選核取方塊,以允許在 CSV 檔案中使用包含換行符號字元的引用資料區段。預設值為 false
    • 針對「Allow jagged rows」(允許不規則資料列),勾選核取方塊,以接受在 CSV 檔案中使用缺少結尾自選欄的資料列。系統會將缺少的值視為空值。如果取消勾選,系統會將缺少結尾資料欄的記錄視為損壞記錄;如果損壞記錄過多,工作結果中就會出現無效錯誤。預設值為 false
    • 針對「Ignore unknown values」(略過不明的值),勾選核取方塊,這樣一來,當資料列不在資料表的結構定義中,系統就會忽略該資料列中的值。
    • 針對「Write preference」(寫入偏好設定),選擇 [Append to table] (附加到資料表中) 或 [Overwrite table] (覆寫資料表)。
    • 「Partitioning Type」(分區類型)、「Partitioning Field」(分區欄位)、「Require partition filter」(需要分區篩選器) 和「Clustering fields」(分群欄位) 等,請保留預設值。您無法藉由附加或覆寫的方式,將資料表轉換為分區資料表或叢集資料表;網頁版 UI 不支援在載入工作中對分區或叢集資料表執行附加或覆寫作業。
    • 在「Destination encryption」(目的地加密) 中,按一下 [Customer-managed encryption] (客戶管理的加密),以便使用金鑰管理服務金鑰來加密資料表。如果您保留 Default 設定,BigQuery 會使用 Google 代管的金鑰加密靜態資料
  7. 按一下 [Create Table] (建立資料表)

CLI

請使用 bq load 指令,然後使用 --source_format 旗標指定 CSV,並加入 Cloud Storage URI。您可以加入單一 URI、以逗號分隔的 URI 清單,或包含萬用字元的 URI。

在結構定義檔中以內嵌方式提供結構定義,或使用結構定義自動偵測功能。

指定 --replace 旗標來覆寫資料表。使用 --noreplace 旗標將資料附加至資料表。未指定任何旗標時,預設為附加資料。

您可以在附加或覆寫資料表時,修改資料表的結構定義。如要進一步瞭解載入作業期間支援的結構定義變更,請參閱修改資料表結構定義一文。

(選用) 提供 --location 旗標,並將值設定為您的位置

其他選用的旗標包括:

  • --allow_jagged_rows:如果有指定,系統會接受在 CSV 檔案中缺少結尾自選欄的資料列。系統會將缺少的值視為空值。如果取消勾選,系統會將缺少結尾資料欄的記錄視為損壞記錄;如果損壞記錄過多,工作結果中就會出現無效錯誤。預設值為 false
  • --allow_quoted_newlines:如果有指定,系統會允許在 CSV 檔案中使用包含換行符號字元的引用資料區段。預設值為 false
  • --field_delimiter:用來表示資料中資料欄間界線的字元,\ttab 都可用來表示 Tab 字元分隔。預設值為 ,
  • --null_marker:選用的自訂字串,代表 CSV 資料中的 NULL 值。
  • --skip_leading_rows:指定在 CSV 檔案頂端要略過的標題列數。預設值為 0
  • --quote:用來括住記錄的引號字元。預設值為 "。如要表示沒有引號字元,請使用空白字串。
  • --max_bad_records:這是一個整數,用來指定整個工作失敗前可允許的錯誤記錄數量上限。預設值為 0。無論 --max_bad_records 的值為何,系統最多只會傳回五個任何類型的錯誤。
  • --ignore_unknown_values:如果指定,CSV 或 JSON 資料中就可以含有其他無法辨識的值 (但系統會予以忽略)。
  • --autodetect:如果指定,系統就會針對 CSV 和 JSON 資料啟用結構定義自動偵測功能。
  • --destination_kms_key:用於加密資料表資料的 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_TRUNCATEWRITE_APPEND,以指定寫入偏好設定。

Go

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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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())
}

Node.js

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

如要取代現有資料表中的資料列,請將 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 參考說明文件

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

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

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
job_config.skip_leading_rows = 1
# The source format defaults to CSV, so the line below is optional.
job_config.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_ref, job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

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

載入 Hive 分區的 CSV 資料

BigQuery 支援載入儲存在 Cloud Storage 的 Hive 分區 CSV 資料,並且將會在目的地 BigQuery 代管資料表中的資料欄,填入 Hive 分區的資料欄。詳情請參閱從 Cloud Storage 載入外部分區資料

CSV 選項

如要變更 BigQuery 剖析 CSV 資料的方式,請在主控台、傳統版 UI、CLI 或 API 中指定額外選項。

如要進一步瞭解 CSV 格式,請參閱 RFC 4180

CSV 選項 主控台選項 傳統版 UI 選項 CLI 旗標 BigQuery API 屬性 說明
欄位分隔符號 欄位分隔符號:逗號、定位點符號、管線符號及自訂符號 欄位分隔符號:逗號、定位點符號及管線符號等 -F--field_delimiter fieldDelimiter (選用) CSV 檔案中的欄位分隔符。分隔符可以是任何 ISO-8859-1 半形字元。如果要使用 128-255 範圍內的字元,必須將字元編碼為 UTF8。BigQuery 會將字串轉換成 ISO-8859-1 編碼格式,並使用已編碼字串的第一個位元組來分割原始的二進位資料。BigQuery 也支援使用逸出序列 "\t" 來指定定位點分隔符。預設值為逗號 (`,`)。
標題列 要略過的標題列 要略過的標題列 --skip_leading_rows skipLeadingRows (選用) 表示來源資料標題列數量的整數。
允許的損壞記錄數量 允許的錯誤數量 允許的錯誤數量 --max_bad_records maxBadRecords (選用) BigQuery 在執行工作時可忽略的損壞記錄數量上限。如果損壞記錄的數量超過這個值,工作結果中就會出現無效錯誤。預設值為 0,表示所有記錄都必須有效。
換行符號字元 允許引用換行符號 允許引用換行符號 --allow_quoted_newlines allowQuotedNewlines (選用) 表示 CSV 檔案中是否允許包含換行符號字元的引用資料區段。預設值為 false。
自訂空值 --null_marker nullMarker (選用) 指定代表 CSV 檔案中空值的字串。例如,如果指定 "\N",載入 CSV 檔案時,BigQuery 會將 "\N" 解譯為空值。預設值為空字串。如果將這個屬性設為自訂值,當 STRING 與 BYTE 以外的所有資料類型出現空字串時,BigQuery 會擲回錯誤。BigQuery 會將 STRING 與 BYTE 資料欄的空字串解譯為空值。
結尾自選欄 允許不規則資料列 允許不規則資料列 --allow_jagged_rows allowJaggedRows (選用) 接受缺少結尾自選欄的資料列。系統會將缺少的值視為空值。如為 false,系統會將缺少結尾資料欄的記錄視為損壞記錄;如果損壞記錄過多,工作結果中就會出現無效錯誤。預設值為 false。僅適用於 CSV,其他格式會忽略此選項。
不明的值 略過不明的值 略過不明的值 --ignore_unknown_values ignoreUnknownValues (選用) 表示 BigQuery 是否應允許不在資料表結構定義中的其他值。如為 true,即會忽略其他值。如為 false,系統會將包含其他欄位的記錄視為損壞記錄;如果損壞記錄過多,工作結果中就會出現無效錯誤。預設值為 false。sourceFormat 屬性決定 BigQuery 將何種內容視為其他值:
  • CSV:結尾資料欄
  • JSON:與任何資料欄名稱均不相符的具名值
引號 --quote quote (選用) 在 CSV 檔案中用來引用資料區段的值。BigQuery 會將字串轉換成 ISO-8859-1 編碼格式,並使用已編碼字串的第一個位元組來分割原始的二進位資料。預設值為雙引號 ('"')。如果資料未包含引用區段,請將這個屬性值設為空字串。如果資料包含引用的換行符號字元,您也必須將 allowQuotedNewlines 屬性設為 true
編碼 -E--encoding encoding (選用) 資料的字元編碼。支援的值為 UTF-8 或 ISO-8859-1。預設值為 UTF-8。使用 quotefieldDelimiter 屬性的值分割原始的二進位資料後,BigQuery 會將資料解碼。