Datastore Queries

A query retrieves entities from Firestore in Datastore mode that meet a specified set of conditions.

The query operates on entities of a given kind; it can specify filters on the entities' property values, keys, and ancestors, and can return zero or more entities as results. A query can also specify sort orders to sequence the results by their property values. The results include all entities that have at least one value for every property named in the filters and sort orders, and whose property values meet all the specified filter criteria. The query can return entire entities, projected entities, or just entity keys.

A typical query includes the following:

• An entity kind to which the query applies
• Zero or more filters based on the entities' property values, keys, and ancestors
• Zero or more sort orders to sequence the results

When executed, the query retrieves all entities of the given kind that satisfy all of the given filters, sorted in the specified order. Queries execute as read-only.

Note: To conserve memory and improve performance, a query should, whenever possible, specify a limit on the number of results returned.

Every query computes its results using one or more indexes, which contain entity keys in a sequence specified by the index's properties and, optionally, the entity's ancestors. The indexes are updated incrementally to reflect any changes the application makes to its entities, so that the correct results of all queries are available with no further computation needed.

The index-based query mechanism supports a wide range of queries and is suitable for most applications. However, it does not support some kinds of query common in other database technologies: in particular, joins and aggregate queries aren't supported within the Datastore mode query engine. See Restrictions on queries, below, for limitations on Datastore mode queries.

Query interface

Here's a basic example of issuing a query against a Datastore mode database. It retrieves all tasks that are not yet done with priorities greater than or equal to 4, sorted in descending order by priority:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

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

Note: The properties being filtered on must have a corresponding predefined index which can be defined in your index configuration file (index.yaml).

Here's how to run a query:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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)
}
snippet_test.go

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

$result = $datastore->runQuery($query);
concepts.php

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

tasks = datastore.run query
sample.rb

GQL

Not Applicable

Query structure

A query can specify an entity kind, zero or more filters, and zero or more sort orders.

Filters

A query's filters set constraints on the properties, keys, and ancestors of the entities to be retrieved.

Property filters

A property filter specifies

• A property name
• A comparison operator
• A property value

This example returns Task entities that are marked not done:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

SELECT * FROM Task WHERE done = FALSE

The property value must be supplied by the application; it cannot refer to or be calculated in terms of other properties. An entity satisfies the filter if it has a property of the given name whose value compares to the value specified in the filter in the manner described by the comparison operator. If the property of the given name is array-valued, the entity satisfies the filter if any of the values compares to the value specified in the filter in the manner described by the comparison operator.

The comparison operator can be any of the following:

Operator	Meaning
EQUAL	Equal to
LESS_THAN	Less than
LESS_THAN_OR_EQUAL	Less than or equal to
GREATER_THAN	Greater than
GREATER_THAN_OR_EQUAL	Greater than or equal to

Composite filters

A composite filter consists of more than one property filter. This example returns Task entities that are marked not done and have a priority of 4:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

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

Firestore in Datastore mode natively supports combining filters with only the AND operator.

Key filters

To filter on the value of an entity's key, use the special property __key__:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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, '>')
snippets.py

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

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

When comparing for inequality, keys are ordered by the following criteria, in order:

1. Ancestor path
2. Entity kind
3. Identifier (key name or numeric ID)

Elements of the ancestor path are compared similarly: by kind (string), then by key name or numeric ID. Kinds and key names are strings and are ordered by byte value; numeric IDs are integers and are ordered numerically. If entities with the same parent and kind use a mix of key name strings and numeric IDs, those with numeric IDs precede those with key names.

Queries on keys use indexes just like queries on properties and require custom indexes in the same cases, with a couple of exceptions: inequality filters or an ascending sort order on the key do not require a custom index, but a descending sort order on the key does. As with all queries, the development server creates appropriate entries in the index configuration file when a query that needs a custom index is used in the development environment.

Sort orders

A query sort order specifies

• A property name.
• A sort direction (ascending or descending). By default the sort order is ascending.

This example sorts Task entities by creation time in ascending order:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

SELECT * FROM Task ORDER BY created ASC

This example sorts Task entities by creation time in descending order:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

SELECT * FROM Task ORDER BY created DESC

If a query includes multiple sort orders, they are applied in the sequence specified. The following example sorts first by descending priority and then by ascending creation time:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

SELECT * FROM Task ORDER BY priority DESC, created ASC

If no sort orders are specified, the results are returned in the order they are retrieved from Datastore mode.

Note: Because of the way Datastore mode executes queries, if a query specifies inequality filters on a property and sort orders on other properties, the property used in the inequality filters must be ordered before the other properties.

Special query types

Some specific types of query deserve special mention:

Ancestor queries

An ancestor query limits its results to the specified entity and its descendants. This example returns all Task entities that have the specified TaskList entity as an ancestor:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

# 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)
snippets.py

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

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

GQL

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

Kindless queries

A query with no kind and no ancestor retrieves all of the entities of an application from Datastore mode. Such kindless queries cannot include filters or sort orders on property values. They can, however, filter on entity keys and use ancestor filters. Key filters can be used by specifying __key__ as the property name:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

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

Projection queries

Most queries return whole entities as their results, but often an application is actually interested in only a few of the entity's properties. Projection queries allow you to query for just those specific properties of an entity that you actually need, at lower latency and cost than retrieving the entire entity.

Projection queries require the specified properties to be indexed.

Keys-only queries

A keys-only query (which is a type of projection query) returns just the keys of the result entities instead of the entities themselves, at lower latency and cost than retrieving entire entities.

It is often more economical to do a keys-only query first, and then fetch a subset of entities from the results, rather than executing a general query which may fetch more entities than you actually need.

Here's how to create a keys-only query:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

$query = $datastore->query()
    ->keysOnly();
concepts.php

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

query = client.query()
query.keys_only()
snippets.py

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

SELECT __key__ FROM Task

A keys-only query is a small operation and counts as only a single entity read for the query itself.

Projections

Projection queries are similar to SQL queries of the form:

SELECT priority, percent_complete FROM Task

You can use all of the filtering and sorting features available for standard entity queries, but note these limitations.

The example SQL query returns abridged results with only the specified properties, priority and percent_complete, populated with values; all other properties are not populated. Here's how you construct this as a projection query:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

SELECT priority, percent_complete FROM Task

And here's how to run the projection query:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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"]);
}
DatastoreTest.cs

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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)
}
snippet_test.go

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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"));
}
ConceptsTest.java

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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,
  };
}
concepts.js

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

priorities = []
percent_completes = []

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

Not Applicable

A projection query that does not use the distinct on clause is a small operation and counts as only a single entity read for the query itself.

Grouping

Projection queries can use the distinct on clause to ensure that only the first result for each distinct combination of values for the specified properties will be returned. This will return only the first result for entities which have the same values for the properties that are being projected.

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

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

Array values

Datastore mode indexes each unique array property value once per index. Thus to query if an array contains a value use an equality filter.

Consider the following when your query includes properties with array values.

Inequality Filters

Because of the way they're indexed, entities with multiple values for the same property can sometimes interact with query filters and sort orders in unexpected and surprising ways.

If a query has multiple inequality filters on a given property, an entity will match the query only if at least one of its individual values for the property satisfies all of the filters. For example, if an entity of kind Task has values fun and programming for property tag, it will not match the query:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

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

Each of the entity's tag values satisfies one of the filters, but neither single value satisfies both.

Multiple equality filters

Unlike inequality filters, multiple equality filters can be used to query for entities that contain a set of values. For example, the same entity will satisfy the query

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

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

even though neither of the entity's individual tag values satisfies both filter conditions.

Sort Order

Similarly, the sort order for multiple-valued properties is unusual. Because such properties appear once in the index for each unique value, the first value seen in the index determines an entity's sort order.

If a multi-valued property is not used in any filter:

• and the query results are sorted in ascending order by the property, the smallest value of the property is used for ordering.
• and the query results are sorted in descending order by the property, the greatest value is used for ordering.
• other values do not affect the sort order, nor does the number of values.

This has the unusual consequence that an entity with property values 1 and 9 precedes an entity with values 4, 5, 6, and 7 in both ascending and descending order.

If a multi-valued property is used in an equality filter, any sort order on that property is ignored.

If a multi-valued property is used in an inequality filter:

• and the query results are sorted in ascending order by the property, the smallest value that satisfies all of the query's inequality filters is used for ordering.
• and the query results are sorted in descending order by the property, the greatest value that satisfies all of the query's inequality filters is used for ordering.

Note that if a set of inequality filters on a property translate into an equality filter, such as

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

any sort order on that property is ignored, as the filters evaluate the same as the equality filter

WHERE tags = 'math'

Projections and array-valued properties

Projecting a property with array values will not populate all values for that property. Instead, a separate entity will be returned for each unique combination of projected values matching the query. For example, suppose you have an entity of kind Task with two multiple-valued properties, tags and collaborators:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

Not Applicable

Then the projection query

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

will return four entities with the following combinations of values:

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

Warning: Including more than one array-valued property in a projection will result in an exploding index.

Cursors, limits, and offsets

You can specify a limit for your query to control the maximum number of results returned in one batch. The following example retrieves at most five Task entities:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

SELECT * FROM Task LIMIT 5

Query cursors allow an application to retrieve a query's results in convenient batches without incurring the overhead of a query offset. After performing a retrieval operation, the application can obtain a cursor, which is an opaque byte string marking the index position of the last result retrieved. The application can save this string (for instance in your Datastore mode database, a cache, or embedded in a web page as a base-64 encoded HTTP GET or POST parameter), and can then use the cursor as the starting point for a subsequent retrieval operation to obtain the next batch of results from the point where the previous retrieval ended. A retrieval can also specify an end cursor, to limit the extent of the result set returned.

The following example demonstrates the use of cursors for pagination:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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()
snippet_test.go

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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();
ConceptsTest.java

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

// 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];
}
concepts.js

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

/**
 * 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
    );
}
concepts.php

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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
snippets.py

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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)
sample.rb

GQL

Not Applicable

Caution: Be careful when passing a cursor to a client, such as in a web form. Although the client cannot change the cursor value to access results outside of the original query, it is possible for it to decode the cursor to expose information about result entities, such as the project ID, entity kind, key name or numeric ID, ancestor keys, and properties used in the query's filters and sort orders. If you don't want users to have access to that information, you can encrypt the cursor, or store it and provide the user with an opaque key.

Although Datastore mode databases support integer offsets, you should avoid using them. Instead, use cursors. Using an offset only avoids returning the skipped entities to your application, but these entities are still retrieved internally. The skipped entities do affect the latency of the query, and your application is billed for the read operations required to retrieve them. Using cursors instead of offsets lets you avoid all these costs.

Limitations of cursors

Cursors are subject to the following limitations:

• A cursor can be used only by the same project that performed the original query, and only to continue the same query. It is not possible to retrieve results using a cursor without setting up the same query from which it was originally generated.
• If any of the following items are changed, a cursor can still be used for subsequent retrievals.
  • start cursor
  • end cursor
  • offset
  • limit
• If any of the following items are changed, a cursor cannot be used for subsequent retrievals.
  • projection
  • kind
  • ancestor
  • filter
  • distinct on
  • sort order

    An exception is if the original query's final sort order was on __key__. In that case, you can use the cursor in a reverse query, which is the original query with each sort order reversed. The reverse query can modify the start cursor, end cursor, offset, and limit.

• Cursors don't always work as expected with a query that uses an inequality filter or a sort order on a property with multiple values. The de-duplication logic for such multiple-valued properties does not persist between retrievals, possibly causing the same result to be returned more than once.
• New Datastore mode releases may change internal implementation details, invalidating cursors that depend on them. If an application attempts to use a cursor that is no longer valid, Firestore in Datastore mode raises an exception.

Cursors and data updates

The cursor represents the location in the result list after the last result returned. A cursor is not a relative position in the list (it's not an offset); it's a marker to which a Datastore mode database can jump when starting an index scan for results. If the results for a query change between uses of a cursor, the query notices only changes that occur in results after the cursor. If a new result appears before the cursor's position for the query, it will not be returned when the results after the cursor are fetched. Similarly, if an entity is no longer a result for a query but had appeared before the cursor, the results that appear after the cursor do not change. If the last result returned is removed from the result set, the cursor still knows how to locate the next result.

When retrieving query results, you can use both a start cursor and an end cursor to return a continuous group of results. When using a start and end cursor to retrieve the results, you are not guaranteed that the size of the results will be the same as when you generated the cursors. Entities may be added or deleted from the database between the time the cursors are generated and when they are used in a query.

Restrictions on queries

The nature of the index query mechanism imposes certain restrictions on what a query can do. Datastore mode queries do not support substring matches, case-insensitive matches, or so-called full-text search. The NOT, OR, and != operators are not natively supported, but some client libraries may add support on top of Datastore mode. Additionally:

Entities lacking a property named in the query are ignored

Entities of the same kind need not have the same properties. To be eligible as a query result, an entity must possess a value (possibly null) for every property named in the query's filters and sort orders. If not, the entity is omitted from the indexes used to execute the query and consequently will not be included in the query's results.

Note: It is not possible to query for entities that are specifically lacking a given property. One alternative is to add the property with a null value, then filter for entities with null as the value of that property.

Filtering on unindexed properties returns no results

A query can't find property values that aren't indexed, nor can it sort on such properties. See the Unindexed properties section for a detailed discussion of unindexed properties.

Inequality filters are limited to at most one property

To avoid having to scan the entire index, the query mechanism relies on all of a query's potential results being adjacent to one another in the index. To satisfy this constraint, a single query may not use inequality comparisons (LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL) on more than one property across all of its filters. For example, the following query is valid, because both inequality filters apply to the same property:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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))
snippet_test.go

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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)
snippets.py

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback

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

GQL

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

However, this query is not valid, because it uses inequality filters on two different properties:

C#

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore C# API reference documentation.

Feedback

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

Go

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Go API reference documentation.

Feedback

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

Java

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Java API reference documentation.

Feedback

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

Node.js

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Node.js API reference documentation.

Feedback

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

PHP

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore PHP API reference documentation.

Feedback

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

Python

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Python API reference documentation.

Feedback

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

Ruby

To learn how to install and use the client library for Cloud Datastore, see the Cloud Datastore Client Libraries. For more information, see the Cloud Datastore Ruby API reference documentation.

Feedback