FIRDatabaseQuery

@interface FIRDatabaseQuery : NSObject

A FIRDatabaseQuery instance represents a query over the data at a particular location.

You create one by calling one of the query methods (queryOrderedByChild:, queryStartingAtValue:, etc.) on a FIRDatabaseReference. The query methods can be chained to further specify the data you are interested in observing

  • observeEventType:withBlock: 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: FIRDataEventType, with block: @escaping (FIRDataSnapshot) -> Void) -> UInt

    Objective-C

    - (FIRDatabaseHandle)
    observeEventType:(FIRDataEventType)eventType
           withBlock:(nonnull void (^)(FIRDataSnapshot *_Nonnull))block;

    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 FIRDataSnapshot.

    Return Value

    A handle used to unregister this block later using removeObserverWithHandle:

  • observeEventType:andPreviousSiblingKeyWithBlock: 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.

    Use removeObserverWithHandle: to stop receiving updates.

    Declaration

    Swift

    func observe(_ eventType: FIRDataEventType, andPreviousSiblingKeyWith block: @escaping (FIRDataSnapshot, String?) -> Void) -> UInt

    Objective-C

    - (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType
           andPreviousSiblingKeyWithBlock:
               (nonnull void (^)(FIRDataSnapshot *_Nonnull,
                                 NSString *_Nullable))block;

    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 FIRDataSnapshot and the previous child’s key.

    Return Value

    A handle used to unregister this block later using removeObserverWithHandle:

  • observeEventType:withBlock: 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 removeObserverWithHandle: to stop receiving updates.

    Declaration

    Swift

    func observe(_ eventType: FIRDataEventType, with block: @escaping (FIRDataSnapshot) -> Void, withCancel cancelBlock: ((Error) -> Void)? = nil) -> UInt

    Objective-C

    - (FIRDatabaseHandle)
    observeEventType:(FIRDataEventType)eventType
           withBlock:(nonnull void (^)(FIRDataSnapshot *_Nonnull))block
     withCancelBlock:(nullable void (^)(NSError *_Nonnull))cancelBlock;

    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 FIRDataSnapshot.

    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 removeObserverWithHandle:

  • observeEventType:andPreviousSiblingKeyWithBlock: 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 removeObserverWithHandle: to stop receiving updates.

    Declaration

    Swift

    func observe(_ eventType: FIRDataEventType, andPreviousSiblingKeyWith block: @escaping (FIRDataSnapshot, String?) -> Void, withCancel cancelBlock: ((Error) -> Void)? = nil) -> UInt

    Objective-C

    - (FIRDatabaseHandle)observeEventType:(FIRDataEventType)eventType
           andPreviousSiblingKeyWithBlock:
               (nonnull void (^)(FIRDataSnapshot *_Nonnull,
                                 NSString *_Nullable))block
                          withCancelBlock:
                              (nullable void (^)(NSError *_Nonnull))cancelBlock;

    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 FIRDataSnapshot 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 removeObserverWithHandle:

  • This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned.

    Declaration

    Swift

    func observeSingleEvent(of eventType: FIRDataEventType, with block: @escaping (FIRDataSnapshot) -> Void)

    Objective-C

    - (void)observeSingleEventOfType:(FIRDataEventType)eventType
                           withBlock:
                               (nonnull void (^)(FIRDataSnapshot *_Nonnull))block;

    Parameters

    eventType

    The type of event to listen for.

    block

    The block that should be called. It is passed the data as a FIRDataSnapshot.

  • This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. In addition, for FIRDataEventTypeChildAdded, FIRDataEventTypeChildMoved, and FIRDataEventTypeChildChanged events, your block will be passed the key of the previous node by priority order.

    Declaration

    Swift

    func observeSingleEvent(of eventType: FIRDataEventType, andPreviousSiblingKeyWith block: @escaping (FIRDataSnapshot, String?) -> Void)

    Objective-C

    - (void)observeSingleEventOfType:(FIRDataEventType)eventType
        andPreviousSiblingKeyWithBlock:
            (nonnull void (^)(FIRDataSnapshot *_Nonnull, NSString *_Nullable))block;

    Parameters

    eventType

    The type of event to listen for.

    block

    The block that should be called. It is passed the data as a FIRDataSnapshot and the previous child’s key.

  • This is equivalent to observeEventType:withBlock:, 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: FIRDataEventType, with block: @escaping (FIRDataSnapshot) -> Void, withCancel cancelBlock: ((Error) -> Void)? = nil)

    Objective-C

    - (void)
    observeSingleEventOfType:(FIRDataEventType)eventType
                   withBlock:(nonnull void (^)(FIRDataSnapshot *_Nonnull))block
             withCancelBlock:(nullable void (^)(NSError *_Nonnull))cancelBlock;

    Parameters

    eventType

    The type of event to listen for.

    block

    The block that should be called. It is passed the data as a FIRDataSnapshot.

    cancelBlock

    The block that will be called if you don’t have permission to access this data

  • This is equivalent to observeEventType:withBlock:, except the block is immediately canceled after the initial data is returned. 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 do not have permission to read data at this location.

    Declaration

    Swift

    func observeSingleEvent(of eventType: FIRDataEventType, andPreviousSiblingKeyWith block: @escaping (FIRDataSnapshot, String?) -> Void, withCancel cancelBlock: ((Error) -> Void)? = nil)

    Objective-C

    - (void)observeSingleEventOfType:(FIRDataEventType)eventType
        andPreviousSiblingKeyWithBlock:(nonnull void (^)(FIRDataSnapshot *_Nonnull,
                                                         NSString *_Nullable))block
                       withCancelBlock:
                           (nullable void (^)(NSError *_Nonnull))cancelBlock;

    Parameters

    eventType

    The type of event to listen for.

    block

    The block that should be called. It is passed the data as a FIRDataSnapshot 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 observeEventType:withBlock:.

    Declaration

    Swift

    func removeObserver(withHandle handle: UInt)

    Objective-C

    - (void)removeObserverWithHandle:(FIRDatabaseHandle)handle;

    Parameters

    handle

    The handle returned by the call to observeEventType:withBlock: which we are trying to remove.

  • Detach all blocks previously attached to this Firebase Database location with observeEventType:withBlock:

    Declaration

    Swift

    func removeAllObservers()

    Objective-C

    - (void)removeAllObservers;
  • By calling keepSynced:YES 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)

    Objective-C

    - (void)keepSynced:(BOOL)keepSynced;

    Parameters

    keepSynced

    Pass YES to keep this location synchronized, pass NO to stop synchronization.

  • queryLimitedToFirst: is used to generate a reference to a limited view of the data at this location. The FIRDatabaseQuery instance returned by queryLimitedToFirst: will respond to at most the first limit child nodes.

    Declaration

    Swift

    func queryLimited(toFirst limit: UInt) -> FIRDatabaseQuery

    Objective-C

    - (nonnull FIRDatabaseQuery *)queryLimitedToFirst:(NSUInteger)limit;

    Parameters

    limit

    The upper bound, inclusive, for the number of child nodes to receive events for

    Return Value

    A FIRDatabaseQuery instance, limited to at most limit child nodes.

  • queryLimitedToLast: is used to generate a reference to a limited view of the data at this location. The FIRDatabaseQuery instance returned by queryLimitedToLast: will respond to at most the last limit child nodes.

    Declaration

    Swift

    func queryLimited(toLast limit: UInt) -> FIRDatabaseQuery

    Objective-C

    - (nonnull FIRDatabaseQuery *)queryLimitedToLast:(NSUInteger)limit;

    Parameters

    limit

    The upper bound, inclusive, for the number of child nodes to receive events for

    Return Value

    A FIRDatabaseQuery instance, limited to at most limit child nodes.

  • queryOrderBy: 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 queryStartingAtValue:, queryEndingAtValue:, or queryEqualToValue:.

    Declaration

    Swift

    func queryOrdered(byChild key: String) -> FIRDatabaseQuery

    Objective-C

    - (nonnull FIRDatabaseQuery *)queryOrderedByChild:(nonnull NSString *)key;

    Parameters

    key

    The child key to use in ordering data visible to the returned FIRDatabaseQuery

    Return Value

    A FIRDatabaseQuery instance, ordered by the values of the specified child key.

  • queryOrderedByKey: 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 queryStartingAtValue:, queryEndingAtValue:, or queryEqualToValue:.

    Declaration

    Swift

    func queryOrderedByKey() -> FIRDatabaseQuery

    Objective-C

    - (nonnull FIRDatabaseQuery *)queryOrderedByKey;

    Return Value

    A FIRDatabaseQuery instance, ordered by child keys.

  • queryOrderedByValue: 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 with queryStartingAtValue:, queryEndingAtValue:, or queryEqualToValue:.

    Declaration

    Swift

    func queryOrderedByValue() -> FIRDatabaseQuery

    Objective-C

    - (nonnull FIRDatabaseQuery *)queryOrderedByValue;

    Return Value

    A FIRDatabaseQuery instance, ordered by child value.

  • queryOrderedByPriority: 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 queryStartingAtValue:, queryEndingAtValue:, or queryEqualToValue:.

    Declaration

    Swift

    func queryOrderedByPriority() -> FIRDatabaseQuery

    Objective-C

    - (nonnull FIRDatabaseQuery *)queryOrderedByPriority;

    Return Value

    A FIRDatabaseQuery instance, ordered by child priorities.

  • queryStartingAtValue: is used to generate a reference to a limited view of the data at this location. The FIRDatabaseQuery instance returned by queryStartingAtValue: will respond to events at nodes with a value greater than or equal to startValue.

    Declaration

    Swift

    func queryStarting(atValue startValue: Any?) -> FIRDatabaseQuery

    Objective-C

    - (nonnull FIRDatabaseQuery *)queryStartingAtValue:(nullable id)startValue;

    Parameters

    startValue

    The lower bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery

    Return Value

    A FIRDatabaseQuery instance, limited to data with value greater than or equal to startValue

  • queryStartingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. The FIRDatabaseQuery instance returned by queryStartingAtValue:childKey will respond to events at nodes with a value greater than startValue, or equal to startValue and with a key greater than or equal to childKey. This is most useful when implementing pagination in a case where multiple nodes can match the startValue.

    Declaration

    Swift

    func queryStarting(atValue startValue: Any?, childKey: String?) -> FIRDatabaseQuery

    Objective-C

    - (nonnull FIRDatabaseQuery *)queryStartingAtValue:(nullable id)startValue
                                              childKey:
                                                  (nullable NSString *)childKey;

    Parameters

    startValue

    The lower bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery

    childKey

    The lower bound, inclusive, for the key of nodes with value equal to startValue

    Return Value

    A FIRDatabaseQuery instance, limited to data with value greater than or equal to startValue

  • queryEndingAtValue: is used to generate a reference to a limited view of the data at this location. The FIRDatabaseQuery instance returned by queryEndingAtValue: will respond to events at nodes with a value less than or equal to endValue.

    Declaration

    Swift

    func queryEnding(atValue endValue: Any?) -> FIRDatabaseQuery

    Objective-C

    - (nonnull FIRDatabaseQuery *)queryEndingAtValue:(nullable id)endValue;

    Parameters

    endValue

    The upper bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery

    Return Value

    A FIRDatabaseQuery instance, limited to data with value less than or equal to endValue

  • queryEndingAtValue:childKey: is used to generate a reference to a limited view of the data at this location. The FIRDatabaseQuery instance returned by queryEndingAtValue:childKey will respond to events at nodes with a value less than endValue, or equal to endValue and with a key less than or equal to childKey. This is most useful when implementing pagination in a case where multiple nodes can match the endValue.

    Declaration

    Swift

    func queryEnding(atValue endValue: Any?, childKey: String?) -> FIRDatabaseQuery

    Objective-C

    - (nonnull FIRDatabaseQuery *)queryEndingAtValue:(nullable id)endValue
                                            childKey:(nullable NSString *)childKey;

    Parameters

    endValue

    The upper bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery

    childKey

    The upper bound, inclusive, for the key of nodes with value equal to endValue

    Return Value

    A FIRDatabaseQuery instance, limited to data with value less than or equal to endValue

  • queryEqualToValue: is used to generate a reference to a limited view of the data at this location. The FIRDatabaseQuery instance returned by queryEqualToValue: will respond to events at nodes with a value equal to the supplied argument.

    Declaration

    Swift

    func queryEqual(toValue value: Any?) -> FIRDatabaseQuery

    Objective-C

    - (nonnull FIRDatabaseQuery *)queryEqualToValue:(nullable id)value;

    Parameters

    value

    The value that the data returned by this FIRDatabaseQuery will have

    Return Value

    A FIRDatabaseQuery instance, limited to data with the supplied value.

  • queryEqualToValue:childKey: is used to generate a reference to a limited view of the data at this location. The FIRDatabaseQuery instance returned by queryEqualToValue:childKey will respond to events at nodes with a value equal to the supplied argument and with their key equal to childKey. There will be at most one node that matches because child keys are unique.

    Declaration

    Swift

    func queryEqual(toValue value: Any?, childKey: String?) -> FIRDatabaseQuery

    Objective-C

    - (nonnull FIRDatabaseQuery *)queryEqualToValue:(nullable id)value
                                           childKey:(nullable NSString *)childKey;

    Parameters

    value

    The value that the data returned by this FIRDatabaseQuery will have

    childKey

    The name of nodes with the right value

    Return Value

    A FIRDatabaseQuery instance, limited to data with the supplied value and the key.

  • ref

    Gets a FIRDatabaseReference for the location of this query.

    Declaration

    Swift

    var ref: FIRDatabaseReference { get }

    Objective-C

    @property (readonly, strong, nonatomic) FIRDatabaseReference *_Nonnull ref;

    Return Value

    A FIRDatabaseReference for the location of this query.