Datastore クエリ

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

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

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

クエリを適用するエンティティの種類
エンティティのプロパティ値、キー、祖先に基づく任意の数のフィルタ（省略可）
結果を順序付けするための任意の数の並べ替え順（省略可）

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

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

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

インデックスベースのクエリメカニズムはさまざまなクエリをサポートしているため、結合クエリなどのスケーリング以外のクエリを除き、ほとんどのアプリケーションに適しています。Datastore モードクエリの制限の詳細については、クエリの制限をご覧ください。

クエリインターフェース

Datastore モードデータベースに対してクエリを発行できます。次の例は、優先値（priority）が 4 以上でまだ完了していない（done ではない）すべてのタスクを取得し、優先値の降順で並べ替える方法を示しています。

C#

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

Cloud Datastore への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

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").
	FilterField("Done", "=", false).
	FilterField("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(
    and([
      new PropertyFilter('done', '=', false),
      new PropertyFilter('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 のリファレンスドキュメントをご覧ください。

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter(filter=PropertyFilter("done", "=", False))
query.add_filter(filter=PropertyFilter("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#

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

Go

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

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

tasks = datastore.run query

GQL

該当なし

クエリの構造

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

フィルタ

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

プロパティフィルタ

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

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

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter(filter=PropertyFilter("done", "=", False))

Ruby

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`	次の値以上
`NOT_EQUAL`	次に等しくない
`IN`	指定されたリストのメンバー。指定されたリストの任意の値に等しい。
`NOT_IN`	指定されたリストのメンバーでない。指定されたリストのいずれとも等しくない。

複合フィルタ

複合フィルタは、複数のプロパティフィルタで構成されています。フィルタは AND や OR と組み合わせることが可能です。次の例では、done とマーク付けされておらず、優先値（priority）が 4 の Task エンティティを返します。

C#

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

Go

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

Java

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

Node.js

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('done', '=', false),
      new PropertyFilter('priority', '=', 4),
    ])
  );

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter(filter=PropertyFilter("done", "=", False))
query.add_filter(filter=PropertyFilter("priority", "=", 4))

Ruby

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

GQL

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

次の例では、フィルタを論理 OR と組み合わせます。

C#

スニペットはありません。

Go

スニペットはありません。

Java

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

Datastore モードへの認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

import com.google.cloud.datastore.Datastore;
import com.google.cloud.datastore.DatastoreOptions;
import com.google.cloud.datastore.Entity;
import com.google.cloud.datastore.Query;
import com.google.cloud.datastore.QueryResults;
import com.google.cloud.datastore.StructuredQuery.CompositeFilter;
import com.google.cloud.datastore.StructuredQuery.Filter;
import com.google.cloud.datastore.StructuredQuery.PropertyFilter;

public class OrFilterQuery {
  public static void invoke() throws Exception {

    // Instantiates a client
    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
    String propertyName = "description";

    // Create the two filters
    Filter orFilter =
        CompositeFilter.or(
            PropertyFilter.eq(propertyName, "Feed cats"),
            PropertyFilter.eq(propertyName, "Buy milk"));

    // Build the query
    Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").setFilter(orFilter).build();

    // Get the results back from Datastore
    QueryResults<Entity> results = datastore.run(query);

    if (!results.hasNext()) {
      throw new Exception("query yielded no results");
    }

    while (results.hasNext()) {
      Entity entity = results.next();
      System.out.printf("Entity: %s%n", entity);
    }
  }
}

Node.js

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const projectId = "your Google Cloud project id";

// Imports the Cloud Datastore
const {Datastore, PropertyFilter, or} = require('@google-cloud/datastore');

async function queryFilterOr() {
  // Instantiate the Datastore
  const datastore = new Datastore();
  const query = datastore
    .createQuery('Task')
    .filter(
      or([
        new PropertyFilter('description', '=', 'Buy milk'),
        new PropertyFilter('description', '=', 'Feed cats'),
      ])
    );

  const [entities] = await datastore.runQuery(query);
  for (const entity of entities) {
    console.log(`Entity found: ${entity['description']}`);
  }
}

queryFilterOr();

PHP

スニペットはありません。

Python

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

from google.cloud import datastore
from google.cloud.datastore import query


def query_filter_or(project_id: str) -> None:
    """Builds a union of two queries (OR) filter.

    Arguments:
        project_id: your Google Cloud Project ID
    """
    client = datastore.Client(project=project_id)

    or_query = client.query(kind="Task")
    or_filter = query.Or(
        [
            query.PropertyFilter("description", "=", "Buy milk"),
            query.PropertyFilter("description", "=", "Feed cats"),
        ]
    )

    or_query.add_filter(filter=or_filter)

    results = list(or_query.fetch())
    for result in results:
        print(result["description"])

Ruby

スニペットを利用できません。

GQL

スニペットはありません。

Datastore モードの Firestore では、フィルタを AND 演算子や OR 演算子と組み合わせることができます。次の例では、スター付きの、または done とマーク付けされていない、優先度（priority）が 4 の Task エンティティを返します。

C#

スニペットはありません。

Go

スニペットはありません。

Java

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

Node.js

スニペットはありません。

PHP

スニペットはありません。

Python

and_or_query = client.query(kind="Task")

query_filter = query.Or(
    [
        query.PropertyFilter("starred", "=", True),
        query.And([query.PropertyFilter("done", "=", False),
                    query.PropertyFilter("priority", "=", 4,),
        ]
        )
    ]
)

and_or_query.add_filter(filter=query_filter)

results = and_or_query.fetch()
for result in results:
    print(result["description"])

Ruby

スニペットを利用できません。

GQL

スニペットを利用できません。

主なフィルタ

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

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

GQL

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

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

祖先パス
エンティティの種類
識別子（キー名または数値 ID）

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

キーに対するクエリでは、プロパティに対するクエリと同じようにインデックスを使用し、同様にカスタムインデックスを必要とします。次の例外については、カスタムインデックスは必要ありません。

不等式フィルタ
キーの昇順での並べ替え順序

キーの降順での並べ替え順序にはカスタムインデックスが必要です。またすべてのクエリに共通することですが、開発環境でカスタムインデックスを必要とするクエリを使用すると、インデックス構成ファイルに適切なエントリが作成されます。

並べ替え順序

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

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

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

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

GQL

SELECT * FROM Task ORDER BY created ASC

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

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

GQL

SELECT * FROM Task ORDER BY created DESC

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

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

GQL

SELECT * FROM Task ORDER BY priority DESC, created ASC

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

制限事項

並べ替え順には次の制限があります。

あるプロパティに対して不等式フィルタを指定し、別のプロパティに対して並べ替え順序を指定する場合は、不等式フィルタで使用されているプロパティを他のプロパティよりも前に並べる必要があります。これは Datastore モードがクエリを実行する仕組みに原因があります。
順序を指定する場合、distinct on 句で指定したプロパティのセットは、並べ替え順序の distinct on 以外のプロパティの前に表示される必要があります。詳細については、クエリのグループ化をご覧ください。
等式フィルタが使用されたプロパティの並べ替え順はすべて無視されます。

特別なタイプのクエリ

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

`!= Not equal`

不等価（!=）演算子を使用すると、指定したプロパティが存在し、その値が比較対象の値と一致しないエンティティが返されます。

C#

該当なし

Go

package datastore_snippets

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/datastore"
	"google.golang.org/api/iterator"
)

func queryNotEquals(w io.Writer, projectId string) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectId)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	q := datastore.NewQuery("TaskList")
	q.FilterField("Task", "!=", []string{"notASimpleTask"})

	it := client.Run(ctx, q)
	for {
		var dst struct {
			Task string
		}
		key, err := it.Next(&dst)
		if err == iterator.Done {
			break
		}

		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Key retrieved: %v\n", key)
	}

	return nil
}

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.neq("category", "Work"))
        .build();

Node.js

該当なし

PHP

該当なし

Python

query = client.query(kind="Task")
query.add_filter("category", "!=", "work")

Ruby

該当なし

GQL

SELECT * FROM Task WHERE category != 'work'

このクエリは、category プロパティが存在し、Work 以外の値に設定されているすべての Task エンティティを返します。

このクエリは、category プロパティが存在しないエンティティを返しません。不等価（!=）クエリと NOT_IN クエリでは、指定されたプロパティが存在しないか、プロパティがインデックス登録から除外されているエンティティが除外されます。プロパティは、空の文字列や null など、任意の値に設定された場合に存在します。

制限事項

!= クエリの次の制限事項に注意してください。

指定したプロパティが存在するエンティティのみがクエリに一致します。
1 つのクエリごとに NOT_IN または != を 1 つだけ使用できます。

`IN`

同一プロパティで論理 OR を使って最大 30 個までの等値（==）句を結合する場合は、IN 演算子を使用します。IN クエリは、指定されたプロパティがいずれかの比較値に一致するエンティティを返します。

C#

該当なし

Go

package datastore_snippets

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/datastore"
	"google.golang.org/api/iterator"
)

func queryIn(w io.Writer, projectId string) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectId)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	q := datastore.NewQuery("TaskList")
	q.FilterField("Task", "in", []string{"simpleTask", "easyTask"})

	it := client.Run(ctx, q)
	for {
		var dst struct {
			Task string
		}
		key, err := it.Next(&dst)
		if err == iterator.Done {
			break
		}

		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Key retrieved: %v\n", key)
	}

	return nil
}

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.in("tag", ListValue.of("learn", "study")))
        .build();

Node.js

該当なし

PHP

該当なし

Python

query = client.query(kind="Task")
query.add_filter("tag", "IN", ["learn", "study"])

Ruby

該当なし

GQL

SELECT * FROM Task WHERE tag IN ARRAY('learn', 'study')

このクエリは、tag プロパティが learn または study に設定されているすべての Task エンティティを返します。これには、tag プロパティにこれらの値のいずれか一方が含まれ、他方が含まれていない Task エンティティが含まれます。

`NOT_IN`

同一プロパティで論理 AND を使って最大 10 個までの不等値（!=）句を結合する場合は、NOT_IN 演算子を使用します。NOT_IN クエリは、指定されたプロパティが存在し、いずれの比較値とも一致しないエンティティを返します。

C#

該当なし

Go

package datastore_snippets

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/datastore"
	"google.golang.org/api/iterator"
)

func queryNotIn(w io.Writer, projectId string) error {
	ctx := context.Background()
	client, err := datastore.NewClient(ctx, projectId)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	q := datastore.NewQuery("TaskList")
	q.FilterField("Task", "not-in", []string{"notASimpleTask", "notAnEasyTask"})

	it := client.Run(ctx, q)
	for {
		var dst struct {
			Task string
		}
		key, err := it.Next(&dst)
		if err == iterator.Done {
			break
		}

		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Key retrieved: %v\n", key)
	}

	return nil
}

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.not_in("category", ListValue.of("Work", "Chores", "School")))
        .build();

Node.js

該当なし

PHP

該当なし

Python

query = client.query(kind="Task")
query.add_filter("category", "NOT_IN", ["work", "chores", "school"])

Ruby

該当なし

GQL

SELECT * FROM Task WHERE category NOT IN ARRAY('work', 'chores', 'school')

このクエリは、category エンティティが存在しないエンティティを返しません。不等価（!=）クエリと NOT_IN クエリでは、指定されたプロパティが存在しないエンティティは除外されます。プロパティは、空の文字列や null など、任意の値に設定された場合に存在します。

制限事項

NOT_IN クエリの次の制限事項に注意してください。

指定したプロパティが存在するエンティティのみがクエリに一致します。
1 つのクエリごとに NOT_IN または != を 1 つだけ使用できます。

祖先クエリ

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

C#

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

Go

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

Java

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

Node.js

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

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

# 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

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

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

GQL

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

祖先クエリの制限

Ancestor クエリの次の制限事項に注意してください。

評価されるすべての論理和には、同じ祖先フィルタが必要です。

種類を指定しないクエリ

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

last_seen_key = client.key("Task", "a")
query = client.query()
query.key_filter(last_seen_key, ">")

Ruby

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

GQL

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

射影クエリ

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

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

キーのみのクエリ

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

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

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

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

GQL

SELECT __key__ FROM Task

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

射影

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

SELECT priority, percent_complete FROM Task

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

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

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

GQL

SELECT priority, percent_complete FROM Task

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

C#

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

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

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

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

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

Python

priorities = []
percent_completes = []

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

Ruby

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#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

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

order by が指定されている場合、distinct on 句で指定されたプロパティのセットは、order by 句の distinct on 以外のプロパティの前に表示される必要があります。

集約クエリ

Datastore モードの Firestore は、count() 集計クエリをサポートしています。集計クエリをご覧ください。

複数のプロパティに対する範囲フィルタと不等式フィルタ

Datastore モードの Firestore では、複合クエリで複数の不等式フィルタがサポートされています。複数のプロパティに対する範囲フィルタと不等式フィルタを使用したクエリをご覧ください。

配列値

Datastore モードでは、インデックスごとに 1 つの一意の配列プロパティ値がインデックスに登録されます。したがって、配列に値が含まれているかどうかをクエリするには、等式フィルタを使用します。

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

不等式フィルタ

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

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

C#

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

Go

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

Java

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

Node.js

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('tag', '>', 'learn'),
      new PropertyFilter('tag', '<', 'math'),
    ])
  );

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter(filter=PropertyFilter("tag", ">", "learn"))
query.add_filter(filter=PropertyFilter("tag", "<", "math"))

Ruby

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

GQL

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

エンティティの tag 値は、それぞれいずれかのフィルタを満たしていますが、どちらも単体では両方のフィルタを満たしていません。

複数の等式フィルタ

複数の等式フィルタを使用して、一連の値が含まれるエンティティをクエリできます。たとえば、プロパティ tag の値 fun と programming を持つ種類 Task のエンティティは、このクエリを満たすことになります。

C#

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

Go

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

Java

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

Node.js

const query = datastore
  .createQuery('Task')
  .filter(
    and([
      new PropertyFilter('tag', '=', 'fun'),
      new PropertyFilter('tag', '=', 'programming'),
    ])
  );

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

query = client.query(kind="Task")
query.add_filter(filter=PropertyFilter("tag", "=", "fun"))
query.add_filter(filter=PropertyFilter("tag", "=", "programming"))

Ruby

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

GQL

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

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

並べ替え順序

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

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

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

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

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

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

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

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

WHERE tag >= 'math' AND tag <= 'math'

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

WHERE tag = 'math'

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

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

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

GQL

該当なし

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

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

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

tag = 'fun'、collaborators = 'alice'
tag = 'fun'、collaborators = 'bob'
tag = 'programming'、collaborators = 'alice'
tag = 'programming'、collaborators = 'bob'

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

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

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

GQL

SELECT * FROM Task LIMIT 5

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

次の例は、ページ分けにカーソルを使う方法を示しています。

C#

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

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

Go

// cursorStr is a cursor to start querying at.
cursorStr := ""

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.
it := client.Run(ctx, query)
var tasks []Task
for {
	var task Task
	_, err := it.Next(&task)
	if err == iterator.Done {
		break
	}
	if err != nil {
		log.Fatalf("Failed fetching results: %v", err)
	}
	tasks = append(tasks, task)
}

// Get the cursor for the next page of results.
// nextCursor.String can be used as the next page's token.
nextCursor, err := it.Cursor()

Java

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

// 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

/**
 * Fetch a query cursor.
 *
 * @param int $pageSize
 * @param string $pageCursor
 * @param string $namespaceId
 */
function cursor_paging(int $pageSize, string $pageCursor = '', string $namespaceId = null)
{
    $datastore = new DatastoreClient(['namespaceId' => $namespaceId]);
    $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;
    }

    printf('Found %s entities', count($entities));

    $entities = [];
    if (!empty($nextPageCursor)) {
        $query = $datastore->query()
          ->kind('Task')
          ->limit($pageSize)
          ->start($nextPageCursor);
        $result = $datastore->runQuery($query);

        foreach ($result as $entity) {
            $entities[] = $entity;
        }

        printf('Found %s entities with next page cursor', count($entities));
    }
}

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()


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

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
- limit
次のいずれかの項目が変更された場合、後続の取得オペレーションではカーソルを使用できなくなります。
- projection
- kind
- ancestor
- filter
- 重複排除（distinct on）
- 並べ替え順序例外は、元のクエリの最後の並べ替え順序が __key__ であった場合です。この場合は「逆引きクエリ」、つまり各並べ替え順序を反転させた元のクエリでカーソルを使用できます。逆引きクエリでは、開始カーソル、終了カーソル、オフセット、制限を変更できます。
複数の値を持つプロパティに対して不等式フィルタまたは並べ替え順序を使用するクエリでは、カーソルが常に予期したとおりに動作するとは限りません。このような複数の値を持つプロパティに対する重複排除ロジックは取得オペレーション間で保持されないため、同じ結果が複数回返される原因となる場合があります。
Datastore モードの新しいリリースでは内部実装の詳細が変更される場合があり、それに依存するカーソルは無効になる可能性があります。無効になったカーソルをアプリケーションで使用しようとすると、Datastore モードの Firestore で例外が発生します。

カーソルとデータ更新

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

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

クエリの制限

インデックスクエリメカニズムの性質上、クエリで実行できることについて一定の制限があります。Datastore モードのクエリでは、部分文字列の一致、大文字と小文字を区別しない一致、さらには全文検索をサポートしていません。また、次の制限が適用されます。

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

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

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

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

不等式フィルタの制限

クエリの実行にコストがかかりすぎないように、Datastore モードの Firestore では、範囲プロパティまたは不等式プロパティの上限が 10 に制限されています。不等式フィルタを使用したクエリの詳細については、複数のプロパティに対する範囲フィルタと不等式フィルタを使用したクエリをご覧ください。

`NOT_EQUAL` と `NOT_IN` の両方は使用できない

NOT_IN を使用する場合は、NOT_EQUAL 句を追加することはできません。

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

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

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

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

C#

該当なし

Go

該当なし

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.eq("tag", "learn"))
        .setOrderBy(OrderBy.asc("tag"))
        .build();

Node.js

該当なし

PHP

該当なし

Python

該当なし

Ruby

該当なし

GQL

# Sort order on an equality filter is ignored
SELECT * FROM Task WHERE tag = 'learn' ORDER BY tag ASC

これは、IN フィルタを含むクエリには適用されません。同一プロパティで論理 OR を使って最大 10 個までの等値（==）句を結合する場合は、IN 演算子を使用します。そのプロパティの並べ替え順を追加すると、結果セットに適用されます。

C#

該当なし

Go

該当なし

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(PropertyFilter.in("tag", ListValue.of("learn", "study")))
        .setOrderBy(OrderBy.asc("tag"))
        .build();

Node.js

該当なし

PHP

該当なし

Python

該当なし

Ruby

該当なし

GQL

SELECT * FROM Task WHERE tag IN ARRAY('learn', 'study') ORDER BY tag ASC

昇順の場合、フィルタを満たす最小値が並べ替えに使用されます。
降順の場合、フィルタを満たす最大値が並べ替えに使用されます。
その他の値は、並べ替え順序には影響しません。また、プロパティ内の値の数にも影響しません。

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

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

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

GQL

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

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

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

GQL

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

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

C#

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

Go

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

Java

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

Node.js

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

PHP

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

Python

from google.cloud import datastore

# For help authenticating your client, visit
# https://cloud.google.com/docs/authentication/getting-started
client = datastore.Client()

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

Ruby

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

GQL

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

`OrderBy` とフィールドの存在

特定のプロパティを基準にクエリを並べ替えると、order-by プロパティが存在するエンティティのみを返すことができます。

たとえば、次のクエリでは、クエリフィルタを満たす場合でも、priority プロパティが設定されていないエンティティは返されません。

Java

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

関連する影響が不等式に適用されます。プロパティに対して不等式フィルタを使用したクエリでは、そのプロパティによる順序付けも意味します。次のクエリは、そのエンティティ内に starred = true がある場合でも、priority プロパティがないエンティティを返しません。回避策として、並べ替えごとに個別のクエリを実行するか、並べ替えたすべてのプロパティに値を割り当てることができます。

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(CompositeFilter.or(
            PropertyFilter.eq("starred", true)),
            PropertyFilter.ge("priority", 4))
        .build();

上記のクエリには、次のような不等式に対する暗黙の order-by が含まれます。暗黙的な order-by の方向は、使用可能なインデックスによって異なります。

Java

Query<Entity> query =
    Query.newEntityQueryBuilder()
        .setKind("Task")
        .setFilter(CompositeFilter.or(
            PropertyFilter.eq("starred", true)),
            PropertyFilter.ge("priority", 4)
        )
        .setOrderBy(OrderBy.asc("priority"))
        .build();

射影の制限事項

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

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

つまり、クエリで使用されるすべてのプロパティ（予想またはフィルタ）が同じインデックス内に存在する必要があります。したがって、select tag from Task where priority = 1 では、優先度とタグに関する複合インデックスが必要です。

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 モードはタイムスタンプ値をマイクロ秒の整数値に変換します。

次のステップ

トランザクションについて学習する。

Datastore クエリ

クエリ インターフェース

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

クエリの構造

フィルタ

プロパティ フィルタ

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

複合フィルタ

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

主なフィルタ

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

並べ替え順序

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

C#

Go

Java

Node.js

PHP

Python

Ruby

GQL

クエリインターフェース

プロパティフィルタ

`!= Not equal`

`IN`

`NOT_IN`