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
| Name | Description |
| _firestore | Firestore
The Firestore Database client. |
| _queryOptions | QueryOptions
<T>
Options that define the query. |
Properties
_allowUndefined
protected
readonly
_allowUndefined
:
boolean
;
| Type | Description |
|---|---|
| boolean |
_firestore
readonly
_firestore
:
Firestore
;
| Type | Description |
|---|---|
| Firestore |
_queryOptions
protected
readonly
_queryOptions
:
QueryOptions<T>
;
| Type | Description |
|---|---|
| QueryOptions <T> |
firestore
get
firestore
()
:
Firestore
;
The [Firestore] Firestore instance for the Firestore database (useful for performing transactions, etc.).
{Firestore} Query#firestore
| Type | Description |
|---|---|
| Firestore |
Methods
_extractFieldValues(documentSnapshot, fieldOrders)
static
_extractFieldValues
(
documentSnapshot
:
DocumentSnapshot
,
fieldOrders
:
FieldOrder
[])
:
unknown
[];
Extracts field values from the DocumentSnapshot based on the provided field order.
| Name | Description |
| documentSnapshot | DocumentSnapshot
The document to extract the fields from. |
| fieldOrders | FieldOrder
[]
The field order that defines what fields we should extract. {Array.<*>} The field values to use. |
| Type | Description |
|---|---|
| unknown[] |
_get(transactionId)
_get
(
transactionId
?:
Uint8Array
)
:
Promise<QuerySnapshot<T>
> ;
Internal get() method that accepts an optional transaction id.
| Name | Description |
| transactionId | Uint8Array
A transaction ID. |
| Type | Description |
|---|---|
| Promise < QuerySnapshot <T>> |
_stream(transactionId)
_stream
(
transactionId
?:
Uint8Array
)
:
NodeJS
.
ReadableStream
;
Internal streaming method that accepts an optional transaction ID.
| Name | Description |
| transactionId | Uint8Array
A transaction ID. |
| Type | Description |
| NodeJS.ReadableStream | A stream of document results. |
_toBundledQuery()
_toBundledQuery
()
:
protos
.
firestore
.
IBundledQuery
;
Converts current Query to an IBundledQuery.
| Type | Description |
|---|---|
| protos. firestore.IBundledQuery |
comparator()
comparator
()
:
(
s1
:
QueryDocumentSnapshot<T>
,
s2
:
QueryDocumentSnapshot<T>
)
=
>
number
;
Returns a function that can be used to sort QueryDocumentSnapshots according to the sort criteria of this query.
| Type | Description |
|---|---|
| (s1: QueryDocumentSnapshot <T>, s2: QueryDocumentSnapshot <T>) => 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.
| Name | Description |
| 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. |
| Type | Description |
| Query <T> | {Query} A query with the new ending point. |
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.
| Name | Description |
| 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. |
| Type | Description |
| Query <T> | {Query} A query with the new ending point. |
get()
get
()
:
Promise<QuerySnapshot<T>
> ;
Executes the query and returns the results as a [QuerySnapshot] QuerySnapshot .
| Type | Description |
|---|---|
| Promise < QuerySnapshot <T>> | {Promise. |
isEqual(other)
isEqual
(
other
:
firestore
.
Query<T>
)
:
boolean
;
Returns true if this Query
is equal to the provided value.
| Name | Description |
| other | FirebaseFirestore.Query
<T>
The value to compare against. {boolean} true if this |
| Type | Description |
|---|---|
| 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.
| Name | Description |
| limit | number
The maximum number of items to return. |
| Type | Description |
|---|---|
| Query <T> | {Query} The created Query. |
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.
| Name | Description |
| limit | number
The maximum number of items to return. The created Query. |
| Type | Description |
|---|---|
| Query <T> |
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.
| Name | Description |
| offset | number
The offset to apply to the Query results |
| Type | Description |
|---|---|
| Query <T> | {Query} The created Query. |
onSnapshot(onNext, onError)
onSnapshot
(
onNext
:
(
snapshot
:
firestore
.
QuerySnapshot<T>
)
=
>
void
,
onError
?:
(
error
:
Error
)
=
>
void
)
:
()
=
>
void
;
Attaches a listener for QuerySnapshot events.
| Name | Description |
| 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. |
| Type | Description |
| () => void | {function()} An unsubscribe function that can be called to cancel the snapshot listener. |
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.
| 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. |
| Type | Description |
|---|---|
| Query <T> | {Query} The created Query. |
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.
| Name | Description |
| fieldPaths | Array
<string | FieldPath
>
The field paths to return. |
| Type | Description |
|---|---|
| Query < FirebaseFirestore.DocumentData > | {Query} The created Query. |
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.
| Name | Description |
| 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. |
| Type | Description |
| Query <T> | {Query} A query with the new starting point. |
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.
| Name | Description |
| 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. |
| Type | Description |
| Query <T> | {Query} A query with the new starting point. |
stream()
stream
()
:
NodeJS
.
ReadableStream
;
Executes the query and streams the results as [QueryDocumentSnapshots] QueryDocumentSnapshot .
| Type | Description |
|---|---|
| NodeJS.ReadableStream | {Stream. |
toProto(transactionIdOrReadTime)
toProto
(
transactionIdOrReadTime
?:
Uint8Array
|
Timestamp
)
:
api
.
IRunQueryRequest
;
Internal method for serializing a query to its RunQuery proto representation with an optional transaction id or read time.
| Name | Description |
| transactionIdOrReadTime | Uint8Array
| Timestamp
A transaction ID or the read time at which to execute the query. |
| Type | Description |
| api.IRunQueryRequest | Serialized JSON for the query. |
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.
| Name | Description |
| 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. |
| Type | Description |
|---|---|
| Query <T> | {Query} The created Query. |
withConverter(converter)
withConverter
(
converter
:
null
)
:
Query<firestore
.
DocumentData
> ;
Applies a custom data converter to this Query, allowing you to use your own custom model objects with Firestore. When you call get() on the returned Query, the provided converter will convert between Firestore data and your custom type U.
Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore.
Passing in null
as the converter parameter removes the current converter.
| Name | Description |
| converter | null
Converts objects to and from Firestore. Passing in
|
| Type | Description |
|---|---|
| Query < FirebaseFirestore.DocumentData > |
withConverter(converter)
withConverter<U>
(
converter
:
firestore
.
FirestoreDataConverter<U>
)
:
Query<U>
;
| Name | Description |
| converter | FirebaseFirestore.FirestoreDataConverter
<U>
|
| Type | Description |
|---|---|
| Query <U> |
| Name | Description |
|---|---|
| U |
