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
- 代表篩選運算式樹狀結構的選用節點。
- orders
- 選用
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)
- 非同步擷取查詢結果清單，設有數量上限。傳回
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)
- 將回呼函式或 Tasklet 對應至查詢結果。也就是說，將函式 (或 Tasklet) 套用至查詢結果中的每個實體。
引數
- callback
- 要套用至每個結果的函式或工作小程式。
- pass_batch_into_callback
- 如果
True，則會使用批次資訊引數呼叫回呼，如下所述。 - merge_future
- 選用的
Future子類別，請見下文。 - **q_options
- 支援所有查詢選項關鍵字引數。
「回呼簽名」：通常會使用實體作為引數來呼叫回呼函式。不過，如果系統可取得
keys_only=True，則會使用 Key 來進行呼叫。如果提供pass_batch_into_callback=True，系統會使用三個引數呼叫回呼函式：目前的批次、批次內的索引，以及該索引處的實體或Key。回呼可以傳回任何內容。如果回呼函式為None，則會將其假定為僅須傳回已傳入實體或金鑰的簡易回呼函式。選用
merge_futuremerge_future是進階引數，可用於覆寫回呼結果合併為整體map()傳回值的方式。根據預設，這個函式會產生一個回呼傳回值的清單。您可以替換其中一小部分的專屬替代方法，藉此以其他方式排列清單。請參閱tasklets.MultiFuture的原始碼，瞭解預設實作方式，以及merge_future物件必須實作的通訊協定說明。同一模組的替代方案包括QueueFuture、SerialQueueFuture和ReducingFuture。傳回所有回呼的結果清單。 (但請參閱上方的「選用
merge_future」)。查詢執行完畢且所有回呼都已傳回時，就會傳回這個值。 - map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
- 以非同步方式將回呼函式或 Tasklet 對應至查詢結果。這是非同步版的 map()。