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, except for non-scaling queries, such as join queries. For more information about limitations on Datastore mode queries, see Restrictions on queries.
Query interface
You can issue a query against a Datastore mode database. The following example shows how to retrieve 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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
SELECT * FROM Task WHERE done = FALSE AND priority => 4 ORDER BY priority DESC
The following example shows how to run a query:
C#
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
Not ApplicableQuery 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 the following:
- A property name
- A comparison operator
- A property value
The following example returns task entities that are marked not done:
C#
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
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 |
NOT_EQUAL |
Not equal to |
IN |
Member of the specified list. Equal to any of the values in a specified list. |
NOT_IN |
Not a member of the specified list. Not equal to any of the values in a specified list. |
Composite filters
A composite filter consists of more than one property filter. You can
combine filters with AND
and OR
. The following 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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
SELECT * FROM Task WHERE done = FALSE AND priority = 4
The following example combines filters with a logical OR
:
C#
Snippet not available.
Go
Snippet not available.
Java
To learn how to install and use the client library for Datastore mode, see Datastore mode client libraries. For more information, see the Datastore mode Java API reference documentation.
To authenticate to Datastore mode, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Datastore mode, see Datastore mode client libraries. For more information, see the Datastore mode Node.js API reference documentation.
To authenticate to Datastore mode, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
Snippet not available.
Python
To learn how to install and use the client library for Datastore mode, see Datastore mode client libraries. For more information, see the Datastore mode Python API reference documentation.
To authenticate to Datastore mode, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
Snippet not available.
GQL
Snippet not available.
AND
and OR
operators. The following example returns Task
entities that are either starred or that
are marked not done and have a priority of 4:
C#
Snippet not available.
Go
Snippet not available.
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
Snippet not available.
PHP
Snippet not available.
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
Snippet not available.
GQL
Snippet not available.
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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
SELECT * FROM Task WHERE __key__ >KEY(Task, s'omeTask)'
When comparing for inequality, keys are ordered by the following criteria, in order:
- Ancestor path
- Entity kind
- 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. The following exceptions don't require a custom index:
- Inequality filters
- Ascending sort order on the key
A descending sort order on the key requires a custom index. 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 the following:
- 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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
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.
Restrictions
Sort orders have the following restrictions:
- 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.
- If ordering is specified, the set of properties specified in the
distinct on
clause must appear before any non-distinct on
properties in the sort orders . For more information, see grouping queries. - Sort orders on properties with equality filters are all ignored.
Special query types
Some specific types of query deserve special mention:
!= Not equal
Use the not-equal (!=
) operator to return entities where the given property
exists and doesn't match the comparison value.
C#
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableGo
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicablePHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicablePython
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableGQL
SELECT * FROM Task WHERE category != w'ork '
This query returns every Task
entity where the category
property exists
and is set to any value other than Work
.
This query doesn't return entities
where the category
property doesn't exist. Not-equal (!=
) and NOT_IN
queries exclude entities where the given property doesn't exist or where the
property is excluded from indexing. A property
exists when it's set to any value, including an empty string or null
.
Limitations
Note the following limitations for !=
queries:
- Only entities where the given property exists can match the query.
- Only a single
NOT_IN
or!=
is allowed per query.
IN
Use the IN
operator to combine up to 30 equality (==
)
clauses on the same property with a logical OR
. An IN
query returns entities where the given property matches any of the comparison
values.
C#
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableGo
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicablePHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicablePython
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableGQL
SELECT * FROM Task WHERE tag IN ARRAY(l'earn,' s'tudy)'
This query returns every Task
entity where the tag
property is set to learn
or study
. This includes Task
entities where the tag
property includes one of
these values but not the other.
NOT_IN
Use the NOT_IN
operator to combine up to 10 not-equal (!=
) clauses on the
same property with a logical AND
. A NOT_IN
query returns entities where the
given property exists and doesn't match any of the comparison values.
C#
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableGo
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicablePHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicablePython
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableGQL
SELECT * FROM Task WHERE category NOT IN ARRAY(w'ork,' c'hores,' s'chool)'
This query doesn't return entities
where the category
entity doesn't exist. Not-equal (!=
) and NOT_IN
queries exclude entities where the given property doesn't exist. A property
exists when it's set to any value, including an empty string or null
.
Limitations
Note the following limitations for NOT_IN
queries:
- Only entities where the given property exists can match the query.
- Only a single
NOT_IN
or!=
is allowed per query.
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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
SELECT * FROM Task WHERE __key__ HAS ANCESTOR KEY(TaskList, d'efault)'
Limitations on Ancestor queries
Note the following limitations for Ancestor
queries:
- All evaluated disjunctions must have the same ancestor filter.
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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
SELECT * WHERE __key__ >KEY(Task, s'omeTask)'
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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
Not ApplicableA projection query that doesn't 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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
SELECT DISTINCT ON (category) category, priority FROM Task ORDER BY category, priority
The set of properties specified in the distinct on
clause must appear before any non-distinct on
properties in the order by
clause if order by
is specified.
Aggregation queries
Firestore in Datastore mode supports the count()
aggregation query. See Aggregation queries.
Range and inequality filters on multiple properties
Firestore in Datastore mode supports multiple inequality filters in a compound query. See Query using range and inequality filters on multiple properties.
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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
SELECT * FROM Task WHERE tag >l'earn 'AND tag <m'ath '
Each of the entity's tag
values satisfies one of the filters, but neither single value satisfies both.
Multiple equality filters
Multiple equality filters can be used to query
for entities that contain a set of values. For example, an entity of kind
Task
with values fun
and programming
for
property tag
will satisfy the query
C#
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
SELECT * FROM Task WHERE tag = f'un 'AND tag = p'rogramming '
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 don't 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 or an NOT_IN
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 tag >= 'math' AND tag <= 'math'
any sort order on that property is ignored, as the filters evaluate the same as the equality filter
WHERE tag = 'math'
Projections and array-valued properties
Projecting a property with array values won't 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, tag
and collaborators
:
C#
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
Not ApplicableThen the projection query
SELECT tag, collaborators FROM Task WHERE collaborators < 'charlie'
will return four entities with the following combinations of values:
tag
= 'fun'
, collaborators
= 'alice'
tag
= 'fun'
, collaborators
= 'bob'
tag
= 'programming'
, collaborators
= 'alice'
tag
= 'programming'
, collaborators
= 'bob'
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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
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 Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
Not ApplicableAlthough 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 doesn't 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 won't 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 don't 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 don't support substring matches, case-insensitive matches, or full-text search. Additionally, the following restrictions apply:
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 won't be included in the query's results.
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. For more information, see Unindexed properties.
Limits on inequality filters
To prevent queries from becoming too expensive to run, Firestore in Datastore mode limits the number of range or inequality properties to 10. For more information on queries with inequality filters, see Query using range and inequality filters on multiple properties.
You can't use both NOT_EQUAL
and NOT_IN
s
If you use the NOT_IN
, you can't also add a
NOT_EQUAL
clause.
Ordering of query results is undefined when no sort order is specified
When a query doesn't specify a sort order, the results are returned in the order they are retrieved. As the Datastore mode implementation evolves (or if a project's indexes change), this order may change. Therefore, if your application requires its query results in a particular order, be sure to explicitly specify that sort order in the query.
Sort orders are ignored on properties with equality filters
Queries that include an equality filter for a given property ignore any sort order specified for that property. This is an optimization to save needless processing for single-valued properties. Since all results have the same value for the property, no further sorting is needed. Multiple-valued properties, however, may have additional values besides the one matched by the equality filter. Because this use case is rare and applying the sort order would be expensive and require extra indexes, the Datastore mode query planner ignores the sort order even in the multiple-valued case. This may cause query results to be returned in a different order than the sort order appears to imply. For example, the sort order is ignored in the following query:
C#
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableGo
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableJava
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicablePHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicablePython
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableRuby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableGQL
# Sort order on an equality filter is ignored SELECT * FROM Task WHERE tag = l'earn 'ORDER BY tag ASC
This doesn't apply to queries that include an IN
filter.
Use the IN
operator to combine up to 10 equality
(==
) clauses on the same property with a logical OR
. If you add a sort
order for that property, it's applied to the result set.
C#
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableGo
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableJava
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicablePHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicablePython
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableRuby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Not ApplicableGQL
SELECT * FROM Task WHERE tag IN ARRAY(l'earn,' s'tudy)' ORDER BY tag ASC
- For ascending order, the smallest value that satisfies the filter is used for ordering.
- For descending order, the greatest value that satisfies the filter is used for ordering.
- Other values don't affect the sort order and nor does the number of values in the property.
Properties used in inequality filters must be sorted first
To retrieve all results that match an inequality filter, a query scans the index for the first row matching the filter, then scans forward until it encounters a non matching row. For the consecutive rows to encompass the complete result set, they must be ordered by the property used in the inequality filter before any other properties. Thus if a query specifies one or more inequality filters along with one or more sort orders, the first sort order must refer to the same property named in the inequality filters. The following is a valid query:
C#
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
SELECT * FROM Task WHERE priority >3 ORDER BY priority, created
This query is not valid, because it doesn't sort on the property used in the inequality filter:
C#
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
# Invalid query! SELECT * FROM Task WHERE priority >3 ORDER BY created
Similarly, this query is not valid because the property used in the inequality filter is not the first one sorted:
C#
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore C# API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Go API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Java API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Node.js API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore PHP API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Python API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Cloud Datastore, see Cloud Datastore client libraries. For more information, see the Cloud Datastore Ruby API reference documentation.
To authenticate to Cloud Datastore, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
GQL
# Invalid query! SELECT * FROM Task WHERE priority >3 ORDER BY created, priority
OrderBy
and existence
When you order a query by a given property, the query can return only the entities where the order-by property exists.
For example, the following query wouldn't return any entities where the
priority
property is not set, even if they otherwise meet the query filters.
Java
Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task") .setFilter(PropertyFilter.eq("done", false)) .setOrderBy(OrderBy.desc("priority")) .build();
A related effect applies to inequalities. A query with an inequality filter
on a property also implies ordering by that property. The following
query doesn't return entities without a priority
property even
if starred = true
in that entity. As a workaround, you can execute
separate queries for each ordering or you can assign a value for all properties
that you order by.
Java
Query<Entity> query = Query.newEntityQueryBuilder() .setKind("Task") .setFilter(CompositeFilter.or( PropertyFilter.eq("starred", true)), PropertyFilter.ge("priority", 4)) .build();
The earlier query includes an implied order-by on the inequality such as the following. The direction of the implied order-by depends on available indexes:
Java
Query<Entity> query = Query.newEntityQueryBuilder() .setKind("Task") .setFilter(CompositeFilter.or( PropertyFilter.eq("starred", true)), PropertyFilter.ge("priority", 4) ) .setOrderBy(OrderBy.asc("priority")) .build();
Limitations on projections
Projection queries are subject to the following limitations:
Only indexed properties can be projected.
This means that all properties used in a query (projected or filters) must exist in the same index. So,
select tag from Task where priority = 1
requires a composite index on priority then tag.Projection is not supported for strings that are longer than 1500 bytes, byte arrays that have more than 1500 elements, and other properties explicitly marked as unindexed.
The same property cannot be projected more than once.
Properties referenced in an equality filter cannot be projected.
For example,
SELECT tag FROM Task WHERE priority = 1
is valid (projected property not used in the equality filter), as is
SELECT tag FROM Task WHERE tag > 'fun`
(not an equality filter), but
SELECT tag FROM Task WHERE tag = 'fun`
(projected property used in equality filter) is not.
Results returned by a projection query shouldn't be saved back to your Datastore mode database.
Because the query returns results that are only partially populated, you shouldn't write them back to the Datastore mode database.
Projection queries convert timestamps into integers.
In the results of a projection query, Datastore mode converts timestamp values to microsecond integer values.
What's next
Learn about Transactions.