Cloud Datastore Client - Class Query (1.28.2)

Reference documentation and code samples for the Cloud Datastore Client class Query.

Represents a CloudDatastore Query

Queries can be created either by using the builder pattern, or by providingaQuerywhen creating this object.

Example:

use Google\Cloud\Datastore\DatastoreClient;$datastore = new DatastoreClient();$query = $datastore->query();$query->kind('Companies');$query->filter('companyName', '=', 'Google');$res = $datastore->runQuery($query);foreach ($res as $company) {    echo $company['companyName']; // Google}
// Queries can also be constructed using a// [Query Object](https://cloud.google.com/datastore/reference/rest/v1/projects/runQuery#query):$query = $datastore->query([    'query' => [        'kind' => [            [                'name' => 'Companies'            ]        ],        'filter' => [            'propertyFilter' => [                'op' => 'EQUAL',                'property' => [                    'name' => 'companyName'                ],                'value' => [                    'stringValue' => 'Google'                ]            ]        ]    ]]);

Namespace

Google \ Cloud \ Datastore \ Query

Methods

__construct

Parameters
NameDescription
entityMapperGoogle\Cloud\Datastore\EntityMapper

An instance of EntityMapper

queryarray

optional(https://cloud.google.com/datastore/reference/rest/v1/projects/runQuery#query)

projection

Set the Query Projection.

Accepts an array of properties. If set, only these properties will bereturned.

Example:

$query->projection(['firstName', 'lastName']);
Parameter
NameDescription
propertiesarray|string

The property or properties to include inthe result.

Returns
TypeDescription
Google\Cloud\Datastore\Query\Query

keysOnly

Set the query to return only keys (no properties).

Example:

$query->keysOnly();
Returns
TypeDescription
Google\Cloud\Datastore\Query\Query

kind

Set the Kind to query.

If empty, returns entities of all kinds. Must be set in order to filterresults. While you may supply as many kinds as you wish, datastore currentlyonly accepts one at a time.

Example:

$query->kind('Person');
Parameter
NameDescription
kindsarray|string

The kind or kinds to return. Only a single kindis currently supported.

Returns
TypeDescription
Google\Cloud\Datastore\Query\Query

filter

Parameters
NameDescription
filterOrPropertystring|array

Either a string property name oran array representation of Property/Composite filter returnedby Filter::and(), Filter::or() and Filter::where().

operatorstring|null

[optional] The operator to use in the filterif property name is used in the first argument. A list ofallowed operators may be foundhere.Short comparison operators are provided for convenience and aremapped to their datastore-compatible equivalents. Available shortoperators are=,!=,<,<=,>,>=,IN andNOT IN.

valuemixed

[optional] The value to check if property name isused in the first argument.

Returns
TypeDescription
Google\Cloud\Datastore\Query\Query

hasAncestor

Query for entities by their ancestors.

Keys can be provided either via aGoogle\Cloud\Datastore\Keyobject, or by providing a kind, identifier and (optionally) an identifiertype.

Example:

$key = $datastore->key('Person', 'Bob');$query->hasAncestor($key);
// Specifying an identifier type$key = $datastore->key('Robots', '1337', [    'identifierType' => Key::TYPE_NAME]);$query->hasAncestor($key);
Parameter
NameDescription
keyGoogle\Cloud\Datastore\Key

The ancestor Key instance.

Returns
TypeDescription
Google\Cloud\Datastore\Query\Query

order

Parameters
NameDescription
propertystring

The property to order by.

directionstring

[optional] The direction to order in. GoogleCloud PHP provides class constants which map to allowed Datastorevalues. Those constants areQuery::ORDER_DESCENDING andQuery::ORDER_ASCENDING.Defaults toQuery::ORDER_ACENDING.

Returns
TypeDescription
Google\Cloud\Datastore\Query\Query

distinctOn

The properties to make distinct.

The query results will contain the first result for each distinctcombination of values for the given properties (if empty, all resultsare returned).

Example:

$query->distinctOn('lastName');
Parameter
NameDescription
propertyarray|string

The property or properties to make distinct.

Returns
TypeDescription
Google\Cloud\Datastore\Query\Query

start

Parameter
NameDescription
cursorstring

The cursor on which to start the result.

Returns
TypeDescription
Google\Cloud\Datastore\Query\Query

end

Parameter
NameDescription
cursorstring

The cursor on which to end the result.

Returns
TypeDescription
Google\Cloud\Datastore\Query\Query

offset

Parameter
NameDescription
numint

The number of results to skip.

Returns
TypeDescription
Google\Cloud\Datastore\Query\Query

limit

Parameter
NameDescription
numint

The number of results to return.

Returns
TypeDescription
Google\Cloud\Datastore\Query\Query

canPaginate

Indicate that this type does support automatic pagination.

Returns
TypeDescription
bool

queryObject

Return a service-compliant array.

Returns
TypeDescription
array

queryKey

Return the query_type union field name.

Returns
TypeDescription
string

aggregation

Parameter
NameDescription
aggregationGoogle\Cloud\Datastore\Query\Aggregation

jsonSerialize

Constants

OP_DEFAULT

Value: self::OP_EQUALS

OP_LESS_THAN

Value: 'LESS_THAN'

OP_LESS_THAN_OR_EQUAL

Value: 'LESS_THAN_OR_EQUAL'

OP_GREATER_THAN

Value: 'GREATER_THAN'

OP_GREATER_THAN_OR_EQUAL

Value: 'GREATER_THAN_OR_EQUAL'

OP_EQUALS

Value: 'EQUAL'

OP_NOT_EQUALS

Value: 'NOT_EQUAL'

OP_IN

Value: 'IN'

OP_NOT_IN

Value: 'NOT_IN'

OP_HAS_ANCESTOR

Value: 'HAS_ANCESTOR'

ORDER_DEFAULT

Value: self::ORDER_ASCENDING

ORDER_DESCENDING

Value: 'DESCENDING'

ORDER_ASCENDING

Value: 'ASCENDING'

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-01-24 UTC.