Cloud Firestore Client - Class Query (1.45.0)

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. This object is created by FirestoreClient, and should not be instantiated outside of this client.
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

sum

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

Example:

$sum = $query->sum();

Sum of integers which exceed maximum integer value returns a float. Sum of numbers exceeding max float value returns INF. Sum of data which contains NaN returns NaN. Non numeric values are ignored.

Parameters
Name Description
field string

The relative path of the field to aggregate upon.
options array

Configuration options is an array.
↳ readTime Timestamp

Reads entities as they were at the given timestamp.
Returns
Type Description
int|float

avg

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

Example:

$avg = $query->avg();

Average of empty valid data set return null. Average of numbers exceeding max float value returns INF. Average of data which contains NaN returns NaN. Non numeric values are ignored.

Parameters
Name Description
field string

The relative path of the field to aggregate upon.
options array

Configuration options is an array.
↳ readTime Timestamp

Reads entities as they were at the given timestamp.
Returns
Type Description
float|null

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

See also:

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\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\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\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\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\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\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__'