A Query refers to a query which you can read or stream from. You can also construct refined Query objects by adding filters and ordering.
Query
Package
@google-cloud/firestoreRemarks
The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the Query
class.
Properties
firestore
get
firestore
()
:
Firestore
;
The [Firestore] Firestore instance for the Firestore database (useful for performing transactions, etc.).
{Firestore} Query#firestore
let
collectionRef
=
firestore
.
collection
(
'col'
);
collectionRef
.
add
({
foo
:
'bar'
}).
then
(
documentReference
=
>
{
let
firestore
=
documentReference
.
firestore
;
console
.
log
(
`Root location for document is
${
firestore
.
formattedName
}
`
);
});
Methods
aggregate(aggregateSpec)
aggregate<T
extends
firestore
.
AggregateSpec
> (
aggregateSpec
:
T
)
:
AggregateQuery<T
,
AppModelType
,
DbModelType
> ;
Returns a query that can perform the given aggregations.
The returned query, when executed, calculates the specified aggregations over the documents in the result set of this query without actually downloading the documents.
Using the returned query to perform aggregations is efficient because only the final aggregation values, not the documents' data, is downloaded. The returned query can perform aggregations of the documents count the documents in cases where the result set is prohibitively large to download entirely (thousands of documents).
aggregateSpec
T
An AggregateSpec
object that specifies the aggregates to perform over the result set. The AggregateSpec specifies aliases for each aggregate, which can be used to retrieve the aggregate result.
T
typescript
const
aggregateQuery
=
col
.
aggregate
(
query
,
{
countOfDocs
:
count
(),
totalHours
:
sum
(
'hours'
),
averageScore
:
average
(
'score'
)
});
const
aggregateSnapshot
=
await
aggregateQuery
.
get
();
const
countOfDocs
:
number
=
aggregateSnapshot
.
data
().
countOfDocs
;
const
totalHours
:
number
=
aggregateSnapshot
.
data
().
totalHours
;
const
averageScore
:
number
|
null
=
aggregateSnapshot
.
data
().
averageScore
;
count()
count
()
:
AggregateQuery
< {
count
:
firestore
.
AggregateField<number>
;
},
AppModelType
,
DbModelType
> ;
Returns a query that counts the documents in the result set of this query.
The returned query, when executed, counts the documents in the result set of this query without actually downloading the documents.
Using the returned query to count the documents is efficient because only the final count, not the documents' data, is downloaded. The returned query can count the documents in cases where the result set is prohibitively large to download entirely (thousands of documents).
a query that counts the documents in the result set of this query. The count can be retrieved from snapshot.data().count
, where snapshot
is the AggregateQuerySnapshot
resulting from running the returned query.
AggregateQuery
<{
count: FirebaseFirestore.AggregateField
<number>;
}, AppModelType, DbModelType>
endAt(fieldValuesOrDocumentSnapshot)
endAt
(...
fieldValuesOrDocumentSnapshot
:
Array<unknown>
)
:
Query<AppModelType
,
DbModelType
> ;
Creates and returns a new [Query] Query that ends 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.
fieldValuesOrDocumentSnapshot
Array
<unknown>
The snapshot of the document the query results should end at or the field values to end this query at, in order of the query's order by.
Query
<AppModelType, DbModelType>
{Query} A query with the new ending point.
let
query
=
firestore
.
collection
(
'col'
);
query
.
orderBy
(
'foo'
).
endAt
(
42
).
get
().
then
(
querySnapshot
=
>
{
querySnapshot
.
forEach
(
documentSnapshot
=
>
{
console
.
log
(
`Found document at
${
documentSnapshot
.
ref
.
path
}
`
);
});
});
endBefore(fieldValuesOrDocumentSnapshot)
endBefore
(...
fieldValuesOrDocumentSnapshot
:
Array<unknown>
)
:
Query<AppModelType
,
DbModelType
> ;
Creates and returns a new [Query] Query that ends before the 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.
fieldValuesOrDocumentSnapshot
Array
<unknown>
The snapshot of the document the query results should end before or the field values to end this query before, in order of the query's order by.
Query
<AppModelType, DbModelType>
{Query} A query with the new ending point.
let
query
=
firestore
.
collection
(
'col'
);
query
.
orderBy
(
'foo'
).
endBefore
(
42
).
get
().
then
(
querySnapshot
=
>
{
querySnapshot
.
forEach
(
documentSnapshot
=
>
{
console
.
log
(
`Found document at
${
documentSnapshot
.
ref
.
path
}
`
);
});
});
get()
get
()
:
Promise<QuerySnapshot<AppModelType
,
DbModelType
>> ;
Executes the query and returns the results as a [QuerySnapshot] QuerySnapshot .
let
query
=
firestore
.
collection
(
'col'
).
where
(
'foo'
,
'=='
,
'bar'
);
query
.
get
().
then
(
querySnapshot
=
>
{
querySnapshot
.
forEach
(
documentSnapshot
=
>
{
console
.
log
(
`Found document at
${
documentSnapshot
.
ref
.
path
}
`
);
});
});
isEqual(other)
isEqual
(
other
:
firestore
.
Query<AppModelType
,
DbModelType
> )
:
boolean
;
Returns true if this Query
is equal to the provided value.
other
FirebaseFirestore.Query
<AppModelType, DbModelType>
The value to compare against. {boolean} true if this Query
is equal to the provided value.
boolean
limit(limit)
limit
(
limit
:
number
)
:
Query<AppModelType
,
DbModelType
> ;
Creates and returns a new [Query] Query that only returns the first matching documents.
This function returns a new (immutable) instance of the Query (rather than modify the existing instance) to impose the limit.
limit
number
The maximum number of items to return.
let
query
=
firestore
.
collection
(
'col'
).
where
(
'foo'
,
'>'
,
42
);
query
.
limit
(
1
).
get
().
then
(
querySnapshot
=
>
{
querySnapshot
.
forEach
(
documentSnapshot
=
>
{
console
.
log
(
`Found document at
${
documentSnapshot
.
ref
.
path
}
`
);
});
});
limitToLast(limit)
limitToLast
(
limit
:
number
)
:
Query<AppModelType
,
DbModelType
> ;
Creates and returns a new [Query] Query that only returns the last matching documents.
You must specify at least one orderBy clause for limitToLast queries, otherwise an exception will be thrown during execution.
Results for limitToLast queries cannot be streamed via the stream()
API.
limit
number
The maximum number of items to return. The created Query.
let
query
=
firestore
.
collection
(
'col'
).
where
(
'foo'
,
'>'
,
42
);
query
.
limitToLast
(
1
).
get
().
then
(
querySnapshot
=
>
{
querySnapshot
.
forEach
(
documentSnapshot
=
>
{
console
.
log
(
`Last matching document is
${
documentSnapshot
.
ref
.
path
}
`
);
});
});
offset(offset)
offset
(
offset
:
number
)
:
Query<AppModelType
,
DbModelType
> ;
Specifies the offset of the returned results.
This function returns a new (immutable) instance of the [Query] Query (rather than modify the existing instance) to impose the offset.
offset
number
The offset to apply to the Query results
let
query
=
firestore
.
collection
(
'col'
).
where
(
'foo'
,
'>'
,
42
);
query
.
limit
(
10
).
offset
(
20
).
get
().
then
(
querySnapshot
=
>
{
querySnapshot
.
forEach
(
documentSnapshot
=
>
{
console
.
log
(
`Found document at
${
documentSnapshot
.
ref
.
path
}
`
);
});
});
onSnapshot(onNext, onError)
onSnapshot
(
onNext
:
(
snapshot
:
QuerySnapshot<AppModelType
,
DbModelType
> )
=
>
void
,
onError
?:
(
error
:
Error
)
=
>
void
)
:
()
=
>
void
;
Attaches a listener for QuerySnapshot events.
onNext
(snapshot: QuerySnapshot
<AppModelType, DbModelType>) => void
A callback to be called every time a new [QuerySnapshot] QuerySnapshot is available.
onError
(error: Error
) => void
A callback to be called if the listen fails or is cancelled. No further callbacks will occur.
() => void
{function()} An unsubscribe function that can be called to cancel the snapshot listener.
let
query
=
firestore
.
collection
(
'col'
).
where
(
'foo'
,
'=='
,
'bar'
);
let
unsubscribe
=
query
.
onSnapshot
(
querySnapshot
=
>
{
console
.
log
(
`Received query snapshot of size
${
querySnapshot
.
size
}
`
);
},
err
=
>
{
console
.
log
(
`Encountered error:
${
err
}
`
);
});
// Remove this listener.
unsubscribe
();
orderBy(fieldPath, directionStr)
orderBy
(
fieldPath
:
string
|
firestore
.
FieldPath
,
directionStr
?:
firestore
.
OrderByDirection
)
:
Query<AppModelType
,
DbModelType
> ;
Creates and returns a new [Query] Query that's additionally sorted by the specified field, optionally in descending order instead of ascending.
This function returns a new (immutable) instance of the Query (rather than modify the existing instance) to impose the field mask.
fieldPath
string | FirebaseFirestore.FieldPath
The field to sort by.
directionStr
firestore.OrderByDirection
Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending.
let
query
=
firestore
.
collection
(
'col'
).
where
(
'foo'
,
'>'
,
42
);
query
.
orderBy
(
'foo'
,
'desc'
).
get
().
then
(
querySnapshot
=
>
{
querySnapshot
.
forEach
(
documentSnapshot
=
>
{
console
.
log
(
`Found document at
${
documentSnapshot
.
ref
.
path
}
`
);
});
});
select(fieldPaths)
select
(...
fieldPaths
:
Array<string
|
FieldPath
> )
:
Query
;
Creates and returns a new [Query] 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.
Queries that contain field masks cannot be listened to via onSnapshot()
listeners.
This function returns a new (immutable) instance of the Query (rather than modify the existing instance) to impose the field mask.
let
collectionRef
=
firestore
.
collection
(
'col'
);
let
documentRef
=
collectionRef
.
doc
(
'doc'
);
return
documentRef
.
set
({
x
:
10
,
y
:
5
}).
then
(()
=
>
{
return
collectionRef
.
where
(
'x'
,
'>'
,
5
).
select
(
'y'
).
get
();
}).
then
((
res
)
=
>
{
console
.
log
(
`y is
${
res
.
docs
[
0
].
get
(
'y'
)
}
.`
);
});
startAfter(fieldValuesOrDocumentSnapshot)
startAfter
(...
fieldValuesOrDocumentSnapshot
:
Array<unknown>
)
:
Query<AppModelType
,
DbModelType
> ;
Creates and returns a new [Query] Query that starts 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.
fieldValuesOrDocumentSnapshot
Array
<unknown>
The snapshot of the document the query results should start after or the field values to start this query after, in order of the query's order by.
Query
<AppModelType, DbModelType>
{Query} A query with the new starting point.
let
query
=
firestore
.
collection
(
'col'
);
query
.
orderBy
(
'foo'
).
startAfter
(
42
).
get
().
then
(
querySnapshot
=
>
{
querySnapshot
.
forEach
(
documentSnapshot
=
>
{
console
.
log
(
`Found document at
${
documentSnapshot
.
ref
.
path
}
`
);
});
});
startAt(fieldValuesOrDocumentSnapshot)
startAt
(...
fieldValuesOrDocumentSnapshot
:
Array<unknown>
)
:
Query<AppModelType
,
DbModelType
> ;
Creates and returns a new [Query] Query that starts 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.
fieldValuesOrDocumentSnapshot
Array
<unknown>
The snapshot of the document the query results should start at or the field values to start this query at, in order of the query's order by.
Query
<AppModelType, DbModelType>
{Query} A query with the new starting point.
let
query
=
firestore
.
collection
(
'col'
);
query
.
orderBy
(
'foo'
).
startAt
(
42
).
get
().
then
(
querySnapshot
=
>
{
querySnapshot
.
forEach
(
documentSnapshot
=
>
{
console
.
log
(
`Found document at
${
documentSnapshot
.
ref
.
path
}
`
);
});
});
stream()
stream
()
:
NodeJS
.
ReadableStream
;
Executes the query and streams the results as [QueryDocumentSnapshots] QueryDocumentSnapshot .
NodeJS.ReadableStream
{Stream.
let
query
=
firestore
.
collection
(
'col'
).
where
(
'foo'
,
'=='
,
'bar'
);
let
count
=
0
;
query
.
stream
().
on
(
'data'
,
(
documentSnapshot
)
=
>
{
console
.
log
(
`Found document with name '
${
documentSnapshot
.
id
}
'`
);
++
count
;
}).
on
(
'end'
,
()
=
>
{
console
.
log
(
`Total count is
${
count
}
`
);
});
where(fieldPath, opStr, value)
where
(
fieldPath
:
string
|
FieldPath
,
opStr
:
firestore
.
WhereFilterOp
,
value
:
unknown
)
:
Query<AppModelType
,
DbModelType
> ;
Creates and returns a new [Query] Query with the additional filter that documents must contain the specified field and that its value should satisfy the relation constraint provided.
This function returns a new (immutable) instance of the Query (rather than modify the existing instance) to impose the filter.
fieldPath
opStr
firestore.WhereFilterOp
A comparison operation in the form of a string. Acceptable operator strings are "<", "<=", "==", "!=", ">=", ">", "array-contains", "in", "not-in", and "array-contains-any".
value
unknown
The value to which to compare the field for inclusion in a query.
let
collectionRef
=
firestore
.
collection
(
'col'
);
collectionRef
.
where
(
'foo'
,
'=='
,
'bar'
).
get
().
then
(
querySnapshot
=
>
{
querySnapshot
.
forEach
(
documentSnapshot
=
>
{
console
.
log
(
`Found document at
${
documentSnapshot
.
ref
.
path
}
`
);
});
});
where(filter)
where
(
filter
:
Filter
)
:
Query<AppModelType
,
DbModelType
> ;
Creates and returns a new [Query] Query with the additional filter that documents should satisfy the relation constraint(s) provided.
This function returns a new (immutable) instance of the Query (rather than modify the existing instance) to impose the filter.
let
collectionRef
=
firestore
.
collection
(
'col'
);
collectionRef
.
where
(
Filter
.
and
(
Filter
.
where
(
'foo'
,
'=='
,
'bar'
),
Filter
.
where
(
'foo'
,
'!='
,
'baz'
))).
get
()
.
then
(
querySnapshot
=
>
{
querySnapshot
.
forEach
(
documentSnapshot
=
>
{
console
.
log
(
`Found document at
${
documentSnapshot
.
ref
.
path
}
`
);
});
});
withConverter(converter)
withConverter
(
converter
:
null
)
:
Query
;
converter
null
withConverter(converter)
withConverter<NewAppModelType
,
NewDbModelType
extends
firestore
.
DocumentData
=
firestore
.
DocumentData
> (
converter
:
firestore
.
FirestoreDataConverter<NewAppModelType
,
NewDbModelType
> )
:
Query<NewAppModelType
,
NewDbModelType
> ;
converter
FirebaseFirestore.FirestoreDataConverter
<NewAppModelType, NewDbModelType>
NewAppModelType
NewDbModelType
