- HTTP request
- Path parameters
- Request body
- Response body
- Authorization Scopes
- Query
- Projection
- PropertyReference
- KindExpression
- Filter
- CompositeFilter
- Operator
- PropertyFilter
- Operator
- Value
- ArrayValue
- PropertyOrder
- Direction
- GqlQuery
- GqlQueryParameter
- QueryResultBatch
- ResultType
- MoreResultsType
- Try it!
Queries for entities.
HTTP request
POST https://datastore.googleapis.com/v1/projects/{projectId}:runQuery
The URL uses Google API HTTP annotation syntax.
Path parameters
Parameters | |
---|---|
projectId |
The ID of the project against which to make the request. |
Request body
The request body contains data with the following structure:
JSON representation | |
---|---|
{ "partitionId": { object( |
Fields | ||
---|---|---|
partitionId |
Entities are partitioned into subsets, identified by a partition ID. Queries are scoped to a single partition. This partition ID is normalized with the standard default context partition ID. |
|
readOptions |
The options for this query. |
|
Union field query_type . The type of query. query_type can be only one of the following: |
||
query |
The query to run. |
|
gqlQuery |
The GQL query to run. |
Response body
If successful, the response body contains data with the following structure:
The response for Datastore.RunQuery
.
JSON representation | |
---|---|
{ "batch": { object( |
Fields | |
---|---|
batch |
A batch of query results (always present). |
query |
The parsed form of the |
Authorization Scopes
Requires one of the following OAuth scopes:
https://www.googleapis.com/auth/datastore
https://www.googleapis.com/auth/cloud-platform
For more information, see the Auth Guide.
Query
A query for entities.
JSON representation | |
---|---|
{ "projection": [ { object( |
Fields | |
---|---|
projection[] |
The projection to return. Defaults to returning all properties. |
kind[] |
The kinds to query (if empty, returns entities of all kinds). Currently at most 1 kind may be specified. |
filter |
The filter to apply. |
order[] |
The order to apply to the query results (if empty, order is unspecified). |
distinctOn[] |
The properties to make distinct. The query results will contain the first result for each distinct combination of values for the given properties (if empty, all results are returned). |
startCursor |
A starting point for the query results. Query cursors are returned in query result batches and can only be used to continue the same query. A base64-encoded string. |
endCursor |
An ending point for the query results. Query cursors are returned in query result batches and can only be used to limit the same query. A base64-encoded string. |
offset |
The number of results to skip. Applies before limit, but after all other constraints. Optional. Must be >= 0 if specified. |
limit |
The maximum number of results to return. Applies after all other constraints. Optional. Unspecified is interpreted as no limit. Must be >= 0 if specified. |
Projection
A representation of a property in a projection.
JSON representation | |
---|---|
{
"property": {
object( |
Fields | |
---|---|
property |
The property to project. |
PropertyReference
A reference to a property relative to the kind expressions.
JSON representation | |
---|---|
{ "name": string, } |
Fields | |
---|---|
name |
The name of the property. If name includes "."s, it may be interpreted as a property name path. |
KindExpression
A representation of a kind.
JSON representation | |
---|---|
{ "name": string, } |
Fields | |
---|---|
name |
The name of the kind. |
Filter
A holder for any type of filter.
JSON representation | |
---|---|
{ // Union field |
Fields | ||
---|---|---|
Union field filter_type . The type of filter. filter_type can be only one of the following: |
||
compositeFilter |
A composite filter. |
|
propertyFilter |
A filter on a property. |
CompositeFilter
A filter that merges multiple other filters using the given operator.
JSON representation | |
---|---|
{ "op": enum( |
Fields | |
---|---|
op |
The operator for combining multiple filters. |
filters[] |
The list of filters to combine. Must contain at least one filter. |
Operator
A composite filter operator.
Enums | |
---|---|
OPERATOR_UNSPECIFIED |
Unspecified. This value must not be used. |
AND |
The results are required to satisfy each of the combined filters. |
PropertyFilter
A filter on a specific property.
JSON representation | |
---|---|
{ "property": { object( |
Fields | |
---|---|
property |
The property to filter by. |
op |
The operator to filter by. |
value |
The value to compare the property to. |
Operator
A property filter operator.
Enums | |
---|---|
OPERATOR_UNSPECIFIED |
Unspecified. This value must not be used. |
LESS_THAN |
Less than. |
LESS_THAN_OR_EQUAL |
Less than or equal. |
GREATER_THAN |
Greater than. |
GREATER_THAN_OR_EQUAL |
Greater than or equal. |
EQUAL |
Equal. |
HAS_ANCESTOR |
Has ancestor. |
Value
A message that can hold any of the supported value types and associated metadata.
JSON representation | |
---|---|
{ "meaning": number, "excludeFromIndexes": boolean, // Union field |
Fields | ||
---|---|---|
meaning |
The |
|
excludeFromIndexes |
If the value should be excluded from all indexes including those defined explicitly. |
|
Union field value_type . Must have a value set. value_type can be only one of the following: |
||
nullValue |
A null value. |
|
booleanValue |
A boolean value. |
|
integerValue |
An integer value. |
|
doubleValue |
A double value. |
|
timestampValue |
A timestamp value. When stored in the Datastore, precise only to microseconds; any additional precision is rounded down. A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: |
|
keyValue |
A key value. |
|
stringValue |
A UTF-8 encoded string value. When |
|
blobValue |
A blob value. May have at most 1,000,000 bytes. When A base64-encoded string. |
|
geoPointValue |
A geo point value representing a point on the surface of Earth. |
|
entityValue |
An entity value.
|
|
arrayValue |
An array value. Cannot contain another array value. A |
ArrayValue
An array value.
JSON representation | |
---|---|
{
"values": [
{
object( |
Fields | |
---|---|
values[] |
Values in the array. The order of this array may not be preserved if it contains a mix of indexed and unindexed values. |
PropertyOrder
The desired order for a specific property.
JSON representation | |
---|---|
{ "property": { object( |
Fields | |
---|---|
property |
The property to order by. |
direction |
The direction to order by. Defaults to |
Direction
The sort direction.
Enums | |
---|---|
DIRECTION_UNSPECIFIED |
Unspecified. This value must not be used. |
ASCENDING |
Ascending. |
DESCENDING |
Descending. |
GqlQuery
A GQL query.
JSON representation | |
---|---|
{ "queryString": string, "allowLiterals": boolean, "namedBindings": { string: { object( |
Fields | |
---|---|
queryString |
A string of the format described here. |
allowLiterals |
When false, the query string must not contain any literals and instead must bind all values. For example, |
namedBindings |
For each non-reserved named binding site in the query string, there must be a named parameter with that name, but not necessarily the inverse. Key must match regex An object containing a list of |
positionalBindings[] |
Numbered binding site @1 references the first numbered parameter, effectively using 1-based indexing, rather than the usual 0. For each binding site numbered i in |
GqlQueryParameter
A binding parameter for a GQL query.
JSON representation | |
---|---|
{ // Union field |
Fields | ||
---|---|---|
Union field parameter_type . The type of parameter. parameter_type can be only one of the following: |
||
value |
A value parameter. |
|
cursor |
A query cursor. Query cursors are returned in query result batches. A base64-encoded string. |
QueryResultBatch
A batch of results produced by a query.
JSON representation | |
---|---|
{ "skippedResults": number, "skippedCursor": string, "entityResultType": enum( |
Fields | |
---|---|
skippedResults |
The number of results skipped, typically because of an offset. |
skippedCursor |
A cursor that points to the position after the last skipped result. Will be set when A base64-encoded string. |
entityResultType |
The result type for every entity in |
entityResults[] |
The results for this batch. |
endCursor |
A cursor that points to the position after the last result in the batch. A base64-encoded string. |
moreResults |
The state of the query after the current batch. |
snapshotVersion |
The version number of the snapshot this batch was returned from. This applies to the range of results from the query's In a single transaction, subsequent query result batches for the same query can have a greater snapshot version number. Each batch's snapshot version is valid for all preceding batches. The value will be zero for eventually consistent queries. |
ResultType
Specifies what data the 'entity' field contains. A ResultType
is either implied (for example, in LookupResponse.missing
from datastore.proto
, it is always KEY_ONLY
) or specified by context (for example, in message QueryResultBatch
, field entityResultType
specifies a ResultType
for all the values in field entityResults
).
Enums | |
---|---|
RESULT_TYPE_UNSPECIFIED |
Unspecified. This value is never used. |
FULL |
The key and properties. |
PROJECTION |
A projected subset of properties. The entity may have no key. |
KEY_ONLY |
Only the key. |
MoreResultsType
The possible values for the moreResults
field.
Enums | |
---|---|
MORE_RESULTS_TYPE_UNSPECIFIED |
Unspecified. This value is never used. |
NOT_FINISHED |
There may be additional batches to fetch from this query. |
MORE_RESULTS_AFTER_LIMIT |
The query is finished, but there may be more results after the limit. |
MORE_RESULTS_AFTER_CURSOR |
The query is finished, but there may be more results after the end cursor. |
NO_MORE_RESULTS |
The query is finished, and there are no more results. |