DatabaseQuery
class DatabaseQuery : NSObject
A DatabaseQuery
instance represents a query over the data at a particular
location.
You create one by calling one of the query methods (queryOrdered(byChild:)
,
queryStarting(atValue:)
, etc.) on a DatabaseReference
. The query methods
can be chained to further specify the data you are interested in observing.
-
This method is used to listen for data changes at a particular location. This is the primary way to read data from the Firebase Database. Your block will be triggered for the initial data and again whenever the data changes.
Use removeObserverWithHandle: to stop receiving updates.
Declaration
Swift
func observe(_ eventType: DataEventType, with block: @escaping (DataSnapshot) -> Void) -> UInt
Parameters
eventType
The type of event to listen for.
block
The block that should be called with initial data and updates. It is passed the data as a
DataSnapshot
.Return Value
A handle used to unregister this block later using
removeObserver(withHandle:)
-
This method is used to listen for data changes at a particular location. This is the primary way to read data from the Firebase Database. Your block will be triggered for the initial data and again whenever the data changes. In addition, for
DataEventTypeChildAdded
,DataEventTypeChildMoved
, andDataEventTypeChildChanged
events, your block will be passed the key of the previous node by priority order.Use
removeObserver(withHandle:)
to stop receiving updates.Declaration
Swift
func observe(_ eventType: DataEventType, andPreviousSiblingKeyWith block: @escaping (DataSnapshot, String?) -> Void) -> UInt
Parameters
eventType
The type of event to listen for.
block
The block that should be called with initial data and updates. It is passed the data as a
DataSnapshot
and the previous child’s key.Return Value
A handle used to unregister this block later using
removeObserver(withHandle:)
-
This method is used to listen for data changes at a particular location. This is the primary way to read data from the Firebase Database. Your block will be triggered for the initial data and again whenever the data changes.
The
cancelBlock
will be called if you will no longer receive new events due to no longer having permission.Use
removeObserver(withHandle:)
to stop receiving updates.Declaration
Swift
func observe(_ eventType: DataEventType, with block: @escaping (DataSnapshot) -> Void, withCancel cancelBlock: ((any Error) -> Void)? = nil) -> UInt
Parameters
eventType
The type of event to listen for.
block
The block that should be called with initial data and updates. It is passed the data as a
DataSnapshot
.cancelBlock
The block that should be called if this client no longer has permission to receive these events
Return Value
A handle used to unregister this block later using
removeObserver(withHandle:)
-
This method is used to listen for data changes at a particular location. This is the primary way to read data from the Firebase Database. Your block will be triggered for the initial data and again whenever the data changes. In addition, for
FIRDataEventTypeChildAdded
,FIRDataEventTypeChildMoved
, and FIRDataEventTypeChildChanged events, your block will be passed the key of the previous node by priority order.The
cancelBlock
will be called if you will no longer receive new events due to no longer having permission.Use
removeObserver(withHandle:)
to stop receiving updates.Declaration
Swift
func observe(_ eventType: DataEventType, andPreviousSiblingKeyWith block: @escaping (DataSnapshot, String?) -> Void, withCancel cancelBlock: ((any Error) -> Void)? = nil) -> UInt
Parameters
eventType
The type of event to listen for.
block
The block that should be called with initial data and updates. It is passed the data as a
DataSnapshot
and the previous child’s key.cancelBlock
The block that should be called if this client no longer has permission to receive these events
Return Value
A handle used to unregister this block later using
removeObserver(withHandle:)
-
This method is used to get the most up-to-date value for this query. This method updates the cache and raises events if successful. If not connected, it returns a locally-cached value.
Declaration
Swift
func getData() async throws -> DataSnapshot
Parameters
block
The block that should be called with the most up-to-date value of this query, or an error if no such value could be retrieved.
-
This is equivalent to
observe(_:with:)
, except the block is immediately canceled after the initial data is returned.Declaration
Swift
func observeSingleEvent(of eventType: DataEventType, with block: @escaping (DataSnapshot) -> Void)
Parameters
eventType
The type of event to listen for.
block
The block that should be called. It is passed the data as a
DataSnapshot
. -
This is equivalent to
observe(_:with:)
, except the block is immediately canceled after the initial data is returned. In addition, forDataEventTypeChildAdded
,DataEventTypeChildMoved
, andDataEventTypeChildChanged
events, your block will be passed the key of the previous node by priority order.Declaration
Swift
func observeSingleEventAndPreviousSiblingKey(of eventType: DataEventType) async -> (DataSnapshot, String?)
Parameters
eventType
The type of event to listen for.
block
The block that should be called. It is passed the data as a
DataSnapshot
and the previous child’s key. -
This is equivalent to
observe(_:with:)
, except the block is immediately canceled after the initial data is returned.The
cancelBlock
will be called if you do not have permission to read data at this location.Declaration
Swift
func observeSingleEvent(of eventType: DataEventType, with block: @escaping (DataSnapshot) -> Void, withCancel cancelBlock: ((any Error) -> Void)? = nil)
Parameters
eventType
The type of event to listen for.
block
The block that should be called. It is passed the data as a
DataSnapshot
.cancelBlock
The block that will be called if you don’t have permission to access this data
-
This is equivalent to
observe(_:with:)
, except the block is immediately canceled after the initial data is returned. In addition, forDataEventTypeChildAdded
,DataEventTypeChildMoved
, andDataEventTypeChildChanged
events, your block will be passed the key of the previous node by priority order.The
cancelBlock
will be called if you do not have permission to read data at this location.Declaration
Swift
func observeSingleEvent(of eventType: DataEventType, andPreviousSiblingKeyWith block: @escaping (DataSnapshot, String?) -> Void, withCancel cancelBlock: ((any Error) -> Void)? = nil)
Parameters
eventType
The type of event to listen for.
block
The block that should be called. It is passed the data as a
DataSnapshot
and the previous child’s key.cancelBlock
The block that will be called if you don’t have permission to access this data
-
Detach a block previously attached with
observe(_:with:)
, or another query observation method. After this method is called, the associated block registered to receive snapshot updates will no longer be invoked.Declaration
Swift
func removeObserver(withHandle handle: UInt)
Parameters
handle
The handle returned by the call to
observe(_:with:)
which we are trying to remove. -
Detach all blocks previously attached to this Firebase Database location with
observe(_:with:)
and other query observation methods.Declaration
Swift
func removeAllObservers()
-
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.Declaration
Swift
func keepSynced(_ keepSynced: Bool)
Parameters
keepSynced
Pass true to keep this location synchronized, or false to stop synchronization.
-
This method is used to generate a reference to a limited view of the data at this location. The
DatabaseQuery
instance returned byqueryLimited(toFirst:)
will respond to at most the first limit child nodes.Declaration
Swift
func queryLimited(toFirst limit: UInt) -> DatabaseQuery
Parameters
limit
The upper bound, inclusive, for the number of child nodes to receive events for
Return Value
A
DatabaseQuery
instance, limited to at most limit child nodes. -
queryLimited(toLast:)
is used to generate a reference to a limited view of the data at this location. TheDatabaseQuery
instance returned by this method will respond to at most the last limit child nodes.Declaration
Swift
func queryLimited(toLast limit: UInt) -> DatabaseQuery
Parameters
limit
The upper bound, inclusive, for the number of child nodes to receive events for
Return Value
A
DatabaseQuery
instance, limited to at most limit child nodes. -
This method is used to generate a reference to a view of the data that’s been sorted by the values of a particular child key. This method is intended to be used in combination with
queryStarting(atValue:)
,queryEnding(atValue:)
, orqueryEqual(toValue:)
.Declaration
Swift
func queryOrdered(byChild key: String) -> DatabaseQuery
Parameters
key
The child key to use in ordering data visible to the returned
DatabaseQuery
Return Value
A
DatabaseQuery
instance, ordered by the values of the specified child key. -
queryOrdered(byKey:) is used to generate a reference to a view of the data that's been sorted by child key. This method is intended to be used in combination with
queryStarting(atValue:),
queryEnding(atValue:), or
queryEqual(toValue:)`.Declaration
Swift
func queryOrderedByKey() -> DatabaseQuery
Return Value
A
DatabaseQuery
instance, ordered by child keys. -
queryOrdered(byValue:)
is used to generate a reference to a view of the data that’s been sorted by child value. This method is intended to be used in combination withqueryStarting(atValue:)
,queryEnding(atValue:)
, orqueryEqual(toValue:)
.Declaration
Swift
func queryOrderedByValue() -> DatabaseQuery
Return Value
A
DatabaseQuery
instance, ordered by child value. -
queryOrdered(byPriority:) is used to generate a reference to a view of the data that's been sorted by child priority. This method is intended to be used in combination with
queryStarting(atValue:),
queryEnding(atValue:), or
queryEqual(toValue:)`.Declaration
Swift
func queryOrderedByPriority() -> DatabaseQuery
Return Value
A
DatabaseQuery
instance, ordered by child priorities. -
queryStarting(atValue:)
is used to generate a reference to a limited view of the data at this location. TheDatabaseQuery
instance returned byqueryStarting(atValue:)
will respond to events at nodes with a value greater than or equal tostartValue
.Declaration
Swift
func queryStarting(atValue startValue: Any?) -> DatabaseQuery
Parameters
startValue
The lower bound, inclusive, for the value of data visible to the returned
DatabaseQuery
Return Value
A
DatabaseQuery
instance, limited to data with value greater than or equal tostartValue
-
queryStarting(atValue:childKey:)
is used to generate a reference to a limited view of the data at this location. TheDatabaseQuery
instance returned byqueryStarting(atValue:childKey:)
will respond to events at nodes with a value greater thanstartValue
, or equal tostartValue
and with a key greater than or equal tochildKey
. This is most useful when implementing pagination in a case where multiple nodes can match thestartValue
.Declaration
Swift
func queryStarting(atValue startValue: Any?, childKey: String?) -> DatabaseQuery
Parameters
startValue
The lower bound, inclusive, for the value of data visible to the returned
DatabaseQuery
childKey
The lower bound, inclusive, for the key of nodes with value equal to
startValue
Return Value
A
DatabaseQuery
instance, limited to data with value greater than or equal tostartValue
-
queryStarting(afterValue:)
is used to generate a reference to a limited view of the data at this location. TheDatabaseQuery
instance returned byqueryStarting(afterValue:)
will respond to events at nodes with a value greater than startAfterValue.Declaration
Swift
func queryStarting(afterValue startAfterValue: Any?) -> DatabaseQuery
Parameters
startAfterValue
The lower bound, exclusive, for the value of data visible to the returned
DatabaseQuery
Return Value
A
DatabaseQuery
instance, limited to data with value greaterstartAfterValue
-
queryStarting(afterValue:childKey:)
is used to generate a reference to a limited view of the data at this location. TheDatabaseQuery
instance returned byqueryStarting(afterValue:childKey:)
will respond to events at nodes with a value greater thanstartAfterValue
, or equal tostartAfterValue
and with a key greater thanchildKey
. This is most useful when implementing pagination in a case where multiple nodes can match thestartAfterValue
.Declaration
Swift
func queryStarting(afterValue startAfterValue: Any?, childKey: String?) -> DatabaseQuery
Parameters
startAfterValue
The lower bound, inclusive, for the value of data visible to the returned
DatabaseQuery
childKey
The lower bound, exclusive, for the key of nodes with value equal to
startAfterValue
Return Value
A
DatabaseQuery
instance, limited to data with value greater thanstartAfterValue
, or equal tostartAfterValue
with a key greater thanchildKey
-
queryEnding(atValue:)
is used to generate a reference to a limited view of the data at this location. The DatabaseQuery instance returned byqueryEnding(atValue:)
will respond to events at nodes with a value less than or equal toendValue
.Declaration
Swift
func queryEnding(atValue endValue: Any?) -> DatabaseQuery
Parameters
endValue
The upper bound, inclusive, for the value of data visible to the returned
DatabaseQuery
Return Value
A
DatabaseQuery
instance, limited to data with value less than or equal toendValue
-
queryEnding(atValue:childKey:)
is used to generate a reference to a limited view of the data at this location. TheDatabaseQuery
instance returned byqueryEnding(atValue:childKey:)
will respond to events at nodes with a value less thanendValue
, or equal toendValue
and with a key less than or equal tochildKey
. This is most useful when implementing pagination in a case where multiple nodes can match theendValue
.Declaration
Swift
func queryEnding(atValue endValue: Any?, childKey: String?) -> DatabaseQuery
Parameters
endValue
The upper bound, inclusive, for the value of data visible to the returned
DatabaseQuery
childKey
The upper bound, inclusive, for the key of nodes with value equal to
endValue
Return Value
A
DatabaseQuery
instance, limited to data with value less than or equal toendValue
-
queryEnding(beforeValue:) is used to generate a reference to a limited view of the data at this location. The
DatabaseQueryinstance returned by
queryEnding(beforeValue:)will respond to events at nodes with a value less than
endValue`.Declaration
Swift
func queryEnding(beforeValue endValue: Any?) -> DatabaseQuery
Parameters
endValue
The upper bound, exclusive, for the value of data visible to the returned
DatabaseQuery
Return Value
A
DatabaseQuery
instance, limited to data with value less thanendValue
-
queryEnding(beforeValue:childKey:)
is used to generate a reference to a limited view of the data at this location. TheDatabaseQuery
instance returned byqueryEnding(beforeValue:childKey:)
will respond to events at nodes with a value less thanendValue
, or equal toendValue
and with a key less than childKey.Declaration
Swift
func queryEnding(beforeValue endValue: Any?, childKey: String?) -> DatabaseQuery
Parameters
endValue
The upper bound, inclusive, for the value of data visible to the returned
DatabaseQuery
childKey
The upper bound, exclusive, for the key of nodes with value equal to endValue
Return Value
A
DatabaseQuery
instance, limited to data with value less than or equal to endValue -
queryEqual(toValue:)
is used to generate a reference to a limited view of the data at this location. TheDatabaseQuery
instance returned byqueryEqual(toValue:)
will respond to events at nodes with a value equal to the supplied argument.Declaration
Swift
func queryEqual(toValue value: Any?) -> DatabaseQuery
Parameters
value
The value that the data returned by this
DatabaseQuery
will haveReturn Value
A
DatabaseQuery
instance, limited to data with the supplied value. -
queryEqual(toValue:childKey:)
is used to generate a reference to a limited view of the data at this location. TheDatabaseQuery
instance returned byqueryEqual(toValue:childKey:)
will respond to events at nodes with a value equal to the supplied argument and with their key equal tochildKey
. There will be at most one node that matches because child keys are unique.Declaration
Swift
func queryEqual(toValue value: Any?, childKey: String?) -> DatabaseQuery
Parameters
value
The value that the data returned by this
DatabaseQuery
will havechildKey
The name of nodes with the right value
Return Value
A
DatabaseQuery
instance, limited to data with the supplied value and the key.
-
Gets a
DatabaseReference
for the location of this query.Declaration
Swift
var ref: FIRDatabaseReference { get }
Return Value
A
DatabaseReference
for the location of this query.