データストアのクエリ

クエリとは、指定した一連の条件を満たすエンティティを Datastore モードの Cloud Firestore から取得する処理です。

クエリは、特定の種類のエンティティに作用します。クエリでは、エンティティのプロパティ値、キー、祖先に基づくフィルタを指定でき、任意の数のエンティティを「結果 」として返すことができます。また、並べ替え順を指定して、プロパティ値で結果を並べ替えることもできます。結果には、フィルタと並べ替え順で指定されているすべてのプロパティに対応する 1 つ以上の値を持つエンティティの中で、指定されているすべてのフィルタ条件をプロパティ値が満たしているものだけが含まれます。クエリはエンティティ全体や射影されたエンティティを返すこともできれば、エンティティのキーだけを返すこともできます。

一般的に、クエリは次のような要素で構成されます。

クエリを実行すると、指定した種類のすべてのエンティティの中で、指定したすべてのフィルタを満たすものが取得され、指定した順序で並べ替えられます。クエリは読み取り専用として実行されます。

注: メモリを節約し、パフォーマンスを向上させるため、クエリでは可能な限り返される結果の数に対す上限を指定してください。

クエリでは、常に 1 つ以上のインデックスを使用して結果が計算されます。インデックスには、インデックスのプロパティとエンティティの祖先(省略可)によって指定されている順序でエンティティ キーが格納されています。インデックスは、アプリケーションがエンティティに加えた変更を反映して増分的に更新されます。そのため追加の計算を行うことなく、すべてのクエリの正しい結果が得られます。

インデックス ベースのクエリ メカニズムはさまざまなクエリをサポートしているため、ほとんどのアプリケーションに適しています。ただし、他のデータベース テクノロジーでは一般にサポートされているいくつかの種類のクエリがサポートされていません。特に Datastore のクエリエンジンでは、結合と集計クエリがサポートされていない点に注意してください。Datastore モードクエリの制限については、後述のクエリの制限をご覧ください。

クエリ インターフェース

ここでは、Datastore モード データベースにクエリを送信するる基本的な例を示します。優先値(priority)が 4 以上でまだ完了していない(done ではない)すべてのタスクが取得され、優先値の降順で並べ替えられます。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("done", false),
        Filter.GreaterThanOrEqual("priority", 4)),
    Order = { { "priority", PropertyOrder.Types.Direction.Descending } }
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").
	Filter("Done =", false).
	Filter("Priority >=", 4).
	Order("-Priority")

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(
        PropertyFilter.eq("done", false), PropertyFilter.ge("priority", 4)))
    .setOrderBy(OrderBy.desc("priority"))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .filter('done', '=', false)
  .filter('priority', '>=', 4)
  .order('priority', {
    descending: true,
  });

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->filter('done', '=', false)
    ->filter('priority', '>=', 4)
    ->order('priority', Query::ORDER_DESCENDING);

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
query.add_filter('done', '=', False)
query.add_filter('priority', '>=', 4)
query.order = ['-priority']

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .where("done", "=", false)
                 .where("priority", ">=", 4)
                 .order("priority", :desc)

GQL


SELECT * FROM Task
WHERE done = FALSE AND priority >= 4
ORDER BY priority DESC

クエリを実行する方法は次のとおりです。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task");
DatastoreQueryResults tasks = _db.RunQuery(query);

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

it := client.Run(ctx, query)
for {
	var task Task
	_, err := it.Next(&task)
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("Error fetching next task: %v", err)
	}
	fmt.Printf("Task %q, Priority %d\n", task.Description, task.Priority)
}

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

QueryResults<Entity> tasks = datastore.run(query);

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const [tasks] = await datastore.runQuery(query);
console.log('Tasks:');
tasks.forEach(task => console.log(task));

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$result = $datastore->runQuery($query);

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query()
results = list(query.fetch())

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

tasks = datastore.run query

GQL

該当なし

クエリの構造

クエリでは、エンティティの種類、任意の数のフィルタ、任意の数の並べ替え順序を指定できます。

フィルタ

クエリのフィルタでは、取得するエンティティのプロパティキー、祖先に対する制約を設定します。

プロパティ フィルタ

プロパティ フィルタでは、次の要素を指定します。

  • プロパティ名
  • 比較演算子
  • プロパティ値

次の例では、done とマーク付けされていない未完了の Task エンティティを返します。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Filter = Filter.Equal("done", false)
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").Filter("Done =", false)

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query =
    Query.newEntityQueryBuilder().setKind("Task").setFilter(PropertyFilter.eq("done", false))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore.createQuery('Task').filter('done', '=', false);

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->filter('done', '=', false);

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
query.add_filter('done', '=', False)

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .where("done", "=", false)

GQL


SELECT * FROM Task WHERE done = FALSE

プロパティ値はアプリケーションで提供する必要があります。他のプロパティを参照することも、他のプロパティを基準として計算することもできません。エンティティが指定された名前のプロパティを持ち、その値がフィルタで指定された値との比較演算子で示された条件に合致する場合、そのエンティティはフィルタを満たすものとみなされます。指定された名前のプロパティが配列値の場合は、そのいずれかの値がフィルタで指定された値との比較演算子で示された条件に合致する場合に、エンティティがフィルタを満たすものとみなされます。

次の比較演算子を使用できます。

演算子 意味
EQUAL 次に等しい
LESS_THAN 次より小さい
LESS_THAN_OR_EQUAL 次の値以下
GREATER_THAN 次より大きい
GREATER_THAN_OR_EQUAL 次の値以上

複合フィルタ

複合フィルタは、複数のプロパティ フィルタで構成されています。次の例では、done とマーク付けされていない優先値(priority)が 4 の Task エンティティを返します。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("done", false),
        Filter.Equal("priority", 4)),
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").Filter("Done =", false).Filter("Priority =", 4)

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(
        CompositeFilter.and(PropertyFilter.eq("done", false), PropertyFilter.eq("priority", 4)))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .filter('done', '=', false)
  .filter('priority', '=', 4);

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->filter('done', '=', false)
    ->filter('priority', '=', 4);

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
query.add_filter('done', '=', False)
query.add_filter('priority', '=', 4)

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .where("done", "=", false)
                 .where("priority", "=", 4)

GQL


SELECT * FROM Task WHERE done = FALSE AND priority = 4

Datastore モードの Cloud Firestore では、AND 演算子のみを使用したフィルタの組み合わせがネイティブでサポートされています。

主なフィルタ

エンティティのキーの値をフィルタリングするには、特殊なプロパティ __key__ を使用します。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Filter = Filter.GreaterThan("__key__", _keyFactory.CreateKey("aTask"))
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

key := datastore.NameKey("Task", "someTask", nil)
query := datastore.NewQuery("Task").Filter("__key__ >", key)

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(PropertyFilter.gt("__key__", keyFactory.newKey("someTask")))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .filter('__key__', '>', datastore.key(['Task', 'someTask']));

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->filter('__key__', '>', $datastore->key('Task', 'someTask'));

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
first_key = client.key('Task', 'first_task')
# key_filter(key, op) translates to add_filter('__key__', op, key).
query.key_filter(first_key, '>')

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .where("__key__", ">", datastore.key("Task", "someTask"))

GQL


SELECT * FROM Task WHERE __key__ > KEY(Task, 'someTask')

異なる要素を比較する場合、キーは次の条件に従って次の順に順序付けられます。

  1. 祖先パス
  2. エンティティの種類
  3. 識別子(キー名または数値 ID)

祖先パスの各要素も同様に比較され、最初に種類(文字列)、次にキー名または数値 ID を基準として比較されます。種類とキー名は文字列であり、バイト値を基準として順序付けられます。また数値 ID は整数値であり、その数値の順に順序付けられます。同じ親と種類を持つエンティティが文字列のキー名と数値 ID を混用している場合、数値 ID を持つエンティティのほうがキー名を持つエンティティよりも優先されます。

キーを基準としたクエリではプロパティを基準としたクエリと同じようにインデックスを使用し、カスタム インデックスを必要とする場面も基本的に同じですが、いくつかの例外があります。キーに対して不等式フィルタを使用する場合、または昇順の並べ替え順を使用する場合はカスタム インデックスを必要としませんが、降順の並べ替え順を使用する場合は必要になります。またすべてのクエリに共通することですが、開発環境でカスタム インデックスを必要とするクエリを使用すると、インデックス構成ファイルに適切なエントリが作成されます。

並べ替え順序

クエリの並べ替え順序では、次の要素を指定します。

  • プロパティ名
  • 並べ替えの方向(昇順または降順)。デフォルトでは、並べ替え順序は昇順です。

次の例では、Task という種類のエンティティを作成時刻の昇順で並べ替えます。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Order = { { "created", PropertyOrder.Types.Direction.Ascending } }
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").Order("created")

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query =
    Query.newEntityQueryBuilder().setKind("Task").setOrderBy(OrderBy.asc("created")).build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore.createQuery('Task').order('created');

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->order('created');

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
query.order = ['created']

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .order("created", :asc)

GQL


SELECT * FROM Task ORDER BY created ASC

次の例では、Task という種類のエンティティを作成時刻の降順で並べ替えます。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Order = { { "created", PropertyOrder.Types.Direction.Descending } }
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").Order("-created")

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query =
    Query.newEntityQueryBuilder().setKind("Task").setOrderBy(OrderBy.desc("created")).build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore.createQuery('Task').order('created', {
  descending: true,
});

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->order('created', Query::ORDER_DESCENDING);

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
query.order = ['-created']

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .order("created", :desc)

GQL


SELECT * FROM Task ORDER BY created DESC

クエリに複数の並べ替え順序が含まれている場合は、指定されている順序で適用されます。次の例では、最初に優先値の降順で並べ替えを行い、次に作成時刻の昇順で並べ替えを行います。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Order = { { "priority", PropertyOrder.Types.Direction.Descending },
        { "created", PropertyOrder.Types.Direction.Ascending } }
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").Order("-priority").Order("created")

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setOrderBy(OrderBy.desc("priority"), OrderBy.asc("created"))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .order('priority', {
    descending: true,
  })
  .order('created');

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->order('priority', Query::ORDER_DESCENDING)
    ->order('created');

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
query.order = [
    '-priority',
    'created'
]

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .order("priority", :desc)
                 .order("created", :asc)

GQL


SELECT * FROM Task ORDER BY priority DESC, created ASC

並べ替え順序が指定されていない場合、結果は Datastore モードから取得された順序で返されます。

注: あるプロパティに対して不等式フィルタを指定し、別のプロパティに対して並べ替え順序を指定する場合は、不等式フィルタで使用されているプロパティを他のプロパティよりも前に並べる必要があります。これは Datastore モードがクエリを実行する仕組みに原因があります。

特別なタイプのクエリ

特別なタイプのクエリについては、次の点に注意してください。

祖先クエリ

祖先クエリでは、指定されたエンティティとその子孫に結果が制限されます。次の例では、指定した TaskList エンティティを祖先として持つすべての Task エンティティを返します。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Filter = Filter.HasAncestor(_db.CreateKeyFactory("TaskList")
        .CreateKey(keyName))
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

ancestor := datastore.NameKey("TaskList", "default", nil)
query := datastore.NewQuery("Task").Ancestor(ancestor)

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(PropertyFilter.hasAncestor(
        datastore.newKeyFactory().setKind("TaskList").newKey("default")))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const ancestorKey = datastore.key(['TaskList', 'default']);

const query = datastore.createQuery('Task').hasAncestor(ancestorKey);

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$ancestorKey = $datastore->key('TaskList', 'default');
$query = $datastore->query()
    ->kind('Task')
    ->hasAncestor($ancestorKey);

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

# Query filters are omitted in this example as any ancestor queries with a
# non-key filter require a composite index.
ancestor = client.key('TaskList', 'default')
query = client.query(kind='Task', ancestor=ancestor)

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

ancestor_key = datastore.key "TaskList", "default"

query = datastore.query("Task")
                 .ancestor(ancestor_key)

GQL


SELECT * FROM Task WHERE __key__ HAS ANCESTOR KEY(TaskList, 'default')

種類を指定しないクエリ

種類も祖先も指定していないクエリは、アプリケーションのすべてのエンティティを Datastore モードから取得します。このような「種類なしのクエリ」では、プロパティ値に対するフィルタや並べ替え順序を含めることはできません。ただしエンティティ キーを基準としたフィルタリングの実行や祖先フィルタの使用は可能です。プロパティ名として __key__ を指定することで、キーフィルタを使用できます。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query()
{
    Filter = Filter.GreaterThan("__key__",
        _keyFactory.CreateKey("aTask"))
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("").Filter("__key__ >", lastSeenKey)

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query =
    Query.newEntityQueryBuilder().setFilter(PropertyFilter.gt("__key__", lastSeenKey)).build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery()
  .filter('__key__', '>', lastSeenKey)
  .limit(1);

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->filter('__key__', '>', $lastSeenKey);

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query()
query.key_filter(last_seen_key, '>')

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = Google::Cloud::Datastore::Query.new
query.where "__key__", ">", last_seen_key

GQL


SELECT * WHERE __key__ > KEY(Task, 'someTask')

射影クエリ

ほとんどのクエリでは結果としてエンティティ全体が返されますが、多くの場合、アプリケーションが必要とするのはエンティティのプロパティの一部分だけです。射影クエリを使用すると、エンティティのプロパティの中で本当に必要なものだけをクエリできるため、エンティティ全体を取得する場合よりもレイテンシとコストを低く抑えられます。

射影クエリで指定するプロパティには、インデックスが必要です。

キーのみのクエリ

キーのみのクエリ(射影クエリの一種)では、エンティティ自体ではなく、エンティティのキーだけが結果として返されるため、エンティティ全体を取得する場合よりもレイテンシとコストを低く抑えられます。

一般的なクエリを実行すると、実際に必要なものよりも多くのエンティティがフェッチされる場合があります。それに対して、まずキーのみのクエリを実行し、その結果からエンティティのサブセットをフェッチしたほうが、多くの場合経済的です。

ここでは、キーのみのクエリを作成する方法を示します。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Projection = { "__key__" }
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").KeysOnly()

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Key> query = Query.newKeyQueryBuilder().setKind("Task").build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery()
  .select('__key__')
  .limit(1);

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->keysOnly();

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query()
query.keys_only()

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .select("__key__")

GQL


SELECT __key__ FROM Task

キーのみのクエリは小規模なオペレーションであり、クエリ自体については 1 回のエンティティ読み取りとしてカウントされます。

射影

射影クエリは、次のような形式の SQL クエリと似ています。

SELECT priority, percent_complete FROM Task

標準的なエンティティ クエリで使用できるフィルタリングや並べ替えの機能はすべて使用できますが、これらの制限に注意してください。

サンプルの SQL クエリでは、要約された結果が返されます。指定されたプロパティ(prioritypercent_complete)だけに値が格納され、他のすべてのプロパティには格納されません。これを投影クエリとして構築する方法は次のとおりです。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Projection = { "priority", "percent_complete" }
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").Project("Priority", "PercentComplete")

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<ProjectionEntity> query = Query.newProjectionEntityQueryBuilder()
    .setKind("Task")
    .setProjection("priority", "percent_complete")
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .select(['priority', 'percent_complete']);

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->projection(['priority', 'percent_complete']);

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
query.projection = ['priority', 'percent_complete']

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .select("priority", "percent_complete")

GQL


SELECT priority, percent_complete FROM Task

次に射影クエリの実行方法を示します。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Projection = { "priority", "percent_complete" }
};
List<long> priorities = new List<long>();
List<double> percentCompletes = new List<double>();
foreach (var entity in _db.RunQuery(query).Entities)
{
    priorities.Add((long)entity["priority"]);
    percentCompletes.Add((double)entity["percent_complete"]);
}

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

var priorities []int
var percents []float64
it := client.Run(ctx, query)
for {
	var task Task
	if _, err := it.Next(&task); err == iterator.Done {
		break
	} else if err != nil {
		log.Fatal(err)
	}
	priorities = append(priorities, task.Priority)
	percents = append(percents, task.PercentComplete)
}

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

List<Long> priorities = new LinkedList<>();
List<Double> percentCompletes = new LinkedList<>();
QueryResults<ProjectionEntity> tasks = datastore.run(query);
while (tasks.hasNext()) {
  ProjectionEntity task = tasks.next();
  priorities.add(task.getLong("priority"));
  percentCompletes.add(task.getDouble("percent_complete"));
}

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

async function runProjectionQuery() {
  const priorities = [];
  const percentCompletes = [];
  const [tasks] = await datastore.runQuery(query);
  tasks.forEach(task => {
    priorities.push(task.priority);
    percentCompletes.push(task.percent_complete);
  });

  return {
    priorities: priorities,
    percentCompletes: percentCompletes,
  };
}

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$priorities = array();
$percentCompletes = array();
$result = $datastore->runQuery($query);
/* @var Entity $task */
foreach ($result as $task) {
    $priorities[] = $task['priority'];
    $percentCompletes[] = $task['percent_complete'];
}

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

priorities = []
percent_completes = []

for task in query.fetch():
    priorities.append(task['priority'])
    percent_completes.append(task['percent_complete'])

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

priorities = []
percent_completes = []
datastore.run(query).each do |task|
  priorities << task["priority"]
  percent_completes << task["percent_complete"]
end

GQL

該当なし

distinct on 句を使用しない射影クエリは小規模なオペレーションであり、クエリ自体はエンティティの読み取り 1 回としてのみカウントされます。

グループ化

射影クエリでは distinct on 句を使用できます。これを使用すると、指定したプロパティの値の組み合わせごとに最初の結果だけが返されます。つまり射影されているプロパティについて同じ値を持つエンティティが複数存在する場合は、最初の結果だけが返されます。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Projection = { "category", "priority" },
    DistinctOn = { "category" },
    Order = {
        { "category", PropertyOrder.Types.Direction.Ascending},
        {"priority", PropertyOrder.Types.Direction.Ascending }
    }
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").
	Project("Priority", "Category").
	DistinctOn("Category").
	Order("Category").Order("Priority")

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<ProjectionEntity> query = Query.newProjectionEntityQueryBuilder()
    .setKind("Task")
    .setProjection("category", "priority")
    .setDistinctOn("category")
    .setOrderBy(OrderBy.asc("category"), OrderBy.asc("priority"))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .groupBy('category')
  .order('category')
  .order('priority');

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->order('category')
    ->order('priority')
    ->projection(['category', 'priority'])
    ->distinctOn('category');

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
query.distinct_on = ['category']
query.order = ['category', 'priority']

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .select("category", "priority")
                 .distinct_on("category")
                 .order("category")
                 .order("priority")

GQL


SELECT DISTINCT ON (category) category, priority FROM Task
ORDER BY category, priority

配列値

クエリに配列値を持つプロパティが含まれる場合は、次の点に注意してください。

配列値を持つプロパティは意外な動作をする場合がある

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

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

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.GreaterThan("tag", "learn"),
        Filter.LessThan("tag", "math"))
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").
	Filter("Tag >", "learn").
	Filter("Tag <", "math")

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(
        PropertyFilter.gt("tag", "learn"), PropertyFilter.lt("tag", "math")))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .filter('tag', '>', 'learn')
  .filter('tag', '<', 'math');

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->filter('tag', '>', 'learn')
    ->filter('tag', '<', 'math');

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
query.add_filter('tag', '>', 'learn')
query.add_filter('tag', '<', 'math')

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .where("tag", ">", "learn")
                 .where("tag", "<", "math")

GQL


SELECT * FROM Task WHERE tag > 'learn' AND tag < 'math'

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

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("tag", "fun"),
        Filter.Equal("tag", "programming"))
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").
	Filter("Tag =", "fun").
	Filter("Tag =", "programming")

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(
        PropertyFilter.eq("tag", "fun"), PropertyFilter.eq("tag", "programming")))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .filter('tag', '=', 'fun')
  .filter('tag', '=', 'programming');

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->filter('tag', '=', 'fun')
    ->filter('tag', '=', 'programming');

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
query.add_filter('tag', '=', 'fun')
query.add_filter('tag', '=', 'programming')

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .where("tag", "=", "fun")
                 .where("tag", "=", "programming")

GQL


SELECT * FROM Task WHERE tag = 'fun' AND tag = 'programming'

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

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

複数の値を持つプロパティが、どのフィルタでも使用されていない場合:

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

これにより、プロパティ値 19 のエンティティが、昇順と降順の両方で、プロパティ値 4567 のエンティティよりも前に並べられるという異常な並び順になります。

複数の値を持つプロパティが等式フィルタで使用されている場合、そのプロパティに対する並べ替え順序はすべて無視されます

複数の値を持つプロパティが不等式フィルタで使用されている場合:

  • クエリ結果をプロパティの昇順で並べ替えると、順序付けには、クエリのすべての不等式フィルタを満たす最小値が使用されます。
  • クエリ結果をプロパティの降順で並べ替えると、順序付けには、クエリのすべての不等式フィルタを満たす最大値が使用されます。

プロパティに対する一連の不等式フィルタを等式フィルタに変換した場合について考えてみましょう。たとえば次のような場合です。

WHERE tags >= 'math' AND tags <= 'math'

この場合、プロパティに対する並べ替え順序は無視されます。これは、次の等式フィルタと同じようにフィルタの評価が行われるためです。

WHERE tags = 'math'

射影と配列値を持つプロパティ

配列値を持つプロパティを射影しても、そのプロパティのすべての値が格納されるわけではありません。その代わり、クエリに一致する射影された値の一意の組み合わせごとに個別のエンティティが返されます。たとえば、複数の値を持つ 2 つのプロパティ tagscollaborators が設定された Task という種類のエンティティがあるとします。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Entity task = new Entity()
{
    Key = _db.CreateKeyFactory("Task").CreateKey("sampleTask"),
    ["collaborators"] = new ArrayValue() { Values = { "alice", "bob" } },
    ["tags"] = new ArrayValue() { Values = { "fun", "programming" } }
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

type Task struct {
	Tags          []string
	Collaborators []string
}
task := &Task{
	Tags:          []string{"fun", "programming"},
	Collaborators: []string{"alice", "bob"},
}

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Entity task = Entity.newBuilder(taskKey)
    .set("tags", "fun", "programming")
    .set("collaborators", ListValue.of("alice", "bob"))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const task = {
  tags: ['fun', 'programming'],
  collaborators: ['alice', 'bob'],
};

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$task = $datastore->entity(
    $key,
    [
        'tags' => ['fun', 'programming'],
        'collaborators' => ['alice', 'bob']
    ]
);

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

task = datastore.Entity(key)
task.update({
    'tags': [
        'fun',
        'programming'
    ],
    'collaborators': [
        'alice',
        'bob'
    ]
})

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

task = datastore.entity "Task", "sampleTask" do |t|
  t["tags"] = ["fun", "programming"]
  t["collaborators"] = ["alice", "bob"]
end

GQL

該当なし

この状況で、次の射影クエリを実行します。

SELECT tags, collaborators FROM Task WHERE collaborators < 'charlie'

この場合、次の値の組み合わせを持つ 4 つのエンティティが返されます。

tags = 'fun'collaborators = 'alice'
= 'fun'collaborators = 'bob'
= 'programming'collaborators = 'alice'
= 'programming'collaborators = 'bob'

カーソル、制限、オフセット

クエリに対して制限を指定することで、1 バッチで返される結果の最大数を制御できます。次の例では、最大で 5 つの Task エンティティを取得します。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Limit = 5,
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").Limit(5)

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").setLimit(5).build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore.createQuery('Task').limit(5);

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->limit(5);

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query()
tasks = list(query.fetch(limit=5))

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .limit(5)

GQL


SELECT * FROM Task LIMIT 5

クエリカーソルを使用すると、アプリケーションでクエリ オフセットのオーバーヘッドを発生させることなく、クエリの結果を一括取得できます。取得オペレーションを実行した後、カーソルを取得できます。カーソルは不透明なバイト文字列で、最後に結果が取得されたインデックス位置をマークします。アプリケーションはこの文字列を保存し(たとえば、Datastore モードのデータベースやキャッシュに保存するか、base-64 でエンコードされた HTTP GET または POST パラメータとしてウェブページに埋め込む)、後続の取得オペレーションの開始点としてカーソルを使用できます。これにより、前の取得オペレーションが終了した位置から次のバッチの結果を取得できます。取得オペレーションでは終了カーソルも指定できるため、返される結果セットの範囲を制限できます。

次の例は、改ページのカーソルの使用法を示しています。

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Limit = pageSize,
};
if (!string.IsNullOrEmpty(pageCursor))
    query.StartCursor = ByteString.FromBase64(pageCursor);

return _db.RunQuery(query).EndCursor?.ToBase64();

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

const pageSize = 5
query := datastore.NewQuery("Tasks").Limit(pageSize)
if cursorStr != "" {
	cursor, err := datastore.DecodeCursor(cursorStr)
	if err != nil {
		log.Fatalf("Bad cursor %q: %v", cursorStr, err)
	}
	query = query.Start(cursor)
}

// Read the tasks.
var tasks []Task
var task Task
it := client.Run(ctx, query)
_, err := it.Next(&task)
for err == nil {
	tasks = append(tasks, task)
	_, err = it.Next(&task)
}
if err != iterator.Done {
	log.Fatalf("Failed fetching results: %v", err)
}

// Get the cursor for the next page of results.
nextCursor, err := it.Cursor()

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

EntityQuery.Builder queryBuilder = Query.newEntityQueryBuilder().setKind("Task")
    .setLimit(pageSize);
if (pageCursor != null) {
  queryBuilder.setStartCursor(pageCursor);
}
QueryResults<Entity> tasks = datastore.run(queryBuilder.build());
while (tasks.hasNext()) {
  Entity task = tasks.next();
  // do something with the task
}
Cursor nextPageCursor = tasks.getCursorAfter();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

// By default, google-cloud-node will automatically paginate through all of
// the results that match a query. However, this sample implements manual
// pagination using limits and cursor tokens.
async function runPageQuery(pageCursor) {
  let query = datastore.createQuery('Task').limit(pageSize);

  if (pageCursor) {
    query = query.start(pageCursor);
  }
  const results = await datastore.runQuery(query);
  const entities = results[0];
  const info = results[1];

  if (info.moreResults !== Datastore.NO_MORE_RESULTS) {
    // If there are more results to retrieve, the end cursor is
    // automatically set on `info`. To get this value directly, access
    // the `endCursor` property.
    const results = await runPageQuery(info.endCursor);

    // Concatenate entities
    results[0] = entities.concat(results[0]);
    return results;
  }

  return [entities, info];
}

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

/**
 * Fetch a query cursor.
 *
 * @param DatastoreClient $datastore
 * @param string $pageSize
 * @param string $pageCursor
 * @return array
 */
function cursor_paging(DatastoreClient $datastore, $pageSize, $pageCursor = '')
{
    $query = $datastore->query()
        ->kind('Task')
        ->limit($pageSize)
        ->start($pageCursor);
    $result = $datastore->runQuery($query);
    $nextPageCursor = '';
    $entities = [];
    /* @var Entity $entity */
    foreach ($result as $entity) {
        $nextPageCursor = $entity->cursor();
        $entities[] = $entity;
    }
    return array(
        'nextPageCursor' => $nextPageCursor,
        'entities' => $entities
    );
}

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。


def get_one_page_of_tasks(cursor=None):
    query = client.query(kind='Task')
    query_iter = query.fetch(start_cursor=cursor, limit=5)
    page = next(query_iter.pages)

    tasks = list(page)
    next_cursor = query_iter.next_page_token

    return tasks, next_cursor

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

page_size = 2
query = datastore.query("Task")
                 .limit(page_size)
tasks = datastore.run query

page_cursor = tasks.cursor

query = datastore.query("Task")
                 .limit(page_size)
                 .start(page_cursor)

GQL

該当なし

Datastore モードのデータベースでは整数のオフセットをサポートしていますが、使用は避けてください。その代わりにカーソルを使用します。オフセットを使用するとスキップされたエンティティがアプリケーションに返されなくなりますが、そのようなエンティティも内部的には引き続き取得されています。スキップされたエンティティはクエリのレイテンシに影響するだけでなく、そのようなエンティティの取得に必要な読み取りオペレーションに対してアプリケーションが課金されます。このようなコストは、オフセットの代わりにカーソルを使用することですべて回避できます。

カーソルの制限

カーソルには次のような制限があります。

  • カーソルを使用できるのは元のクエリを実行したプロジェクトと同じプロジェクトだけであり、同じクエリに対してのみ処理を継続します。元の生成元から同じクエリを設定しない限り、カーソルを使用して結果を取得することはできません。
  • 次のいずれかの項目が変更された場合でも、後続の取得オペレーションでは引き続きカーソルを使用できます。
    • 開始カーソル
    • 終了カーソル
    • オフセット(offset)
    • 上限
  • 次のいずれかの項目が変更された場合、後続の取得オペレーションではカーソルを使用できなくなります。
    • 射影(projection)
    • 種類(kind)
    • 祖先(ancestor)
    • フィルタ(filter)
    • 重複排除(distinct on)
    • 並べ替え順序(sort order)

      例外は、元のクエリの最後の並べ替え順序が __key__ であった場合です。この場合は「逆引きクエリ」、つまり各並べ替え順序を反転させた元のクエリでカーソルを使用できます。逆引きクエリでは、開始カーソル、終了カーソル、オフセット、上限を変更できます。

  • 複数の値を持つプロパティに対して不等式フィルタまたは並べ替え順序を使用するクエリでは、カーソルが常に予期したとおりに動作するとは限りません。このような複数の値を持つプロパティに対する重複排除ロジックは取得オペレーション間で保持されないため、同じ結果が複数回返される原因となる場合があります。
  • Datastore モードの新しいリリースでは内部実装の詳細が変更される場合があり、それに依存するカーソルは無効になる可能性があります。無効になったカーソルをアプリケーションで使用しようとすると、Datastore モードの Cloud Firestore で例外が発生します。

カーソルとデータ更新

カーソルは、最後の結果が返された後の結果リスト内の位置を表します。カーソルはリスト内の相対位置を示すものではありません(オフセットではありません)。結果のインデックス スキャンを開始するときに Datastore モードのデータベースが移動する可能性があるマーカーです。以前のカーソル使用時からクエリの結果が変更されている場合、クエリが認識するのは、そのカーソル位置よりも後の結果で発生した変化だけです。新しい結果の位置がクエリのカーソル位置よりも前の場合、カーソルより後の結果をフェッチしても、その新しい結果は返されません。同様に、あるエンティティがクエリの結果ではなくなったものの、カーソルよりも前の位置に存在していた場合、カーソルよりも後の位置の結果は変化しません。また最後に返された結果が結果セットから削除された場合でも、その次の結果の位置は引き続きカーソルで特定できます。

クエリ結果を取得するときに、開始カーソルと終了カーソルの両方を使用して、連続したグループを返すことができます。開始カーソルと終了カーソルを使用して結果を取得する場合、結果セットのサイズがカーソル生成時と同じであることは保証されません。これはカーソル生成時からクエリでの使用時までの間に、データベースでエンティティの追加または削除が実行される可能性があるためです。

クエリの制限

インデックス クエリ メカニズムの性質上、クエリで実行できることについて一定の制限があります。Datastore モードのクエリでは、部分文字列の一致、大文字と小文字を区別しない一致、さらには全文検索をサポートしていません。NOTOR!= の各演算子はネイティブでサポートされてはいませんが、一部のクライアント ライブラリでは Datastore モードに追加する形でこれらの演算子をサポートしています。また、次のような制限もあります。

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

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

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

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

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

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

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.GreaterThan("created", _startDate),
        Filter.LessThan("created", _endDate))
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").
	Filter("Created >", time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC)).
	Filter("Created <", time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC))

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(
        PropertyFilter.gt("created", startDate), PropertyFilter.lt("created", endDate)))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .filter('created', '>', new Date('1990-01-01T00:00:00z'))
  .filter('created', '<', new Date('2000-12-31T23:59:59z'));

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->filter('created', '>', new DateTime('1990-01-01T00:00:00z'))
    ->filter('created', '<', new DateTime('2000-12-31T23:59:59z'));

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

start_date = datetime.datetime(1990, 1, 1)
end_date = datetime.datetime(2000, 1, 1)
query = client.query(kind='Task')
query.add_filter(
    'created', '>', start_date)
query.add_filter(
    'created', '<', end_date)

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .where("created", ">=", Time.utc(1990, 1, 1))
                 .where("created", "<", Time.utc(2000, 1, 1))

GQL


SELECT * FROM Task
WHERE created > DATETIME('1990-01-01T00:00:00z')
  AND created < DATETIME('2000-12-31T23:59:59z')

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

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.GreaterThan("created", _startDate),
        Filter.GreaterThan("priority", 3))
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").
	Filter("Created >", time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC)).
	Filter("Priority >", 3)

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(
        PropertyFilter.gt("created", startDate), PropertyFilter.gt("priority", 3)))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .filter('priority', '>', 3)
  .filter('created', '>', new Date('1990-01-01T00:00:00z'));

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->filter('created', '>', new DateTime('1990-01-01T00:00:00z'));

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

start_date = datetime.datetime(1990, 1, 1)
query = client.query(kind='Task')
query.add_filter(
    'created', '>', start_date)
query.add_filter(
    'priority', '>', 3)

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .where("created", ">=", Time.utc(1990, 1, 1))
                 .where("priority", ">", 3)

GQL


# Invalid query!
SELECT * FROM Task
WHERE created > DATETIME('1990-01-01T00:00:00z')
AND priority > 3

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

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Filter = Filter.And(Filter.Equal("priority", 4),
        Filter.GreaterThan("created", _startDate),
        Filter.LessThan("created", _endDate))
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").
	Filter("Priority =", 4).
	Filter("Done =", false).
	Filter("Created >", time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC)).
	Filter("Created <", time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC))

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(CompositeFilter.and(PropertyFilter.eq("priority", 4),
        PropertyFilter.gt("created", startDate), PropertyFilter.lt("created", endDate)))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .filter('priority', '=', 4)
  .filter('done', '=', false)
  .filter('created', '>', new Date('1990-01-01T00:00:00z'))
  .filter('created', '<', new Date('2000-12-31T23:59:59z'));

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '=', 4)
    ->filter('done', '=', false)
    ->filter('created', '>', new DateTime('1990-01-01T00:00:00z'))
    ->filter('created', '<', new DateTime('2000-12-31T23:59:59z'));

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

start_date = datetime.datetime(1990, 1, 1)
end_date = datetime.datetime(2000, 12, 31, 23, 59, 59)
query = client.query(kind='Task')
query.add_filter('priority', '=', 4)
query.add_filter('done', '=', False)
query.add_filter(
    'created', '>', start_date)
query.add_filter(
    'created', '<', end_date)

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .where("done", "=", false)
                 .where("priority", "=", 4)
                 .where("created", ">=", Time.utc(1990, 1, 1))
                 .where("created", "<", Time.utc(2000, 1, 1))

GQL


SELECT * FROM Task
WHERE priority = 4
  AND done = FALSE
  AND created > DATETIME('1990-01-01T00:00:00z')
  AND created < DATETIME('2000-12-31T23:59:59z')

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

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

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

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

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

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

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Filter = Filter.GreaterThan("priority", 3),
    Order = { { "priority", PropertyOrder.Types.Direction.Ascending},
        {"created", PropertyOrder.Types.Direction.Ascending } }
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").
	Filter("Priority >", 3).
	Order("Priority").
	Order("Created")

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(PropertyFilter.gt("priority", 3))
    .setOrderBy(OrderBy.asc("priority"), OrderBy.asc("created"))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .filter('priority', '>', 3)
  .order('priority')
  .order('created');

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->order('priority')
    ->order('created');

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
query.add_filter('priority', '>', 3)
query.order = ['priority', 'created']

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .where("priority", ">", 3)
                 .order("priority")
                 .order("created")

GQL


SELECT * FROM Task WHERE priority > 3 ORDER BY priority, created

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

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Filter = Filter.GreaterThan("priority", 3),
    Order = { { "created", PropertyOrder.Types.Direction.Ascending } }
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").
	Filter("Priority >", 3).
	Order("Created")

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(PropertyFilter.gt("priority", 3))
    .setOrderBy(OrderBy.asc("created"))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .filter('priority', '>', 3)
  .order('created');

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->order('created');

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
query.add_filter('priority', '>', 3)
query.order = ['created']

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .where("priority", ">", 3)
                 .order("created")

GQL


# Invalid query!
SELECT * FROM Task WHERE priority > 3 ORDER BY created

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

C#

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore C# API のリファレンス ドキュメントをご覧ください。

Query query = new Query("Task")
{
    Filter = Filter.GreaterThan("priority", 3),
    Order = { {"created", PropertyOrder.Types.Direction.Ascending },
        { "priority", PropertyOrder.Types.Direction.Ascending} }
};

Go

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Go API のリファレンス ドキュメントをご覧ください。

query := datastore.NewQuery("Task").
	Filter("Priority >", 3).
	Order("Created").
	Order("Priority")

Java

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Java API のリファレンス ドキュメントをご覧ください。

Query<Entity> query = Query.newEntityQueryBuilder()
    .setKind("Task")
    .setFilter(PropertyFilter.gt("priority", 3))
    .setOrderBy(OrderBy.asc("created"), OrderBy.asc("priority"))
    .build();

Node.js

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Node.js API のリファレンス ドキュメントをご覧ください。

const query = datastore
  .createQuery('Task')
  .filter('priority', '>', 3)
  .order('created')
  .order('priority');

PHP

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore PHP API のリファレンス ドキュメントをご覧ください。

$query = $datastore->query()
    ->kind('Task')
    ->filter('priority', '>', 3)
    ->order('created')
    ->order('priority');

Python

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Python API のリファレンス ドキュメントをご覧ください。

query = client.query(kind='Task')
query.add_filter('priority', '>', 3)
query.order = ['created', 'priority']

Ruby

Cloud Datastore 用のクライアント ライブラリをインストールして使用する方法については、Cloud Datastore のクライアント ライブラリをご覧ください。詳細については、Cloud Datastore Ruby API のリファレンス ドキュメントをご覧ください。

query = datastore.query("Task")
                 .where("priority", ">", 3)
                 .order("created")
                 .order("priority")

GQL


# Invalid query!
SELECT * FROM Task WHERE priority > 3 ORDER BY created, priority

射影の制限事項

射影クエリには次のような制限事項があります。

  • 射影できるのはインデックス付けされたプロパティのみ。

    1,500 バイトを超える長さの文字列、1,500 個を超える要素を持つバイト配列、インデックス付けしないと明示的にマークされているプロパティについては、射影がサポートされていません。

  • 同じプロパティは複数回射影できない。

  • 等式フィルタで参照されているプロパティは射影できない

    たとえば、

    SELECT tag FROM Task WHERE priority = 1
    

    は有効です(射影されたプロパティが等式フィルタで使用されていないため)。同様に、

    SELECT tag FROM Task WHERE tag > 'fun`
    

    も有効です(等式フィルタではないため)。ただし、

    SELECT tag FROM Task WHERE tag = 'fun`
    

    は無効です(射影されたプロパティが等式フィルタで使用されているため)。

  • 射影クエリから返された結果を Datastore モードのデータベースに再保存するべきではない

    このようなクエリでは部分的に格納された結果しか返されないため、Datastore モードのデータベースに書き戻すべきではありません。

  • 射影クエリでは、タイムスタンプが整数に変換される

    射影クエリの結果では、Datastore モードはタイムスタンプ値をマイクロ秒の整数値に変換します。

次のステップ

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

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

Cloud Datastore ドキュメント