Query 物件代表 NDB 查詢，這是針對經過篩選及排序的實體清單提出的要求。
本頁為參考說明文件。如需 NDB 查詢的一般討論，請參閱「查詢」。
查詢選項
許多查詢方法都會採用一組標準的額外選項，這些選項可以是關鍵字引數的形式 (例如 keys_only=True)，也可以是透過 options=QueryOptions(...) 傳遞的 QueryOptions 物件。
查詢支援多種設定選項。這些項目會透過 Query 方法的關鍵字引數指定：
| 引數 | 類型 | 預設值 | 說明 |
|---|---|---|---|
| keys_only | bool | False | 所有作業都會傳回金鑰，而非實體。 |
| projection | 屬性 (或字串) 的組合 (或清單) | None
| 作業只會傳回包含指定屬性集合的實體。projection=[Article.title, Article.date] 或 projection=['title', 'date'] 會擷取只設定這兩個欄位的實體。(請參閱「投影查詢」)。 |
| offset | int | 0 | 要略過的查詢結果數量。 |
| limit | int | 不限 | 要傳回的查詢結果數量上限。 |
| batch_size | int | 20 | 批次大小。 只會影響查詢效率；批次大小越大，使用的記憶體越多，但 RPC 呼叫次數會減少。 |
| prefetch_size | int | None | 覆寫傳回第一批資料的批次大小。 |
| produce_cursors | bool | False
| 從查詢產生游標 (請參閱「查詢疊代器」)。查詢游標)。 |
| start_cursor | Cursor | None
| 搜尋的起點 (請參閱「查詢游標」)。 |
| end_cursor | Cursor | None
| 搜尋結束點 (請參閱「查詢游標」)。 |
| deadline | int | 取決於 Context
| 覆寫遠端程序呼叫 (RPC) 期限 (如果 Context 建立時未經過覆寫，則預設值為 5 秒) |
| read_policy | ndb.EVENTUAL_CONSISTENCY
| 讀取政策。將其設為 ndb.EVENTUAL_CONSISTENCY 即有可能更快取得結果，而不必等候 Datastore 對所有傳回的記錄套用待處理的變更。 |
若要使用一組特定選項執行查詢，請將關鍵字引數傳送至適用的方法：
qry = Employee.query().filter(...).order(...) # Create a query for acct in qry.fetch(10, offset=20): # Skip the first 20 print acct
您有時候可能想要保存一組查詢選項，以便在不同的地方派上用場。雖然您可以將這些值保留在字典中，並使用 **kwds 將此字典傳遞至方法，但您也可以建立 QueryOptions 物件，並使用選項關鍵字引數傳遞該物件。以下兩個範例的效果相同：
qo = ndb.QueryOptions(keys_only=True, offset=20) results = qry.fetch(10, options=qo) results = qry.fetch(10, keys_only=True, offset=20)
建構函式
一般來說，應用程式會透過呼叫 Model.query() 建立 Query。但也可以呼叫 ndb.Query()。
引數
- kind
- 選用的類型字串。通常是實體類別的名稱。
- ancestor
- 選用祖系鍵。
- filters
- 代表篩選器運算式樹狀結構的選用節點。
- 訂單
- 選用
datastore_query.Order物件。 - 應用程式
- 選用應用程式 ID。
- 命名空間
- 選用命名空間。如未指定，系統會使用執行查詢時的預設命名空間。
- projection
- 要投射的選用屬性清單或組合。
- group_by
- 要依據哪些屬性進行分組的選用清單或組合。
- default_options
- 選用的
QueryOptions物件，提供執行查詢時可用的預設查詢選項。
實例方法
- filter(filter1, filter2, ...)
- 傳回已套用其他篩選器的新
Query。採用查詢中所述的篩選器引數。qry.filter(filter1).filter(filter2)等同於qry.filter(filter1, filter2) - get(**q_options)
- 會傳回第一個查詢結果 (如果有)，否則傳回
None。這類似於呼叫q.fetch(1)並傳回結果清單的第一個項目。引數
- **q_options
- 支援所有查詢選項關鍵字引數。
- order(order1, order2, ...)
- 會傳回已套用額外排序順序的新
Query。接受一或多個屬性或「否定」屬性的引數。舉例來說，如要依年齡排序使用者，並依名稱「打破平手」，您可以使用qry.order(-Account.birthday, Account.name)之類的函式。 - bind(...values...)
- 這個函式可搭配使用參數繫結 (
:1、:2等) 或命名繫結 (:foo、:bar等) 的 GQL 查詢。它會將傳入的值綁定至參數。如要繫結參數，您可以呼叫
qry.bind("USA", 49)之類的函式。如要繫結已命名參數，您可以呼叫qry.bind(region = "USA", threshold = 49)之類的函式。傳回已繫結參數值的新
Query物件。 - count(limit=None, **q_options)
- 傳回查詢結果數量，設有數量上限。這會傳回與
len(q.fetch(limit))相同的結果，但效率更高。引數
- count_async(limit, **q_options)
- 非同步計算查詢結果數量，設有數量上限，可傳回結果為數字的
Future。這是 count() 的非同步版本。 - fetch(limit, **q_options)
- 擷取查詢結果清單，最多可擷取至限制。
引數
- limit
- 最多可計算的結果數量
- **q_options
- 支援所有查詢選項關鍵字引數。
- fetch_async(limit, **q_options)
- 非同步擷取查詢結果清單，數量上限為 1000。傳回
Future，其結果為結果清單。這是 fetch() 的非同步版本。 - fetch_page(page_size, **q_options)
- 擷取「頁面」的結果。這是專門用於分頁使用者介面的特殊方法。
引數
- page_size
- 最多會傳回這麼多結果。
- **q_options
- 支援所有查詢選項關鍵字引數。
(results, cursor, more)：- results 查詢結果清單
- cursor：指向「下一批」結果的查詢游標。如果沒有其他結果，則可能是
None。 - more
bool代表這批結果之後是否 (可能) 還有其他結果。如果為False，則代表已無任何結果。如果為True，則代表「可能」還有更多結果。
如要擷取下一頁，請使用
start_cursor=cursor將呼叫傳回的游標傳送至下一項呼叫。常見的慣用語是使用cursor.urlsafe()將游標傳遞至用戶端，並使用Cursor(urlsafe=string)在後續要求中重建該游標。 - fetch_page_async(page_size, **q_options)
- 以非同步方式擷取結果的「頁面」。這是 fetch_page() 的非同步版本。
- get_async(**q_options)
- 會以非同步方式傳回第一個查詢結果 (如果有) (否則為
None)。這是 get() 的非同步版本。 - iter(**q_options)
- 會建構並傳回查詢的迭代器。
引數
- **q_options
- 支援所有查詢選項關鍵字引數。
傳回 QueryIterator 物件。
- map(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
- 將回呼函式或子工作對應至查詢結果。也就是將函式 (或子工作) 套用至查詢結果中的每個實體。
引數
- 回呼
- 要套用至每個結果的函式或子任務。
- pass_batch_into_callback
- 如果為
True，則會以以下所述的批次資訊引數呼叫回呼。 - merge_future
- 選用的
Future子類別，請見下文。 - **q_options
- 支援所有查詢選項關鍵字引數。
「回呼簽名」：通常會使用實體作為引數來呼叫回呼函式。不過，如果系統可取得
keys_only=True，則會使用金鑰來進行呼叫。如果提供pass_batch_into_callback=True，回呼會使用三個引數呼叫：目前的批次、批次中的索引，以及該索引的實體或Key。回呼可以傳回任何內容。如果回呼函式為None，則會將其假定為僅須傳回已傳入實體或金鑰的簡易回呼函式。選用
merge_futuremerge_future是進階引數，可用於覆寫回呼結果如何合併至整體map()傳回值。根據預設，這個函式會產生一個回呼傳回值的清單。您可以替換其中一小部分的專屬替代方法，藉此以其他方式排列清單。如要瞭解預設實作方式，以及merge_future物件必須實作的通訊協定，請參閱tasklets.MultiFuture的原始碼。同一個模組的替代值包括QueueFuture、SerialQueueFuture和ReducingFuture。傳回所有回呼結果的清單。(但請參閱上方的「選用
merge_future」)。在查詢執行完畢且所有回呼都已傳回時，系統會傳回此值。 - map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
- 以非同步方式將回呼函式或子工作對查詢結果進行對應。這是非同步版的 map()。