Cloud Firestore Client - Class Query (1.36.1)

Version 1.36.1

• 1.47.1 (latest)
• 1.47.0
• 1.46.0
• 1.45.2
• 1.44.1
• 1.43.3
• 1.40.0
• 1.39.0
• 1.38.0
• 1.37.7
• 1.36.1
• 1.35.0
• 1.34.0
• 1.33.0
• 1.32.0
• 1.31.0
• 1.30.0
• 1.28.0
• 1.27.3

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

A Cloud Firestore Query.

This class is immutable; any filters applied will return a new instance of the class.

Example:

use Google\Cloud\Firestore\FirestoreClient;

$firestore = new FirestoreClient();

$collection = $firestore->collection('users');
$query = $collection->where('age', '>', 18);

Namespace

Google \ Cloud \ Firestore

Methods

__construct

Parameters
Name	Description
connection	Google\Cloud\Firestore\Connection\ConnectionInterface A Connection to Cloud Firestore.
valueMapper	Google\Cloud\Firestore\ValueMapper A Firestore Value Mapper.
parent	string The parent of the query.
query	array The Query object
limitToLast	bool Limit a query to return only the last matching documents.

count

Gets the count of all documents matching the provided query filters.

Example:

$count = $query->count();

Parameters
Name	Description
options	array Configuration options is an array.
↳ readTime	Timestamp Reads entities as they were at the given timestamp.

Returns
Type	Description
int

addAggregation

Returns an aggregate query provided an aggregation with existing query filters.

Example:

use Google\Cloud\Firestore\Aggregate;

$aggregation = Aggregate::count()->alias('count_upto_1');
$aggregateQuery = $query->limit(1)->addAggregation($aggregation);
$aggregateQuerySnapshot = $aggregateQuery->getSnapshot();
$countUpto1 = $aggregateQuerySnapshot->get('count_upto_1');

Parameter
Name	Description
aggregate	Google\Cloud\Firestore\Aggregate Aggregate properties to be applied over query.

Returns
Type	Description
Google\Cloud\Firestore\AggregateQuery

documents

Get all documents matching the provided query filters.

Example:

$result = $query->documents();

Parameters
Name	Description
options	array Configuration options.
↳ maxRetries	int The maximum number of times to retry a query. Defaults to 5.

Returns
Type	Description
Google\Cloud\Firestore\QuerySnapshot<\google\cloud\firestore\documentsnapshot>

select

Add a SELECT to the Query.

Creates and returns a new Query instance that applies a field mask to the result and returns only the specified subset of fields. You can specify a list of field paths to return, or use an empty list to only return the references of matching documents.

Subsequent calls to this method will override previous values.

Example:

$query = $query->select(['firstName']);

Parameter
Name	Description
fieldPaths	string[]|array<Google\Cloud\Firestore\FieldPath> The projection to return, in the form of an array of field paths. To only return the name of the document, provide an empty array.

Returns
Type	Description
Google\Cloud\Firestore\Query	A new instance of Query with the given changes applied.

where

Add a WHERE clause to the Query.

For a list of all available operators, see Google\Cloud\Firestore\Google\Cloud\Firestore\V1\StructuredQuery\FieldFilter\Operator. This method also supports a number of comparison operators which you will be familiar with, such as =, >, <, <= and >=. For array fields, the array-contains, IN and array-contains-any operators are also available. This method also supports usage of Filters (see Google\Cloud\Firestore\Google\Cloud\Firestore\Filter). The Filter class helps to create complex queries using AND and OR operators.

Example:

$query = $query->where('firstName', '=', 'John');

// Filtering against `null` and `NAN` is supported only with the equality operator.
$query = $query->where('coolnessPercentage', '=', NAN);

// Use `array-contains` to select documents where the array contains given elements.
$query = $query->where('friends', 'array-contains', ['Steve', 'Sarah']);

use Google\Cloud\Firestore\Filter;

// Filtering with Filter::or
$query = $query->where(Filter::or([
    Filter::field('firstName', '=', 'John'),
    Filter::field('firstName', '=', 'Monica')
]));

Parameters
Name	Description
fieldPath	string|array|Google\Cloud\Firestore\FieldPath The field to filter by, or array of Filters. If filter array is provided, other params will be ignored.
operator	string|int The operator to filter by.
value	mixed The value to compare to.

Returns
Type	Description
Google\Cloud\Firestore\Query	A new instance of Query with the given changes applied.

orderBy

Add an ORDER BY clause to the Query.

Example:

$query = $query->orderBy('firstName', 'DESC');

Parameters
Name	Description
fieldPath	string|Google\Cloud\Firestore\FieldPath The field to order by.
direction	string|int The direction to order in. Defaults to ASC.

Returns
Type	Description
Google\Cloud\Firestore\Query	A new instance of Query with the given changes applied.

limit

Limits a query to return only the first matching documents.

Applies after all other constraints. Must be >= 0 if specified.

Example:

$query = $query->limit(10);

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

Returns
Type	Description
Google\Cloud\Firestore\Query	A new instance of Query with the given changes applied.

limitToLast

Limits a query to return only the last matching documents.

Applies after all other constraints. Must be >= 0 if specified.

You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution.

Example:

$query = $query->limitToLast(10)
    ->orderBy('firstName');

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

Returns
Type	Description
Google\Cloud\Firestore\Query	A new instance of Query with the given changes applied.

offset

The number of results to skip.

Applies before limit, but after all other constraints. Must be >= 0 if specified.

Example:

$query = $query->offset(10);

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

Returns
Type	Description
Google\Cloud\Firestore\Query	A new instance of Query with the given changes applied.

startAt

A starting point for the query results.

Starts results at the provided set of field values relative to the order of the query. The order of the provided values must match the order of the order by clauses of the query. Values in the given cursor will be included in the result set, if found.

Multiple invocations of this call overwrite previous calls. Calling startAt() will overwrite both previous startAt() and startAfter() calls.

Example:

$query = $query->orderBy('age', 'ASC')->startAt([18]);
$users18YearsOrOlder = $query->documents();

Parameter
Name	Description
fieldValues	array|Google\Cloud\Firestore\DocumentSnapshot A list of values, or an instance of Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentSnapshot defining the query starting point.

Returns
Type	Description
Google\Cloud\Firestore\Query	A new instance of Query with the given changes applied.

startAfter

A starting point for the query results.

Starts results after the provided set of field values relative to the order of the query. The order of the provided values must match the order of the order by clauses of the query. Values in the given cursor will not be included in the result set.

Multiple invocations of this call overwrite previous calls. Calling startAt() will overwrite both previous startAt() and startAfter() calls.

Example:

$query = $query->orderBy('age', 'ASC')->startAfter([17]);
$users18YearsOrOlder = $query->documents();

Parameter
Name	Description
fieldValues	array|Google\Cloud\Firestore\DocumentSnapshot A list of values, or an instance of Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentSnapshot defining the query starting point.

Returns
Type	Description
Google\Cloud\Firestore\Query	A new instance of Query with the given changes applied.

endBefore

An end point for the query results.

Ends results before the provided set of field values relative to the order of the query. The order of the provided values must match the order of the order by clauses of the query. Values in the given cursor will be included in the result set, if found.

Multiple invocations of this call overwrite previous calls. Calling endBefore() will overwrite both previous endBefore() and endAt() calls.

Example:

$query = $query->orderBy('age', 'ASC')->endBefore([18]);
$usersYoungerThan18 = $query->documents();

Parameter
Name	Description
fieldValues	array|Google\Cloud\Firestore\DocumentSnapshot A list of values, or an instance of Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentSnapshot defining the query end point.

Returns
Type	Description
Google\Cloud\Firestore\Query	A new instance of Query with the given changes applied.

endAt

An end point for the query results.

Ends results at the provided set of field values relative to the order of the query. The order of the provided values must match the order of the order by clauses of the query. Values in the given cursor will not be included in the result set.

Multiple invocations of this call overwrite previous calls. Calling endBefore() will overwrite both previous endBefore() and endAt() calls.

Example:

$query = $query->orderBy('age', 'ASC')->endAt([17]);
$usersYoungerThan18 = $query->documents();

Parameter
Name	Description
fieldValues	array|Google\Cloud\Firestore\DocumentSnapshot A list of values, or an instance of Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentSnapshot defining the query end point.

Returns
Type	Description
Google\Cloud\Firestore\Query	A new instance of Query with the given changes applied.

queryHas

Check if a given constraint type has been specified on the query.

Parameter
Name	Description
key	string The constraint name.

Returns
Type	Description
bool

queryKey

Get the constraint data from the current query.

Parameter
Name	Description
key	string The constraint name

Returns
Type	Description
mixed

Constants

OP_LESS_THAN

Value: \Google\Cloud\Firestore\V1\StructuredQuery\FieldFilter\Operator::LESS_THAN

OP_LESS_THAN_OR_EQUAL

Value: \Google\Cloud\Firestore\V1\StructuredQuery\FieldFilter\Operator::LESS_THAN_OR_EQUAL

OP_GREATER_THAN

Value: \Google\Cloud\Firestore\V1\StructuredQuery\FieldFilter\Operator::GREATER_THAN

OP_GREATER_THAN_OR_EQUAL

Value: \Google\Cloud\Firestore\V1\StructuredQuery\FieldFilter\Operator::GREATER_THAN_OR_EQUAL

OP_EQUAL

Value: \Google\Cloud\Firestore\V1\StructuredQuery\FieldFilter\Operator::EQUAL

OP_ARRAY_CONTAINS

Value: \Google\Cloud\Firestore\V1\StructuredQuery\FieldFilter\Operator::ARRAY_CONTAINS

OP_NAN

Value: \Google\Cloud\Firestore\V1\StructuredQuery\UnaryFilter\Operator::IS_NAN

OP_NULL

Value: \Google\Cloud\Firestore\V1\StructuredQuery\UnaryFilter\Operator::IS_NULL

DIR_ASCENDING

Value: \Google\Cloud\Firestore\V1\StructuredQuery\Direction::ASCENDING

DIR_DESCENDING

Value: \Google\Cloud\Firestore\V1\StructuredQuery\Direction::DESCENDING

DOCUMENT_ID

Value: '__name__'