複合式索引設定

Firestore (Datastore 模式) 會對您的應用程式發出的每一項查詢使用索引。這些索引會隨著實體的變更一併更新，因此應用程式執行查詢時，能夠快速得到結果。Datastore 模式會自動提供內建索引，但需要事先得知應用程式需要的複合式索引。您可在設定檔中指定應用程式需要哪些複合式索引。Datastore 模擬器可在您測試應用程式時，自動產生 Datastore 模式複合式索引設定。gcloud 指令列工具提供了各種指令，能讓您更新可供實際工作環境 Datastore 模式資料庫使用的索引。

系統需求

如要使用 gcloud CLI，必須先安裝 Google Cloud CLI。

關於 index.yaml

應用程式發出的每一個 Datastore 模式查詢都需要有對應的索引。系統會自動建立簡單查詢的索引 (例如針對單一屬性的查詢)，如要進行複雜查詢，您必須在名為 index.yaml 的設定檔中定義複合式索引。這個檔案會隨應用程式上傳，然後在 Datastore 模式資料庫中建立複合索引。

當應用程式嘗試執行需要複合式索引的查詢時，如果設定檔中沒有合適的項目，Datastore 模擬器會自動在此檔案中新增項目。您可以調整複合索引，或是以手動方式編輯檔案來建立新的索引。index.yaml 位於 <project-directory>/WEB-INF/ 資料夾中。根據預設，含有 WEB-INF/appengine-generated/index.yaml 的資料目錄是 ~/.config/gcloud/emulators/datastore/。如需其他詳細資料，請參閱 Datastore 模擬器專案目錄的相關說明。

index.yaml 檔案的範例如下：

indexes:

- kind: Task
  ancestor: no
  properties:
  - name: done
  - name: priority
    direction: desc

- kind: Task
  properties:
  - name: collaborators
    direction: asc
  - name: created
    direction: desc

- kind: TaskList
  ancestor: yes
  properties:
  - name: percent_complete
    direction: asc
  - name: type
    direction: asc

index.yaml 的語法是 YAML 格式。如要進一步瞭解這種語法，請參閱 YAML 網站。

複合式索引定義

index.yaml 具有名叫 indexes 的單一清單元素。清單中的每個元素都代表應用程式的複合索引。

索引元素可以有下列元素：

kind
查詢的實體種類。此為必要元素。
properties

依排序順序，以複合索引欄形式加入的屬性清單：先加入用於等式篩選器的屬性，再加入用於不等式篩選器的屬性，然後是排序順序及其排序方向。

此清單中的每個元素都具有下列元素：

name
屬性的 Datastore 模式名稱。
direction
此為排序方向，asc 代表遞增，desc 代表遞減。只有用於查詢的排序順序屬性才需要此排序方向，且必須符合查詢所使用的方向。預設值為 asc。
ancestor

如果查詢包含祖系子句，則為 yes。預設值為 no。

自動和手動複合式索引

當 Datastore 模擬器將產生的複合索引定義新增到 index.yaml 時，會視需要將定義插入到以下這行底下：

# AUTOGENERATED

模擬器會將這一行下方的所有複合索引定義視為自動項目，並且會在應用程式執行查詢時，更新這一行下方的現行定義。

系統會將所有位在這個行列上方的複合式索引定義視為手動控制，因此模擬器不會更新這些定義。模擬器僅會變更這個字行下方的定義，且僅在完整的 index.yaml 檔案並未描述負責應用程式所執行查詢的複合索引時，才會進行這類變更。如要控制自動複合索引定義，請將索引移至此行上方。

更新複合式索引

datastore indexes create 指令會檢查本機 Datastore 複合式索引設定 (index.yaml 檔案)，如果複合式索引設定定義的複合式索引尚不存在於您實際工作環境的 Datastore 模式資料庫中，您的資料庫就會建立新的複合式索引。如要瞭解如何使用 indexes create，請參閱使用 gcloud CLI 的開發工作流程。

如要建立複合式索引，資料庫必須設定複合式索引，然後使用現有資料回填複合式索引。複合式索引建立時間是設定時間和回填時間的總和：

  • 設定複合索引需要幾分鐘的時間。即使是空白資料庫，建立複合式索引也至少需要幾分鐘。

  • 回填時間取決於屬於新複合索引的現有資料量。複合式索引包含的屬性值越多，回填複合式索引所需的時間就越長。

如果應用程式執行的查詢需要的複合式索引尚未建構完成，查詢動作將會引發例外狀況。如要防止這個狀況發生，在新複合式索引建構完成之前，您必須小心部署需要複合式索引的新版應用程式。

您可以在Google Cloud 控制台的「索引」頁面中查看複合式索引的狀態。

刪除未使用的複合式索引

當您變更或移除複合索引設定中的複合索引時，系統「不會」自動從 Datastore 模式資料庫中刪除原始複合索引。因此，您可以在執行舊版應用程式的同時建置新的複合索引，也可以在新版出現問題時立即將其還原為舊版。

如果確認不再需要舊的複合索引，可以使用 datastore indexes cleanup 指令將其刪除。這個指令會刪除未在 index.yaml 本機版本中提及之所有實際工作環境 Datastore 模式執行個體的複合索引。如要瞭解如何使用 indexes cleanup，請參閱使用 gcloud CLI 的開發工作流程。

指令列引數

如要進一步瞭解建立及清除複合索引的指令列引數，請分別參閱 datastore indexes create 和 datastore indexes cleanup。如要進一步瞭解 gcloud CLI 的指令列引數，請參閱 gcloud CLI 參考資料。

管理長時間執行的作業

複合式索引建構作業是長時間執行的作業，可能需要相當長的時間才能完成。

開始建構複合索引後，Datastore 模式會為作業指派專屬名稱。作業名稱的前置字串為 projects/[PROJECT_ID]/databases/(default)/operations/，例如：

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

不過，為 describe 指令指定作業名稱時，可以省略前置字串。

列出所有長時間執行的作業

如要列出長時間執行的作業，請使用 gcloud datastore operations list 指令。這個指令會列出進行中和最近完成的作業。 匯出完成後其項目會保留幾天以供存取：

gcloud

gcloud datastore operations list

rest

使用任何要求資料之前，請先替換以下項目：

  • project-id：您的專案 ID

HTTP 方法和網址：

GET https://datastore.googleapis.com/v1/projects/project-id/operations

如要傳送要求，請展開以下其中一個選項：

請查看以下回應的相關資訊。

舉例來說，最近完成的複合索引建構作業會顯示下列資訊：

{
  "operations": [
  {
    "name": "projects/project-id/operations/S01vcFVpSmdBQ0lDDCoDIGRiNTdiZDQNmE4YS0yMTVmNWUzZSQadGx1YWZlZAcSMXRzYWVzdS1yZXhlZG5pLW5pbWRhFQpWEg",
    "done": true,
    "metadata": {
      "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
      "common": {
        "endTime": "2020-06-23T16:55:29.923562Z",
        "operationType": "CREATE_INDEX",
        "startTime": "2020-06-23T16:55:10Z",
        "state": "SUCCESSFUL"
      },
      "indexId": "CICAJiUpoMK",
      "progressEntities": {
        "workCompleted": "2193027",
        "workEstimated": "2198182"
      }
    },
    "response": {
      "@type": "type.googleapis.com/google.datastore.admin.v1.Index",
      "ancestor": "NONE",
      "indexId": "CICAJiUpoMK",
      "kind": "Task",
      "projectId": "project-id",
           "properties": [
        {
          "direction": "ASCENDING",
          "name": "priority"
        },
        {
          "direction": "ASCENDING",
          "name": "done"
        },
        {
          "direction": "DESCENDING",
          "name": "created"
        }
      ],
      "state": "READY"
    }
  },
  ]
}

描述單一作業

您可以列出單一作業的詳細資料，而不必列出所有長時間執行的作業：

gcloud

使用 operations describe 指令顯示複合索引建構的狀態。

gcloud datastore operations describe operation-name

rest

使用任何要求資料之前，請先替換以下項目：

  • project-id：您的專案 ID

HTTP 方法和網址：

GET https://datastore.googleapis.com/v1/projects/project-id/operations

如要傳送要求，請展開以下其中一個選項：

請查看以下回應的相關資訊。

估算完成時間

作業執行時，可查看 state 欄位值，以瞭解作業的整體狀態。

用於取得長時間執行作業狀態的要求，也會傳回 workEstimated 和workCompleted 指標。這些指標會針對實體數量回傳。workEstimated 會根據資料庫統計資料，顯示作業將要處理的實體總數預估值。workCompleted 會顯示目前處理過的實體數。作業完成後，workCompleted 會反映出實際處理的實體總數，可能與 workEstimated 的值不同。

將 workCompleted 除以 workEstimated 可得出進度的粗估值。此估計可能不準確，因為此取決於延遲的統計數據收集。

舉例來說，以下是複合式索引建構作業的進度狀態：

{
  "operations": [
    {
      "name": "projects/project-id/operations/AyAyMDBiM2U5NTgwZDAtZGIyYi0zYjc0LTIzYWEtZjg1ZGdWFmZWQHEjF0c2Flc3UtcmV4ZWRuaS1uaW1kYRUKSBI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.IndexOperationMetadata",
        "common": {
          "operationType": "CREATE_INDEX",
          "startTime": "2020-06-23T16:52:25.697539Z",
          "state": "PROCESSING"
        },
        "progressEntities": {
          "workCompleted": "219327",
          "workEstimated": "2198182"
        }
       },
    },
    ...

作業完成時，作業說明中會包含 "done": true。查看 state 欄位值可得知作業結果。如果未在回應中設定 done 欄位，則其值為 false。若是進行中的作業，則不用考慮是否有 done 值。