Class AsyncDocumentReference (2.14.0)

A reference to a document in a Firestore database.

The document may already exist or can be created by this class.

List subcollections of the current document.

Create the current document in the Firestore database.

Delete the current document in the Firestore database.

Retrieve a snapshot of the current document.

See xref_field_path for more information on field paths.

If a transaction is used and it already has write operations added, this method cannot be used (i.e. read-after-write is not allowed).

Replace the current document in the Firestore database.

A write option can be specified to indicate preconditions of the "set" operation. If no option is specified and this document doesn't exist yet, this method will create it.

Overwrites all content for the document with the fields in document_data. This method performs almost the same functionality as create. The only difference is that this method doesn't make any requirements on the existence of the document (unless option is used), whereas as create will fail if the document already exists.

Update an existing document in the Firestore database.

By default, this method verifies that the document exists on the server before making updates. A write option can be specified to override these preconditions.

Each key in field_updates can either be a field name or a field path (For more information on field paths, see xref_field_path.) To illustrate this, consider a document with

>>> snapshot = await document.get()
>>> snapshot.to_dict()
{
    'foo': {
        'bar': 'baz',
    },
    'other': True,
}

stored on the server. If the field name is used in the update:

>>> field_updates = {
...     'foo': {
...         'quux': 800,
...     },
... }
>>> await document.update(field_updates)

then all of foo will be overwritten on the server and the new value will be

>>> snapshot = await document.get()
>>> snapshot.to_dict()
{
    'foo': {
        'quux': 800,
    },
    'other': True,
}

On the other hand, if a .-delimited field path is used in the update:

>>> field_updates = {
...     'foo.quux': 800,
... }
>>> await document.update(field_updates)

then only foo.quux will be updated on the server and the field foo.bar will remain intact:

>>> snapshot = await document.get()
>>> snapshot.to_dict()
{
    'foo': {
        'bar': 'baz',
        'quux': 800,
    },
    'other': True,
}

>>> field_updates = {
...     'other': firestore.DELETE_FIELD,
... }
>>> await document.update(field_updates)

would update the value on the server to:

>>> snapshot = await document.get()
>>> snapshot.to_dict()
{
    'foo': {
        'bar': 'baz',
    },
}

To set a field to the current time on the server when the update is received, use the xref_SERVER_TIMESTAMP sentinel. Sending

>>> field_updates = {
...     'foo.now': firestore.SERVER_TIMESTAMP,
... }
>>> await document.update(field_updates)

would update the value on the server to:

>>> snapshot = await document.get()
>>> snapshot.to_dict()
{
    'foo': {
        'bar': 'baz',
        'now': datetime.datetime(2012, ...),
    },
    'other': True,
}