DocumentSnapshot

public class DocumentSnapshot

Known direct subclasses
QueryDocumentSnapshot

A QueryDocumentSnapshot contains data read from a document in your Cloud Firestore database as part of a query.


A DocumentSnapshot contains data read from a document in your Cloud Firestore database. The data can be extracted with the getData or get methods.

If the DocumentSnapshot points to a non-existing document, getData and its corresponding methods will return null. You can always explicitly check for a document's existence by calling exists.

Subclassing Note: Cloud Firestore classes are not meant to be subclassed except for use in test mocks. Subclassing is not supported in production code and new SDK releases may break code that does so.

Summary

Nested types

Controls the return value for server timestamps that have not yet been set to their final value.

Public fields

final SnapshotMetadata

Public methods

boolean

Returns whether or not the field exists in the document.

boolean

Returns whether or not the field exists in the document.

boolean
boolean
@Nullable Object
get(@NonNull String field)

Returns the value at the field or null if the field doesn't exist.

@Nullable Object
get(@NonNull FieldPath fieldPath)

Returns the value at the field or null if the field or document doesn't exist.

@Nullable Object
get(
    @NonNull String field,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field or null if the field doesn't exist.

@Nullable T
<T> get(@NonNull String field, @NonNull Class<T> valueType)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

@Nullable Object
get(
    @NonNull FieldPath fieldPath,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field or null if the field or document doesn't exist.

@Nullable T
<T> get(@NonNull FieldPath fieldPath, @NonNull Class<T> valueType)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

@Nullable T
<T> get(
    @NonNull String field,
    @NonNull Class<T> valueType,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

@Nullable T
<T> get(
    @NonNull FieldPath fieldPath,
    @NonNull Class<T> valueType,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

@Nullable Blob

Returns the value of the field as a Blob.

@Nullable Boolean

Returns the value of the field as a boolean.

@Nullable Map<StringObject>

Returns the fields of the document as a Map or null if the document doesn't exist.

@Nullable Map<StringObject>
getData(
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the fields of the document as a Map or null if the document doesn't exist.

@Nullable Date

Returns the value of the field as a Date.

@Nullable Date
getDate(
    @NonNull String field,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value of the field as a Date.

@Nullable DocumentReference

Returns the value of the field as a DocumentReference.

@Nullable Double

Returns the value of the field as a double.

@Nullable GeoPoint

Returns the value of the field as a GeoPoint.

@NonNull String
@Nullable Long

Returns the value of the field as a long.

@NonNull SnapshotMetadata
@NonNull DocumentReference

Gets the reference to the document.

@Nullable String

Returns the value of the field as a String.

@Nullable Timestamp

Returns the value of the field as a com.google.firebase.Timestamp.

@Nullable Timestamp
getTimestamp(
    @NonNull String field,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value of the field as a com.google.firebase.Timestamp.

int
@Nullable T
<T> toObject(@NonNull Class<T> valueType)

Returns the contents of the document converted to a POJO or null if the document doesn't exist.

@Nullable T
<T> toObject(
    @NonNull Class<T> valueType,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the contents of the document converted to a POJO or null if the document doesn't exist.

String

Extension functions

final T
<T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull String field
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

final T
<T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull String field,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

final T
<T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull FieldPath fieldPath
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

final T
<T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull FieldPath fieldPath,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

final T
<T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull String field
)

This method is deprecated. Migrate to use the KTX API from the main module: https://firebase.google.com/docs/android/kotlin-migration.

final T
<T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull String field,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

This method is deprecated. Migrate to use the KTX API from the main module: https://firebase.google.com/docs/android/kotlin-migration.

final T
<T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull FieldPath fieldPath
)

This method is deprecated. Migrate to use the KTX API from the main module: https://firebase.google.com/docs/android/kotlin-migration.

final T
<T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull FieldPath fieldPath,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

This method is deprecated. Migrate to use the KTX API from the main module: https://firebase.google.com/docs/android/kotlin-migration.

final T

Returns the contents of the document converted to a POJO or null if the document doesn't exist.

final T
<T extends Object> FirestoreKt.toObject(
    @NonNull DocumentSnapshot receiver,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the contents of the document converted to a POJO or null if the document doesn't exist.

final T

This method is deprecated. Migrate to use the KTX API from the main module: https://firebase.google.com/docs/android/kotlin-migration.

final T
<T extends Object> FirestoreKt.toObject(
    @NonNull DocumentSnapshot receiver,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

This method is deprecated. Migrate to use the KTX API from the main module: https://firebase.google.com/docs/android/kotlin-migration.

Public fields

metadata

public final SnapshotMetadata metadata

Public methods

contains

public boolean contains(@NonNull String field)

Returns whether or not the field exists in the document. Returns false if the document does not exist.

Parameters
@NonNull String field

the path to the field.

Returns
boolean

true iff the field exists.

contains

public boolean contains(@NonNull FieldPath fieldPath)

Returns whether or not the field exists in the document. Returns false if the document does not exist.

Parameters
@NonNull FieldPath fieldPath

the path to the field.

Returns
boolean

true iff the field exists.

equals

public boolean equals(@Nullable Object obj)

exists

public boolean exists()
Returns
boolean

true if the document existed in this snapshot.

get

public @Nullable Object get(@NonNull String field)

Returns the value at the field or null if the field doesn't exist.

Parameters
@NonNull String field

The path to the field

Returns
@Nullable Object

The value at the given field or null.

get

public @Nullable Object get(@NonNull FieldPath fieldPath)

Returns the value at the field or null if the field or document doesn't exist.

Parameters
@NonNull FieldPath fieldPath

The path to the field

Returns
@Nullable Object

The value at the given field or null.

get

public @Nullable Object get(
    @NonNull String field,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field or null if the field doesn't exist.

Parameters
@NonNull String field

The path to the field

@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet been set to their final value.

Returns
@Nullable Object

The value at the given field or null.

get

public @Nullable T <T> get(@NonNull String field, @NonNull Class<T> valueType)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

Parameters
@NonNull String field

The path to the field

@NonNull Class<T> valueType

The Java class to convert the field value to.

Returns
@Nullable T

The value at the given field or null.

get

public @Nullable Object get(
    @NonNull FieldPath fieldPath,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field or null if the field or document doesn't exist.

Parameters
@NonNull FieldPath fieldPath

The path to the field

@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet been set to their final value.

Returns
@Nullable Object

The value at the given field or null.

get

public @Nullable T <T> get(@NonNull FieldPath fieldPath, @NonNull Class<T> valueType)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

Parameters
@NonNull FieldPath fieldPath

The path to the field

@NonNull Class<T> valueType

The Java class to convert the field value to.

Returns
@Nullable T

The value at the given field or null.

get

public @Nullable T <T> get(
    @NonNull String field,
    @NonNull Class<T> valueType,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

Parameters
@NonNull String field

The path to the field

@NonNull Class<T> valueType

The Java class to convert the field value to.

@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet been set to their final value.

Returns
@Nullable T

The value at the given field or null.

get

public @Nullable T <T> get(
    @NonNull FieldPath fieldPath,
    @NonNull Class<T> valueType,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

Parameters
@NonNull FieldPath fieldPath

The path to the field

@NonNull Class<T> valueType

The Java class to convert the field value to.

@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet been set to their final value.

Returns
@Nullable T

The value at the given field or null.

getBlob

public @Nullable Blob getBlob(@NonNull String field)

Returns the value of the field as a Blob.

Parameters
@NonNull String field

The path to the field.

Returns
@Nullable Blob

The value of the field

Throws
java.lang.RuntimeException java.lang.RuntimeException

if the value is not a Blob.

getBoolean

public @Nullable Boolean getBoolean(@NonNull String field)

Returns the value of the field as a boolean. If the value is not a boolean this will throw a runtime exception.

Parameters
@NonNull String field

The path to the field.

Returns
@Nullable Boolean

The value of the field

getData

public @Nullable Map<StringObjectgetData()

Returns the fields of the document as a Map or null if the document doesn't exist. Field values will be converted to their native Java representation.

Returns
@Nullable Map<StringObject>

The fields of the document as a Map or null if the document doesn't exist.

getData

public @Nullable Map<StringObjectgetData(
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the fields of the document as a Map or null if the document doesn't exist. Field values will be converted to their native Java representation.

Parameters
@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet been set to their final value.

Returns
@Nullable Map<StringObject>

The fields of the document as a Map or null if the document doesn't exist.

getDate

public @Nullable Date getDate(@NonNull String field)

Returns the value of the field as a Date.

Parameters
@NonNull String field

The path to the field.

Returns
@Nullable Date

The value of the field

Throws
java.lang.RuntimeException java.lang.RuntimeException

if the value is not a Date.

getDate

public @Nullable Date getDate(
    @NonNull String field,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value of the field as a Date.

Parameters
@NonNull String field

The path to the field.

@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet been set to their final value.

Returns
@Nullable Date

The value of the field

Throws
java.lang.RuntimeException java.lang.RuntimeException

if the value is not a Date.

getDocumentReference

public @Nullable DocumentReference getDocumentReference(@NonNull String field)

Returns the value of the field as a DocumentReference.

Parameters
@NonNull String field

The path to the field.

Returns
@Nullable DocumentReference

The value of the field

Throws
java.lang.RuntimeException java.lang.RuntimeException

if the value is not a DocumentReference.

getDouble

public @Nullable Double getDouble(@NonNull String field)

Returns the value of the field as a double.

Parameters
@NonNull String field

The path to the field.

Returns
@Nullable Double

The value of the field

Throws
java.lang.RuntimeException java.lang.RuntimeException

if the value is not a number.

getGeoPoint

public @Nullable GeoPoint getGeoPoint(@NonNull String field)

Returns the value of the field as a GeoPoint.

Parameters
@NonNull String field

The path to the field.

Returns
@Nullable GeoPoint

The value of the field

Throws
java.lang.RuntimeException java.lang.RuntimeException

if the value is not a GeoPoint.

getId

public @NonNull String getId()
Returns
@NonNull String

The id of the document.

getLong

public @Nullable Long getLong(@NonNull String field)

Returns the value of the field as a long.

Parameters
@NonNull String field

The path to the field.

Returns
@Nullable Long

The value of the field

Throws
java.lang.RuntimeException java.lang.RuntimeException

if the value is not a number.

getMetadata

public @NonNull SnapshotMetadata getMetadata()
Returns
@NonNull SnapshotMetadata

The metadata for this document snapshot.

getReference

public @NonNull DocumentReference getReference()

Gets the reference to the document.

Returns
@NonNull DocumentReference

The reference to the document.

getString

public @Nullable String getString(@NonNull String field)

Returns the value of the field as a String.

Parameters
@NonNull String field

The path to the field.

Returns
@Nullable String

The value of the field

Throws
java.lang.RuntimeException java.lang.RuntimeException

if the value is not a String.

getTimestamp

public @Nullable Timestamp getTimestamp(@NonNull String field)

Returns the value of the field as a com.google.firebase.Timestamp.

Parameters
@NonNull String field

The path to the field.

Returns
@Nullable Timestamp

The value of the field

Throws
java.lang.RuntimeException java.lang.RuntimeException

if this is not a timestamp field.

getTimestamp

public @Nullable Timestamp getTimestamp(
    @NonNull String field,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value of the field as a com.google.firebase.Timestamp.

Parameters
@NonNull String field

The path to the field.

@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet been set to their final value.

Returns
@Nullable Timestamp

The value of the field

Throws
java.lang.RuntimeException java.lang.RuntimeException

if the value is not a timestamp field.

hashCode

public int hashCode()

toObject

public @Nullable T <T> toObject(@NonNull Class<T> valueType)

Returns the contents of the document converted to a POJO or null if the document doesn't exist.

Parameters
@NonNull Class<T> valueType

The Java class to create

Returns
@Nullable T

The contents of the document in an object of type T or null if the document doesn't exist.

toObject

public @Nullable T <T> toObject(
    @NonNull Class<T> valueType,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the contents of the document converted to a POJO or null if the document doesn't exist.

Parameters
@NonNull Class<T> valueType

The Java class to create

@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet been set to their final value.

Returns
@Nullable T

The contents of the document in an object of type T or null if the document doesn't exist.

toString

public String toString()

Extension functions

FirestoreKt.getField

public final T <T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull String field
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

Parameters
<T extends Object>

The type to convert the field value to.

@NonNull String field

The path to the field.

Returns
T

The value at the given field or null.

FirestoreKt.getField

public final T <T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull String field,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

Parameters
<T extends Object>

The type to convert the field value to.

@NonNull String field

The path to the field.

@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet

        been set to their final value.
@return

The value at the given field or null.

FirestoreKt.getField

public final T <T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull FieldPath fieldPath
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

Parameters
<T extends Object>

The type to convert the field value to.

@NonNull FieldPath fieldPath

The path to the field.

Returns
T

The value at the given field or null.

FirestoreKt.getField

public final T <T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull FieldPath fieldPath,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

Parameters
<T extends Object>

The type to convert the field value to.

@NonNull FieldPath fieldPath

The path to the field.

@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet

        been set to their final value.
@return

The value at the given field or null.

FirestoreKt.getField

public final T <T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull String field
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

Deprecation Notice: The Kotlin extensions (KTX) APIs have been added to their respective main modules, and the Kotlin extension (KTX) APIs in com.google.firebase.firebase-database-ktx are now deprecated. As early as April 2024, we'll no longer release KTX modules. For details, see the FAQ about this initiative.

Parameters
<T extends Object>

The type to convert the field value to.

@NonNull String field

The path to the field.

Returns
T

The value at the given field or null.

FirestoreKt.getField

public final T <T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull String field,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

Deprecation Notice: The Kotlin extensions (KTX) APIs have been added to their respective main modules, and the Kotlin extension (KTX) APIs in com.google.firebase.firebase-database-ktx are now deprecated. As early as April 2024, we'll no longer release KTX modules. For details, see the FAQ about this initiative.

Parameters
<T extends Object>

The type to convert the field value to.

@NonNull String field

The path to the field.

@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet

        been set to their final value.
@return

The value at the given field or null.

FirestoreKt.getField

public final T <T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull FieldPath fieldPath
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

Deprecation Notice: The Kotlin extensions (KTX) APIs have been added to their respective main modules, and the Kotlin extension (KTX) APIs in com.google.firebase.firebase-database-ktx are now deprecated. As early as April 2024, we'll no longer release KTX modules. For details, see the FAQ about this initiative.

Parameters
<T extends Object>

The type to convert the field value to.

@NonNull FieldPath fieldPath

The path to the field.

Returns
T

The value at the given field or null.

FirestoreKt.getField

public final T <T extends Object> FirestoreKt.getField(
    @NonNull DocumentSnapshot receiver,
    @NonNull FieldPath fieldPath,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the value at the field, converted to a POJO, or null if the field or document doesn't exist.

Deprecation Notice: The Kotlin extensions (KTX) APIs have been added to their respective main modules, and the Kotlin extension (KTX) APIs in com.google.firebase.firebase-database-ktx are now deprecated. As early as April 2024, we'll no longer release KTX modules. For details, see the FAQ about this initiative.

Parameters
<T extends Object>

The type to convert the field value to.

@NonNull FieldPath fieldPath

The path to the field.

@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet

        been set to their final value.
@return

The value at the given field or null.

FirestoreKt.toObject

public final T <T extends Object> FirestoreKt.toObject(@NonNull DocumentSnapshot receiver)

Returns the contents of the document converted to a POJO or null if the document doesn't exist.

Parameters
<T extends Object>

The type of the object to create.

Returns
T

The contents of the document in an object of type T or null if the document doesn't

    exist.

FirestoreKt.toObject

public final T <T extends Object> FirestoreKt.toObject(
    @NonNull DocumentSnapshot receiver,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the contents of the document converted to a POJO or null if the document doesn't exist.

Parameters
<T extends Object>

The type of the object to create.

@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet

        been set to their final value.
@return

The contents of the document in an object of type T or null if the document doesn't

    exist.

FirestoreKt.toObject

public final T <T extends Object> FirestoreKt.toObject(@NonNull DocumentSnapshot receiver)

Returns the contents of the document converted to a POJO or null if the document doesn't exist.

Deprecation Notice: The Kotlin extensions (KTX) APIs have been added to their respective main modules, and the Kotlin extension (KTX) APIs in com.google.firebase.firebase-database-ktx are now deprecated. As early as April 2024, we'll no longer release KTX modules. For details, see the FAQ about this initiative.

Parameters
<T extends Object>

The type of the object to create.

Returns
T

The contents of the document in an object of type T or null if the document doesn't

    exist.

FirestoreKt.toObject

public final T <T extends Object> FirestoreKt.toObject(
    @NonNull DocumentSnapshot receiver,
    @NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior
)

Returns the contents of the document converted to a POJO or null if the document doesn't exist.

Deprecation Notice: The Kotlin extensions (KTX) APIs have been added to their respective main modules, and the Kotlin extension (KTX) APIs in com.google.firebase.firebase-database-ktx are now deprecated. As early as April 2024, we'll no longer release KTX modules. For details, see the FAQ about this initiative.

Parameters
<T extends Object>

The type of the object to create.

@NonNull DocumentSnapshot.ServerTimestampBehavior serverTimestampBehavior

Configures the behavior for server timestamps that have not yet

        been set to their final value.
@return

The contents of the document in an object of type T or null if the document doesn't

    exist.