Firestore API - Class DocumentReference (3.4.0)

Version 3.4.0

• 3.9.0 (latest)
• 3.8.0
• 3.7.0
• 3.6.0
• 3.5.1
• 3.4.0
• 3.3.0
• 3.2.0
• 3.1.0
• 3.0.0
• 2.5.0
• 2.4.0
• 2.3.1

public sealed class DocumentReference : IEquatable<DocumentReference>, IComparable<DocumentReference>

Reference documentation and code samples for the Firestore API class DocumentReference.

A reference to a document in a Firestore database. The existence of this object does not imply that the document currently exists in storage.

Inheritance

object > DocumentReference

Implements

IEquatableDocumentReference, IComparableDocumentReference

Inherited Members

object.GetType()

Namespace

Google.Cloud.Firestore

Assembly

Google.Cloud.Firestore.dll

Properties

Database

public FirestoreDb Database { get; }

The database which contains the document.

Property Value
Type	Description
FirestoreDb

Id

public string Id { get; }

The final part of the complete document path; this is the identity of the document relative to its parent collection.

Property Value
Type	Description
string

Parent

public CollectionReference Parent { get; }

The parent collection. Never null.

Property Value
Type	Description
CollectionReference

Path

public string Path { get; }

The complete document path, including project and database ID.

Property Value
Type	Description
string

Methods

Collection(string)

public CollectionReference Collection(string path)

Creates a CollectionReference for a child collection of this document.

Parameter
Name	Description
path	string The path to the collection, relative to this document. Must not be null, and must contain an odd number of slash-separated path elements.

Returns
Type	Description
CollectionReference	A CollectionReference for the specified collection.

CompareTo(DocumentReference)

public int CompareTo(DocumentReference other)

Parameter
Name	Description
other	DocumentReference

Returns
Type	Description
int

CreateAsync(object, CancellationToken)

public Task<WriteResult> CreateAsync(object documentData, CancellationToken cancellationToken = default)

Asynchronously creates a document on the server with the given data. The document must not exist beforehand.

Parameters
Name	Description
documentData	object The data for the document. Must not be null.
cancellationToken	CancellationToken A cancellation token to monitor for the asynchronous operation.

Returns
Type	Description
TaskWriteResult	The write result of the server operation.

DeleteAsync(Precondition, CancellationToken)

public Task<WriteResult> DeleteAsync(Precondition precondition = null, CancellationToken cancellationToken = default)

Asynchronously deletes the document referred to by this path, with an optional precondition.

Parameters
Name	Description
precondition	Precondition Optional precondition for deletion. May be null, in which case the deletion is unconditional.
cancellationToken	CancellationToken A cancellation token to monitor for the asynchronous operation.

Returns
Type	Description
TaskWriteResult	The write result of the server operation.

Remarks

If no precondition is specified and the document doesn't exist, this returned task will succeed. If a precondition is specified and not met, the returned task will fail with an RpcException.

GetHashCode()

public override int GetHashCode()

Returns
Type	Description
int

Overrides

object.GetHashCode()

GetSnapshotAsync(CancellationToken)

public Task<DocumentSnapshot> GetSnapshotAsync(CancellationToken cancellationToken = default)

Asynchronously fetches a snapshot of the document.

Parameter
Name	Description
cancellationToken	CancellationToken

Returns
Type	Description
TaskDocumentSnapshot	A snapshot of the document. The snapshot may represent a missing document.

ListCollectionsAsync()

public IAsyncEnumerable<CollectionReference> ListCollectionsAsync()

Retrieves the collections within this document.

Returns
Type	Description
IAsyncEnumerableCollectionReference	A lazily-iterated sequence of collection references within this document.

Listen(Action<DocumentSnapshot>, CancellationToken)

public FirestoreChangeListener Listen(Action<DocumentSnapshot> callback, CancellationToken cancellationToken = default)

Watch this document for changes. This method is a convenience method over Listen(Func<DocumentSnapshot, CancellationToken, Task>, CancellationToken), wrapping a synchronous callback to create an asynchronous one.

Parameters
Name	Description
callback	ActionDocumentSnapshot The callback to invoke each time the query results change. Must not be null.
cancellationToken	CancellationToken Optional cancellation token which may be used to cancel the listening operation.

Returns
Type	Description
FirestoreChangeListener	A FirestoreChangeListener which may be used to monitor the listening operation and stop it gracefully.

Listen(Func<DocumentSnapshot, CancellationToken, Task>, CancellationToken)

public FirestoreChangeListener Listen(Func<DocumentSnapshot, CancellationToken, Task> callback, CancellationToken cancellationToken = default)

Watch this document for changes.

Parameters
Name	Description
callback	FuncDocumentSnapshotCancellationTokenTask The callback to invoke each time the document changes. Must not be null.
cancellationToken	CancellationToken Optional cancellation token which may be used to cancel the listening operation.

Returns
Type	Description
FirestoreChangeListener	A FirestoreChangeListener which may be used to monitor the listening operation and stop it gracefully.

SetAsync(object, SetOptions, CancellationToken)

public Task<WriteResult> SetAsync(object documentData, SetOptions options = null, CancellationToken cancellationToken = default)

Asynchronously sets data in the document, either replacing it completely or merging fields.

Parameters
Name	Description
documentData	object The data to store in the document. Must not be null.
options	SetOptions The options to use when updating the document. May be null, which is equivalent to Overwrite.
cancellationToken	CancellationToken A cancellation token to monitor for the asynchronous operation.

Returns
Type	Description
TaskWriteResult	The write result of the server operation.

ToString()

public override string ToString()

Returns
Type	Description
string

Overrides

object.ToString()

UpdateAsync(IDictionary<FieldPath, object>, Precondition, CancellationToken)

public Task<WriteResult> UpdateAsync(IDictionary<FieldPath, object> updates, Precondition precondition = null, CancellationToken cancellationToken = default)

Asynchronously performs a set of updates on the document referred to by this path, with an optional precondition.

Parameters
Name	Description
updates	IDictionaryFieldPathobject The updates to perform on the document, keyed by the field path to update. Fields not present in this dictionary are not updated. Must not be null or empty.
precondition	Precondition Optional precondition for updating the document. May be null, which is equivalent to MustExist.
cancellationToken	CancellationToken A cancellation token to monitor for the asynchronous operation.

Returns
Type	Description
TaskWriteResult	The write result of the server operation.

UpdateAsync(IDictionary<string, object>, Precondition, CancellationToken)

public Task<WriteResult> UpdateAsync(IDictionary<string, object> updates, Precondition precondition = null, CancellationToken cancellationToken = default)

Asynchronously performs a set of updates on the document referred to by this path, with an optional precondition.

Parameters
Name	Description
updates	IDictionarystringobject The updates to perform on the document, keyed by the dot-separated field path to update. Fields not present in this dictionary are not updated. Must not be null or empty.
precondition	Precondition Optional precondition for updating the document. May be null, which is equivalent to MustExist.
cancellationToken	CancellationToken A cancellation token to monitor for the asynchronous operation.

Returns
Type	Description
TaskWriteResult	The write result of the server operation.

UpdateAsync(string, object, Precondition, CancellationToken)

public Task<WriteResult> UpdateAsync(string field, object value, Precondition precondition = null, CancellationToken cancellationToken = default)

Asynchronously performs a single field update on the document referred to by this path, with an optional precondition.

Parameters
Name	Description
field	string The dot-separated name of the field to update. Must not be null.
value	object The new value for the field. May be null.
precondition	Precondition Optional precondition for updating the document. May be null, which is equivalent to MustExist.
cancellationToken	CancellationToken A cancellation token to monitor for the asynchronous operation.

Returns
Type	Description
TaskWriteResult	The write result of the server operation.