Cloud Firestore Client - Class Query (1.38.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

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

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