從 Cloud Firestore 匯出檔案載入資料

BigQuery 支援從使用 Cloud Firestore 代管的匯入與匯出服務建立的 Cloud Firestore 匯出檔案來載入資料。代管的匯入與匯出服務會將 Cloud Firestore 文件匯出至 Cloud Storage 值區,之後您可以將匯出的資料載入到 BigQuery 資料表中。

限制

當您在 BigQuery 中載入 Cloud Firestore 匯出檔案中的資料時,請注意下列幾點限制:

  • 您的資料集必須位於與包含匯出檔案的 Cloud Storage 值區相同的地區或多地區位置。
  • 您只能指定一個 Cloud Storage URI,且無法使用 URI 萬用字元。
  • Cloud Firestore 匯出資料中的文件必須有一致的結構定義,且其中不重複的欄位名稱數量未逾 10,000 個,這樣才能順利載入匯出資料。
  • 您可以建立新資料表來儲存資料,也可以覆寫現有資料表,但無法在現有資料表中附加 Cloud Firestore 匯出資料。
  • 您的匯出指令必須指定 collection-ids 篩選器。未指定集合 ID 篩選器的匯出資料無法載入 BigQuery。

所需權限

將資料載入 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 權限。

載入 Cloud Firestore 匯出服務資料

您可以使用 BigQuery 網頁版 UI、bq 指令列工具API 來載入 Cloud Firestore 匯出中繼資料檔案中的資料。

UI 或指令中有時會使用 Cloud Datastore 術語,不過下列程序與 Cloud Firestore 匯出檔案仍會相容。Cloud Firestore 與 Cloud Datastore 共用一種匯出格式。

主控台

  1. 在 GCP Console 中開啟 BigQuery 網頁版 UI。
    前往 BigQuery 網頁版 UI
  2. 在導覽面板的「Resources」(資源) 區段,展開您的專案並選取資料集。按一下 [Create table] (建立資料表)。載入資料的程序與建立空白資料表的程序相同。 建立資料表
  3. 在「Create table」(建立資料表) 頁面的「Source」(來源) 區段中:

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

    • 在「Source」(來源) 欄位中,輸入 Cloud Storage URI。Cloud Storage 值區必須和資料集位於相同位置。Cloud Firestore 匯出檔案 URI 的結尾應為 [KIND_COLLECTION_ID].export_metadata,例如 default_namespace_kind_Book.export_metadata。在本範例中,Book 是集合 ID,default_namespace_kind_Book 是由 Cloud Firestore 產生的檔案名稱。

      確認您的 Cloud Storage URI 中已指定 [KIND_COLLECTION_ID]。如果指定的 URI 中沒有 [KIND_COLLECTION_ID],您會收到以下錯誤訊息:does not contain valid backup metadata. (error code: invalid)

    • 在「File format」(檔案格式) 部分中,選取 [Cloud Datastore Backup] (Cloud Datastore 備份)。[Cloud Datastore Backup] (Cloud Datastore 備份) 是 Cloud Firestore 的所需選項。Cloud Firestore 與 Cloud Datastore 使用相同的匯出格式。

  4. 在「Create table」(建立資料表) 頁面的「Destination」(目的地) 區段中:

    • 在「Dataset name」(資料集名稱) 部分選擇合適的資料集。

      選取資料集

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

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

  5. 在「Schema」(結構定義) 區段中,無需採取任何行動。系統會推測 Cloud Firestore 匯出檔案的結構定義。

  6. 在「Advanced options」(進階選項) 區段中選取適合的項目。如果您要覆寫現有資料表,請將「Write preference」(寫入偏好設定) 設為 [Overwrite table] (覆寫資料表)

    覆寫資料表

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

傳統版 UI

  1. 前往傳統 BigQuery 網頁版 UI。
    前往 BigQuery 網頁版 UI
  2. 在導覽面板中,將游標懸停在某個資料集上,點選向下箭頭圖示 向下箭號圖示圖片,然後按一下 [Create new table] (建立新資料表)
  3. 在「Create Table」(建立資料表) 頁面的「Source Data」(來源資料) 區段中:

    • 保持選取 [Create from source]
    • 在「Location」(位置) 中選取 [Cloud Storage],然後在「Source」(來源) 欄位中輸入 Cloud Storage URI。Cloud Storage 值區必須與您的資料集位於相同位置。Cloud Firestore 匯出檔案 URI 的結尾應為 [KIND_COLLECTION_ID].export_metadata,例如 default_namespace_kind_Book.export_metadata。在本範例中,Book 是集合 ID,default_namespace_kind_Book 是由 Cloud Firestore 產生的檔案名稱。

      確認您的 Cloud Storage URI 中已指定 [KIND_COLLECTION_ID]。如果指定的 URI 中沒有 [KIND_COLLECTION_ID],您會收到以下錯誤訊息:does not contain valid backup metadata. (error code: invalid)

    • 在「File format」(檔案格式) 部分中,選取 [Cloud Datastore Backup] (Cloud Datastore 備份)。[Cloud Datastore Backup] (Cloud Datastore 備份) 是 Cloud Firestore 的所需選項。Cloud Firestore 與 Cloud Datastore 使用相同的匯出格式。

  4. 在「Create Table」(建立資料表) 頁面的「Destination Table」(目標資料表) 區段中:

    • 在「Table name」(資料表名稱) 部分選擇合適的資料集,並在資料表名稱欄位中輸入要在 BigQuery 中建立的資料表名稱。
    • 確認「Table type」(資料表類型) 已設為「Native table」(原生資料表)
  5. 在「Schema」(結構定義) 區段中,無需採取任何行動。系統會推測 Cloud Firestore 匯出檔案的結構定義。

  6. 在「Options」(選項) 區段中選取適合的項目。如果您要覆寫現有資料表,請將「Write preference」(寫入偏好設定) 設為 [Overwrite table] (覆寫資料表)

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

CLI

使用 bq load 指令,並將 source_format 設為 DATASTORE_BACKUP。提供 --location 標記,並將值設為您的位置。如果您要覆寫現有資料表,請加上 --replace 標記。

如果只要載入特定欄位,請使用 --projection_fields 標記

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

其中:

  • [LOCATION] 是您的位置。--location 是選用標記。
  • [FORMAT]DATASTORE_BACKUP。[Cloud Datastore Backup] (Cloud Datastore 備份) 是 Cloud Firestore 的所需選項。Cloud Firestore 與 Cloud Datastore 共用一種匯出格式。
  • [DATASET] 是特定資料集,該資料集包含您要在當中載入資料的資料表。
  • [TABLE] 是您要在當中載入資料的資料表。如果該資料表不存在,系統就會建立新資料表。
  • [PATH_TO_SOURCE]Cloud Storage URI

舉例來說,下列指令會在名為 book_data 的資料表中載入 gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata Cloud Firestore 匯出檔案。 mybucketmydataset 建立於 US 多地區位置。

bq --location=US load \
--source_format=DATASTORE_BACKUP \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

設定下列屬性,以便使用 API 載入 Cloud Firestore 匯出資料。

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

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

  3. sourceUris 必須完整且符合下列格式:gs://[BUCKET]/[OBJECT]。檔案 (物件) 名稱的結尾必須是 [KIND_NAME].export_metadata。您只能針對 Cloud Firestore 匯出檔案指定一個 URI,且不得使用萬用字元。

  4. 在載入工作設定中,將 sourceFormat 屬性設為 DATASTORE_BACKUP 以指定資料格式。[Cloud Datastore Backup] (Cloud Datastore 備份) 是 Cloud Firestore 的所需選項。Cloud Firestore 與 Cloud Datastore 使用相同的匯出格式。

  5. 如要僅載入特定欄位,請設定 projectionFields 屬性。

  6. 如要覆寫現有資料表,請將 writeDisposition 屬性設為 WRITE_TRUNCATE 以指定寫入配置。

Cloud Firestore 選項

如要變更 BigQuery 剖析 Cloud Firestore 匯出資料的方式,請指定下列選項:

CSV 選項 傳統版 UI 選項 CLI 標記 BigQuery API 屬性 說明
Projection fields (投影欄位) --projection_fields projectionFields (選用) 逗號分隔的清單,用來指定要從 Cloud Firestore 匯出檔案載入的文件欄位。根據預設,BigQuery 會載入所有欄位。欄位名稱區分大小寫,且必須存在於匯出檔案中。您無法在例如 map.foo 等對應欄位內指定欄位路徑。
允許的損壞記錄數量 允許的錯誤數量 --max_bad_records maxBadRecords (選用) BigQuery 在執行工作時可忽略的損壞記錄數量上限。如果損壞記錄的數量超過這個值,工作結果中就會出現無效錯誤。預設值為 0,表示所有紀錄都必須有效。

資料類型轉換

BigQuery 會將 Cloud Firestore 匯出檔案中各個文件的資料轉換成 BigQuery 的資料類型。下表說明不同資料類型的轉換對應關係。

Cloud Firestore 資料類型 BigQuery 資料類型
陣列 RECORD
布林值 BOOLEAN
參考資料 RECORD
日期和時間 TIMESTAMP
對應 RECORD
浮點數 FLOAT
地理點

RECORD


[{"lat","FLOAT"},
 {"long","FLOAT"}]
        
整數 INTEGER
字串 STRING (截斷至 64 KB)

Firestore 金鑰屬性

Cloud Firestore 中每個文件都有專屬金鑰,當中包含文件 ID 和文件路徑等資訊。BigQuery 會為金鑰建立 RECORD 資料類型 (也稱為 STRUCT),並透過巢狀欄位整理不同類型的資訊,如下表所示。

金鑰屬性 說明 BigQuery 資料類型
__key__.app Cloud Firestore 應用程式名稱。 字串
__key__.id 文件的 ID;如有設定 __key__.name,則為 null 整數
__key__.kind 文件的集合 ID。 字串
__key__.name 文件的名稱;如有設定 __key__.id,則為 null 字串
__key__.namespace Cloud Firestore 不支援自訂命名空間。預設命名空間會以空白字串表示。 字串
__key__.path 文件的路徑:文件的序列與根集合的集合配對。例如 "Country", "USA", "PostalCode", 10011, "Route", 1234 字串
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁