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

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.