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()。