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物件。 - app
- 選用的應用程式 ID。
- namespace
- 選用的命名空間。如未指定，將使用執行查詢時的預設命名空間。
- 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
- 可套用至每個結果的函式或 tasklet。
- pass_batch_into_callback
- 如為
True，則使用下述的批次資訊引數來呼叫回呼函式。 - merge_future
- 選用的
Future子類別，請見下文。 - **q_options
- 支援所有的查詢選項關鍵字引數。
「回呼簽名」：通常會使用實體作為引數來呼叫回呼函式。不過，如果系統可取得
keys_only=True，則會使用金鑰來進行呼叫。如果提供了pass_batch_into_callback=True，則會使用三個引數來呼叫回呼函式：目前的批次、批次中的索引，以及該索引處的實體或Key。回呼函式可傳回任何所需的內容。如果回呼函式為None，則會將其假定為僅須傳回已傳入實體或金鑰的簡易回呼函式。「選用的」
merge_future。merge_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()。
