Class DocumentSnapshot (2.9.0)

DocumentSnapshot(reference, data, exists, read_time, create_time, update_time)

A snapshot of document data in a Firestore database.

This represents data retrieved at a specific time and may not contain all fields stored for the document (i.e. a hand-picked selection of fields may have been retrieved).

Instances of this class are not intended to be constructed by hand, rather they'll be returned as responses to various methods, such as xref_get.

Parameters

Name	Description
`reference`	`DocumentReference` A document reference corresponding to the document that contains the data in this snapshot.
`data`	`Dict[str, Any]` The data retrieved in the snapshot.
`exists`	`bool` Indicates if the document existed at the time the snapshot was retrieved.
`read_time`	`proto.datetime_helpers.DatetimeWithNanoseconds` The time that this snapshot was read from the server.
`create_time`	`proto.datetime_helpers.DatetimeWithNanoseconds` The time that this document was created.
`update_time`	`proto.datetime_helpers.DatetimeWithNanoseconds` The time that this document was last updated.

Properties

exists

Existence flag.

Indicates if the document existed at the time this snapshot was retrieved.

Returns

Type	Description
`bool`	The existence flag.

id

The document identifier (within its collection).

Returns

Type	Description
`str`	The last component of the path of the document.

reference

Document reference corresponding to document that owns this data.

Returns

Type	Description
`DocumentReference`	A document reference corresponding to this document.

Methods

get

get(field_path: str)

Get a value from the snapshot data.

If the data is nested, for example:

>>> snapshot.to_dict()
{
    'top1': {
        'middle2': {
            'bottom3': 20,
            'bottom4': 22,
        },
        'middle5': True,
    },
    'top6': b'  foo',
}

a field path can be used to access the nested data. For example:

>>> snapshot.get('top1')
{
    'middle2': {
        'bottom3': 20,
        'bottom4': 22,
    },
    'middle5': True,
}
>>> snapshot.get('top1.middle2')
{
    'bottom3': 20,
    'bottom4': 22,
}
>>> snapshot.get('top1.middle2.bottom3')
20

See xref_field_path for more information on field paths.

A copy is returned since the data may contain mutable values, but the data stored in the snapshot must remain immutable.

Parameter

Name	Description
`field_path`	`str` A field path (`.`-delimited list of field names).

Exceptions

Type	Description
`KeyError`	If the `field_path` does not match nested data in the snapshot.

Returns

Type	Description
`Any or None`	(A copy of) the value stored for the `field_path` or None if snapshot document does not exist.

to_dict

to_dict()

Retrieve the data contained in this snapshot.

A copy is returned since the data may contain mutable values, but the data stored in the snapshot must remain immutable.

Returns

Type	Description
`Dict[str, Any] or None`	The data in the snapshot. Returns None if reference does not exist.