DatabaseReference

class DatabaseReference : Query


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

This class is the starting point for all Database operations. After you've initialized it with a URL, you can use it to read data, write data, and to create new DatabaseReferences.

Summary

Nested types

This interface is used as a method of being notified when an operation has been acknowledged by the Database servers and can be considered complete

Public functions

DatabaseReference
child(pathString: String)

Get a reference to location relative to this one

Boolean
equals(other: Any!)
FirebaseDatabase

Gets the Database instance associated with this reference.

String?
DatabaseReference?
DatabaseReference
java-static Unit

Manually disconnect the Firebase Database client from the server and disable automatic reconnection.

java-static Unit

Manually reestablish a connection to the Firebase Database server and enable automatic reconnection.

Int
OnDisconnect

Provides access to disconnect operations at this location

DatabaseReference

Create a reference to an auto-generated child location.

Task<Void!>

Set the value at this location to 'null'

Unit

Set the value at this location to 'null'

Unit

Run a transaction on the data at this location.

Unit
runTransaction(handler: Transaction.Handler, fireLocalEvents: Boolean)

Run a transaction on the data at this location.

Task<Void!>
setPriority(priority: Any?)

Set a priority for the data at this Database location.

Unit
setPriority(
    priority: Any?,
    listener: DatabaseReference.CompletionListener?
)

Set a priority for the data at this Database location.

Task<Void!>
setValue(value: Any?)

Set the data at this location to the given value.

Unit

Set the data at this location to the given value.

Task<Void!>
setValue(value: Any?, priority: Any?)

Set the data and priority to the given values.

Unit
setValue(
    value: Any?,
    priority: Any?,
    listener: DatabaseReference.CompletionListener?
)

Set the data and priority to the given values.

String!
Task<Void!>

Update the specific child keys to the specified values.

Unit
updateChildren(
    update: (Mutable)Map<String!, Any!>,
    listener: DatabaseReference.CompletionListener?
)

Update the specific child keys to the specified values.

Inherited functions

From com.google.firebase.database.Query
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.

Public functions

child

fun child(pathString: String): DatabaseReference

Get a reference to location relative to this one

Parameters
pathString: String

The relative path from this reference to the new one that should be created

Returns
DatabaseReference

A new DatabaseReference to the given path

equals

fun equals(other: Any!): Boolean

getDatabase

fun getDatabase(): FirebaseDatabase

Gets the Database instance associated with this reference.

Returns
FirebaseDatabase

The Database object for this reference.

getKey

fun getKey(): String?
Returns
String?

The last token in the location pointed to by this reference or null if this reference points to the database root

getParent

fun getParent(): DatabaseReference?
Returns
DatabaseReference?

A DatabaseReference to the parent location, or null if this instance references the root location

getRoot

fun getRoot(): DatabaseReference
Returns
DatabaseReference

A reference to the root location of this Firebase Database

goOffline

java-static fun goOffline(): Unit

Manually disconnect the Firebase Database client from the server and disable automatic reconnection.

Note: Invoking this method will impact all Firebase Database connections.

goOnline

java-static fun goOnline(): Unit

Manually reestablish a connection to the Firebase Database server and enable automatic reconnection.

Note: Invoking this method will impact all Firebase Database connections.

hashCode

fun hashCode(): Int

onDisconnect

fun onDisconnect(): OnDisconnect

Provides access to disconnect operations at this location

Returns
OnDisconnect

An object for managing disconnect operations at this location

push

fun push(): DatabaseReference

Create a reference to an auto-generated child location. The child key is generated client-side and incorporates an estimate of the server's time for sorting purposes. Locations generated on a single client will be sorted in the order that they are created, and will be sorted approximately in order across all clients.

Returns
DatabaseReference

A DatabaseReference pointing to the new location

removeValue

fun removeValue(): Task<Void!>

Set the value at this location to 'null'

Returns
Task<Void!>

The Task for this operation.

removeValue

fun removeValue(listener: DatabaseReference.CompletionListener?): Unit

Set the value at this location to 'null'

Parameters
listener: DatabaseReference.CompletionListener?

A listener that will be triggered when the operation is complete

runTransaction

fun runTransaction(handler: Transaction.Handler): Unit

Run a transaction on the data at this location. For more information on running transactions, see Transaction.Handler.

Parameters
handler: Transaction.Handler

An object to handle running the transaction

runTransaction

fun runTransaction(handler: Transaction.Handler, fireLocalEvents: Boolean): Unit

Run a transaction on the data at this location. For more information on running transactions, see Transaction.Handler.

Parameters
handler: Transaction.Handler

An object to handle running the transaction

fireLocalEvents: Boolean

Defaults to true. If set to false, events will only be fired for the final result state of the transaction, and not for any intermediate states

setPriority

fun setPriority(priority: Any?): Task<Void!>

Set a priority for the data at this Database location. Priorities can be used to provide a custom ordering for the children at a location (if no priorities are specified, the children are ordered by key). You cannot set a priority on an empty location. For this reason setValue(data, priority) should be used when setting initial data with a specific priority and setPriority should be used when updating the priority of existing data. Children are sorted based on this priority using the following rules:

  • Children with no priority come first.
  • Children with a number as their priority come next. They are sorted numerically by priority (small to large).
  • Children with a string as their priority come last. They are sorted lexicographically by priority.
  • Whenever two children have the same priority (including no priority), they are sorted by key. Numeric keys come first (sorted numerically), followed by the remaining keys (sorted lexicographically).
Note that numerical priorities are parsed and ordered as IEEE 754 double-precision floating-point numbers. Keys are always stored as strings and are treated as numeric only when they can be parsed as a 32-bit integer.
Parameters
priority: Any?

The priority to set at the specified location or null to clear the existing priority

Returns
Task<Void!>

The Task for this operation.

setPriority

fun setPriority(
    priority: Any?,
    listener: DatabaseReference.CompletionListener?
): Unit

Set a priority for the data at this Database location. Priorities can be used to provide a custom ordering for the children at a location (if no priorities are specified, the children are ordered by key). You cannot set a priority on an empty location. For this reason setValue(data, priority) should be used when setting initial data with a specific priority and setPriority should be used when updating the priority of existing data. Children are sorted based on this priority using the following rules:

  • Children with no priority come first.
  • Children with a number as their priority come next. They are sorted numerically by priority (small to large).
  • Children with a string as their priority come last. They are sorted lexicographically by priority.
  • Whenever two children have the same priority (including no priority), they are sorted by key. Numeric keys come first (sorted numerically), followed by the remaining keys (sorted lexicographically).
Note that numerical priorities are parsed and ordered as IEEE 754 double-precision floating-point numbers. Keys are always stored as strings and are treated as numeric only when they can be parsed as a 32-bit integer.
Parameters
priority: Any?

The priority to set at the specified location or null to clear the existing priority

listener: DatabaseReference.CompletionListener?

A listener that will be triggered with results of the operation

setValue

fun setValue(value: Any?): Task<Void!>

Set the data at this location to the given value. Passing null to setValue() will delete the data at the specified location. The native types accepted by this method for the value correspond to the JSON types:

  • Boolean
  • Long
  • Double
  • String
  • Map<String, Object>
  • List<Object>
In addition, you can set instances of your own class into this location, provided they satisfy the following constraints:
  1. The class must have a default constructor that takes no arguments
  2. The class must define public getters for the properties to be assigned. Properties without a public getter will be set to their default value when an instance is deserialized
Generic collections of objects that satisfy the above constraints are also permitted, i.e. Map<String, MyPOJO>, as well as null values.
Parameters
value: Any?

The value to set at this location or null to delete the existing data

Returns
Task<Void!>

The Task for this operation.

setValue

fun setValue(value: Any?, listener: DatabaseReference.CompletionListener?): Unit

Set the data at this location to the given value. Passing null to setValue() will delete the data at the specified location. The native types accepted by this method for the value correspond to the JSON types:

  • Boolean
  • Long
  • Double
  • String
  • Map<String, Object>
  • List<Object>
In addition, you can set instances of your own class into this location, provided they satisfy the following constraints:
  1. The class must have a default constructor that takes no arguments
  2. The class must define public getters for the properties to be assigned. Properties without a public getter will be set to their default value when an instance is deserialized
Generic collections of objects that satisfy the above constraints are also permitted, i.e. Map<String, MyPOJO>, as well as null values.
Parameters
value: Any?

The value to set at this location or null to delete the existing data

listener: DatabaseReference.CompletionListener?

A listener that will be triggered with the results of the operation

setValue

fun setValue(value: Any?, priority: Any?): Task<Void!>

Set the data and priority to the given values. Passing null to setValue() will delete the data at the specified location. The native types accepted by this method for the value correspond to the JSON types:

  • Boolean
  • Long
  • Double
  • String
  • Map<String, Object>
  • List<Object>
In addition, you can set instances of your own class into this location, provided they satisfy the following constraints:
  1. The class must have a default constructor that takes no arguments
  2. The class must define public getters for the properties to be assigned. Properties without a public getter will be set to their default value when an instance is deserialized
Generic collections of objects that satisfy the above constraints are also permitted, i.e. Map<String, MyPOJO>, as well as null values.
Parameters
value: Any?

The value to set at this location or null to delete the existing data

priority: Any?

The priority to set at this location or null to clear the existing priority

Returns
Task<Void!>

The Task for this operation.

setValue

fun setValue(
    value: Any?,
    priority: Any?,
    listener: DatabaseReference.CompletionListener?
): Unit

Set the data and priority to the given values. The native types accepted by this method for the value correspond to the JSON types:

  • Boolean
  • Long
  • Double
  • String
  • Map<String, Object>
  • List<Object>
In addition, you can set instances of your own class into this location, provided they satisfy the following constraints:
  1. The class must have a default constructor that takes no arguments
  2. The class must define public getters for the properties to be assigned. Properties without a public getter will be set to their default value when an instance is deserialized
Generic collections of objects that satisfy the above constraints are also permitted, i.e. Map<String, MyPOJO>, as well as null values.
Parameters
value: Any?

The value to set at this location or null to delete the existing data

priority: Any?

The priority to set at this location or null to clear the existing priority

listener: DatabaseReference.CompletionListener?

A listener that will be triggered with the results of the operation

toString

fun toString(): String!
Returns
String!

The full location url for this reference

updateChildren

fun updateChildren(update: (Mutable)Map<String!, Any!>): Task<Void!>

Update the specific child keys to the specified values. Passing null in a map to updateChildren() will remove the value at the specified location.

Parameters
update: (Mutable)Map<String!, Any!>

The paths to update and their new values

Returns
Task<Void!>

The Task for this operation.

updateChildren

fun updateChildren(
    update: (Mutable)Map<String!, Any!>,
    listener: DatabaseReference.CompletionListener?
): Unit

Update the specific child keys to the specified values. Passing null in a map to updateChildren() will remove the value at the specified location.

Parameters
update: (Mutable)Map<String!, Any!>

The paths to update and their new values

listener: DatabaseReference.CompletionListener?

A listener that will be triggered with results of the operation