查詢游標

「查詢游標」讓應用程式能夠方便地分批擷取查詢結果,建議在分頁時使用此游標取代整數位移。如要進一步瞭解如何進行應用程式的結構查詢,請參閱查詢一文。

查詢游標

「查詢游標」讓應用程式能夠方便地分批擷取查詢結果,而不會產生查詢位移的負擔。執行擷取作業後,應用程式會取得一個游標,此游標為不透明 base64 編碼的字串,用來標示最後一次擷取結果時的索引位置。應用程式可將此字串儲存於 Cloud Datastore、Memcache 或工作佇列的工作仇載之中,或是做為 HTTP GETPOST 參數嵌入網頁,然後再使用游標當做接續擷取作業的起點,即可從上一次擷取結束後的時間點起取得下一批次的查詢結果。擷取也可以指定結束的游標,來限制傳回結果集的範圍。

位移與游標的比較

雖然 Cloud Datastore 支援整數位移,建議您盡量避免使用,並改用游標。使用位移只能避免將略過的實體傳回應用程式中,但是系統仍會在內部擷取這些實體。略過的實體會確實影響到查詢的延遲度,而且仍會為了擷取實體而進行讀取,因此需要收取應用程式的費用。改用游標而非使用位移,就能避免額外的費用。

查詢游標範例

在 Python 中,應用程式會呼叫 Query 物件的 cursor() 方法,以此方式擷取查詢結果後,即可取得游標。為了從游標的位置擷取其他結果,應用程式會準備實體種類、篩選器、排序順序類似的查詢,並在執行擷取之前,將游標傳送至查詢的 with_cursor() 方法:

from google.appengine.api import memcache
from google.appengine.ext import db

# class Person(db.Model): ...

# Start a query for all Person entities
people = Person.all()

# If the application stored a cursor during a previous request, use it
person_cursor = memcache.get('person_cursor')
if person_cursor:
  people.with_cursor(start_cursor=person_cursor)

# Iterate over the results
for person in people:
  # Do something

# Get updated cursor and store it for next time
person_cursor = people.cursor()
memcache.set('person_cursor', person_cursor)

游標的限制

游標有下列限制:

  • 游標只能由執行原始查詢的同一個應用程式所使用,並且只能接續相同的查詢。如要在接續的擷取作業中使用游標,必須重新構成完全相同的原始查詢,包含相同的實體類型、祖項篩選器、屬性篩選器及排列順序。必須將作業設定為與最初產生游標的相同的查詢條件,才能使用游標擷取結果。
  • 由於 !=IN 運算子是以多個查詢加以實作,使用這些運算子的查詢不支援游標。
  • 如果查詢使用的篩選器不同,或是含有多個值的屬性排列順序不同,游標就無法如預期般運作。每次擷取作業之間不會保留這種針對多值屬性的清除重複邏輯,可能會導致系統重複傳回相同結果。
  • App Engine 新版本可能會變更內部實作的詳細資料,而撤銷依附在上的游標。如果應用程式企圖使用無效的游標,Cloud Datastore 就會引發 BadRequestError 例外狀況。

游標與資料更新

游標位置的定義是最後一個結果傳回之後,游標在結果清單中的位置。游標不是清單中的一個相對位置 (並非位移);而是開始在結果中進行索引掃描時,用於標出哪個 Cloud Datastore 可以跳過的標記。如果查詢結果在兩次使用游標期間有所變更,查詢只會注意到游標之後的結果變更。如果新的查詢結果出現在游標位置之前,則在擷取游標之後的結果後,並不會傳回該新的結果。同樣的道理,如果某個實體已不再是查詢的結果,但卻出現在游標之前,則出現在游標之後的結果不會變更。如果將最後傳回的結果從結果集移除,游標仍然知道如何找到下一個結果。

在擷取查詢結果時,您可以使用開始游標及結束游標傳回來自 Cloud Datastore 的多組連續結果。當您使用開始游標和結束游標來擷取結果時,系統無法保證結果的大小會與您產生游標時大小相同。在游標產生和用於查詢之間的期間,系統可能會新增或刪除來自 Cloud Datastore 的實體。

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

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

這個網頁
App Engine standard environment for Python 2