Firestore API - Class DocumentReference (3.4.0)

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

Namespace

Google.Cloud.Firestore

Assembly

Google.Cloud.Firestore.dll

Properties

Database

public FirestoreDb Database { get; }

The database which contains the document.

Property Value
TypeDescription
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
TypeDescription
string

Parent

public CollectionReference Parent { get; }

The parent collection. Never null.

Property Value
TypeDescription
CollectionReference

Path

public string Path { get; }

The complete document path, including project and database ID.

Property Value
TypeDescription
string

Methods

Collection(string)

public CollectionReference Collection(string path)

Creates a CollectionReference for a child collection of this document.

Parameter
NameDescription
pathstring

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

A CollectionReference for the specified collection.

CompareTo(DocumentReference)

public int CompareTo(DocumentReference other)
Parameter
NameDescription
otherDocumentReference
Returns
TypeDescription
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
NameDescription
documentDataobject

The data for the document. Must not be null.

cancellationTokenCancellationToken

A cancellation token to monitor for the asynchronous operation.

Returns
TypeDescription
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
NameDescription
preconditionPrecondition

Optional precondition for deletion. May be null, in which case the deletion is unconditional.

cancellationTokenCancellationToken

A cancellation token to monitor for the asynchronous operation.

Returns
TypeDescription
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
TypeDescription
int
Overrides

GetSnapshotAsync(CancellationToken)

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

Asynchronously fetches a snapshot of the document.

Parameter
NameDescription
cancellationTokenCancellationToken
Returns
TypeDescription
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
TypeDescription
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
NameDescription
callbackActionDocumentSnapshot

The callback to invoke each time the query results change. Must not be null.

cancellationTokenCancellationToken

Optional cancellation token which may be used to cancel the listening operation.

Returns
TypeDescription
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
NameDescription
callbackFuncDocumentSnapshotCancellationTokenTask

The callback to invoke each time the document changes. Must not be null.

cancellationTokenCancellationToken

Optional cancellation token which may be used to cancel the listening operation.

Returns
TypeDescription
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
NameDescription
documentDataobject

The data to store in the document. Must not be null.

optionsSetOptions

The options to use when updating the document. May be null, which is equivalent to Overwrite.

cancellationTokenCancellationToken

A cancellation token to monitor for the asynchronous operation.

Returns
TypeDescription
TaskWriteResult

The write result of the server operation.

ToString()

public override string ToString()
Returns
TypeDescription
string
Overrides

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
NameDescription
updatesIDictionaryFieldPathobject

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.

preconditionPrecondition

Optional precondition for updating the document. May be null, which is equivalent to MustExist.

cancellationTokenCancellationToken

A cancellation token to monitor for the asynchronous operation.

Returns
TypeDescription
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
NameDescription
updatesIDictionarystringobject

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.

preconditionPrecondition

Optional precondition for updating the document. May be null, which is equivalent to MustExist.

cancellationTokenCancellationToken

A cancellation token to monitor for the asynchronous operation.

Returns
TypeDescription
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
NameDescription
fieldstring

The dot-separated name of the field to update. Must not be null.

valueobject

The new value for the field. May be null.

preconditionPrecondition

Optional precondition for updating the document. May be null, which is equivalent to MustExist.

cancellationTokenCancellationToken

A cancellation token to monitor for the asynchronous operation.

Returns
TypeDescription
TaskWriteResult

The write result of the server operation.