Firestore API - Class DocumentReference (3.5.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

Implements

IEquatable DocumentReference, IComparable DocumentReference

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)

Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object.

Parameter
Name	Description
`other`	`DocumentReference` An object to compare with this instance.

Returns

Type Description

int

A value that indicates the relative order of the objects being compared. The return value has these meanings:
Value

Meaning

Less than zero

This instance precedes other in the sort order.

Zero

This instance occurs in the same position in the sort order as other.

Greater than zero

This instance follows other in the sort order.

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

Serves as the default hash function.

Returns
Type	Description
`int`	A hash code for the current object.

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 a string that represents the current object.

Returns
Type	Description
`string`	A string that represents the current object.

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.