Cloud Firestore Client - Class Query (1.39.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);

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

Example:

$count = $query->count();

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.

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.

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');

See also:

• RunQuery

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']);

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')
]));

Add an ORDER BY clause to the Query.

Example:

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

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

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');

The number of results to skip.

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

Example:

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

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();

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();

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();

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();

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

Get the constraint data from the current query.