注: Python 2.7 は、2024 年 1 月 31 日にサポートが終了しました。既存の Python 2.7 アプリケーションは引き続き実行され、トラフィックを受信します。ただし、サポート終了日を過ぎると、ランタイムを使用するアプリケーションの再デプロイが App Engine によってブロックされることがあります。サポートされている最新バージョンの Python に移行することをおすすめします。

NDB Query クラス

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

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

クエリオプション

多くのクエリメソッドには、追加で指定できるクエリオプションの標準セットがあり、keys_only=True などのキーワード引数の形式か、options=QueryOptions(...) によって渡される QueryOptions オブジェクトとして指定されます。

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

引数	タイプ	デフォルト	説明
keys_only	`bool`	`False`	すべての演算で、エンティティではなく、キーを返します。
projection	プロパティ（または文字列）のタプル（またはリスト）	`None`	指定したプロパティセットのみを持つエンティティを返します。`projection=[Article.title, Article.date]` または `projection=['title', 'date']` は、この 2 つのフィールドセットを持つエンティティを取得します。射影クエリをご覧ください。
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 オブジェクトを作成し、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)

コンストラクタ

通常、アプリケーションから Model.query() を呼び出して 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(filter1, filter2) と同等です。

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: すべてのクエリオプションキーワード引数がサポートされます。

タプル

(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 オブジェクトで実装する必要のあるプロトコルの説明をご覧ください。同じモジュールからの選択肢としては、QueueFuture、SerialQueueFuture、ReducingFuture などがあります。

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

map_async(callback, pass_batch_into_callback=None, merge_future=None, **q_options)

クエリ結果に対してコールバック関数やタスクレットを非同期的にマッピングします。これは、map() の非同期バージョンです。

NDB Query クラス

クエリ オプション

コンストラクタ

インスタンス メソッド

クエリオプション

インスタンスメソッド