從 Cloud Firestore 匯出檔案載入資料

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

所需權限

如果您要將資料載入至 BigQuery,您必須擁有專案或資料集層級的權限,才能將資料載入至新的或現有的 BigQuery 資料表與分區。如果是從 Cloud Storage 載入檔案,您還需要擁有包含您的資料的值區存取權。

BigQuery 權限

如果您要將資料從 Cloud Storage 載入至 BigQuery,您必須獲得專案層級或資料集層級的 bigquery.dataOwnerbigquery.dataEditor 角色授權。這兩種角色授予使用者與群組將資料載入至新資料表或將資料附加至現有資料表或覆寫現有資料表的權限。

授予專案層級的角色可讓使用者或群組有權將資料載入至專案中任何資料集的資料表。授予資料集層級的角色可讓使用者或群組只能將資料載入至該資料集的資料表。

如需設定資料集存取權的詳細資訊,請參閱控管資料集存取權。如要進一步瞭解 BigQuery 中的身分與存取權管理 (IAM) 角色,請參閱存取權控管

Cloud Storage 權限

若要從 Cloud Storage 值區載入資料,您必須被授予專案層級的 storage.objects.get 授權或該個別值區的授權。如要使用 URI 萬用字元,您也必須具備 storage.objects.list 權限。

授予預先定義的身分與存取權角色 storage.objectViewer,即可提供 storage.objects.getstorage.objects.list 權限。

限制

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

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

載入 Cloud Firestore 匯出服務資料

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

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

主控台

  1. 在 GCP 主控台中開啟 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] (建立資料表)

指令列

使用 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. 建立載入工作設定指向 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 等對應欄位內指定欄位路徑。
允許的損壞記錄數量 Number of errors allowed --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 字串
本頁內容對您是否有任何幫助?請提供意見:

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

這個網頁