Python 2 は、コミュニティによるサポートを終了しました。Python 2 アプリを Python 3 に移行することをおすすめします。

NDB Query クラス

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

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

クエリ オプション

多くのクエリメソッドには、追加で指定できるクエリ オプションの標準セットがあり、keys_only=True などのキーワード引数の形式か、options=QueryOptions(...) によって渡される 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 オブジェクトを作成し options キーワード引数を使用して渡したりもできます。次の 2 つのサンプルは同じことを意味します。

qo = ndb.QueryOptions(keys_only=True, offset=20)
results = qry.fetch(10, options=qo)
results = qry.fetch(10, keys_only=True, offset=20)

コンストラクタ

通常、アプリケーションから Query を呼び出して Model.query() を作成します。ただし、ndb.Query() を呼び出すこともできます。

引数

kind
オプションの 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)) と同じ結果を返しますが、より効率的です。

引数

上限
結果の最大カウント数。
**q_options
すべてのクエリ オプション キーワード引数コンテキスト オプションがサポートされます。
count_async(limit, **q_options)
上限値まで、クエリ結果の数を非同期的にカウントします。これによって返される Future の結果は数値です。これは count() の非同期バージョンです。
fetch(limit, **q_options)
制限値まで、クエリ結果のリストをフェッチします。

引数

上限
結果の最大カウント数。
**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 の場合、結果がそれ以上存在する可能性があります

次のページをフェッチするには、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() の非同期バージョンです。