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 \ FirestoreMethods
__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 |
Returns | |
---|---|
Type | Description |
Google\Cloud\Firestore\QuerySnapshotGoogle\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
|
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__'