Class DocumentReference (2.17.2)

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 a document in the Firestore database.

document_data = {"a": 1, "b": {"c": "Two"}} document.get().to_dict() is None # does not exist True document.create(document_data) document.get().to_dict() == document_data # exists True

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

Watch this document.

This starts a watch on this document using a background thread. The provided callback is run on the snapshot.

Create / replace / merge a document in the Firestore database.

• To "upsert" a document (create if it doesn't exist, replace completely if it does), leave the merge argument at its default:

  document_data = {"a": 1, "b": {"c": "Two"}} document.get().to_dict() is None # document exists False document.set(document_data) document.get().to_dict() == document_data # exists True

• To "merge" document_data with an existing document (creating if the document does not exist), pass merge as True`:

  document_data = {"a": 1, "b": {"c": "Two"}} document.get().to_dict() == {"d": "Three", "b": {}} # exists document.set(document_data, merge=True) document.get().to_dict() == {"a": 1, "d": "Three", "b": {"c": "Two"}} True

  In this case, existing documents with top-level keys which are not present in document_data ("d") will preserve the values of those keys.

• To merge only specific fields of document_data with existing documents (creating if the document does not exist), pass merge as a list of field paths:

document_data = {"a": 1, "b": {"c": "Two"}} document.get().to_dict() == {"b": {"c": "One", "d": "Four" }} # exists True document.set(document_data, merge=["b.c"]) document.get().to_dict() == {"b": {"c": "Two", "d": "Four" }} True

For more information on field paths, see xref_field_path.

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 = 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,
...     },
... }
>>> document.update(field_updates)

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

>>> snapshot = 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,
... }
>>> document.update(field_updates)

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

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

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

would update the value on the server to:

>>> snapshot = 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,
... }
>>> document.update(field_updates)

would update the value on the server to:

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