GQL リファレンス

GQL は、App Engine のスケーラブルなデータストアからデータ エンティティを検索するための、SQL のような言語です。GQL の機能は従来のリレーショナル データベースに使用するクエリ言語の機能とは異なりますが、GQL の構文は SQL の構文と似ています。

GQL の構文を要約すると、次のようになります。

  SELECT * FROM <kind>
    [WHERE <condition> [AND <condition> ...]]
    [ORDER BY <property> [ASC | DESC] [, <property> [ASC | DESC] ...]]
    [LIMIT [<offset>,]<count>]
    [OFFSET <offset>]

  <condition> := <property> {< | <= | > | >= | = | != } <value>
  <condition> := <property> IN <list>
  <condition> := ANCESTOR IS <entity or key>

SQL の場合と同様、GQL キーワードは大文字と小文字が区別されません。種類とプロパティの名前は、大文字と小文字が区別されます。

GQL クエリは、要求された種類のデータ エンティティを、その種類のモデル クラスのインスタンスとして 0 個以上返します。結果は常に完全なエンティティですから、どの GQL クエリも必ず SELECT * FROM で始まり、次にその種類の名前が続きます （SQL のようなフィールドの指定子は常に * です。親しみやすいように SQL 構文を保持しています）。GQL クエリでは SQL のような「結合」クエリは使用できません。

オプションの WHERE 節は、結果セットを 1 つ以上の条件を満たすエンティティにフィルタリングします。各条件では、比較演算子を使用して、エンティティのプロパティと値を比較します。AND キーワードを使用して複数の条件を指定すると、クエリはすべての条件を満たしたエンティティを返します。GQL では OR 演算子を使用しません。ただし、GQL は IN 演算子を使用します。これは制限付きの OR です。

IN 演算子は、プロパティの値とリスト内の各アイテムを比較します。IN 演算子は、各値に 1 つのクエリが OR 演算された多数の = クエリに相当します。このクエリでは、指定されたプロパティの値がリスト内の値と同じであるエンティティが返されます。

注: IN と != の各演算子は、背後で複数のクエリを使用します。たとえば IN 演算子は、リスト内のどのアイテムについても、基礎となるデータストア クエリを個別に実行します。返されたエンティティは、すべての基礎となるデータストア クエリのクロス積の結果であり、重複が除去されます。1 つの GQL クエリに最大 30 のデータストア クエリが許可されます。

条件によって、指定されたエンティティが、あるエンティティの祖先かどうか、ANCESTOR IS 演算子を使用してテストすることもできます。値は祖先エンティティのモデル インスタンスか Key です。祖先の詳細については、キーとエンティティ グループをご覧ください。

比較の左側は常にプロパティ名です。右側は（プロパティのデータ型に応じて）次のいずれかです。

• str リテラル（一重引用符で囲まれた文字列）文字列内の一重引用符は '' としてエスケープされます。例: 'Joe''s Diner'
• 整数または浮動小数点数リテラル。例: 42.7
• Boolean リテラル（TRUE または FALSE）
• 日時、日付、時刻リテラル（数値または文字列表現）で、次の形式のもの:
  • DATETIME(year, month, day, hour, minute, second)
  • DATETIME('YYYY-MM-DD HH:MM:SS')
  • DATE(year, month, day)
  • DATE('YYYY-MM-DD')
  • TIME(hour, minute, second)
  • TIME('HH:MM:SS')
• エンティティ キー リテラル（文字列エンコードされたキー、または種類の完全パスとキー名/ID 付き）:
  • KEY('encoded key')
  • KEY(kind, name/ID [, kind, name/ID...])
• User オブジェクト リテラル（ユーザーのメール アドレス付き）:
  USER(email-address)
• GeoPt リテラル（浮動小数点数値の緯度と経度付き）:
  GEOPT(lat, long)
• バウンド パラメータ値。クエリ文字列では、位置パラメータが数値によって参照されます。title = :1キーワード パラメータは名前によって参照されます。title = :mytitle

バウンド パラメータは、GqlQuery コンストラクタや Model クラスの gql() メソッドに渡される位置引数またはキーワード引数としてバインドされます。対応する値リテラル構文を持たないプロパティ データ型は、リスト データ型を含め、パラメータ バインディングを使用して指定する必要があります。パラメータ バインディングは（たとえばクエリを効率よく再利用するため）GqlQuery インスタンスの寿命が存続しているうちに、bind() メソッドを使用して新しい値と再バインドすることができます。

オプションの ORDER BY 節は、指定されたプロパティに応じて昇順（ASC）または降順（DESC）で結果を並び替えて返すように指定します。並び替えの順序を指定しないと、デフォルトの ASC になります。ORDER BY 節は複数の並び替え順序を、左から右に評価されたカンマ区切りリストとして指定することができます。

オプションの LIMIT 節によって、最初の count エンティティの後、クエリが結果を返さなくなります。多数の結果をスキップして最初に返す結果を見つけるために、LIMIT に offset を含めることもできます。オプションの OFFSET 節では offset を指定できます（LIMIT 節がある場合）。

注: LIMIT 節の最大値は 1000 です。limit の指定値がこれより大きい場合は、最大値が使用されます。これと同じ最大値が GqlQuery クラスの fetch() メソッドにも適用されます。

注: fetch()メソッドの offsetパラメータと同様、GQL クエリ文字列内の OFFSET によって、データストアからフェッチされたエンティティの数は減りません。fetch() メソッドによって返される結果に影響を与えるだけです。offset のないクエリのパフォーマンス特性は offset サイズと直線的に比例します。

GQL クエリの実行、パラメータ バインディング、結果へのアクセスについては、GqlQuery クラスと Model.gql() クラス メソッドをご覧ください。