firebase::firestore::DocumentReference

#include <document_reference.h>

ADocumentReference refers to a document location in aFirestore database and can be used to write, read, or listen to the location.

Summary

There may or may not exist a document at the referenced location. ADocumentReference can also be used to create aCollectionReference to a subcollection.

Create aDocumentReference viaFirestore::Document(const std::string& path).

Note: Firestore classes are not meant to be subclassed except for use in test mocks. Subclassing is not supported in production code and new SDK releases may break code that does so.

Constructors and Destructors

DocumentReference()
Creates an invalidDocumentReference that has to be reassigned before it can be used.
DocumentReference(constDocumentReference & other)
Copy constructor.
DocumentReference(DocumentReference && other)
Move constructor.
~DocumentReference()

Friend classes

operator<<
friend std::ostream &
Outputs the string representation of thisDocumentReference to the given stream.

Public functions

AddSnapshotListener(std::function< void(constDocumentSnapshot &,Error, const std::string &)> callback)
Starts listening to the document referenced by thisDocumentReference.
AddSnapshotListener(MetadataChanges metadata_changes, std::function< void(constDocumentSnapshot &,Error, const std::string &)> callback)
Starts listening to the document referenced by thisDocumentReference.
Collection(const char *collection_path) const
Returns aCollectionReference instance that refers to the subcollection at the specified path relative to this document.
Collection(const std::string & collection_path) const
Returns aCollectionReference instance that refers to the subcollection at the specified path relative to this document.
Delete()
virtualFuture< void >
Removes the document referred to by thisDocumentReference.
Get(Source source) const
Reads the document referenced by thisDocumentReference.
Parent() const
Returns aCollectionReference to the collection that contains this document.
Set(constMapFieldValue & data, constSetOptions & options)
virtualFuture< void >
Writes to the document referred to by thisDocumentReference.
ToString() const
std::string
Returns a string representation of thisDocumentReference for logging/debugging purposes.
Update(constMapFieldValue & data)
virtualFuture< void >
Updates fields in the document referred to by thisDocumentReference.
Update(constMapFieldPathValue & data)
virtualFuture< void >
Updates fields in the document referred to by thisDocumentReference.
firestore() const
virtual constFirestore *
Returns theFirestore instance associated with this document reference.
firestore()
virtualFirestore *
Returns theFirestore instance associated with this document reference.
id() const
virtual const std::string &
Returns the string ID of this document location.
is_valid() const
bool
Returns true if thisDocumentReference is valid, false if it is not valid.
operator=(constDocumentReference & other)
Copy assignment operator.
operator=(DocumentReference && other)
Move assignment operator.
path() const
virtual std::string
Returns the path of this document (relative to the root of the database) as a slash-separated string.

Friend classes

operator<<

friendstd::ostream&operator<<(std::ostream&out,constDocumentReference&reference)

Outputs the string representation of thisDocumentReference to the given stream.

See also:ToString() for comments on the representation format.

Public functions

AddSnapshotListener

virtualListenerRegistrationAddSnapshotListener(std::function<void(constDocumentSnapshot&,Error,conststd::string&)>callback)

Starts listening to the document referenced by thisDocumentReference.

Details
Parameters
callback
The std::function to call. When this function is called, snapshot value is valid if and only if error is Error::kErrorOk. The std::string is an error message; the value may be empty if an error message is not available.
Returns
A registration object that can be used to remove the listener.

AddSnapshotListener

virtualListenerRegistrationAddSnapshotListener(MetadataChangesmetadata_changes,std::function<void(constDocumentSnapshot&,Error,conststd::string&)>callback)

Starts listening to the document referenced by thisDocumentReference.

Details
Parameters
metadata_changes
Indicates whether metadata-only changes (that is, onlyDocumentSnapshot::metadata() changed) should trigger snapshot events.
callback
The std::function to call. When this function is called, snapshot value is valid if and only if error is Error::kErrorOk. The std::string is an error message; the value may be empty if an error message is not available.
Returns
A registration object that can be used to remove the listener.

Collection

virtualCollectionReferenceCollection(constchar*collection_path)const

Returns aCollectionReference instance that refers to the subcollection at the specified path relative to this document.

Details
Parameters
collection_path
A slash-separated relative path to a subcollection. The pointer only needs to be valid during this call.
Returns
TheCollectionReference instance.

Collection

virtualCollectionReferenceCollection(conststd::string&collection_path)const

Returns aCollectionReference instance that refers to the subcollection at the specified path relative to this document.

Details
Parameters
collection_path
A slash-separated relative path to a subcollection.
Returns
TheCollectionReference instance.

Delete

virtualFuture<void>Delete()

Removes the document referred to by thisDocumentReference.

Details
Returns
AFuture that will be resolved when the delete completes.

DocumentReference

DocumentReference()

Creates an invalidDocumentReference that has to be reassigned before it can be used.

Calling any member function on an invalidDocumentReference will be a no-op. If the function returns a value, it will return a zero, empty, or invalid value, depending on the type of the value.

DocumentReference

DocumentReference(constDocumentReference&other)

Copy constructor.

DocumentReference can be efficiently copied because it simply refers to a location in the database.

Details
Parameters
other
DocumentReference to copy from.

DocumentReference

DocumentReference(DocumentReference&&other)

Move constructor.

Moving is more efficient than copying for aDocumentReference. After being moved from, aDocumentReference is equivalent to its default-constructed state.

Details
Parameters
other
DocumentReference to move data from.

Get

virtualFuture<DocumentSnapshot>Get(Sourcesource)const

Reads the document referenced by thisDocumentReference.

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 Source parameter.

Details
Parameters
source
A value to configure the get behavior (optional).
Returns
AFuture that will be resolved with the contents of the Document at thisDocumentReference.

Parent

virtualCollectionReferenceParent()const

Returns aCollectionReference to the collection that contains this document.

Set

virtualFuture<void>Set(constMapFieldValue&data,constSetOptions&options)

Writes to the document referred to by thisDocumentReference.

If the document does not yet exist, it will be created. If you passSetOptions, the provided data can be merged into an existing document.

Details
Parameters
data
A map of the fields and values to write to the document.
options
An object to configure theSet() behavior (optional).
Returns
AFuture that will be resolved when the write finishes.

ToString

std::stringToString()const

Update

virtualFuture<void>Update(constMapFieldValue&data)

Updates fields in the document referred to by thisDocumentReference.

If no document exists yet, the update will fail.

Details
Parameters
data
A map of field / value pairs to update. Fields can contain dots to reference nested fields within the document.
Returns
AFuture that will be resolved when the client is online and the commit has completed against the server. The future will not resolve when the device is offline, though local changes will be visible immediately.

Update

virtualFuture<void>Update(constMapFieldPathValue&data)

Updates fields in the document referred to by thisDocumentReference.

If no document exists yet, the update will fail.

Details
Parameters
data
A map fromFieldPath toFieldValue to update.
Returns
AFuture that will be resolved when the client is online and the commit has completed against the server. The future will not resolve when the device is offline, though local changes will be visible immediately.

firestore

virtualconstFirestore*firestore()const

Returns theFirestore instance associated with this document reference.

The pointer will remain valid indefinitely.

Details
Returns
FirebaseFirestore instance that thisDocumentReference refers to.

firestore

virtualFirestore*firestore()

Returns theFirestore instance associated with this document reference.

The pointer will remain valid indefinitely.

Details
Returns
FirebaseFirestore instance that thisDocumentReference refers to.

id

virtualconststd::string&id()const

Returns the string ID of this document location.

Details
Returns
String ID of this document location.

is_valid

boolis_valid()const

Returns true if thisDocumentReference is valid, false if it is not valid.

An invalidDocumentReference could be the result of:

Details
Returns
true if thisDocumentReference is valid, false if thisDocumentReference is invalid.

operator=

DocumentReference&operator=(constDocumentReference&other)

Copy assignment operator.

DocumentReference can be efficiently copied because it simply refers to a location in the database.

Details
Parameters
other
DocumentReference to copy from.
Returns
Reference to the destinationDocumentReference.

operator=

DocumentReference&operator=(DocumentReference&&other)

Move assignment operator.

Moving is more efficient than copying for aDocumentReference. After being moved from, aDocumentReference is equivalent to its default-constructed state.

Details
Parameters
other
DocumentReference to move data from.
Returns
Reference to the destinationDocumentReference.

path

virtualstd::stringpath()const

Returns the path of this document (relative to the root of the database) as a slash-separated string.

Details
Returns
String path of this document location.

~DocumentReference

virtual~DocumentReference()

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 2024-01-23 UTC.