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

概要

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

世界には非常に多くのクエリ API が存在するものと思われます。

ここで取り上げる基本的な 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

内容

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

ベース: object

クエリ オブジェクト。

通常、Model.query() を呼び出すことによって構築されます。

例については、docstring モジュールをご覧ください。

クエリに対するすべてのオペレーションが _MultiQuery インスタンスでサポートされるわけではないことに注意してください。後者は、演算子 !=、IN、または OR のいずれかを使用した場合に必要に応じて生成されます。

analyze()ソース

クエリで必要なパラメータを示すリストを返します。

ancestor

祖先のアクセサー(Key または None)。

app

アプリのアクセサー(文字列または None)。

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

パラメータ値をバインドします。新しいクエリ オブジェクトを返します。

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

クエリ結果の数を制限値までカウントします。

これは len(q.fetch(limit)) と同じ結果をより効率的に返します。

クエリによって実行される処理量を制限するには、最大値を渡す必要があります。

パラメータ
  • limit - カウントする結果の最大数。

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

戻り値:

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

クエリ結果の数を制限値までカウントします。

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

default_options

default_options のアクセサー(QueryOptions インスタンスまたは None)。

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

制限値まで、クエリ結果のリストをフェッチします。

パラメータ
  • limit - 取得する結果の最大数。

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

戻り値

結果のリスト。

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

制限値まで、クエリ結果のリストをフェッチします。

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

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

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

ユーザー インターフェースのページングで使用するための特別なメソッドです。

パラメータ

page_size - リクエストするページサイズ。返される結果の最大サイズです。

さらに、QueryOptions クラスでサポートされているキーワード引数はすべてサポートされています。特に次ページをフェッチするには、ある呼び出しで返されたカーソルを、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 つを置換することで、別の設定にすることができます。デフォルトの実装および merge_future オブジェクトでデフォルトを実装する必要があるプロトコルの説明については、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.QueryOptionsソース

ベース: 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 によって返されるシリアル化されたカーソル。

戻り値

カーソル。

発生
  • datastore_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)ソース

ベース: object

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

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

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() はエンティティの代わりにキーを返します。

produce_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 オブジェクトを渡す必要があります。

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

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.ConjunctionNodeソース

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

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

resolve(bindings, used)ソース
class google.appengine.ext.ndb.query.DisjunctionNodeソース

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

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

resolve(bindings, used)ソース
class google.appengine.ext.ndb.query.FilterNodeソース

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

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

class google.appengine.ext.ndb.query.PostFilterNodeソース

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

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

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

class google.appengine.ext.ndb.query.FalseNodeソース

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

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

class google.appengine.ext.ndb.query.Nodeソース

ベース: object

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

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

resolve(bindings, used)ソース

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

パラメータ
  • bindings - 整数と文字列を値にマッピングする辞書。

  • used - バインディングの使用が記録された辞書。

戻り値

ノード インスタンス。

class google.appengine.ext.ndb.query.ParameterNodeソース

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

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

resolve(bindings, used)ソース
class google.appengine.ext.ndb.query.ParameterizedThingソース

ベース: object

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

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

class google.appengine.ext.ndb.query.Parameter(key)ソース

ベース: 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 のインスタンス。

このページは役立ちましたか?評価をお願いいたします。

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

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