Query クラス

Query クラスは、オブジェクトとメソッドを使用してクエリを作成するデータストア クエリ インターフェースです。

Query は、google.appengine.ext.db モジュールによって提供されます。

• 概要
• Query()
• インスタンス メソッド:
  • filter()
  • order()
  • ancestor()
  • get()
  • fetch()
  • count()

概要

アプリケーションは、照会するエンティティが属する Model クラスを使用してコンストラクタを呼び出すか、そのクラスの all() クラス メソッドを呼び出して、Query オブジェクトを作成します。

class Song(db.Model):
  title = db.StringProperty()
  composer = db.StringProperty()
  date = db.DateTimeProperty()

query = db.Query(Song)

query = Song.all()

変更がなければ、オブジェクトは、指定された種類のすべてのエンティティのクエリを表します。メソッドの呼び出しは、プロパティ条件（filter()）、祖先条件（ancestor()）、並び替え（order()）を使用して、クエリをカスタマイズします。便宜上、これらのメソッドは、1 つのステートメントでチェーン処理することができるように self を返します。

query.filter('title =', 'Imagine')
query.order('-date')
query.ancestor(key)

query.filter('title =', 'Imagine').order('-date').ancestor(key)

アプリケーションがクエリを実行する方法は、次の 2 つの内のどちらかです。

• fetch() メソッドを呼び出す方法。これによってデータストアが 1 回呼び出され、指定された上限数の結果がフェッチされます。Query オブジェクトは結果をキャッシュしないので、次に fetch() を呼び出すると、またクエリが実行されます。

  results = query.fetch(limit=5)
  for song in results:
    print song.title
  

• Query オブジェクトを iterable として処理する方法。イテレータはデータストアからの結果を小さなバッチで取得することにより、アプリケーションによる結果の繰り返し処理を防ぎ、必要以上のフェッチをしないようにします。クエリに一致した結果がすべて取得されると、繰り返しは停止します。fetch() と同様、イテレータ インターフェースは結果をキャッシュしないので、Query オブジェクトから新しいイテレータを作成すると、またクエリが実行されます。

  for song in query:
    print song.title
  

GqlQuery（SQL に似たクエリ言語を使用するクエリ クラス）もご覧ください。

注: データストア クエリを強化するインデックス ベースのデータ構造とアルゴリズムは、一部の種類のクエリをサポートしていません。詳細については、クエリとインデックス: クエリの制限をご覧ください。

コンストラクタ

Query クラスのコンストラクタは、次のように定義されます。

class Query(model_class)

オブジェクトとメソッドを使用してクエリを作成するデータストア クエリ インターフェース。

コンストラクタが返す Query インスタンスは、その種類のすべてのエンティティに対応するクエリを表します。filter()、order()、ancestor() の各インスタンス メソッドは、クエリに条件を適用して結果のフィルタリングや並び替えを行います。

引数:

model_class

クエリに対応したデータストア エンティティの種類を表す Model（または Expando）のクラス。

インスタンス メソッド

Query クラスのインスタンスには次のメソッドがあります。

filter(property_operator, value)

プロパティ条件フィルタをクエリに追加します。すべての条件に合ったプロパティを持つエンティティだけが、クエリによって返されます。

引数:

property_operator

プロパティ名と、オプションの比較演算子を含む文字列。名前と演算子は、age > と同様にスペースで区切る必要があります。比較演算子として、< <= = >= > != IN がサポートされています。演算子が文字列で省略されている場合（引数がプロパティ名だけの場合）、フィルタでは = 演算子が使用されます。

value

比較する場合に、式の右辺に使用する値。値の型は、比較するプロパティに合ったデータ型にします。詳細については、型とプロパティ クラスをご覧ください。

query.filter('height >', 42).filter('city = ', 'Seattle')

query.filter('user = ', users.get_current_user())

order(property)

結果の並び替えを追加します。最初に追加した順序で始まるように、結果を並び替えます。

引数:

property

並び替えるプロパティの名前の文字列。並び替えを降順に指定するには、名前の前にハイフン（-）を付けます。ハイフンを付けないと、並び替えは昇順になります。

# Order by last name, alphabetical:
query.order('last_name')

# Order tallest to shortest:
query.order('-height')

ancestor(ancestor)

祖先条件フィルタをクエリに追加します。指定されたエンティティを（パスのどこかに）祖先として持つエンティティだけが、クエリによって返されます。

引数:

ancestor

祖先を表す Model インスタンスまたは Key インスタンス。

get()

クエリを実行して、最初の結果を返すか、クエリが結果を返さない場合は None と出力されます。

get() は「制限」が 1 であることを暗黙に示します。最大 1 件の結果がデータストアからフェッチされます。

fetch(limit, offset=0)

クエリを実行して、結果を返します。

limit および offset 引数はそれぞれ、データストアからフェッチする結果の数と fetch() メソッドによって返される結果の数をコントロールします。

• データストアが offset +limit の結果をフェッチし、アプリケーションに渡します。最初の offset 結果は、データストアそのものによってスキップ されません。
• fetch() メソッドが最初の offset 結果をスキップし、残り（limit 結果）を返します。
• クエリの性能特性は、offset 数 + limit と直線的に比例します。

注: fetch() は最大 1000 件の結果を返します。クエリに一致するエンティティが 1000 を超えた場合は、limit が指定されていないか、使用している limit が 1000 より大きいと、fetch() は最初の 1000 の結果だけを返します。

引数:

limit

返す結果の数。条件に合った結果が不足していると、返される結果の数は limit より少なくなる場合があります。

limit は必須の引数です。結果の数が不明のとき、クエリからすべての結果を得るには、fetch() メソッドを使用せずに、Query オブジェクトを iterable として使用します。

offset

スキップする結果の数。

戻り値はモデル インスタンスのリストです。これは空のリストの場合もあります。

count(limit)

このクエリがフェッチする結果の数を返します。

count() は、一定の係数ですべてのデータを検索するよりはいくらか高速ですが、実行時間は結果セットのサイズに応じて長くなります。count が小さいと予測される場合だけ count() を使用するか、limit を指定するのがよいでしょう。

注: count() の戻り値は最大 1000 です。クエリ条件に合う実際のエンティティ数が最大数を超えると、count() は 1000 を返します。

引数:

limit

カウントする結果の最大数。