Cloud Datastore 專用的 Python DB 用戶端程式庫

附註:強烈建議建構新應用程式的開發人員使用 NDB 用戶端程式庫;相較於此用戶端程式庫,NDB 用戶端程式庫有幾項優點,例如能透過 Memcache API 自動快取實體。若您目前使用舊版的「DB 用戶端程式庫」,請參閱 DB 至 NDB 移轉指南

本文件說明儲存在 Cloud Datastore 中之物件的資料模型、使用 API 建構查詢的方法,以及處理交易的方法。

實體

Cloud Datastore 中的物件又稱為「實體」。實體有一個或多個具名「屬性」,每個屬性可以有一個或多個值。屬性值可以屬於各種資料類型,包括整數、浮點數、字串、日期和二進位資料等。查詢具有多個值的屬性,可測試是否有值符合查詢條件。這可讓這類屬性適合用於成員資格測試。

種類、金鑰與 ID

每個 Cloud Datastore 實體都屬於特定「種類」,可將實體分門別類,方便查詢。舉例來說,人力資源應用程式可能會用 Employee 種類的實體來代表公司的每位員工。此外,每個實體都有專門用來識別該實體的專屬「金鑰」。金鑰是由以下元件組成:

  • 實體的種類
  • ID,可能是以下兩者之一:
    • 「金鑰名稱」字串
    • 整數 ID
  • 選用的祖系路徑,可在 Cloud Datastore 階層之中找到實體的位置

ID 會在實體建立時指派。由於 ID 是實體金鑰的一部分,因此與實體之間具有永久關聯,無法變更。ID 可利用兩種方式指派:

  • 您的應用程式可以指定實體專屬的金鑰名稱字串。
  • 您可以讓 Cloud Datastore 自動指派整數的數字 ID 給實體。

祖系路徑

Cloud Datastore 中的實體會形成階層結構空間,與檔案系統的目錄結構相似。建立實體時,可選擇將其他實體指定為「父項」;新實體則為父系實體的「子項」(請注意,不同於檔案系統,父項實體不需要實際存在)。沒有父系的實體則是「根實體」。 實體與父項實體之間具有永久關聯性,一旦實體建立後就無法變更。Cloud Datastore 絕對不會將相同的數字 ID 指派給父項相同的兩個實體,也不會指派給兩個根實體 (即沒有父項的實體)。

實體的父項、父項的父項等以此類推,全都是這個實體的「祖系」;實體的子項、子項的子項等等,則都是其「子系」。 根實體及所有子系都屬於相同的「實體群組」。 從根實體開始,再從父項到子項,最後到指定實體的實體序列,即構成該實體的「祖系路徑」。 完整金鑰代表包含種類-ID 組合的實體,該組合指定其祖系路徑,並且止於實體本身的這類組合:

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

根實體的祖系路徑是空白路徑,其金鑰只包含實體本身的種類與 ID。

[Person:GreatGrandpa]

本概念以下圖說明:

顯示實體群組中根實體與子系實體的關係

查詢和索引

除了按照實體金鑰直接從 Cloud Datastore 擷取實體之外,應用程式也可以執行查詢,以按照實體的屬性值來擷取實體。查詢可針對指定種類的實體運作;其可針對實體的屬性值、金鑰與祖系指定篩選器,且可傳回零或多個實體做為「結果」。 查詢也可以指定排序順序,按結果的屬性值對結果進行順序排列。結果包含的所有實體都具有每個屬性的至少一個值 (有可能是空值),這些屬性都在篩選器中具名,並按排序順序列出,其屬性值符合所有指定的篩選條件。查詢可傳回完整實體、投影實體,或只傳回實體金鑰

典型的查詢包含以下幾項:

執行時,查詢會擷取符合所有指定篩選條件的特定種類實體,並按照指定的順序進行排序。查詢會以唯讀方式執行。

附註:為了節省記憶體並提升效能,查詢應盡可能指定傳回結果數目限制。

查詢也可以包含祖系篩選器,將結果限制為來自指定祖系的實體群組。這種查詢稱為祖系查詢。根據預設,祖系查詢會傳回同步一致的結果,如此就能保證跟上最新的資料更新。相反地,非祖系查詢可以跨越整個 Cloud Datastore,而不只是單一實體群組,但這種查詢只是最終一致的,且可能傳回過時結果。如果同步一致性對應用程式而言很重要,那麼建構資料時您可能需要考慮這一點,並將相關實體放在相同實體群組中,以便可透過祖系查詢 (而不是非祖系查詢) 擷取這些實體;詳情請參閱建立資料結構以達到同步一致性一文。

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

如需有關索引和查詢的深入說明,請參閱索引選取與進階搜尋一文。

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

交易

每次嘗試插入、更新或刪除實體時,都是在交易的背景下進行。單一交易可包含的前述作業數量不受限制。為了維持資料一致性,交易會確保將其中的所有作業以單元方式套用至 Cloud Datastore,如有任何作業失敗,則不會套用至任何作業。

您可以對單一交易中的實體執行多次動作。例如,如要增加物件的計數器欄位,您需要讀取計數器的值、計算新值,然後將值儲存回欄位。若沒有交易,可能會有其他程序在您讀取值與更新值這段期間增加計數器,進而導致應用程式覆寫更新的值。在單一交易中進行讀取、計算與寫入,可確保沒有其他程序會對遞增量造成干擾。

交易和實體群組

交易中只允許祖系查詢:也就是說,每個交易查詢都必須限制為單一實體群組。交易本身可套用至多個實體,而實體可以屬於單一實體群組,或 (若為跨群組交易) 屬於多達二十五個不同的實體群組。

Cloud Datastore 使用最佳化並行管理交易。當兩個或多個交易同時嘗試變更相同實體群組 (更新現有實體或建立新實體) 時,修訂的第一個交易會成功,其他所有的交易都會在修訂時失敗,然後這些交易可在更新的資料上重試。請注意,這會限制您可以對指定實體群組中的任何實體執行的並行寫入次數。

跨群組交易

對屬於不同實體群組的實體進行的交易稱為「跨群組 (XG) 交易」。交易最多可套用至二十五個實體群組,並且只要沒有並行交易涉及其套用的任何實體群組,交易就會成功。這可讓您在整理資料時享有更大的彈性,因為您不必為了對資料執行完整寫入而被迫將資料的不同部分放在同一個祖系下。

就像單一群組交易一樣,您無法在 XG 交易中執行非祖系查詢。但是,您可以對個別實體群組執行祖系查詢。非交易 (非祖系) 查詢可能會看到先前修訂之交易的全部或部分結果,也可能看不到任何結果。(如要瞭解這個問題的背景,請參閱 Cloud Datastore 寫入功能與資料瀏覽權限一文。) 但是,與部分修訂的單一群組交易相比,這種非交易查詢更有可能看到部分修訂的 XG 交易結果。

僅涉及單一實體群組之 XG 交易的效能與成本,與單一群組的非 XG 交易完全一致。在涉及多個實體群組的 XG 交易中,作業成本與在非 XG 交易中執行的成本相同,但延遲時間可能比較長。

Cloud Datastore 寫入功能與資料瀏覽權限

資料會以兩個階段寫入 Cloud Datastore:

  1. 在「修訂」階段,實體資料會記錄在大多數備用資源的交易記錄中,而未記錄資料的任何備用資源都會標示為無最新記錄。
  2. 「套用」階段會在每個備用資源中單獨進行,並且包含兩個平行執行的動作:
    • 實體資料會寫入這個備用資源。
    • 實體的索引列會寫入這個備用資源。(請注意,這個動作花費的時間比寫入資料本身花費的時間要長。)

「修訂」階段之後,寫入作業會立即傳回結果,然後「套用」階段會以非同步方式進行,可能在每個備用資源中進行的時間都不同,並且可能在「修訂」階段完成後延遲幾百毫秒或更長的時間再進行。「修訂」階段如出現失敗情形,會自動重試;但若持續失敗,Cloud Datastore 會傳回錯誤訊息,指示應用程式出現例外狀況。若特定備用資源的「修訂」階段成功,但「套用」失敗,只要發生以下任一情形,就會將這個備用資源的「套用」向前輪動至完成:

  • 定期 Cloud Datastore 掃掠檢查未完成的「修訂」工作,並且套用這些工作。
  • 使用受影響實體群組的某些作業 (getputdelete 和祖系查詢) 會使已修訂但尚未套用的任何變更在備用資源中變為已完成,並且會先執行這些作業,然後再繼續執行新作業。

對於在「修訂」與「套用」階段的不同部分,這個寫入行為會對應用程式公開資料的方式和時間點產生若干影響:

  • 如果寫入作業報告逾時錯誤,則無法確定 (在不嘗試讀取資料的情況下) 作業成功還是失敗。
  • 由於 Cloud Datastore 的取得與祖系查詢作業會將任何未解決的修改套用至執行修改的備用資源,因此這些作業一律會看到先前所有成功交易的一致視圖。這表示,get 作業 (按實體金鑰查詢更新的實體) 一定會看到最新版本的實體。
  • 非祖系查詢可能會傳回過時結果,因為這種查詢可能會對尚未套用最新交易的備用資源執行。即使執行了保證套用未完成交易的作業,也會發生這種情況,因為查詢可能會在與前一個作業不同的備用資源上執行。
  • 並行變更的時間可能會影響非祖系查詢的結果。如果實體最初符合查詢,但後來又變成不再符合了,這個實體可能仍會包含在查詢的結果集中,但前提是變更尚未套用至執行查詢所在備用資源中的索引。=

Cloud Datastore 統計資料

Cloud Datastore 會留存與應用程式預存資料相關的統計資料,例如有多少實體符合特定種類,或者特定類型的屬性值使用多少空間。您可在 GCP 主控台的 Cloud Datastore 資訊主頁頁面中查看這些統計資料。您也可以使用 Cloud Datastore API 查詢名稱特殊的實體,以程式輔助方式在應用程式內部存取這些值;詳情請參閱 Python 中的資料儲存庫統計資料

Python 資料儲存庫範例

在 Python API 中,模型說明一種類別,包括其屬性的類型和設定。應用程式使用 Python 類別定義模型,並使用類別屬性說明屬性。類別的名稱會變成實體種類的名稱。特定種類的實體由模型類別的執行個體表示,並由執行個體屬性表示屬性值。如要建立新實體,請建構所需類別的物件、設定其屬性,然後予以儲存 (透過呼叫 put() 之類的方法):

import datetime
from google.appengine.ext import db
from google.appengine.api import users

class Employee(db.Model):
  name = db.StringProperty(required=True)
  role = db.StringProperty(required=True,
                           choices=set(["executive", "manager", "producer"]))
  hire_date = db.DateProperty()
  new_hire_training_completed = db.BooleanProperty(indexed=False)
  email = db.StringProperty()

e = Employee(name="John",
             role="manager",
             email=users.get_current_user().email())
e.hire_date = datetime.datetime.now().date()
e.put()

Cloud Datastore API 提供兩種查詢介面:查詢物件介面與類似 SQL 的查詢語言 (稱為 GQL)。查詢會以模型類別執行個體的形式傳回實體。

training_registration_list = ["Alfred.Smith@example.com",
                              "jharrison@example.com",
                              "budnelson@example.com"]
employees_trained = db.GqlQuery("SELECT * FROM Employee WHERE email IN :1",
                                training_registration_list)
for e in employees_trained:
  e.new_hire_training_completed = True
  db.put(e)
本頁內容對您是否有任何幫助?請提供意見:

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

這個網頁
Python 2 適用的 App Engine 標準環境