金鑰和實體群組

資料存放區中的每個實體都具有金鑰，對於應用程式中的所有實體而言，金鑰是實體的唯一識別項。金鑰有幾個元件：路徑描述實體和另一個實體之間的父子式關聯性，實體的種類，以及應用程式指派給實體的名稱或資料存放區指派的數字 ID。

• 種類、名稱和 ID
• 實體群組、上階和路徑
• 路徑和金鑰唯一性

種類、名稱和 ID

每個實體都是一種特別的種類，一種查詢可以傳回的實體群組。 與表格中的列不同，兩個相同種類的實體不需要具有相同屬性 (儘管應用程式可以在資料模型中建立這種限制)。Datastore API (資料存放區 API) 使用 Model (或 Expando) 子類別的名稱，做為種類的名稱。

例如，此類別為名稱為 "Story" 的種類定義模型：

class Story(db.Model):
  title = db.StringProperty()
  author = db.StringProperty()

每個實體都有識別項。應用程式可以指派其本身的識別項，用於金鑰之中，只要指定實例建構函式的 key_name 引數 (為 str 值) 即可：

s = Story(key_name="xzy123")

key_name 會儲存為 Unicode 字串 (使用 str 值轉換為 ASCII 文字)。 key_name 的開頭不能是數字，而且不能是 __*__ 格式 (開頭和結尾都是兩個底線)。 若您的應用程式以使用者提交的資料做為資料存放區實體金鑰名稱 (例如電子郵件地址)，則應用程式要先處理好該值，例如加上已知字串的首碼，以符合這些要求。

若未指定 key_name，則實體第一次儲存在資料存放區時，會指派數字 ID。

s2 = Story()    # s2 does not have a name or an ID.
s2.put()        # s2 is given an ID by the datastore.

一旦建立實體後，便不能變更其 ID 或名稱。

提示：金鑰名稱和 ID 不是屬性值。不過，您可以使用特殊的屬性名稱 __key__ 來執行限定的一組查詢。如果所有實體具有相同的種類和父系，則篩選器和排序順序可套用於金鑰名稱或 ID。請參閱「查詢金鑰」。

實體群組、上階和路徑

每個實體都隸屬於一個實體群組，也就是可以在單一交易中操縱的一或多個實體。實體群組的關聯性會告訴應用服務引擎，將幾個實體都儲存在分散式網路中的相同部分。 交易為實體群組設定資料存放區操作，而所有操作會以群組方式來一起套用；若交易失敗，則完全不套用。

應用程式建立實體時，它可以使用 Model 建構函式的 parent 引數，將另一個實體指派為這個新實體的「父系」。 指派父系給新實體，會將新實體放置於父系實體相同的實體群組。

沒有父系的實體是根實體。一個實體即使已是另一個實體的父系，也可以再有父系。從實體到根的父系實體鏈結，是該實體的路徑，而該路徑的成員是實體的上階。 實體建立時，就會定義其父系，而且之後無法變更。

具有指定根實體做為上階的每個實體，都位於相同的實體群組。群組中的所有實體，會儲存在相同的資料存放區節點。單一交易可以修改單一群組中的多個實體，也可以將新實體新增至群組 (指定群組中的現有實體為新實體的父系)。

如需進一步了解交易，請參閱交易。

若刪除的實體是另一個實體的上階，其子系實體並不會刪除。仍然可以使用子系實體的完整 Key 或路徑來存取它。

建立實體時，可以先具有上階路徑即可，而不一定需要建立父系實體。若要這樣做，您可以使用種類和金鑰名稱，來建立上階的 Key，然後用它做為新實體的父系。具有相同根上階的所有實體，都隸屬於相同的實體群組，不論路徑的根是否代表實際的實體。

使用實體群組的提示：

• 交易需要實體群組時，才使用實體群組。針對其他實體之間的關聯性，請使用 ReferenceProperty 屬性和 Key 值，這些都可以在查詢中使用。
• 應用程式的實體群組愈多—也就是有較多的根實體—資料存放區就可以更有效率地將實體群組分散至資料存放區節點。若資料分散情形較佳，則可提升建立和更新資料的效能。此外，若多位使用者同時嘗試更新相同實體群組中的實體，將導致部分使用者必須重試交易，也可能會導致部分交易無法認可變更。請勿將應用程式的所有實體放在一個根之下。
• 實體群組的良好規則概念，就是它們的大小應該與單一使用者資料的價值類似，或者更小。
• 實體群組對查詢的速度沒有明顯地影響。

路徑和金鑰唯一性

實體的完整金鑰 (包括路徑、種類以及名稱或數字 ID) 是唯一的，專對該實體使用。在資料存放區建立實體時，就會指派完整的金鑰，而且金鑰的任何部分都無法變更。

兩個不同實體的金鑰可以有某些部分類似，只要至少有一個部分不同即可。例如，兩個實體可以有相同的種類和名稱，只要具有不同的父系即可。同樣地，兩個實體可以有相同的父系 (或沒有父系) 和名稱，只要種類不同即可。

應用程式不應依賴隨著實體建立的先後順序而指派遞增順序的數字 ID。這是指一般狀況，但並不保證。