NDB Query クラス

Query オブジェクトは、NDB クエリを示します。NDB クエリとは、フィルタリングと並べ替えを行ったエンティティ リストに対するリクエストです。

このページには、リファレンス ドキュメントがあります。NDB クエリの概要については、クエリをご覧ください。

クエリ オプション

多くのクエリメソッドには、追加オプションの標準セットがあります。「keys_only=True」のようなキーワード引数を使用する場合や、QueryOptions オブジェクトに対して「options=QueryOptions(...)」と設定して渡す場合などがあります。

クエリは、さまざまな構成オプションをサポートします。Query メソッドに対して指定するキーワード引数は次のとおりです。

引数タイプデフォルト説明
keys_onlybool False すべてのオペレーションで、エンティティではなく、キーを返します。
projection プロパティ(または文字列)のタプル(またはリスト) None 指定したプロパティ セットのみを持つエンティティを返します。 projection=[Article.title, Article.date] または projection=['title', 'date'] は、この 2 つのフィールド セットを持つエンティティをフェッチします。射影クエリをご覧ください。
offsetint 0 スキップするクエリ結果の数。
limitint 上限なし返されるクエリ結果の最大件数。
batch_sizeint 20 バッチサイズ。

クエリの効率性にのみ影響します。バッチサイズが大きくなると、メモリの使用量が増えますが、RPC コールは少なくなります。
prefetch_sizeint None 最初に返されたバッチのバッチサイズをオーバーライドします。
produce_cursorsbool False クエリからカーソルを生成します。クエリ イテレータークエリカーソルをご覧ください。
start_cursor Cursor None 検索の開始点。クエリカーソルをご覧ください。
end_cursorCursor None 検索の終了点。クエリカーソルをご覧ください。
deadlineint Context に依存 RPC の期限をオーバーライドします(Context が作成されるときにオーバーライドされない場合、デフォルトで 5 秒に設定されます)。
read_policy ndb.EVENTUAL_CONSISTENCY 読み取りポリシー。ndb.EVENTUAL_CONSISTENCY に設定すると、返されたすべての記録に対してデータストアが保留中の変更を適用するのを待つことがなくなるため、結果をより早く取得できる可能性が高まります。

特定のオプション セットでクエリを実行するには、キーワード引数を該当メソッドに渡します。

qry = Employee.query().filter(...).order(...) # Create a query
for acct in qry.fetch(10, offset=20): # Skip the first 20
  print acct

場合によっては、クエリ オプション セットをすぐに利用できる状態にして、さまざまな場で使用することが必要となることがあります。ディクショナリに保存して、**kwds を使用するメソッドにディクショナリを渡すこともできますが、QueryOptions オブジェクトを作成して、オプションのキーワード引数を使用して渡すこともできます。次の 2 つのサンプルは同じことを意味します。

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 を返します。1 つまたは複数の引数を受け取ります。これは、プロパティまたは「否定」プロパティです。たとえば、年齢でユーザーを並べ替えて、名前で区分する場合、「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
すべてのクエリ オプション キーワード引数がサポートされます。
タプルを返します(resultscursormore):
  • results - クエリ結果のリスト。
  • cursor - 結果の次のバッチを指すクエリカーソル。結果がそれ以上ない場合は None になります。
  • more - このバッチの後に結果がまだ存在する可能性があるかどうかを示す boolFalse の場合、結果はそれ以上存在しません。True の場合、結果がそれ以上存在する可能性があります

次のページをフェッチするには、1 回の呼び出しで返されたカーソルを、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)
クエリ結果に対してコールバック関数やタスクレットをマッピングします。つまりクエリ結果の各エンティティに対して、関数(タスクレット)を適用します。

引数

callback
各結果に適用する関数/タスクレット。
pass_batch_into_callback
True の場合、バッチ情報引数を備えたコールバックを呼び出します(下記参照)。
merge_future
オプションの Future サブクラス(下記参照)。
**q_options
すべてのクエリ オプション キーワード引数がサポートされます。

コールバック署名: コールバックでは通常、引数としてエンティティを使って呼び出されます。ただし、keys_only=True が指定されている場合は、Key を使って呼び出されます。pass_batch_into_callback=True が指定された場合、コールバックは、3 つの引数(現在のバッチ、バッチ内のインデックス、対象インデックスのエンティティ / Key)を使って呼び出されます。コールバックは、どんなものでも返します。コールバックが None の場合、渡されたエンティティまたはキーを返す簡単なコールバックが想定されます。

オプションの merge_future: merge_future は、コールバックの結果を map() の戻り値全体に対して結合する方法をオーバーライドするために使用できる、高度な引数です。デフォルトでは、コールバック戻り値のリストが作成されます。小数の専用選択肢の 1 つを置換することで、別の設定にすることができます。デフォルト実装用の tasklets.MultiFuture のソースコードと、merge_future オブジェクトで実装する必要のあるプロトコルの説明をご覧ください。同じモジュールからの選択肢としては、QueueFutureSerialQueueFutureReducingFuture などがあります。

すべてのコールバックの結果リストを返します。ただし、上記で説明したオプションの merge_future をご覧ください。クエリが完了に向かい、すべてのコールバックが返されたときに返されます。

map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options) 
クエリ結果に対してコールバック関数やタスクレットを非同期的にマッピングします。map() の非同期バージョンです。
このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

Python 2 の App Engine スタンダード環境