Class DocumentSnapshot (2.17.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) -> typing.Any

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() -> typing.Optional[typing.Dict[str, typing.Any]]

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.