ACollectionReference object can be used for adding documents, gettingdocument references, and querying for documents (using the methodsinherited fromQuery).

Type parameters

  • T

Index

Constructors

Private constructor

Properties

firestore

firestore:Firestore

Inherited fromQuery.firestore

TheFirestore for the Firestore database (useful for performingtransactions, etc.).

id

id:string

The collection's identifier.

parent

A reference to the containingDocumentReference if this is a subcollection.If this isn't a subcollection, the reference is null.

path

path:string

A string representing the path of the referenced collection (relativeto the root of the database).

Methods

add

  • add(data: T):Promise<DocumentReference<T>>

  • Add a new document to this collection with the specified data, assigningit a document ID automatically.

    Parameters

    • data:T

      An Object containing the data for the new document.

    ReturnsPromise<DocumentReference<T>>

    A Promise resolved with aDocumentReference pointing to thenewly created document after it has been written to the backend.

doc

  • doc(documentPath?: string):DocumentReference<T>

  • Get aDocumentReference for the document within the collection at thespecified path. If no path is specified, an automatically-generatedunique ID will be used for the returned DocumentReference.

    Parameters

    • Optional documentPath:string

      A slash-separated path to a document.

    ReturnsDocumentReference<T>

    TheDocumentReference instance.

endAt

  • endAt(snapshot: DocumentSnapshot<any>):Query<T>

  • Inherited fromQuery.endAt

    Creates and returns a new Query that ends at the provided document(inclusive). The end position is relative to the order of the query. Thedocument must contain all of the fields provided in the orderBy of thisquery.

    Parameters

    ReturnsQuery<T>

    The created Query.

  • endAt(...fieldValues: any[]):Query<T>

  • Inherited fromQuery.endAt

    Creates and returns a new Query that ends at the provided fieldsrelative to the order of the query. The order of the field valuesmust match the order of the order by clauses of the query.

    Parameters

    • Rest...fieldValues:any[]

      The field values to end this query at, in orderof the query's order by.

    ReturnsQuery<T>

    The created Query.

endBefore

  • endBefore(snapshot: DocumentSnapshot<any>):Query<T>

  • Inherited fromQuery.endBefore

    Creates and returns a new Query that ends before the provided document(exclusive). The end position is relative to the order of the query. Thedocument must contain all of the fields provided in the orderBy of thisquery.

    Parameters

    ReturnsQuery<T>

    The created Query.

  • endBefore(...fieldValues: any[]):Query<T>

  • Inherited fromQuery.endBefore

    Creates and returns a new Query that ends before the provided fieldsrelative to the order of the query. The order of the field valuesmust match the order of the order by clauses of the query.

    Parameters

    • Rest...fieldValues:any[]

      The field values to end this query before, in orderof the query's order by.

    ReturnsQuery<T>

    The created Query.

get

  • get(options?: GetOptions):Promise<QuerySnapshot<T>>

  • Inherited fromQuery.get

    Executes the query and returns the results as aQuerySnapshot.

    Note: By default, get() attempts to provide up-to-date data when possibleby waiting for data from the server, but it may return cached data or failif you are offline and the server cannot be reached. This behavior can bealtered via theGetOptions parameter.

    Parameters

    • Optional options:GetOptions

      An object to configure the get behavior.

    ReturnsPromise<QuerySnapshot<T>>

    A Promise that will be resolved with the results of the Query.

isEqual

limit

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

  • Inherited fromQuery.limit

    Creates and returns a new Query that only returns the first matchingdocuments.

    Parameters

    • limit:number

      The maximum number of items to return.

    ReturnsQuery<T>

    The created Query.

limitToLast

  • limitToLast(limit: number):Query<T>

  • Inherited fromQuery.limitToLast

    Creates and returns a new Query that only returns the last matchingdocuments.

    You must specify at least oneorderBy clause forlimitToLast queries,otherwise an exception will be thrown during execution.

    Parameters

    • limit:number

      The maximum number of items to return.

    ReturnsQuery<T>

    The created Query.

onSnapshot

  • onSnapshot(observer: {complete?:() =>void;error?:(error: FirestoreError) =>void;next?:(snapshot: QuerySnapshot<T>) =>void }):() =>void

  • Inherited fromQuery.onSnapshot

    Attaches a listener for QuerySnapshot events. You may either passindividualonNext andonError callbacks or pass a single observerobject withnext anderror callbacks. The listener can be cancelled bycalling the function that is returned whenonSnapshot is called.

    NOTE: Although anonCompletion callback can be provided, it willnever be called because the snapshot stream is never-ending.

    Parameters

    Returns() =>void

    An unsubscribe function that can be called to cancelthe snapshot listener.

      • ():void

      • Returnsvoid

  • onSnapshot(options: SnapshotListenOptions, observer: {complete?:() =>void;error?:(error: FirestoreError) =>void;next?:(snapshot: QuerySnapshot<T>) =>void }):() =>void

  • Inherited fromQuery.onSnapshot

    Attaches a listener for QuerySnapshot events. You may either passindividualonNext andonError callbacks or pass a single observerobject withnext anderror callbacks. The listener can be cancelled bycalling the function that is returned whenonSnapshot is called.

    NOTE: Although anonCompletion callback can be provided, it willnever be called because the snapshot stream is never-ending.

    Parameters

    Returns() =>void

    An unsubscribe function that can be called to cancelthe snapshot listener.

      • ():void

      • Returnsvoid

  • onSnapshot(onNext: (snapshot: QuerySnapshot<T>) =>void, onError?: (error: FirestoreError) =>void, onCompletion?: () =>void):() =>void

  • Inherited fromQuery.onSnapshot

    Attaches a listener for QuerySnapshot events. You may either passindividualonNext andonError callbacks or pass a single observerobject withnext anderror callbacks. The listener can be cancelled bycalling the function that is returned whenonSnapshot is called.

    NOTE: Although anonCompletion callback can be provided, it willnever be called because the snapshot stream is never-ending.

    Parameters

    • onNext:(snapshot:QuerySnapshot<T>) =>void

      A callback to be called every time a newQuerySnapshotis available.

    • Optional onError:(error:FirestoreError) =>void

      A callback to be called if the listen fails or iscancelled. No further callbacks will occur.

    • Optional onCompletion:() =>void
        • ():void

        • Returnsvoid

    Returns() =>void

    An unsubscribe function that can be called to cancelthe snapshot listener.

      • ():void

      • Returnsvoid

  • onSnapshot(options: SnapshotListenOptions, onNext: (snapshot: QuerySnapshot<T>) =>void, onError?: (error: FirestoreError) =>void, onCompletion?: () =>void):() =>void

  • Inherited fromQuery.onSnapshot

    Attaches a listener for QuerySnapshot events. You may either passindividualonNext andonError callbacks or pass a single observerobject withnext anderror callbacks. The listener can be cancelled bycalling the function that is returned whenonSnapshot is called.

    NOTE: Although anonCompletion callback can be provided, it willnever be called because the snapshot stream is never-ending.

    Parameters

    Returns() =>void

    An unsubscribe function that can be called to cancelthe snapshot listener.

      • ():void

      • Returnsvoid

orderBy

  • orderBy(fieldPath: string |FieldPath, directionStr?: OrderByDirection):Query<T>

  • Inherited fromQuery.orderBy

    Creates and returns a new Query that's additionally sorted by thespecified field, optionally in descending order instead of ascending.

    Parameters

    • fieldPath:string |FieldPath

      The field to sort by.

    • Optional directionStr:OrderByDirection

      Optional direction to sort by (asc ordesc). Ifnot specified, order will be ascending.

    ReturnsQuery<T>

    The created Query.

startAfter

  • startAfter(snapshot: DocumentSnapshot<any>):Query<T>

  • Inherited fromQuery.startAfter

    Creates and returns a new Query that starts after the provided document(exclusive). The starting position is relative to the order of the query.The document must contain all of the fields provided in the orderBy ofthis query.

    Parameters

    ReturnsQuery<T>

    The created Query.

  • startAfter(...fieldValues: any[]):Query<T>

  • Inherited fromQuery.startAfter

    Creates and returns a new Query that starts after the provided fieldsrelative to the order of the query. The order of the field valuesmust match the order of the order by clauses of the query.

    Parameters

    • Rest...fieldValues:any[]

      The field values to start this query after, in orderof the query's order by.

    ReturnsQuery<T>

    The created Query.

startAt

  • startAt(snapshot: DocumentSnapshot<any>):Query<T>

  • Inherited fromQuery.startAt

    Creates and returns a new Query that starts at the provided document(inclusive). The starting position is relative to the order of the query.The document must contain all of the fields provided in theorderBy ofthis query.

    Parameters

    ReturnsQuery<T>

    The created Query.

  • startAt(...fieldValues: any[]):Query<T>

  • Inherited fromQuery.startAt

    Creates and returns a new Query that starts at the provided fieldsrelative to the order of the query. The order of the field valuesmust match the order of the order by clauses of the query.

    Parameters

    • Rest...fieldValues:any[]

      The field values to start this query at, in orderof the query's order by.

    ReturnsQuery<T>

    The created Query.

where

  • where(fieldPath: string |FieldPath, opStr: WhereFilterOp, value: any):Query<T>

  • Inherited fromQuery.where

    Creates and returns a new Query with the additional filter that documentsmust contain the specified field and the value should satisfy therelation constraint provided.

    Parameters

    • fieldPath:string |FieldPath

      The path to compare

    • opStr:WhereFilterOp

      The operation string (e.g "<", "<=", "==", ">", ">=").

    • value:any

      The value for comparison

    ReturnsQuery<T>

    The created Query.

withConverter

  • withConverter(converter: null):CollectionReference<DocumentData>

  • OverridesQuery.withConverter

    Applies a custom data converter to this CollectionReference, allowing youto use your own custom model objects with Firestore. When you call add()on the returned CollectionReference instance, the provided converter willconvert between Firestore data and your custom type U.

    Passing innull as the converter parameter removes the currentconverter.

    Parameters

    • converter:null

      Converts objects to and from Firestore. Passing innull removes the current converter.

    ReturnsCollectionReference<DocumentData>

    A CollectionReference that uses the provided converter.

  • withConverter<U>(converter: FirestoreDataConverter<U>):CollectionReference<U>

  • OverridesQuery.withConverter

    Applies a custom data converter to this CollectionReference, allowing youto use your own custom model objects with Firestore. When you call add()on the returned CollectionReference instance, the provided converter willconvert between Firestore data and your custom type U.

    Passing innull as the converter parameter removes the currentconverter.

    Type parameters

    • U

    Parameters

    • converter:FirestoreDataConverter<U>

      Converts objects to and from Firestore. Passing innull removes the current converter.

    ReturnsCollectionReference<U>

    A CollectionReference that uses the provided converter.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2022-07-27 UTC.