查詢游標

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

查詢游標

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

偏移與游標的比較

雖然 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 的新版本可能會變更內部實作的細節，而使依靠這些實作細節的游標失效。如果應用程式嘗試使用已經失效的游標，Datastore 就會引發 BadRequestError 例外狀況。

游標與資料更新

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

擷取查詢結果時，您可以同時使用開始游標和結束游標，從 Datastore 傳回連續的結果。使用開始游標和結束游標擷取結果時，系統不保證結果大小會與產生游標時的大小相同。在產生游標到在查詢中使用游標的這段期間，系統可能會新增或刪除 Datastore 中的實體。

後續步驟