Method: projects.runQuery

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

string

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(PartitionId)
  },
  "readOptions": {
    object(ReadOptions)
  },

  // Union field query_type can be only one of the following:
  "query": {
    object(Query)
  },
  "gqlQuery": {
    object(GqlQuery)
  },
  // End of list of possible types for union field query_type.
}
Fields
partitionId

object(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

object(ReadOptions)

The options for this query.

Union field query_type. The type of query. query_type can be only one of the following:
query

object(Query)

The query to run.

gqlQuery

object(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(QueryResultBatch)
  },
  "query": {
    object(Query)
  },
}
Fields
batch

object(QueryResultBatch)

A batch of query results (always present).

query

object(Query)

The parsed form of the GqlQuery from the request, if it was set.

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(Projection)
    }
  ],
  "kind": [
    {
      object(KindExpression)
    }
  ],
  "filter": {
    object(Filter)
  },
  "order": [
    {
      object(PropertyOrder)
    }
  ],
  "distinctOn": [
    {
      object(PropertyReference)
    }
  ],
  "startCursor": string,
  "endCursor": string,
  "offset": number,
  "limit": number,
}
Fields
projection[]

object(Projection)

The projection to return. Defaults to returning all properties.

kind[]

object(KindExpression)

The kinds to query (if empty, returns entities of all kinds). Currently at most 1 kind may be specified.

filter

object(Filter)

The filter to apply.

order[]

object(PropertyOrder)

The order to apply to the query results (if empty, order is unspecified).

distinctOn[]

object(PropertyReference)

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

string (bytes format)

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

string (bytes format)

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

number

The number of results to skip. Applies before limit, but after all other constraints. Optional. Must be >= 0 if specified.

limit

number

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(PropertyReference)
  },
}
Fields
property

object(PropertyReference)

The property to project.

PropertyReference

A reference to a property relative to the kind expressions.

JSON representation 
{
  "name": string,
}
Fields
name

string

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

string

The name of the kind.

Filter

A holder for any type of filter.

JSON representation 
{

  // Union field filter_type can be only one of the following:
  "compositeFilter": {
    object(CompositeFilter)
  },
  "propertyFilter": {
    object(PropertyFilter)
  },
  // End of list of possible types for union field filter_type.
}
Fields
Union field filter_type. The type of filter. filter_type can be only one of the following:
compositeFilter

object(CompositeFilter)

A composite filter.

propertyFilter

object(PropertyFilter)

A filter on a property.

CompositeFilter

A filter that merges multiple other filters using the given operator.

JSON representation 
{
  "op": enum(Operator),
  "filters": [
    {
      object(Filter)
    }
  ],
}
Fields
op

enum(Operator)

The operator for combining multiple filters.

filters[]

object(Filter)

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(PropertyReference)
  },
  "op": enum(Operator),
  "value": {
    object(Value)
  },
}
Fields
property

object(PropertyReference)

The property to filter by.

op

enum(Operator)

The operator to filter by.

value

object(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 value_type can be only one of the following:
  "nullValue": null,
  "booleanValue": boolean,
  "integerValue": string,
  "doubleValue": number,
  "timestampValue": string,
  "keyValue": {
    object(Key)
  },
  "stringValue": string,
  "blobValue": string,
  "geoPointValue": {
    object(LatLng)
  },
  "entityValue": {
    object(Entity)
  },
  "arrayValue": {
    object(ArrayValue)
  },
  // End of list of possible types for union field value_type.
}
Fields
meaning

number

The meaning field should only be populated for backwards compatibility.

excludeFromIndexes

boolean

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

null

A null value.

booleanValue

boolean

A boolean value.

integerValue

string (int64 format)

An integer value.

doubleValue

number

A double value.

timestampValue

string (Timestamp format)

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: "2014-10-02T15:01:23.045123456Z".
keyValue

object(Key)

A key value.

stringValue

string

A UTF-8 encoded string value. When excludeFromIndexes is false (it is indexed) , may have at most 1500 bytes. Otherwise, may be set to at least 1,000,000 bytes.

blobValue

string (bytes format)

A blob value. May have at most 1,000,000 bytes. When excludeFromIndexes is false, may have at most 1500 bytes. In JSON requests, must be base64-encoded.

A base64-encoded string.
geoPointValue

object(LatLng)

A geo point value representing a point on the surface of Earth.

entityValue

object(Entity)

An entity value.

  • May have no key.
  • May have a key with an incomplete key path.
  • May have a reserved/read-only key.
arrayValue

object(ArrayValue)

An array value. Cannot contain another array value. A Value instance that sets field arrayValue must not set fields meaning or excludeFromIndexes.

ArrayValue

An array value.

JSON representation 
{
  "values": [
    {
      object(Value)
    }
  ],
}
Fields
values[]

object(Value)

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(PropertyReference)
  },
  "direction": enum(Direction),
}
Fields
property

object(PropertyReference)

The property to order by.

direction

enum(Direction)

The direction to order by. Defaults to ASCENDING.

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(GqlQueryParameter)
    },
    ...
  },
  "positionalBindings": [
    {
      object(GqlQueryParameter)
    }
  ],
}
Fields
queryString

string

A string of the format described here.

allowLiterals

boolean

When false, the query string must not contain any literals and instead must bind all values. For example, SELECT * FROM Kind WHERE a = 'string literal' is not allowed, while SELECT * FROM Kind WHERE a = @value is.

namedBindings

map (key: string, value: object(GqlQueryParameter))

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 [A-Za-z_$][A-Za-z_$0-9]*, must not match regex __.*__, and must not be "".

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
positionalBindings[]

object(GqlQueryParameter)

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 queryString, there must be an i-th numbered parameter. The inverse must also be true.

GqlQueryParameter

A binding parameter for a GQL query.

JSON representation 
{

  // Union field parameter_type can be only one of the following:
  "value": {
    object(Value)
  },
  "cursor": string,
  // End of list of possible types for union field parameter_type.
}
Fields
Union field parameter_type. The type of parameter. parameter_type can be only one of the following:
value

object(Value)

A value parameter.

cursor

string (bytes format)

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(ResultType),
  "entityResults": [
    {
      object(EntityResult)
    }
  ],
  "endCursor": string,
  "moreResults": enum(MoreResultsType),
  "snapshotVersion": string,
}
Fields
skippedResults

number

The number of results skipped, typically because of an offset.

skippedCursor

string (bytes format)

A cursor that points to the position after the last skipped result. Will be set when skippedResults != 0.

A base64-encoded string.
entityResultType

enum(ResultType)

The result type for every entity in entityResults.

entityResults[]

object(EntityResult)

The results for this batch.

endCursor

string (bytes format)

A cursor that points to the position after the last result in the batch.

A base64-encoded string.
moreResults

enum(MoreResultsType)

The state of the query after the current batch.

snapshotVersion

string (int64 format)

The version number of the snapshot this batch was returned from. This applies to the range of results from the query's startCursor (or the beginning of the query if no cursor was given) to this batch's endCursor (not the query's endCursor).

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.

Try it!