資料儲存庫索引

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

附註：我們強烈建議建構新應用程式的開發人員使用 NDB 用戶端程式庫，因為 NDB 用戶端程式庫與本用戶端程式庫相較之下有幾個優點，例如能透過 Memcache API 自動將實體加入快取。如果您目前使用的是舊版的 DB 用戶端程式庫，請參閱從 DB 至 NDB 的遷移指南。

應用程式引擎會針對實體的每個屬性預先定義簡單的索引。App Engine 應用程式可在名為 index.yaml 的索引設定檔中進一步定義自訂索引。開發伺服器遇到無法使用現有索引執行的查詢時，即會自動在這個檔案中新增建議。您可在上載應用程式之前編輯設定檔，以手動調整索引。

附註：基於索引的查詢機制支援各種查詢，適用於大多數應用程式。不過，這種機制並不支援其他資料庫技術常見的某些查詢種類，Datastore 查詢引擎尤其不支援彙整與匯總查詢。如要瞭解 Datastore 查詢的限制，請參閱 Datastore 查詢頁面。

索引定義和結構

索引的定義列於指定實體種類的屬性清單中，每個屬性會有對應的排序順序 (遞增或遞減)。如需與祖系查詢一同使用，索引也可以選擇是否包含實體的祖系。

索引表格中，該索引定義中提及的屬性都各自有一欄。表格中的每一列代表 Datastore 中的一個實體，且此實體可能是以索引為基礎的查詢結果。只有在索引使用的每個屬性均已設定編入索引的值時，該實體才會加入索引中；如果索引定義參照實體未設有值的屬性，該實體將不會出現在索引中，且因此不會在任何基於該索引的查詢結果中傳回。

注意：Datastore 會區分不含屬性值的實體，以及屬性值含空值 (None) 的實體。如果您明確將實體的屬性指定為空值，該實體便可能列入參照該屬性的查詢結果中。

注意：如果索引含有多個屬性，則每個屬性不得設為未編入索引。

索引表的資料列會依照索引定義的指定順序，先按祖系排序，再按屬性值排序。查詢的「完美索引」可以讓查詢以最有效率的方式執行，此索引由下列屬性依序定義：

1. 等式篩選器使用的屬性
2. 不等式篩選器使用的屬性 (可以不超過一個)
3. 排序順序使用的屬性

這可確保每個潛在查詢執行作業的所有結果，都會出現在表格的連續列中。Datastore 會依照下列步驟使用完美索引執行查詢：

1. 找出查詢種類、篩選屬性、篩選運算子以及排序順序所對應的索引。
2. 從索引的開頭開始掃描，直至找出符合該查詢所有篩選條件的第一個實體。
3. 連續掃描索引，依次傳回每個實體，直到：
   • 遇到不符合篩選條件的實體，或
   • 抵達索引尾端，或
   • 已收集到查詢所要求的結果數上限。

例如，請思考以下的查詢 (在 GQL 中聲明)：

SELECT * FROM Person WHERE last_name = "Smith"
                       AND height < 72
                  ORDER BY height DESC

此查詢的完美索引是 Person 種類實體的索引鍵表格，其中包含 last_name 和 height 屬性值的欄。索引的排序方式是先依 last_name 遞增排序，再依 height 遞減排序。

如要產生這些索引，請按照下列方式設定索引：

indexes:
- kind: Person
  properties:
  - name: last_name
    direction: asc
  - name: height
    direction: desc

屬於相同表單但具有不同篩選器值的兩個查詢，將使用相同的索引。例如，以下查詢使用與前述查詢相同的索引：

SELECT * FROM Person WHERE last_name = "Jones"
                       AND height < 63
                     ORDER BY height DESC

以下兩個查詢雖然形式不同，但也使用相同索引：

SELECT * FROM Person WHERE last_name = "Friedkin"
                       AND first_name = "Damian"
                     ORDER BY height ASC

和

SELECT * FROM Person WHERE last_name = "Blair"
                  ORDER BY first_name, height ASC

索引設定

根據預設，Datastore 會針對每種實體種類的每個屬性，自動預先定義索引。這些預先定義的索引便足以執行許多簡易查詢，例如只使用等式的查詢以及簡易的不等式查詢。對於所有其他查詢，應用程式必須在名為 index.yaml 的索引設定檔中定義所需的索引。如果應用程式嘗試執行的查詢無法以可用索引 (預先定義的索引，或是索引設定檔指定的索引) 執行，查詢便會失敗並顯示 NeedIndexError 例外狀況。

Datastore 會為下列形式的查詢建構自動索引：

• 僅使用祖系和金鑰篩選器的無種類查詢
• 僅使用祖系和等式篩選條件的查詢
• 僅使用不等式篩選條件的查詢 (只限單一屬性)
• 只使用祖系篩選條件、等式篩選條件 (查詢屬性)，以及不等式篩選條件 (查詢金鑰) 的查詢
• 沒有篩選條件，且只有一個按遞增或遞減順序查詢屬性的排序順序

其他形式的查詢必須在索引設定檔中指定索引，包含：

• 使用祖系和不等式篩選條件的查詢
• 使用一或多個不等式篩選條件查詢某個屬性，並使用一或多個等式查詢其他屬性的查詢
• 按遞減順序排序金鑰的查詢
• 採用多種排序順序的查詢

索引和屬性

關於索引以及索引與 Datastore 中實體屬性之間的關聯性，請謹記以下幾項注意事項：

具有混合值類型的屬性

如果兩個實體所含的屬性名稱相同但值類型不同，屬性索引會先依據值類型排序實體，再按照適合各個類型的次要順序排序。舉例來說，如果兩個實體各有一個名為 age 的屬性，其中一個含有整數值，另一個含有字串值，則在依 age 屬性排序時，不論屬性值本身為何，含有整數值的實體一律排在含有字串值的實體之前。

如果是整數和浮點數，尤其要注意這一點，因為 Datastore 會將這兩種類型視為不同的類型。由於會先排序所有整數再排序所有浮點數，因此若屬性含整數值 38，其排序順序就會在含浮點值 37.5 的屬性之前。

未編入索引的屬性

如果您確定永遠都不需要篩選或排序特定屬性，則可以將該屬性宣告為「未編入索引」，藉以告知 Datastore 不用維護該屬性的索引項目。這樣可以降低必須執行的 Datastore 寫入次數，進而減少應用程式的執行費用。含有未編入索引屬性的實體，行為方式與未設定該屬性的實體一樣：該實體將永遠不符合篩選或排序該屬性的查詢。

附註：如果屬性出現在由多個屬性組成的索引中，將該屬性設為未編入索引，便會防止該屬性編入多屬性的索引中。

舉例來說，假設某實體含有「a」和「b」兩種屬性，且您想要建立一個能夠符合諸如 WHERE a ="bike" and b="red" 查詢的索引。另外假設您對查詢 WHERE a="bike" 和 WHERE b="red" 不感興趣。如果您將「a」設為「不編入索引」，並為「a」和「b」建立索引，Datastore 不會為「a」和「b」索引建立索引項目，因此 WHERE a="bike" and b="red" 查詢無法發揮作用。如要讓 Datastore 為「a」和「b」索引建立項目，「a」和「b」皆必須編入索引。

您可以在屬性建構函式中設定 indexed=False，藉此宣告特定屬性不編入索引：

class Person(db.Model):
  name = db.StringProperty()
  age = db.IntegerProperty(indexed=False)

之後您可以使用 indexed=True 再次呼叫建構函式，將屬性改回已編入索引：

class Person(db.Model):
  name = db.StringProperty()
  age = db.IntegerProperty(indexed=True)

但請注意，將屬性從未編入索引變更為編入索引，並不會影響改變之前建立的任何現有實體。查詢使用該屬性進行篩選時，將不會傳回這類現有實體，因為這些實體在建立時並未寫入查詢的索引。為使實體可供未來的查詢使用，您必須將實體重新寫入 Datastore，才能讓實體加入適當的索引中。亦即，您必須為每個現有實體執行以下動作：

1. 從 Datastore 擷取 (get) 實體。
2. 將實體寫入 (put) 回 Datastore。

同樣地，將屬性從已編入索引變更為未編入索引，只會影響後續寫入 Datastore 的實體。在更新或刪除實體之前，含有該屬性的任何現有實體仍會保有其索引項目。為了避免不必要的結果，您必須清除按該屬性 (現在未編入索引的屬性) 篩選或排序的所有查詢程式碼。

索引限制

針對可以與單一實體相關聯的索引項目，Datastore 會限制數量和總體大小。這些限制相當寬鬆，大多數應用程式都不受影響。不過，有些情況下您可能會受到限制。

如前文所述，Datastore 會針對每個實體的每個屬性，在預先定義索引中建立一個項目，但不含長文字字串 (Text)、長位元組字串 (Blob) 和您已明確聲明為未編入索引的屬性。另外，該項屬性也有可能包含在 index.yaml 設定檔中宣告的額外自訂索引中。如果實體並未列出屬性，則實體在每個這類的自訂索引 (非祖系索引) 中最多有一個項目，或在每個祖系 (祖系索引) 中有一個項目。每次變更屬性值時，就必須更新每個索引項目。

如果某屬性在每個實體只有單一值，便必須在該屬性的預先定義索引中，為每個實體儲存僅一次每個可能的值。即便如此，仍可能有實體因為該單一值屬性過大，導致超過索引項目或大小限制。同樣地，相同屬性可以有多個值的實體必須為每個值儲存不同的索引項目；同理，如果可能值的數字太大，便可能超過項目限制。

如果實體含有多個屬性，而每個屬性都有多個值，則情況會變得更嚴重。為了適應這類實體，索引必須包含每個可能屬性值「組合」的項目。如果自訂索引參照多個屬性，且每個屬性有多個值，只要實體有大量項目及相對較少的可能屬性值，便可能在組合的情況下「爆炸」。由於有大量必須更新的索引項目，這類「爆炸式索引」可能會大幅提高在 Datastore 寫入實體的費用，也能夠輕易使實體超過索引項目或大小上限。

舉例來說，查詢：

SELECT * FROM Widget WHERE x=1 AND y=2 ORDER BY date

會使 SDK 建議下列索引：

indexes:
- kind: Widget
  properties:
  - name: x
  - name: y
  - name: date

class Widget(db.Expando):
  pass

e2 = Widget()
e2.x = [1, 2, 3, 4]
e2.y = ['red', 'green', 'blue']
e2.date = datetime.datetime.now()
e2.put()

會建立一個實體，其中的 x 屬性含有四個值，y 屬性含有三個值，date 則設為目前日期。這會需要 12 個索引項目，一個項目代表一個可能的屬性值組合：

(1, "red", <now>) (1, "green", <now>) (1, "blue", <now>)

(2, "red", <now>) (2, "green", <now>) (2, "blue", <now>)

(3, "red", <now>) (3, "green", <now>) (3, "blue", <now>)

(4, "red", <now>) (4, "green", <now>) (4, "blue", <now>)

多次重複同一個屬性後，Datastore 可能會偵測到爆炸式索引並建議替代索引。然而，在所有其他情況下 (例如本範例定義的查詢)，Datastore 仍會產生爆炸式索引。在此情況下，您可以手動在索引設定檔中設定索引以避免此情形：

indexes:
- kind: Widget
  properties:
  - name: x
  - name: date
- kind: Widget
  properties:
  - name: y
  - name: date

(1, <now>) (2, <now>) (3, <now>) (4, <now>)

("red", <now>) ("green", <now>) ("blue", <now>)

任何會導致索引超出索引項目或大小限制的 Put 作業都會失敗，並顯示 BadRequestError 例外狀況。例外狀況的文字會說明您超出了何種上限 ("Too many indexed properties" 或 "Index entries too large")，以及原因是哪一個自訂索引。如果新索引在建立時會超過任何實體的限制，查詢該索引就會失敗，而該索引也會在 Google Cloud 主控台中顯示為 Error 狀態。如要解決 Error 狀態的索引：

1. 從 index.yaml 檔案移除 Error 狀態的索引。

2. 從 index.yaml 所在的目錄執行下列指令，以便從 Datastore 中移除該索引：

   gcloud datastore indexes cleanup index.yaml
   

3. 解決錯誤原因。例如：

   • 重新制定索引定義和對應查詢。
   • 移除導致索引爆炸的實體。

4. 將索引加回 index.yaml 檔案。

5. 從 index.yaml 所在的目錄執行下列指令，以便在 Datastore 中建立索引：

   gcloud datastore indexes create index.yaml
   

若要避免爆炸式索引，可以使用清單屬性避開需要自訂索引的查詢。如上所述，其中包括含多種排序順序的查詢，或是混用等式及不等式篩選條件的查詢。