查詢游標

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

查詢游標

「查詢游標」讓應用程式能夠方便地分批擷取查詢結果,而不會產生查詢偏移的負擔。執行擷取作業後,應用程式會取得一個游標,這個游標為不透明的 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 的實體。

後續步驟

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

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

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