Method: projects.runQuery

Queries for entities.

HTTP request

POST https://datastore.googleapis.com/v1/projects/{projectId}:runQuery

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
projectId

string

Required. 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. This query must be a non-aggregation query.

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 Authentication Overview.

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": integer,
  "limit": integer
}
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

integer

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

limit

integer

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

The given property is less than the given value.

Requires:

  • That property comes first in order_by.
LESS_THAN_OR_EQUAL

The given property is less than or equal to the given value.

Requires:

  • That property comes first in order_by.
GREATER_THAN

The given property is greater than the given value.

Requires:

  • That property comes first in order_by.
GREATER_THAN_OR_EQUAL

The given property is greater than or equal to the given value.

Requires:

  • That property comes first in order_by.
EQUAL The given property is equal to the given value.
HAS_ANCESTOR

Limit the result set to the given entity and its descendants.

Requires:

  • That value is an entity key.

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.

QueryResultBatch

A batch of results produced by a query.

JSON representation
{
  "skippedResults": integer,
  "skippedCursor": string,
  "entityResultType": enum (ResultType),
  "entityResults": [
    {
      object (EntityResult)
    }
  ],
  "endCursor": string,
  "moreResults": enum (MoreResultsType),
  "snapshotVersion": string
}
Fields
skippedResults

integer

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.