Class Query (6.4.1)

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/firestore

Constructors

(constructor)(_firestore, _queryOptions)

constructor(
    _firestore: Firestore, 
    _queryOptions: QueryOptions<T>);

Constructs a new instance of the Query class

Parameters
NameDescription
_firestore Firestore

The Firestore Database client.

_queryOptions QueryOptions<T>

Options that define the query.

Properties

_allowUndefined

protected readonly _allowUndefined: boolean;

_firestore

readonly _firestore: Firestore;

_queryOptions

protected readonly _queryOptions: QueryOptions<T>;

firestore

get firestore(): Firestore;

The [Firestore]Firestore instance for the Firestore database (useful for performing transactions, etc.).

{Firestore} Query#firestore

Example 

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

count()

count(): AggregateQuery<{
        count: firestore.AggregateField<number>;
    }>;

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 even count the documents if the result set would be prohibitively large to download entirely (e.g. 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
TypeDescription
AggregateQuery<{ count: FirebaseFirestore.AggregateField<number>; }>

endAt(fieldValuesOrDocumentSnapshot)

endAt(...fieldValuesOrDocumentSnapshot: Array<firestore.DocumentSnapshot<unknown> | unknown>): Query<T>;

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
NameDescription
fieldValuesOrDocumentSnapshot Array<FirebaseFirestore.DocumentSnapshot<unknown> | 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
TypeDescription
Query<T>

{Query} A query with the new ending point.

Example 

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<firestore.DocumentSnapshot<unknown> | unknown>): Query<T>;

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
NameDescription
fieldValuesOrDocumentSnapshot Array<FirebaseFirestore.DocumentSnapshot<unknown> | 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
TypeDescription
Query<T>

{Query} A query with the new ending point.

Example 

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

Executes the query and returns the results as a [QuerySnapshot]QuerySnapshot.

Returns
TypeDescription
Promise<QuerySnapshot<T>>

{Promise.

Example 

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<T>): boolean;

Returns true if this Query is equal to the provided value.

Parameter
NameDescription
other FirebaseFirestore.Query<T>

The value to compare against. {boolean} true if this Query is equal to the provided value.

Returns
TypeDescription
boolean

limit(limit)

limit(limit: number): Query<T>;

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
NameDescription
limit number

The maximum number of items to return.

Returns
TypeDescription
Query<T>

{Query} The created Query.

Example 

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

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
NameDescription
limit number

The maximum number of items to return. The created Query.

Returns
TypeDescription
Query<T>
Example 

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

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
NameDescription
offset number

The offset to apply to the Query results

Returns
TypeDescription
Query<T>

{Query} The created Query.

Example 

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: firestore.QuerySnapshot<T>) => void, onError?: (error: Error) => void): () => void;

Attaches a listener for QuerySnapshot events.

Parameters
NameDescription
onNext (snapshot: FirebaseFirestore.QuerySnapshot<T>) => 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
TypeDescription
() => void

{function()} An unsubscribe function that can be called to cancel the snapshot listener.

Example 

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

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
NameDescription
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
TypeDescription
Query<T>

{Query} The created Query.

Example 

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<firestore.DocumentData>;

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
NameDescription
fieldPaths Array<string | FieldPath>

The field paths to return.

Returns
TypeDescription
Query<FirebaseFirestore.DocumentData>

{Query} The created Query.

Example 

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<firestore.DocumentSnapshot<unknown> | unknown>): Query<T>;

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
NameDescription
fieldValuesOrDocumentSnapshot Array<FirebaseFirestore.DocumentSnapshot<unknown> | 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
TypeDescription
Query<T>

{Query} A query with the new starting point.

Example 

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<firestore.DocumentSnapshot<unknown> | unknown>): Query<T>;

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
NameDescription
fieldValuesOrDocumentSnapshot Array<FirebaseFirestore.DocumentSnapshot<unknown> | 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
TypeDescription
Query<T>

{Query} A query with the new starting point.

Example 

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
TypeDescription
NodeJS.ReadableStream

{Stream.

Example 

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 | firestore.FieldPath, opStr: firestore.WhereFilterOp, value: unknown): Query<T>;

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.

Returns a new Query that constrains the value of a Document property.

This function returns a new (immutable) instance of the Query (rather than modify the existing instance) to impose the filter.

Parameters
NameDescription
fieldPath string | FirebaseFirestore.FieldPath

The name of a property value to compare.

opStr firestore.WhereFilterOp

A comparison operation in the form of a string (e.g., "<").

value unknown

The value to which to compare the field for inclusion in a query.

Returns
TypeDescription
Query<T>

{Query} The created Query.

Example 

let collectionRef = firestore.collection('col');

collectionRef.where('foo', '==', 'bar').get().then(querySnapshot => {
  querySnapshot.forEach(documentSnapshot => {
    console.log(`Found document at ${documentSnapshot.ref.path}`);
  });
});

withConverter(converter)

withConverter(converter: null): Query<firestore.DocumentData>;
Parameter
NameDescription
converter null
Returns
TypeDescription
Query<FirebaseFirestore.DocumentData>

withConverter(converter)

withConverter<U>(converter: firestore.FirestoreDataConverter<U>): Query<U>;
Parameter
NameDescription
converter FirebaseFirestore.FirestoreDataConverter<U>
Returns
TypeDescription
Query<U>
Type Parameter
NameDescription
U