Cloud Datastore Client - Class Query (1.18.1)

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

Queries can be created either by using the builder pattern, or by providing a Query when 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'
                ]
            ]
        ]
    ]
]);

Methods

__construct

Parameters
Name	Description
`entityMapper`	`Google\Cloud\Datastore\EntityMapper` An instance of EntityMapper
`query`	`array` [optional] Query

projection

Set the Query Projection.

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

Example:

$query->projection(['firstName', 'lastName']);

Parameter
Name	Description
`properties`	`array\|string` The property or properties to include in the result.

Returns
Type	Description
`Google\Cloud\Datastore\Query\Query`

keysOnly

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

Example:

$query->keysOnly();

Returns
Type	Description
`Google\Cloud\Datastore\Query\Query`

kind

Set the Kind to query.

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

Example:

$query->kind('Person');

Parameter
Name	Description
`kinds`	`array\|string` The kind or kinds to return. Only a single kind is currently supported.

Returns
Type	Description
`Google\Cloud\Datastore\Query\Query`

filter

Add a filter to the query.

If the top-level filter is specified as a propertyFilter, it will be replaced. Any composite filters will be preserved and the new filter will be added.

Example:

$query->filter('firstName', '=', 'Bob')
    ->filter('lastName', '=', 'Testguy');

Parameters
Name	Description
`property`	`string` The property to filter.
`operator`	`string` The operator to use in the filter. A list of allowed operators may be found here. Short comparison operators are provided for convenience and are mapped to their datastore-compatible equivalents. Available short operators are `=`, `!=`, `<`, `<=`, `>`, and `>=`.
`value`	`mixed` The value to check.

Returns
Type	Description
`Google\Cloud\Datastore\Query\Query`

hasAncestor

Query for entities by their ancestors.

Keys can be provided either via a Google\Cloud\Datastore\Query\Google\Cloud\Datastore\Key object, or by providing a kind, identifier and (optionally) an identifier type.

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
Name	Description
`key`	`Google\Cloud\Datastore\Key` The ancestor Key instance.

Returns
Type	Description
`Google\Cloud\Datastore\Query\Query`

order

Specify an order for the query.

Example:

$query->order('birthDate', Query::ORDER_DESCENDING);

Parameters
Name	Description
`property`	`string` The property to order by.
`direction`	`string` [optional] The direction to order in. Google Cloud PHP provides class constants which map to allowed Datastore values. Those constants are `Query::ORDER_DESCENDING` and `Query::ORDER_ASCENDING`. Defaults to `Query::ORDER_ACENDING`.

Returns
Type	Description
`Google\Cloud\Datastore\Query\Query`

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).

Example:

$query->distinctOn('lastName');

Parameter
Name	Description
`property`	`array\|string` The property or properties to make distinct.

Returns
Type	Description
`Google\Cloud\Datastore\Query\Query`

start

The starting point for the query results.

Example:

$query->start($lastResultCursor);

Parameter
Name	Description
`cursor`	`string` The cursor on which to start the result.

Returns
Type	Description
`Google\Cloud\Datastore\Query\Query`

end

The ending point for the query results.

Example:

$query->end($lastResultCursor);

Parameter
Name	Description
`cursor`	`string` The cursor on which to end the result.

Returns
Type	Description
`Google\Cloud\Datastore\Query\Query`

offset

The number of results to skip.

Example:

$query->offset(2);

Parameter
Name	Description
`num`	`int` The number of results to skip.

Returns
Type	Description
`Google\Cloud\Datastore\Query\Query`

limit

The number of results to return.

Example:

$query->limit(50);

Parameter
Name	Description
`num`	`int` The number of results to return.

Returns
Type	Description
`Google\Cloud\Datastore\Query\Query`

canPaginate

Indicate that this type does support automatic pagination.

Returns
Type	Description
`bool`

queryObject

Return a service-compliant array.

This method is intended for use internally by the PHP client.

Returns
Type	Description
`array`

queryKey

Return the query_type union field name.

Returns
Type	Description
`string`

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'