message  Send Feedback

DocumentReference

A DocumentReference refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. A DocumentReference can also be used to create a CollectionReference to a subcollection.

Properties

Methods


Properties

firestore

firestore: Module;

The Firestore instance the document is in. This is useful for performing transactions, for example.


id

id: string;

The document's identifier within its collection.


parent

parent: CollectionReference;

The Collection this DocumentReference belongs to.


path

path: string;

A string representing the path of the referenced document (relative to the root of the database).


Methods

collection

collection(
  collectionPath: string
): CollectionReference;

Gets a CollectionReference instance that refers to the collection at the specified path.

Example

const collectionRef = firebase.firestore().doc('users/alovelace').collection('orders');

Parameters

  • collectionPath: string
    A slash-separated path to a collection.

delete

delete(): Promise<void>;

Deletes the document referred to by this DocumentReference.

Example

await firebase.firestore().doc('users/alovelace').delete();

The Promise is resolved once the document has been successfully deleted from the backend (Note that it won't resolve while you're offline).


get

get(
  options?: GetOptions
): Promise<DocumentSnapshot>;

Reads the document referred to by this DocumentReference.

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

await firebase.firestore().doc('users/alovelace').get({
source: 'server',
});

Parameters

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

isEqual

isEqual(
  other: DocumentReference
): boolean;

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

Example

const alovelace = firebase.firestore().doc('users/alovelace');
const dsmith = firebase.firestore().doc('users/dsmith');
// false
alovelace.isEqual(dsmith);
``
@param other The `DocumentReference` to compare against.

Parameters


onSnapshot

Signature:

onSnapshot(
  observer: 
): () => void;

Attaches a listener for DocumentSnapshot events.

NOTE: Although an complete 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().doc('users/alovelace')
.onSnapshot({
error: (e) => console.error(e),
next: (documentSnapshot) => {},
});
unsubscribe();

Parameters

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


Signature:

onSnapshot(
  options: SnapshotListenOptions,
  observer: 
): () => void;

Attaches a listener for DocumentSnapshot events with snapshot listener options.

NOTE: Although an complete 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().doc('users/alovelace')
.onSnapshot({
includeMetadataChanges: true,
}, {
error: (e) => console.error(e),
next: (documentSnapshot) => {},
});
unsubscribe();

Parameters

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


Signature:

onSnapshot(
  onNext: (snapshot: DocumentSnapshot) => void,
  onError?: undefined | (error: Error) => void,
  onCompletion?: undefined | () => void
): () => void;

Attaches a listener for DocumentSnapshot events.

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().doc('users/alovelace')
.onSnapshot(
(documentSnapshot) => {}, // onNext
(error) => console.error(error), // onError
);
unsubscribe();

Parameters

  • onNext: (snapshot: DocumentSnapshot) => void
    A callback to be called every time a new `DocumentSnapshot` 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: (snapshot: DocumentSnapshot) => void,
  onError?: undefined | (error: Error) => void,
  onCompletion?: undefined | () => void
): () => void;

Attaches a listener for DocumentSnapshot 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().doc('users/alovelace')
.onSnapshot(
{ includeMetadataChanges: true }, // SnapshotListenerOptions
(documentSnapshot) => {}, // onNext
(error) => console.error(error), // onError
);
unsubscribe();

Parameters

  • options: SnapshotListenOptions
    Options controlling the listen behavior.
  • onNext: (snapshot: DocumentSnapshot) => void
    A callback to be called every time a new `DocumentSnapshot` 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.

set

set(
  data: { [key: string]: value },
  options?: SetOptions
): Promise<void>;

Writes to the document referred to by this DocumentReference. If the document does not yet exist, it will be created. If you pass SetOptions, the provided data can be merged into an existing document.

Example

const user = firebase.firestore().doc('users/alovelace');
// Set new data
await user.set({
name: 'Ada Lovelace',
age: 30,
city: 'LON',
});
``
@param data A map of the fields and values for the document.
@param options An object to configure the set behavior.

Parameters


update

Signature:

update(
  data: { [key: string]: value }
): Promise<void>;

Updates fields in the document referred to by this DocumentReference. The update will fail if applied to a document that does not exist.

Example

const user = firebase.firestore().doc('users/alovelace');

// Update age but leave other fields untouched
await user.update({
  age: 31,
});

Parameters

  • data: { [key: string]: value }
    An object containing the fields and values with which to update the document. Fields can contain dots to reference nested fields within the document.


Signature:

update(
  field: string | FieldPath,
  value: any,
  moreFieldsAndValues: any[]
): Promise<void>;

Updates fields in the document referred to by this DocumentReference. The update will fail if applied to a document that does not exist.

Example

const user = firebase.firestore().doc('users/alovelace');

// Update age & city but leve other fields untouched
await user.update('age', 31, 'city', 'SF');

Parameters

  • field: string | FieldPath
    The first field to update.
  • value: any
    The first value.
  • moreFieldsAndValues: any[]
    Additional key value pairs.

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