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/firestoreConstructors
(constructor)(_firestore, _queryOptions)
constructor(
_firestore: Firestore,
_queryOptions: QueryOptions<AppModelType, DbModelType>);
Constructs a new instance of the Query
class
Parameters | |
---|---|
Name | Description |
_firestore |
Firestore
The Firestore Database client. |
_queryOptions |
QueryOptions<AppModelType, DbModelType>
Options that define the query. |
Properties
_allowUndefined
protected readonly _allowUndefined: boolean;
_firestore
readonly _firestore: Firestore;
_queryOptions
protected readonly _queryOptions: QueryOptions<AppModelType, DbModelType>;
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
_hasRetryTimedOut(methodName, startTime)
_hasRetryTimedOut(methodName: string, startTime: number): boolean;
Parameters | |
---|---|
Name | Description |
methodName |
string
|
startTime |
number
|
Returns | |
---|---|
Type | Description |
boolean |
_isPermanentRpcError(err, methodName)
_isPermanentRpcError(err: GoogleError, methodName: string): boolean;
Parameters | |
---|---|
Name | Description |
err |
GoogleError
|
methodName |
string
|
Returns | |
---|---|
Type | Description |
boolean |
_parseCompositeFilter(compositeFilterData)
_parseCompositeFilter(compositeFilterData: CompositeFilter): FilterInternal;
Parameter | |
---|---|
Name | Description |
compositeFilterData |
CompositeFilter
|
Returns | |
---|---|
Type | Description |
FilterInternal |
_parseFieldFilter(fieldFilterData)
_parseFieldFilter(fieldFilterData: UnaryFilter): FieldFilterInternal;
Parameter | |
---|---|
Name | Description |
fieldFilterData |
UnaryFilter
|
Returns | |
---|---|
Type | Description |
FieldFilterInternal |
_parseFilter(filter)
_parseFilter(filter: Filter): FilterInternal;
Parameter | |
---|---|
Name | Description |
filter |
Filter
|
Returns | |
---|---|
Type | Description |
FilterInternal |
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).
Parameter | |
---|---|
Name | Description |
aggregateSpec |
T
An |
Returns | |
---|---|
Type | Description |
AggregateQuery<T, AppModelType, DbModelType> |
Type Parameter | |
---|---|
Name | Description |
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.
Returns | |
---|---|
Type | Description |
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.
Parameter | |
---|---|
Name | Description |
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. |
Returns | |
---|---|
Type | Description |
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.
Parameter | |
---|---|
Name | Description |
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. |
Returns | |
---|---|
Type | Description |
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.
Returns | |
---|---|
Type | Description |
Promise<QuerySnapshot<AppModelType, DbModelType>> | {Promise.
|
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.
Parameter | |
---|---|
Name | Description |
other |
FirebaseFirestore.Query<AppModelType, DbModelType>
The value to compare against. {boolean} true if this |
Returns | |
---|---|
Type | Description |
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.
Parameter | |
---|---|
Name | Description |
limit |
number
The maximum number of items to return. |
Returns | |
---|---|
Type | Description |
Query<AppModelType, DbModelType> | {Query} The created Query. |
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.
Parameter | |
---|---|
Name | Description |
limit |
number
The maximum number of items to return. The created Query. |
Returns | |
---|---|
Type | Description |
Query<AppModelType, DbModelType> |
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.
Parameter | |
---|---|
Name | Description |
offset |
number
The offset to apply to the Query results |
Returns | |
---|---|
Type | Description |
Query<AppModelType, DbModelType> | {Query} The created Query. |
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.
Parameters | |
---|---|
Name | Description |
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. |
Returns | |
---|---|
Type | Description |
() => 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.
Parameters | |
---|---|
Name | Description |
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. |
Returns | |
---|---|
Type | Description |
Query<AppModelType, DbModelType> | {Query} The created Query. |
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.
Parameter | |
---|---|
Name | Description |
fieldPaths |
Array<string | FieldPath>
The field paths to return. |
Returns | |
---|---|
Type | Description |
Query | {Query} The created Query. |
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.
Parameter | |
---|---|
Name | Description |
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. |
Returns | |
---|---|
Type | Description |
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.
Parameter | |
---|---|
Name | Description |
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. |
Returns | |
---|---|
Type | Description |
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.
Returns | |
---|---|
Type | Description |
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.
Parameters | |
---|---|
Name | Description |
fieldPath |
string | FieldPath
The name of a property value to compare. |
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. |
Returns | |
---|---|
Type | Description |
Query<AppModelType, DbModelType> | {Query} The created 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.
Parameter | |
---|---|
Name | Description |
filter |
Filter
A unary or composite filter to apply to the Query. |
Returns | |
---|---|
Type | Description |
Query<AppModelType, DbModelType> | {Query} The created Query. |
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;
Parameter | |
---|---|
Name | Description |
converter |
null
|
Returns | |
---|---|
Type | Description |
Query |
withConverter(converter)
withConverter<NewAppModelType, NewDbModelType extends firestore.DocumentData = firestore.DocumentData>(converter: firestore.FirestoreDataConverter<NewAppModelType, NewDbModelType>): Query<NewAppModelType, NewDbModelType>;
Parameter | |
---|---|
Name | Description |
converter |
FirebaseFirestore.FirestoreDataConverter<NewAppModelType, NewDbModelType>
|
Returns | |
---|---|
Type | Description |
Query<NewAppModelType, NewDbModelType> |
Type Parameters | |
---|---|
Name | Description |
NewAppModelType | |
NewDbModelType |