查詢游標

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

查詢游標

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

偏移與游標的比較

雖然 Datastore 支援整數位移，但建議您避免使用。最好改用游標。使用偏移只能避免將略過的實體傳回應用程式中，但是系統仍會在內部擷取這些實體。略過的實體其實仍會影響到查詢延遲時間，而且會為了擷取實體而進行讀取作業，因此需要向應用程式收費。改用游標而不使用偏移就能避免這些額外費用。

查詢游標範例

在 Go 中，應用程式會呼叫 Iterator 值的 Cursor 方法，以此方式擷取查詢結果後，即可取得游標。如要從游標所在位置擷取其他結果，應用程式會準備實體種類、篩選條件及排序順序皆相同的相似查詢，並在執行擷取之前，將游標傳送至查詢的 Start 方法：

// Create a query for all Person entities.
q := datastore.NewQuery("Person")

// If the application stored a cursor during a previous request, use it.
item, err := memcache.Get(ctx, "person_cursor")
if err == nil {
	cursor, err := datastore.DecodeCursor(string(item.Value))
	if err == nil {
		q = q.Start(cursor)
	}
}

// Iterate over the results.
t := q.Run(ctx)
for {
	var p Person
	_, err := t.Next(&p)
	if err == datastore.Done {
		break
	}
	if err != nil {
		log.Errorf(ctx, "fetching next Person: %v", err)
		break
	}
	// Do something with the Person p
}

// Get updated cursor and store it for next time.
if cursor, err := t.Cursor(); err == nil {
	memcache.Set(ctx, &memcache.Item{
		Key:   "person_cursor",
		Value: []byte(cursor.String()),
	})
}

游標的限制

游標必須遵循以下限制：

  • 只有執行原始查詢的同一個應用程式才能使用游標，而且只能繼續進行相同的查詢。如要在後續的擷取作業中使用游標，則必須完全重新建構原始查詢，包括相同的實體種類、祖系篩選器、屬性篩選器和排序順序。如未設定原始產生游標的相同查詢，就無法使用游標擷取結果。
  • 如果查詢使用不等式篩選器或以多值屬性做為排序順序，游標就不一定能夠發揮正常作用。每次擷取作業之間不會保留此類多值屬性的清除重複邏輯，因此可能會重複傳回同一個結果。
  • App Engine 的新版本可能會變更內部實作的細節，而使依靠這些實作細節的游標失效。如果應用程式嘗試使用無效的游標，Datastore 會傳回錯誤。

游標與資料更新

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

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

後續步驟