Class DocumentReference (2.5.0) 

public sealed class DocumentReference : IEquatable<DocumentReference>, IComparable<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

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
Int32

CreateAsync(Object, CancellationToken)

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

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
Task<WriteResult>

The write result of the server operation.

DeleteAsync(Precondition, CancellationToken)

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

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
Task<WriteResult>

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
Int32
Overrides

GetSnapshotAsync(CancellationToken)

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

Asynchronously fetches a snapshot of the document.

Parameter
Name Description
cancellationToken CancellationToken
Returns
Type Description
Task<DocumentSnapshot>

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
IAsyncEnumerable<CollectionReference>

A lazily-iterated sequence of collection references within this document.

Listen(Action<DocumentSnapshot>, CancellationToken)

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

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 Action<DocumentSnapshot>

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(CancellationToken))

Watch this document for changes.

Parameters
Name Description
callback Func<DocumentSnapshot, CancellationToken, Task>

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(CancellationToken))

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
Task<WriteResult>

The write result of the server operation.

ToString()

public override string ToString()
Returns
Type Description
String
Overrides

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

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

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

Parameters
Name Description
updates IDictionary<FieldPath, Object>

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
Task<WriteResult>

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(CancellationToken))

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

Parameters
Name Description
updates IDictionary<String, Object>

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
Task<WriteResult>

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(CancellationToken))

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
Task<WriteResult>

The write result of the server operation.