message  Send Feedback

CollectionReference

A CollectionReference object can be used for adding documents, getting document references, and querying for documents (using the methods inherited from Query).

Properties

Methods


Properties

id

id: string;

The collection's identifier.


parent

parent: DocumentReference | null;

A reference to the containing DocumentReference 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 (relative to the root of the database).


Methods

add

add(
  data: { [key: string]: value }
): Promise<DocumentReference>;

Add a new document to this collection with the specified data, assigning it a document ID automatically.

Example

const documentRef = await firebase.firestore().collection('users').add({
name: 'Ada Lovelace',
age: 30,
});

Parameters

  • data: { [key: string]: value }
    An Object containing the data for the new document.

doc

doc(
  documentPath?: undefined | string
): DocumentReference;

Get a DocumentReference for the document within the collection at the specified path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference.

Example

await firebase.firestore().collection('users').doc('alovelace').set({
name: 'Ada Lovelace',
age: 30,
});

Parameters

  • documentPath: (optional) undefined | string
    A slash-separated path to a document.

endAt

Signature:

endAt(
  snapshot: DocumentSnapshot
): Query;
keyboard_return Inherited from 
Query.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. The document must contain all of the fields provided in the orderBy of this query.

Example

const user = await firebase.firestore().doc('users/alovelace').get();
// Get all users up to a specific user in order of age
const querySnapshot = await firebase.firestore()
.collection('users')
.orderBy('age')
.endAt(user);

Cursor snapshot queries have limitations. Please see Query limitations for more information.

Parameters



Signature:

endAt(
  fieldValues: any[]
): Query;
keyboard_return Inherited from 
Query.endAt

Creates and returns a new Query that ends at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.

Example

// Get all users who's age is 30 or less
const querySnapshot = await firebase.firestore()
.collection('users')
.orderBy('age')
.endAt(30);

Parameters

  • fieldValues: any[]
    The field values to end this query at, in order of the query's order by.

endBefore

Signature:

endBefore(
  snapshot: DocumentSnapshot
): Query;
keyboard_return Inherited from 
Query.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. The document must contain all of the fields provided in the orderBy of this query.

Example

const user = await firebase.firestore().doc('users/alovelace').get();
// Get all users up to, but not including, a specific user in order of age
const querySnapshot = await firebase.firestore()
.collection('users')
.orderBy('age')
.endBefore(user);

Cursor snapshot queries have limitations. Please see Query limitations for more information.

Parameters



Signature:

endBefore(
  fieldValues: any[]
): Query;
keyboard_return Inherited from 
Query.endBefore

Creates and returns a new Query that ends before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.

Example

// Get all users who's age is 29 or less
const querySnapshot = await firebase.firestore()
.collection('users')
.orderBy('age')
.endBefore(30);

Parameters

  • fieldValues: any[]
    The field values to end this query before, in order of the query's order by.

get

get(
  options?: GetOptions
): Promise<QuerySnapshot>;
keyboard_return Inherited from 
Query.get

Executes the query and returns the results as a QuerySnapshot.

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

Example

const querySnapshot = await firebase.firestore()
.collection('users')
.orderBy('age')
.get({
source: 'server',
});

Parameters

  • options: (optional) GetOptions
    An object to configure the get behavior.

isEqual

isEqual(
  other: Query
): boolean;
keyboard_return Inherited from 
Query.isEqual

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

Example

const query = firebase.firestore()
.collection('users')
.orderBy('age');
// false
query.isEqual(
firebase.firestore()
.collection('users')
.orderBy('name')
);

Parameters

  • other: Query
    The `Query` to compare against.

limit

limit(
  limit: number
): Query;
keyboard_return Inherited from 
Query.limit

Creates and returns a new Query where the results are limited to the specified number of documents.

Example

// Get 10 users in order of age
const querySnapshot = firebase.firestore()
.collection('users')
.orderBy('age')
.limit(10)
.get();

Parameters

  • limit: number
    The maximum number of items to return.

onSnapshot

Signature:

onSnapshot(
  observer: 
): () => void;
keyboard_return Inherited from 
Query.onSnapshot

Attaches a listener for QuerySnapshot events.

Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.

Returns an unsubscribe function to stop listening to events.

Example

const unsubscribe = firebase.firestore().collection('users')
.onSnapshot({
error: (e) => console.error(e),
next: (querySnapshot) => {},
});
unsubscribe();

Parameters

  • observer:
    A single object containing `next` and `error` callbacks.


Signature:

onSnapshot(
  options: SnapshotListenOptions,
  observer: 
): () => void;
keyboard_return Inherited from 
Query.onSnapshot

Attaches a listener for QuerySnapshot events with snapshot listener options.

Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.

Returns an unsubscribe function to stop listening to events.

Example

const unsubscribe = firebase.firestore().collection('users')
.onSnapshot({
includeMetadataChanges: true,
}, {
error: (e) => console.error(e),
next: (querySnapshot) => {},
});
unsubscribe();

Parameters

  • options: SnapshotListenOptions
    Options controlling the listen behavior.
  • observer:
    A single object containing `next` and `error` callbacks.


Signature:

onSnapshot(
  onNext: (snapshot: QuerySnapshot) => void,
  onError?: undefined | (error: Error) => void,
  onCompletion?: undefined | () => void
): () => void;
keyboard_return Inherited from 
Query.onSnapshot

Attaches a listener for QuerySnapshot events.

Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.

Returns an unsubscribe function to stop listening to events.

Example

const unsubscribe = firebase.firestore().collection('users')
.onSnapshot(
(querySnapshot) => {}, // onNext
(error) => console.error(error), // onError
);
unsubscribe();

Parameters

  • onNext: (snapshot: QuerySnapshot) => void
    A callback to be called every time a new `QuerySnapshot` is available.
  • onError: (optional) undefined | (error: Error) => void
    A callback to be called if the listen fails or is cancelled. No further callbacks will occur.
  • onCompletion: (optional) undefined | () => void
    An optional function which will never be called.


Signature:

onSnapshot(
  options: SnapshotListenOptions,
  onNext: Function,
  onError?: Function,
  onCompletion?: Function
): () => void;
keyboard_return Inherited from 
Query.onSnapshot

Attaches a listener for QuerySnapshot events with snapshot listener options.

NOTE: Although an onCompletion callback can be provided, it will never be called because the snapshot stream is never-ending.

Returns an unsubscribe function to stop listening to events.

Example

const unsubscribe = firebase.firestore().collection('users')
.onSnapshot(
{ includeMetadataChanges: true }, // SnapshotListenerOptions
(querySnapshot) => {}, // onNext
(error) => console.error(error), // onError
);
unsubscribe();

Parameters

  • options: SnapshotListenOptions
    Options controlling the listen behavior.
  • onNext: Function
    A callback to be called every time a new `QuerySnapshot` is available.
  • onError: (optional) Function
    A callback to be called if the listen fails or is cancelled. No further callbacks will occur.
  • onCompletion: (optional) Function
    An optional function which will never be called.

orderBy

orderBy(
  fieldPath: string | FieldPath,
  directionStr?: 'asc' | 'desc'
): Query;
keyboard_return Inherited from 
Query.orderBy

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

  • Example

Example

// Get users in order of age, descending
const querySnapshot = firebase.firestore()
.collection('users')
.orderBy('age', 'desc')
.get();

Parameters

  • fieldPath: string | FieldPath
    The field to sort by. Either a string or FieldPath instance.
  • directionStr: (optional) 'asc' | 'desc'
    Optional direction to sort by (`asc` or `desc`). If not specified, order will be ascending.

startAfter

Signature:

startAfter(
  snapshot: DocumentSnapshot
): Query;
keyboard_return Inherited from 
Query.startAfter

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

Example

const user = await firebase.firestore().doc('users/alovelace').get();
// Get all users up to, but not including, a specific user in order of age
const querySnapshot = await firebase.firestore()
.collection('users')
.orderBy('age')
.startAfter(user)
.get();

Cursor snapshot queries have limitations. Please see Query limitations for more information.

Parameters



Signature:

startAfter(
  fieldValues: any[]
): Query;
keyboard_return Inherited from 
Query.startAfter

Creates and returns a new Query that starts after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.

Example

// Get all users who's age is above 30
const querySnapshot = await firebase.firestore()
.collection('users')
.orderBy('age')
.startAfter(30)
.get();

Parameters

  • fieldValues: any[]
    The field values to start this query after, in order of the query's order by.

startAt

Signature:

startAt(
  snapshot: DocumentSnapshot
): Query;
keyboard_return Inherited from 
Query.startAt

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

Example

const user = await firebase.firestore().doc('users/alovelace').get();
// Get all users up to a specific user in order of age
const querySnapshot = await firebase.firestore()
.collection('users')
.orderBy('age')
.startAt(user)
.get();

Cursor snapshot queries have limitations. Please see Query limitations for more information.

Parameters



Signature:

startAt(
  fieldValues: any[]
): Query;
keyboard_return Inherited from 
Query.startAt

Creates and returns a new Query that starts at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query.

Example

// Get all users who's age is 30 or above
const querySnapshot = await firebase.firestore()
.collection('users')
.orderBy('age')
.startAt(30)
.get();

Parameters

  • fieldValues: any[]
    The field values to start this query at, in order of the query's order by.

where

where(
  fieldPath: string | FieldPath,
  opStr: WhereFilterOp,
  value: any
): Query;
keyboard_return Inherited from 
Query.where

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

Example

// Get all users who's age is 30 or above
const querySnapshot = await firebase.firestore()
.collection('users')
.where('age', '>=', 30);
.get();

Parameters

  • fieldPath: string | FieldPath
    The path to compare.
  • opStr: WhereFilterOp
    The operation string (e.g "<", "<=", "==", ">", ">=", "array-contains").
  • value: any
    The comparison value.

React Native Market

Looking for pre-built React Native apps to kick start your next project? Check out the React Native Market by Invertase.

Your purchases help support our open-source projects such as React Native Firebase. All items are currently 50% off to celebrate the release of React Native Firebase version 6.
shopping_cartVisit React Native Market