NDB 查詢類別

Query 物件代表 NDB 查詢,這是針對經過篩選及排序的實體清單提出的要求。

本頁為參考說明文件。有關 NDB 查詢的一般討論,請參閱查詢

查詢選項

許多查詢方法都有一套標準的附加選項,這些選項可以是關鍵字引數 (如 keys_only=True),也可以是使用 options=QueryOptions(...) 傳送的 QueryOptions 物件。

查詢支援各種設定選項。這些選項是由關鍵字引數指定至 Query 方法:

引數 類型 預設值說明
keys_onlybool False 所有運算都會傳回金鑰,而非實體。
projection屬性 (或字串) 的組合 (或清單)None 運算僅會傳回已設定指定屬性的實體。 projection=[Article.title, Article.date]projection=['title', 'date'] 會擷取只設定了這兩個欄位的實體 (請參閱投影查詢)。
offset int 0 略過的查詢結果數量。
limit int 不限傳回的查詢結果數量上限。
batch_size int 20 批次大小。

只會對查詢效率造成影響;批次越大,使用的記憶體越大,但執行 RPC 呼叫的次數較少。
prefetch_sizeint None 覆寫第一批傳回的批次大小。
produce_cursors bool False 從查詢產生游標 (請參閱查詢疊代器查詢游標)。
start_cursorCursor None 搜尋的起點 (請參閱查詢游標)。
end_cursorCursor None 搜尋的終點 (請參閱查詢游標)。
deadlineint 取決於 Context 覆寫遠端程序呼叫 (RPC) 期限 (如果 Context 建立時未經過覆寫,則預設值為 5 秒)
read_policyndb.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(filter1filter2)
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)) 一樣的結果,但效率更高。

引數

limit
最多可以計算的結果數量。
**q_options
支援所有的查詢選項關鍵字引數內容選項
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
  • morebool 代表這批結果之後是否 (可能) 還有其他結果。如為 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_futuremerge_future 是一種進階引數,可用於覆寫回呼結果併入整體 map() 傳回值的方式。根據預設,這個函式會產生一個回呼傳回值的清單。您可以替換其中一小部分的專屬替代方法,藉此以其他方式排列清單。請參閱 tasklets.MultiFuture 的原始碼來瞭解預設部署作業資訊,以及 merge_future 物件必須部署的通訊協定相關說明。屬於相同模組的替代方法包括 QueueFutureSerialQueueFutureReducingFuture

傳回所有回呼函式的結果清單 (但請參閱上方「選用的 merge_future」相關說明)。 此清單會在查詢執行完成時傳回,並且會傳回所有回呼函式的結果。

map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)
將回呼函式或 tasklet 非同步對應到查詢結果。這是非同步版的 map()
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Python 2 適用的 App Engine 標準環境