お気に入り | 日本語 | ログイン

GqlQuery クラス

GqlQuery クラスは、App Engine クエリ言語 GQL を使用するデータストア クエリ インターフェースです。

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

概要

GQL は、App Engine データストアのクエリに適した、SQL のようなクエリ言語です。GQL の構文と機能の詳細については、GQL リファレンスをご覧ください。

GqlQuery コンストラクタは、SELECT * FROM model-name で始まる完全な GQL ステートメントを引数とします。WHERE 節内の値は、文字列リテラルや数値リテラルにするか、値に対するパラメータ バインディングを使用できます。バウンド パラメータを最初にバインドするには、コンストラクタに渡す位置引数やキーワード引数を使用します。

query = GqlQuery("SELECT * FROM Song WHERE composer = 'Lennon, John'")

query = GqlQuery("SELECT * FROM Song WHERE composer = :1", "Lennon, John")

query = GqlQuery("SELECT * FROM Song WHERE composer = :composer", composer="Lennon, John")

便宜上、Model と Expando の各クラスには、GqlQuery インスタンスを返す gql() メソッドがあります。このメソッドの GQL クエリ文字列に SELECT * FROM model-name の記述はありませんが、暗黙に示されています。

query = Song.gql("WHERE composer = 'Lennon, John'")

Query クラスと同様、アプリケーションはクエリを実行して、fetch() メソッドを呼び出すか、GqlQuery オブジェクトを iterable として処理する方法で、そのクエリの結果にアクセスします。詳細については、Query のドキュメントをご覧ください。

Query と GqlQuery では、結果にアクセスする方法に 1 つの違いがあります。 GQL クエリに LIMIT 節または OFFSET 節が含まれている場合、イテレータ インターフェースを使用して結果にアクセスしても、同等の fetch() メソッドを使用した場合と同じ結果が得られます。GQL に LIMIT や OFFSET が含まれている GqlQuery を iterable として使用すると、一度の呼び出しですべての結果がフェッチされ、イテレータがメモリから個別の結果を返します。

for song in q:
  print song.title

Query（オブジェクトとメソッドを使用して GQL ではなくクエリを作成するクエリ クラス）もご覧ください。

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

コンストラクタ

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

class GqlQuery(query_string, *args, **kwds)

App Engine クエリ言語 GQL を使用したクエリ オブジェクト。

引数:

query_string
SELECT * FROM model-name で始まる完全な GQL ステートメント。
*args
位置パラメータ バインディング。
**kwds
キーワード パラメータ バインディング。

インスタンス メソッド

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

bind(*args, **kwds)

クエリのパラメータを再バインドします。パラメータが再バインドされた後、初めて結果にアクセスしたときに、新しいクエリが実行されます。

再バインドではクエリ文字列を再度解析する必要がないので、新しい GqlQuery オブジェクトを作成するよりも、新しいパラメータで GqlQuery オブジェクトを再利用した方が処理が速くなります。

引数:

*args
新しい位置パラメータ バインディング。
**kwds
新しいキーワード パラメータ バインディング。
get()

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

get() は「制限」が 1 であることを暗黙に示し、GQL クエリの LIMIT 節があれば、これをオーバーライドします。最大 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

返す結果の数。この値は、GQL クエリ ステートメントの LIMIT 節（ある場合）をオーバーライドします。条件に合った結果が不足していると、返される結果の数は limit より少なくなる場合があります。

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

offset
スキップする結果の数。この値は、GQL クエリ ステートメントの OFFSET 節（または LIMIT 節の ofse）（ある場合）をオーバーライドします。

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

count(limit)

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

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

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

引数:

limit

カウントする結果の最大数。この値は、GQL クエリ ステートメントの LIMIT 節（ある場合）をオーバーライドします。