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

このページの内容
Summary

google.appengine.ext.ndb.query モジュール

概要

高レベルのクエリラッパー。

ここで取り上げる基本的な API は、6 つの比較演算子をオーバーロードしてプロパティ値に対するフィルタを表現し、AND 演算と OR 演算をサポートしています（これらは関数として実装されています。Python の「and」演算子と「or」演算子はオーバーロードできず、「&」演算子と「|」演算子の優先度は比較演算子の優先度と競合します）。例:

class Employee(Model):
  name = StringProperty()
  age = IntegerProperty()
  rank = IntegerProperty()

  @classmethod
  def demographic(cls, min_age, max_age):
    return cls.query().filter(AND(cls.age >= min_age, cls.age <= max_age))

  @classmethod
  def ranked(cls, rank):
    return cls.query(cls.rank == rank).order(cls.age)

for emp in Employee.seniors(42, 5):
  print emp.name, emp.age, emp.rank

「in」演算子のオーバーロードはできませんが、IN() メソッドを通じてサポートされています。次に例を示します。

Employee.query().filter(Employee.rank.IN([4, 5, 6]))

並べ替え順序は order() メソッドでサポートされています。降順を表す場合は、プロパティクラスに単項マイナスがオーバーロードされます。

Employee.query().order(Employee.name, -Employee.age)

AND() と OR() を使用する以外にも、.filter() を繰り返し呼び出すことによってフィルタを組み合わせることもできます。

q1 = Employee.query()  # A query that returns all employees
q2 = q1.filter(Employee.age >= 30)  # Only those over 30
q3 = q2.filter(Employee.age < 40)  # Only those in their 30s

さらにショートカットするには、複数の引数を指定して .filter() を呼び出します。これは AND() を意味します。

q1 = Employee.query()  # A query that returns all employees
q3 = q1.filter(Employee.age >= 30,
               Employee.age < 40)  # Only those in their 30s

最後に、1 つまたは複数のフィルタ式を query() メソッドに直接渡すこともできます。

q3 = Employee.query(Employee.age >= 30,
                    Employee.age < 40)  # Only those in their 30s

クエリオブジェクトは不変であるため、これらのメソッドは常に新しいクエリオブジェクトを返します。上記のように filter() を呼び出しても q1 には影響しません（一方、事実上何もしないオペレーションは元のクエリオブジェクトを返すことがあります）。

並べ替え順序もこのように組み合わせることができ、.filter() の呼び出しと .order() の呼び出しが混在することもあります。

q4 = q3.order(-Employee.age)
q5 = q4.order(Employee.name)
q6 = q5.filter(Employee.rank == 5)

繰り返しますが、複数の .order() の呼び出しを組み合わせることができます。

q5 = q3.order(-Employee.age, Employee.name)

クエリ結果を取得する最も簡単な方法は for-loop です。

for emp in q3:
  print emp.name, emp.age

他のいくつかのメソッドでも、クエリを実行してその結果にアクセスできます。

q.iter() # Return an iterator; same as iter(q) but more flexible
q.map(callback) # Call the callback function for each query result
q.fetch(N) # Return a list of the first N results
q.get() # Return the first result
q.count(N) # Return the number of results, with a maximum of N
q.fetch_page(N, start_cursor=cursor) # Return (results, cursor, has_more)

上記のメソッドには、keys_only=True などのキーワード引数の形式か、options=QueryOptions(...) によって渡される QueryOptions オブジェクトとして、追加のクエリオプションの標準セットを使用できます。最も重要なクエリオプションは次のとおりです。

keys_only: bool。設定した場合、結果はエンティティではなくキーになります。
limit: int。返される結果の数を制限します。
offset: int。指定した数の結果を最初にスキップします。
start_cursor: カーソル。この位置より後の結果から返されます。
end_cursor: カーソル。この位置より後の結果は返されません。
batch_size: int。RPC ごとに返される結果の数に関するヒントです。
prefetch_size: int。最初の RPC における結果の数に関するヒントです。
produce_cursors: bool。結果とともにカーソルオブジェクトを返します。

カーソルの説明を含め、追加の（不明瞭な）クエリオプションとそれらの詳細については、datastore_query.py をご覧ください。

iter() を除く上記のすべてのメソッドに、Future を返す非同期バリエーションがあります。オペレーションの最終的な結果を取得するには、Future を出力する（タスクレット内）か、Future の get_result() メソッドを呼び出します（タスクレット外）。

q.map_async(callback)  # Callback may be a task or a plain function
q.fetch_async(N)
q.get_async()
q.count_async(N)
q.fetch_page_async(N, start_cursor=cursor)

最後に、タスクレット内のクエリ結果を効率的にループし、適切なときに適切に結果を出力するイディオムも用意されています。

it = q.iter()
while (yield it.has_next_async()):
  emp = it.next()
  print emp.name, emp.age

さらに、QueryOptions クラスでサポートされているキーワード引数はすべてサポートされています。特に、次のページをフェッチするには、1 回の呼び出しで返されたカーソルを、start_cursor=<cursor> を使用して次の呼び出しに渡します。一般的には、<cursor>.to_websafe_string() を使用してカーソルをクライアントに渡し、Cursor.from_websafe_string(<string>) を使用して後続のリクエストに対するカーソルを再作成します。

戻り値

タプル (results, cursor, more)。results はクエリ結果のリスト、cursor は最後に返された結果の直後を示すカーソル、more はそれ以降の結果がある（可能性がある）かどうかを示すブール値です。

fetch_page_async(*args, **kwds)ソース

結果のページをフェッチします。

これは Query.fetch_page() の非同期バージョンです。

filter(*args)ソース: 追加のフィルタを適用して、新しいクエリを返します。

filters: フィルタのアクセサー（ノードまたは None）。

get(**q_options)ソース

最初のクエリ結果（ある場合）を取得します。

これは、q.fetch(1) の呼び出しに似ており、結果のリストがある場合はその最初のアイテムを返します。そうでない場合は None を返します。

パラメータ

**q_options - すべてのクエリオプションのキーワード引数がサポートされています。

戻り値

1 つの結果か、結果がない場合は None。

get_async(**q_options)ソース

最初のクエリ結果（ある場合）を取得します。

これは Query.get() の非同期バージョンです。

group_by: group by プロパティのアクセサー（タプルインスタンスまたは None）。

is_distinct

結果に固有のプロパティ値のセットが確実に含まれている場合は True。

これは、group_by のすべてのプロパティが射影にもある場合に発生します。

iter(**q_options)ソース

クエリに対してイテレータを構築します。

パラメータ

**q_options - すべてのクエリオプションのキーワード引数がサポートされています。

戻り値

QueryIterator オブジェクト。

kind: 種類のアクセサー（文字列または None）。

map(*args, **kwds)ソース

クエリ結果に対してコールバック関数やタスクレットをマッピングします。

パラメータ

callback - 各結果に適用する関数またはタスクレット。下記をご覧ください。
merge_future - 省略可能な Future サブクラス。下記をご覧ください。
**q_options - すべてのクエリオプションのキーワード引数がサポートされています。

コールバック署名: コールバックは通常、引数としてエンティティを使用して呼び出されます。ただし、keys_only=True を指定した場合、Key を使用して呼び出されます。また、pass_batch_into_callback が True の場合、現在のバッチ、バッチ内のインデックス、およびそのインデックスのエンティティまたは Key の 3 つの引数を使用して呼び出されます。コールバックは、どんなものでも返します。コールバックが None の場合、渡されたエンティティまたはキーを返すだけの簡単なコールバックが想定されます（produce_cursors は無視されます）。

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

戻り値

クエリの実行が完了し、すべてのコールバックが返されると、map() はすべてのコールバックの結果のリストを返します（ただし、上記で説明した省略可能な merge_future をご覧ください）。

map_async(*args, **kwds)ソース

クエリ結果に対してコールバック関数やタスクレットをマッピングします。

これは Query.map() の非同期バージョンです。

namespace: 名前空間のアクセサー（文字列または None）。

order(*args)ソース: 追加の並べ替え順序を適用して、新しいクエリを返します。

orders: フィルタのアクセサー（datastore_query.Order または None）。

projection: projected プロパティのアクセサー（タプルインスタンスまたは None）。

run_to_queue(*args, **kwds)ソース: このクエリを実行して、エンティティを指定のキューに配置します。

class google.appengine.ext.ndb.query.QueryOptionssource

ベース: google.appengine.ext.ndb.context.ContextOptions、google.appengine.datastore.datastore_query.QueryOptions

コンテキストオプションとクエリオプションの両方をサポートします（特に use_cache）。

class google.appengine.ext.ndb.query.Cursor(*args, **kwds)ソース

ベース： google.appengine.datastore.datastore_query._BaseComponent

クエリ内の相対位置を表す不変クラス。

カーソルで示される位置は、指定のクエリの結果が削除された場合でもその結果に相対的になります。通常は、バッチによって最後に返された結果の直後に配置されます。

カーソルは、それを生成したものと同一の署名を持つクエリ、またはその並べ替え順序を逆にしたクエリでのみ使用してください。

advance(offset, query, conn)ソース

指定したオフセット分だけカーソルを進めます。

パラメータ

offset - 現在のクエリを進める量。
query - このカーソルの作成元となったクエリと同一のクエリ。
conn - 使用する datastore_rpc.Connection。

戻り値

指定のクエリを使用してオフセット分だけ進められる新しいカーソル。

static from_bytes(cursor)ソース

バイト文字列としてシリアル化されたカーソルを取得します。

シリアル化されたカーソルの形式は、下位互換性のない方法で変更される可能性があります。この場合、カーソルは新しいクエリリクエストから再生成する必要があります。

パラメータ

cursor - .to_bytes によって返されるシリアル化されたカーソル。

戻り値

カーソル。

発生

cursor_errors.BadValueError。カーソル引数が

static from_websafe_string(cursor)ソース

ウェブセーフな文字列としてシリアル化されたカーソルを取得します。

パラメータ

cursor - .to_websafe_string によって返されるシリアル化されたカーソル。

戻り値

カーソル。

発生

カーソル引数が文字列でない場合は datastore_errors.BadValueError

reversed()ソース

非推奨。カーソルに対して reversed() を呼び出す必要はなくなりました。

クエリによって返されたカーソルは、並べ替え順序が逆になっているクエリでも使用できます。このメソッドは、元のカーソルのコピーを返します。

to_bytes()ソース: カーソルをバイト文字列としてシリアル化します。

to_websafe_string()ソース

カーソルをウェブセーフな文字列としてシリアル化します。

戻り値

base64 でエンコードされシリアル化されたカーソル。

urlsafe()ソース

カーソルをウェブセーフな文字列としてシリアル化します。

戻り値

base64 でエンコードされシリアル化されたカーソル。

class google.appengine.ext.ndb.query.QueryIterator(*args, **kwds)ソース

ベース: オブジェクト

このイテレータは、同期呼び出し元と非同期呼び出し元の両方で動作します。

同期呼び出し元では、単に以下を使用します。

for entity in Account.query():: <use entity>

非同期呼び出し元では、以下のイディオムを使用します。

it = iter(Account.query()) while (yield it.has_next_async()):

entity = it.next() <use entity>

iter(q) の代わりに q.iter([options]) を使用することもできます。その場合、keys_only や produce_cursors などのクエリオプションを渡すことができます。

keys_only が設定されている場合、it.next() はエンティティの代わりにキーを返します。

generate_cursors を設定すると、it.cursor_before() および it.cursor_after() メソッドは、it.next() によって返されたアイテムの直前と直後のクエリ位置に対応するカーソルオブジェクトを返します。 it.next() が初めて呼び出されると、どちらも例外が発生します。ループを使い果たすと、最後のアイテムが返された後にカーソルが返されます。it.has_next() を呼び出しても、カーソルには影響しません。カーソルを移動する前に it.next() を呼び出す必要があります。カーソルをリクエストする際に Cloud Datastore ラウンドトリップが必要になる場合もあります（ただし、バッチ境界に対応するカーソルをリクエストする場合は必要ありません）。produce_cursors が設定されていない場合、両方のメソッドで常に例外が発生します。

複数のクエリ（IN、!=、または OR 演算子を使用するクエリ）のメモリ内のマージを必要とするクエリでは、クエリオプションはサポートされていないことに注意してください。

cursor_after()ソース

現在のアイテムの後にカーソルを返します。

これを機能させるには、produce_cursors=True を指定した QueryOptions オブジェクトを渡す必要があります。

カーソルまたは現在のアイテムが存在しない場合、BadArgumentError が発生します。 next() によって返されるまで、カーソルは存在しません。ループを使い果たすと、最後のアイテムの後にカーソルが返されます。

cursor_before()ソース

現在のアイテムの前にカーソルを返します。

これを機能させるには、produce_cursors=True を指定した QueryOptions オブジェクトを渡す必要があります。

has_next()ソース

次のアイテムが利用可能かどうかを返します。

使用パターンについては、docstring モジュールをご覧ください。

has_next_async(*args, **kwds)ソース

Future を返します。その結果は、次のアイテムが利用可能かどうかを示します。

使用パターンについては、docstring モジュールをご覧ください。

index_list()ソース

このクエリに使用されるインデックスのリストを返します。

これは、インデックス表現が get_indexes() によって返されるものと同じインデックス表現のリストを返します。

最初の結果が取得されるまで、情報は利用できず、None が返されます。これは空のリストと同じではありません。空のリストは、クエリを実行するためにインデックスが使用されなかったことを意味します（dev_appserver では、空のリストは組み込みインデックスのみが使用されたことも意味する場合があります。メタデータクエリもここで空のリストを返します）。

適切な使用法は次のとおりです。

q = <modelclass>.query(<filters>) i = q.iter() try:

i.next()

except Stopiteration:: pass

indexes = i.index_list() assert isinstance(indexes, list)

注: - produce_cursors=False を強制すると常に None が返されます。 - マルチクエリでは常に None が返されます。

next()ソース: イテレータプロトコル: 次のアイテムを取得します。取得できない場合は、StopIteration が発生します。

probably_has_next()ソース

次のアイテムが（おそらく）利用可能かどうかを返します。

これは has_next() とまったく同じではありません。

produce_cursors が設定されている場合、いくつかのショートカットが可能なためです。しかし、場合によっては（クエリに post_filter がある場合など）、偽陽性になることがあります（True が返されますが、next() で StopIteration が発生します）。偽陰性はありません。

class google.appengine.ext.ndb.query.RepeatedStructuredPropertyPredicate(match_keys, pb, key_prefix)ソース: ベース： google.appengine.datastore.datastore_query.FilterPredicate

google.appengine.ext.ndb.query.AND: ConjunctionNode のエイリアス

google.appengine.ext.ndb.query.OR: DisjunctionNode のエイリアス

class google.appengine.ext.ndb.query.ConjunctionNodesource

Bases: google.appengine.ext.ndb.query.Node

2 つ以上のノードに対するブール AND 演算子を表すツリーノード。

resolve(bindings, used)ソース

class google.appengine.ext.ndb.query.DisjunctionNodesource

Bases: google.appengine.ext.ndb.query.Node

2 つ以上のノードに対するブール OR 演算子を表すツリーノード。

resolve(bindings, used)ソース

class google.appengine.ext.ndb.query.FilterNodesource

Bases: google.appengine.ext.ndb.query.Node

1 つのフィルタ式のツリーノード。

class google.appengine.ext.ndb.query.PostFilterNodesource

Bases: google.appengine.ext.ndb.query.Node

メモリ内フィルタリングオペレーションを表すツリーノード。

これは、構造化された値のクエリなど、データストアで実行できないフィルタを表すのに使用されます。

class google.appengine.ext.ndb.query.FalseNodesource

Bases: google.appengine.ext.ndb.query.Node

常に失敗するフィルタのツリーノード。

class google.appengine.ext.ndb.query.Nodesource

ベース: オブジェクト

フィルタ式ツリーノードの基本クラス。

ツリーノードは、不変ではないパラメータインスタンスを含んでいる場合がありますが、不変であるとみなされます。特に、2 つの同一のツリーは、異なるコンテキストで同じノードオブジェクトで表すことができます。

resolve(bindings, used)ソース

パラメータを選択した値に置き換えたノードを返します。

パラメータ

bindings - 整数と文字列を値にマッピングする辞書。
used - バインディングの使用が記録された辞書。

戻り値

ノードインスタンス。

class google.appengine.ext.ndb.query.ParameterNodesource

Bases: google.appengine.ext.ndb.query.Node

パラメータ化されたフィルタのツリーノード。

resolve(bindings, used)ソース

class google.appengine.ext.ndb.query.ParameterizedThingsource

ベース: オブジェクト

Parameter および ParameterizedFunction の基本クラス。

これは単に isinstance() チェックのために存在します。

class google.appengine.ext.ndb.query.Parameter(key)source

ベース: google.appengine.ext.ndb.query.ParameterizedThing

GQL クエリのバインドされた変数を表します。

Parameter(1) は、GQL クエリで「:1」というラベルの付いたスロットに対応します。 Parameter(‘xyz’) は、「:xyz」というラベルの付いたスロットに対応します。

値は、.set(value) を呼び出すことによって個別に設定（バインド）されなければなりません。

key: キーを取得します。

resolve(bindings, used)ソース

class google.appengine.ext.ndb.query.ParameterizedFunction(func, values)ソース

ベース: google.appengine.ext.ndb.query.ParameterizedThing

パラメータ化された引数を持つ GQL 関数を表します。

たとえば、ParameterizedFunction(‘key’, [Parameter(1)]) は GQL 構文 KEY(:1) を表します。

func

is_parameterized()ソース

resolve(bindings, used)ソース

values

google.appengine.ext.ndb.query.gql(query_string, *args, **kwds)ソース

GQL クエリ文字列を解析します。

パラメータ

query_string - 完全な GQL クエリ。たとえば、'SELECT * FROM Kind WHERE prop = 1' です。
**kwds (*args,) -
存在する場合は、bind() を呼び出すために使用されます。

戻り値

query_class のインスタンス。

google.appengine.ext.ndb.query モジュール

概要

目次