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

クエリの制限

このページでは、Google App Engine から Datastore に行うクエリに関する制限について説明します。次のリストは、Datastore 向けの開発時に課される一般的な制限です。

クエリで指定されたプロパティがないエンティティは無視される

同じ種類のエンティティが同じプロパティを持つとは限りません。エンティティがクエリ結果の対象になるためには、クエリのフィルタと並べ替え順序で指定されているすべてのプロパティについて値（場合によっては null）を持っていなければなりません。そうでない場合、そのエンティティはクエリの実行に使われるインデックスから除外され、クエリの結果に含まれなくなります。

インデックス付けされていないプロパティのフィルタリングには結果が返されない

クエリは、インデックス付けされていないプロパティ値を見つけられず、そのようなプロパティを並べ替えることもできません。

不等式フィルタの対象は最大で 1 つのプロパティに制限される

インデックス全体をスキャンしなくても済むように、クエリメカニズムでは、潜在的なクエリの結果がすべてインデックス内で互いに隣接していることが求められます。この制約を満たすため、単一のクエリの中では、すべてのフィルタにわたり複数のプロパティに対して不等比較（<、<=、>、>=）を使うことはできません。たとえば次のクエリは、どちらの不等式フィルタも同じプロパティに適用されているため有効です。

q := datastore.NewQuery("Person").
	Filter("BirthYear >=", minBirthYear).
	Filter("BirthYear <=", maxBirthYear)

ただし次のクエリは 2 種類のプロパティに対して不等式フィルタを使用しているため無効です。

q := datastore.NewQuery("Person").
	Filter("BirthYear >=", minBirthYear).
	Filter("Height <=", maxHeight) // ERROR

クエリでは、複数のプロパティに対する等式（=）フィルタと、単一のプロパティに対する 1 つ以上の不等式フィルタを組み合わせることができます。そのため、次のクエリは有効です。

q := datastore.NewQuery("Person").
	Filter("LastName =", targetLastName).
	Filter("City =", targetCity).
	Filter("BirthYear >=", minBirthYear).
	Filter("BirthYear <=", maxBirthYear)

並べ替え順序が指定されていない場合、クエリ結果の順序付けは定義されない

クエリで並べ替え順序を指定していない場合、結果は取得された順序で返されます。この順序は、Datastore 実装の進展（またはアプリケーションのインデックスの変更）に伴って変化する可能性があります。そのため、クエリの結果が特定の順序に並べ替えられている必要があるアプリケーションでは、並べ替え順序をクエリで明示的に指定してください。

等式フィルタが使用されたプロパティでは並べ替え順序が無視される

特定のプロパティに対して等式フィルタが使われているクエリでは、そのプロパティに対するいかなる並べ替え順序も無視されます。そのプロパティについては、すべての結果で同じ値になるため、それ以上の並べ替えは不要です。これは、単一値のプロパティに対する不要な処理を節減するシンプルな最適化といえます。ただし複数の値を持つプロパティは、等式フィルタに一致したもの以外にも値を持つ可能性があります。このユースケースはまれであり、並べ替え順序を適用するとコストがかかり、余分なインデックスが必要となるため、Datastore のクエリプランナーでは複数の値を持つ場合であっても単純に並べ替え順序を無視しています。これは、プロパティの値から連想される順序とは異なる順序でクエリの結果が返される原因となる可能性があります。

不等式フィルタで使われているプロパティは最初に並べ替える必要がある

不等式フィルタに一致するすべての結果を取得するため、クエリは、まずフィルタに一致する最初の行のインデックスをスキャンし、一致しない行に遭遇するまでスキャンを進めます。連続した行に結果セット全体が含まれるようにするため、他のプロパティよりも前に、不等式フィルタで使われているプロパティを基準として行を並べ替える必要があります。そのため、クエリで 1 つ以上の不等式フィルタとともに 1 つ以上の並べ替え順序を指定している場合は、最初の並べ替え順序で参照するプロパティが不等式フィルタで指定されているプロパティと同じものでなければなりません。次に有効なクエリを示します。

q := datastore.NewQuery("Person").
	Filter("BirthYear >=", minBirthYear).
	Order("BirthYear").
	Order("LastName")

次のクエリは、不等式フィルタで使われているプロパティを基準として並べ替えを行っていないため無効です。

q := datastore.NewQuery("Person").
	Filter("BirthYear >=", minBirthYear).
	Order("LastName") // ERROR

同様に、次のクエリは不等式フィルタで使われているプロパティが最初に並べ替えられていないため無効です。

q := datastore.NewQuery("Person").
	Filter("BirthYear >=", minBirthYear).
	Order("LastName").
	Order("BirthYear") // ERROR

複数の値を持つプロパティは予期せぬ動作をする場合がある

同じプロパティに対して複数の値があるエンティティでは、クエリのフィルタや並べ替え順序に対する動作が予期しない意外なものになる場合があります。これはインデックス付けの仕組みによります。

特定のプロパティに対して複数の不等式フィルタが使われているクエリの場合、そのプロパティの個別の値の少なくとも 1 つがフィルタの「すべて」を満たす場合のみ、エンティティがクエリと一致するものとみなされます。たとえば、種類 Widget のエンティティのプロパティ x の値が 1 と 2 である場合、クエリと一致しません。

q := datastore.NewQuery("Widget").
	Filter("x >", 1).
	Filter("x <", 2)

エンティティの x 値は、それぞれいずれかのフィルタを満たしていますが、どちらも単体では両方のフィルタを満たしていません。これは等式フィルタには適用されない点に注意してください。たとえば、同じエンティティであれば、クエリ条件を満たします。

q := datastore.NewQuery("Widget").
	Filter("x =", 1).
	Filter("x =", 2)

エンティティの x 値は、個別では両方のフィルタ条件を満たすものがないことに注目してください。

同様に、複数の値を持つプロパティの並べ替え順序も通常とは異なります。このようなプロパティは一意の値ごとに 1 回しかインデックスに表れないため、インデックスに表れる最初の値によってエンティティの並べ替え順序が決定されます。

クエリ結果を昇順で並べ替えると、順序付けにはプロパティの最小値が使用されます。
クエリ結果を降順で並べ替えると、順序付けには最大値が使用されます。
その他の値は、並べ替え順序にも値の数にも影響しません。

これにより、プロパティ値 1 と 9 を持つエンティティが、昇順と降順の両方で、プロパティ値 4、5、6、7 を持つエンティティよりも前に並べられるという、通常とは異なる並び順になります。

トランザクション内のクエリは祖先フィルタを含んでいなければならない

Datastore のトランザクションは、同じエンティティグループ（共通の祖先を持つ子孫）に属するエンティティに対してのみ機能します。この制限を保持するには、トランザクション内で実行されすべてのクエリは、そのトランザクション内の他のオペレーションと同じエンティティグループの祖先を指定する祖先フィルタを含んでいる必要があります。