Query

class Query

Known direct subclasses
DatabaseReference

A Firebase reference represents a particular location in your Database and can be used for reading or writing data to that Database location.


The Query class (and its subclass, DatabaseReference) are used for reading data. Listeners are attached, and they will be triggered when the corresponding data changes. Instances of Query are obtained by calling startAt(), endAt(), or limit() on a DatabaseReference.

Summary

Public functions

ChildEventListener

Add a listener for child events occurring at this location.

Unit

Add a listener for a single change in the data at this location.

ValueEventListener

Add a listener for changes in the data at this location.

Query
endAt(value: String?)

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default.

Query
endAt(value: Double)

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default.

Query
endAt(value: Boolean)

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default.

Query
endAt(value: String?, key: String?)

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key less than or equal to the given key.

Query
endAt(value: Double, key: String?)

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key less than or equal to the given key.

Query
endAt(value: Boolean, key: String?)

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key less than or equal to the given key.

Query
endBefore(value: String?)

Creates a query constrained to only return child nodes with a value less than the given value, using the given orderBy directive or priority as default.

Query
endBefore(value: Double)

Creates a query constrained to only return child nodes with a value less than the given value, using the given orderBy directive or priority as default.

Query

Creates a query constrained to only return child nodes with a value less than the given value, using the given orderBy directive or priority as default.

Query
endBefore(value: String?, key: String?)

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key less than the given key.

Query
endBefore(value: Double, key: String?)

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key less than the given key.

Query
endBefore(value: Boolean, key: String?)

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key less than the given key.

Query
equalTo(value: String?)

Creates a query constrained to only return child nodes with the given value.

Query
equalTo(value: Double)

Creates a query constrained to only return child nodes with the given value.

Query
equalTo(value: Boolean)

Creates a query constrained to only return child nodes with the given value.

Query
equalTo(value: String?, key: String?)

Creates a query constrained to only return the child node with the given key and value.

Query
equalTo(value: Double, key: String?)

Creates a query constrained to only return the child node with the given key and value.

Query
equalTo(value: Boolean, key: String?)

Creates a query constrained to only return the child node with the given key and value.

Task<DataSnapshot!>
get()

Gets the server values for this query.

DatabaseReference
Unit
keepSynced(keepSynced: Boolean)

By calling `keepSynced(true)` on a location, the data for that location will automatically be downloaded and kept in sync, even when no listeners are attached for that location.

Query
limitToFirst(limit: Int)

Creates a query with limit and anchor it to the start of the window.

Query
limitToLast(limit: Int)

Creates a query with limit and anchor it to the end of the window.

Query

Creates a query in which child nodes are ordered by the values of the specified path.

Query

Creates a query in which child nodes are ordered by their keys.

Query

Creates a query in which child nodes are ordered by their priorities.

Query

Creates a query in which nodes are ordered by their value

Unit

Remove the specified listener from this location.

Unit

Remove the specified listener from this location.

Query
startAfter(value: String?)

Creates a query constrained to only return child nodes with a value greater than the given value, using the given orderBy directive or priority as default.

Query

Creates a query constrained to only return child nodes with a value greater than the given value, using the given orderBy directive or priority as default.

Query

Creates a query constrained to only return child nodes with a value greater than the given value, using the given orderBy directive or priority as default.

Query
startAfter(value: String?, key: String?)

Creates a query constrained to only return child nodes with a value greater or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key greater than the given key.

Query
startAfter(value: Double, key: String?)

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key greater than the given key.

Query
startAfter(value: Boolean, key: String?)

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key greater than the given key.

Query
startAt(value: String?)

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default.

Query
startAt(value: Double)

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default.

Query
startAt(value: Boolean)

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default.

Query
startAt(value: String?, key: String?)

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key greater than or equal to the given key.

Query
startAt(value: Double, key: String?)

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key greater than or equal to the given key.

Query
startAt(value: Boolean, key: String?)

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key greater than or equal to the given key.

Extension functions

inline Flow<T?>
<T : Any> Query.values()

Starts listening to this query and emits its values converted to a POJO via a Flow.

inline Flow<T?>
<T : Any> Query.values()

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

Extension properties

Flow<ChildEvent>

Starts listening to this query's child events and emits its values via a Flow.

Flow<ChildEvent>

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

Flow<DataSnapshot>

Starts listening to this query and emits its values via a Flow.

Flow<DataSnapshot>

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

Public functions

addChildEventListener

fun addChildEventListener(listener: ChildEventListener): ChildEventListener

Add a listener for child events occurring at this location. When child locations are added, removed, changed, or moved, the listener will be triggered for the appropriate event

Parameters
listener: ChildEventListener

The listener to be called with changes

Returns
ChildEventListener

A reference to the listener provided. Save this to remove the listener later.

addListenerForSingleValueEvent

fun addListenerForSingleValueEvent(listener: ValueEventListener): Unit

Add a listener for a single change in the data at this location. This listener will be triggered once with the value of the data at the location.

Parameters
listener: ValueEventListener

The listener to be called with the data

addValueEventListener

fun addValueEventListener(listener: ValueEventListener): ValueEventListener

Add a listener for changes in the data at this location. Each time the data changes, your listener will be called with an immutable snapshot of the data.

Parameters
listener: ValueEventListener

The listener to be called with changes

Returns
ValueEventListener

A reference to the listener provided. Save this to remove the listener later.

endAt

fun endAt(value: String?): Query

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default.

Parameters
value: String?

The value to end at, inclusive

Returns
Query

A query with the new constraint

endAt

fun endAt(value: Double): Query

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default.

Parameters
value: Double

The value to end at, inclusive

Returns
Query

A query with the new constraint

endAt

fun endAt(value: Boolean): Query

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default.

2.0

Parameters
value: Boolean

The value to end at, inclusive

Returns
Query

A query with the new constraint

endAt

fun endAt(value: String?, key: String?): Query

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key less than or equal to the given key.

Parameters
value: String?

The value to end at, inclusive

key: String?

The key to end at, inclusive

Returns
Query

A query with the new constraint

endAt

fun endAt(value: Double, key: String?): Query

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key less than or equal to the given key.

Parameters
value: Double

The value to end at, inclusive

key: String?

The key to end at, inclusive

Returns
Query

A query with the new constraint

endAt

fun endAt(value: Boolean, key: String?): Query

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key less than or equal to the given key.

2.0

Parameters
value: Boolean

The value to end at, inclusive

key: String?

The key to end at, inclusive

Returns
Query

A query with the new constraint

endBefore

fun endBefore(value: String?): Query

Creates a query constrained to only return child nodes with a value less than the given value, using the given orderBy directive or priority as default.

19.6

Parameters
value: String?

The value to end at, exclusive

Returns
Query

A query with the new constraint

endBefore

fun endBefore(value: Double): Query

Creates a query constrained to only return child nodes with a value less than the given value, using the given orderBy directive or priority as default.

19.6

Parameters
value: Double

The value to end at, exclusive

Returns
Query

A query with the new constraint

endBefore

fun endBefore(value: Boolean): Query

Creates a query constrained to only return child nodes with a value less than the given value, using the given orderBy directive or priority as default.

19.6

Parameters
value: Boolean

The value to end at, exclusive

Returns
Query

A query with the new constraint

endBefore

fun endBefore(value: String?, key: String?): Query

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key less than the given key.

19.6

Parameters
value: String?

The value to end at

key: String?

The key to end at, exclusive

Returns
Query

A query with the new constraint

endBefore

fun endBefore(value: Double, key: String?): Query

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key less than the given key.

19.6

Parameters
value: Double

The value to end at

key: String?

The key to end at, exclusive

Returns
Query

A query with the new constraint

endBefore

fun endBefore(value: Boolean, key: String?): Query

Creates a query constrained to only return child nodes with a value less than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key less than the given key.

19.6

Parameters
value: Boolean

The value to end at

key: String?

The key to end at, exclusive

Returns
Query

A query with the new constraint

equalTo

fun equalTo(value: String?): Query

Creates a query constrained to only return child nodes with the given value.

Parameters
value: String?

The value to query for

Returns
Query

A query with the new constraint

equalTo

fun equalTo(value: Double): Query

Creates a query constrained to only return child nodes with the given value.

Parameters
value: Double

The value to query for

Returns
Query

A query with the new constraint

equalTo

fun equalTo(value: Boolean): Query

Creates a query constrained to only return child nodes with the given value.

2.0

Parameters
value: Boolean

The value to query for

Returns
Query

A query with the new constraint

equalTo

fun equalTo(value: String?, key: String?): Query

Creates a query constrained to only return the child node with the given key and value. Note that there is at most one such child as names are unique.

Parameters
value: String?

The value to query for

key: String?

The key of the child

Returns
Query

A query with the new constraint

equalTo

fun equalTo(value: Double, key: String?): Query

Creates a query constrained to only return the child node with the given key and value. Note that there is at most one such child as keys are unique.

Parameters
value: Double

The value to query for

key: String?

The key of the child

Returns
Query

A query with the new constraint

equalTo

fun equalTo(value: Boolean, key: String?): Query

Creates a query constrained to only return the child node with the given key and value. Note that there is at most one such child as keys are unique.

Parameters
value: Boolean

The value to query for

key: String?

The name of the child

Returns
Query

A query with the new constraint

get

fun get(): Task<DataSnapshot!>

Gets the server values for this query. Updates the cache and raises events if successful. If not connected, falls back to a locally-cached value.

getRef

fun getRef(): DatabaseReference
Returns
DatabaseReference

A DatabaseReference to this location

keepSynced

fun keepSynced(keepSynced: Boolean): Unit

By calling `keepSynced(true)` on a location, the data for that location will automatically be downloaded and kept in sync, even when no listeners are attached for that location. Additionally, while a location is kept synced, it will not be evicted from the persistent disk cache.

2.3

Parameters
keepSynced: Boolean

Pass `true` to keep this location synchronized, pass `false` to stop synchronization.

limitToFirst

fun limitToFirst(limit: Int): Query

Creates a query with limit and anchor it to the start of the window.

2.0

Parameters
limit: Int

The maximum number of child nodes to return

Returns
Query

A query with the new constraint

limitToLast

fun limitToLast(limit: Int): Query

Creates a query with limit and anchor it to the end of the window.

2.0

Parameters
limit: Int

The maximum number of child nodes to return

Returns
Query

A query with the new constraint

orderByChild

fun orderByChild(path: String): Query

Creates a query in which child nodes are ordered by the values of the specified path.

2.0

Parameters
path: String

The path to the child node to use for sorting

Returns
Query

A query with the new constraint

orderByKey

fun orderByKey(): Query

Creates a query in which child nodes are ordered by their keys.

2.0

Returns
Query

A query with the new constraint

orderByPriority

fun orderByPriority(): Query

Creates a query in which child nodes are ordered by their priorities.

2.0

Returns
Query

A query with the new constraint

orderByValue

fun orderByValue(): Query

Creates a query in which nodes are ordered by their value

2.2

Returns
Query

A query with the new constraint

removeEventListener

fun removeEventListener(listener: ChildEventListener): Unit

Remove the specified listener from this location.

Parameters
listener: ChildEventListener

The listener to remove

removeEventListener

fun removeEventListener(listener: ValueEventListener): Unit

Remove the specified listener from this location.

Parameters
listener: ValueEventListener

The listener to remove

startAfter

fun startAfter(value: String?): Query

Creates a query constrained to only return child nodes with a value greater than the given value, using the given orderBy directive or priority as default.

19.6

Parameters
value: String?

The value to start at, exclusive

Returns
Query

A query with the new constraint

startAfter

fun startAfter(value: Double): Query

Creates a query constrained to only return child nodes with a value greater than the given value, using the given orderBy directive or priority as default.

19.6

Parameters
value: Double

The value to start at, exclusive

Returns
Query

A query with the new constraint

startAfter

fun startAfter(value: Boolean): Query

Creates a query constrained to only return child nodes with a value greater than the given value, using the given orderBy directive or priority as default.

19.6

Parameters
value: Boolean

The value to start at, exclusive

Returns
Query

A query with the new constraint

startAfter

fun startAfter(value: String?, key: String?): Query

Creates a query constrained to only return child nodes with a value greater or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key greater than the given key.

19.6

Parameters
value: String?

The value to start at

key: String?

The key to start at, exclusive

Returns
Query

A query with the new constraint

startAfter

fun startAfter(value: Double, key: String?): Query

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key greater than the given key.

19.6

Parameters
value: Double

The value to start at

key: String?

The key name to start at, exclusive

Returns
Query

A query with the new constraint

startAfter

fun startAfter(value: Boolean, key: String?): Query

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key greater than the given key.

19.6

Parameters
value: Boolean

The value to start at

key: String?

The key to start at, exclusive

Returns
Query

A query with the new constraint

startAt

fun startAt(value: String?): Query

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default.

Parameters
value: String?

The value to start at, inclusive

Returns
Query

A query with the new constraint

startAt

fun startAt(value: Double): Query

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default.

Parameters
value: Double

The value to start at, inclusive

Returns
Query

A query with the new constraint

startAt

fun startAt(value: Boolean): Query

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default.

2.0

Parameters
value: Boolean

The value to start at, inclusive

Returns
Query

A query with the new constraint

startAt

fun startAt(value: String?, key: String?): Query

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key greater than or equal to the given key.

Parameters
value: String?

The priority to start at, inclusive

key: String?

The key to start at, inclusive

Returns
Query

A query with the new constraint

startAt

fun startAt(value: Double, key: String?): Query

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key greater than or equal to the given key.

Parameters
value: Double

The priority to start at, inclusive

key: String?

The key name to start at, inclusive

Returns
Query

A query with the new constraint

startAt

fun startAt(value: Boolean, key: String?): Query

Creates a query constrained to only return child nodes with a value greater than or equal to the given value, using the given orderBy directive or priority as default, and additionally only child nodes with a key greater than or equal to the given key.

2.0

Parameters
value: Boolean

The priority to start at, inclusive

key: String?

The key to start at, inclusive

Returns
Query

A query with the new constraint

Extension functions

values

inline fun <T : Any> Query.values(): Flow<T?>

Starts listening to this query and emits its values converted to a POJO via a Flow.

  • When the returned flow starts being collected, a ValueEventListener will be attached.

  • When the flow completes, the listener will be removed.

values

inline fun <T : Any> Query.values(): Flow<T?>

Starts listening to this query and emits its values converted to a POJO via a Flow.

  • When the returned flow starts being collected, a ValueEventListener will be attached.

  • When the flow completes, the listener will be removed.

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.

Extension properties

childEvents

val Query.childEventsFlow<ChildEvent>

Starts listening to this query's child events and emits its values via a Flow.

  • When the returned flow starts being collected, a ChildEventListener will be attached.

  • When the flow completes, the listener will be removed.

childEvents

val Query.childEventsFlow<ChildEvent>

Starts listening to this query's child events and emits its values via a Flow.

  • When the returned flow starts being collected, a ChildEventListener will be attached.

  • When the flow completes, the listener will be removed.

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.

snapshots

val Query.snapshotsFlow<DataSnapshot>

Starts listening to this query and emits its values via a Flow.

  • When the returned flow starts being collected, a ValueEventListener will be attached.

  • When the flow completes, the listener will be removed.

snapshots

val Query.snapshotsFlow<DataSnapshot>

Starts listening to this query and emits its values via a Flow.

  • When the returned flow starts being collected, a ValueEventListener will be attached.

  • When the flow completes, the listener will be removed.

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.