FIRDatabaseReference

@interface FIRDatabaseReference : FIRDatabaseQuery

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

This class is the starting point for all Firebase Database operations. After you’ve obtained your first FIRDatabaseReference via [FIRDatabase reference], you can use it to read data (ie. observeEventType:withBlock:), write data (ie. setValue:), and to create new FIRDatabaseReferences (ie. child:).

  • Gets a FIRDatabaseReference for the location at the specified relative path. The relative path can either be a simple child key (e.g. ‘fred’) or a deeper slash-separated path (e.g. ‘fred/name/first’).

    Declaration

    Swift

    func child(_ pathString: String) -> FIRDatabaseReference

    Objective-C

    - (nonnull FIRDatabaseReference *)child:(nonnull NSString *)pathString;

    Parameters

    pathString

    A relative path from this location to the desired child location.

    Return Value

    A FIRDatabaseReference for the specified relative path.

  • childByAppendingPath: is deprecated, use child: instead.

    Declaration

    Swift

    func child(byAppendingPath pathString: String) -> FIRDatabaseReference

    Objective-C

    - (nonnull FIRDatabaseReference *)childByAppendingPath:
        (nonnull NSString *)pathString;
  • childByAutoId generates a new child location using a unique key and returns a FIRDatabaseReference to it. This is useful when the children of a Firebase Database location represent a list of items.

    The unique key generated by childByAutoId: is prefixed with a client-generated timestamp so that the resulting list will be chronologically-sorted.

    Declaration

    Swift

    func childByAutoId() -> FIRDatabaseReference

    Objective-C

    - (nonnull FIRDatabaseReference *)childByAutoId;

    Return Value

    A FIRDatabaseReference for the generated location.

  • Write data to this Firebase Database location.

    This will overwrite any data at this location and all child locations.

    Data types that can be set are:

    • NSString – @Hello World
    • NSNumber (also includes boolean) – @YES, @43, @4.333
    • NSDictionary – @{@key: @value, @nested: @{@another: @value} }
    • NSArray

    The effect of the write will be visible immediately and the corresponding events will be triggered. Synchronization of the data to the Firebase Database servers will also be started.

    Passing null for the new value is equivalent to calling remove:; all data at this location or any child location will be deleted.

    Note that setValue: will remove any priority stored at this location, so if priority is meant to be preserved, you should use setValue:andPriority: instead.

    Declaration

    Swift

    func setValue(_ value: Any?)

    Objective-C

    - (void)setValue:(nullable id)value;

    Parameters

    value

    The value to be written.

  • The same as setValue: with a block that gets triggered after the write operation has been committed to the Firebase Database servers.

    Declaration

    Swift

    func setValue(_ value: Any?, withCompletionBlock block: @escaping (Error?, FIRDatabaseReference) -> Void)

    Objective-C

    - (void)setValue:(nullable id)value
        withCompletionBlock:(nonnull void (^)(NSError *_Nullable,
                                              FIRDatabaseReference *_Nonnull))block;

    Parameters

    value

    The value to be written.

    block

    The block to be called after the write has been committed to the Firebase Database servers.

  • The same as setValue: with an additional priority to be attached to the data being written. Priorities are used to order items.

    Declaration

    Swift

    func setValue(_ value: Any?, andPriority priority: Any?)

    Objective-C

    - (void)setValue:(nullable id)value andPriority:(nullable id)priority;

    Parameters

    value

    The value to be written.

    priority

    The priority to be attached to that data.

  • The same as setValue:andPriority: with a block that gets triggered after the write operation has been committed to the Firebase Database servers.

    Declaration

    Swift

    func setValue(_ value: Any?, andPriority priority: Any?, withCompletionBlock block: @escaping (Error?, FIRDatabaseReference) -> Void)

    Objective-C

    - (void)setValue:(nullable id)value
                andPriority:(nullable id)priority
        withCompletionBlock:(nonnull void (^)(NSError *_Nullable,
                                              FIRDatabaseReference *_Nonnull))block;

    Parameters

    value

    The value to be written.

    priority

    The priority to be attached to that data.

    block

    The block to be called after the write has been committed to the Firebase Database servers.

  • Remove the data at this Firebase Database location. Any data at child locations will also be deleted.

    The effect of the delete will be visible immediately and the corresponding events will be triggered. Synchronization of the delete to the Firebase Database servers will also be started.

    remove: is equivalent to calling setValue:nil

    Declaration

    Swift

    func removeValue()

    Objective-C

    - (void)removeValue;
  • The same as remove: with a block that gets triggered after the remove operation has been committed to the Firebase Database servers.

    Declaration

    Swift

    func removeValue(completionBlock block: @escaping (Error?, FIRDatabaseReference) -> Void)

    Objective-C

    - (void)removeValueWithCompletionBlock:
        (nonnull void (^)(NSError *_Nullable, FIRDatabaseReference *_Nonnull))block;

    Parameters

    block

    The block to be called after the remove has been committed to the Firebase Database servers.

  • Sets a priority for the data at this Firebase 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:andPriority: 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 priorities are parsed and ordered as IEEE 754 double-precision floating-point numbers. Keys are always stored as strings and are treated as numbers only when they can be parsed as a 32-bit integer

    Declaration

    Swift

    func setPriority(_ priority: Any?)

    Objective-C

    - (void)setPriority:(nullable id)priority;

    Parameters

    priority

    The priority to set at the specified location.

  • The same as setPriority: with a block that is called once the priority has been committed to the Firebase Database servers.

    Declaration

    Swift

    func setPriority(_ priority: Any?, withCompletionBlock block: @escaping (Error?, FIRDatabaseReference) -> Void)

    Objective-C

    - (void)setPriority:(nullable id)priority
        withCompletionBlock:(nonnull void (^)(NSError *_Nullable,
                                              FIRDatabaseReference *_Nonnull))block;

    Parameters

    priority

    The priority to set at the specified location.

    block

    The block that is triggered after the priority has been written on the servers.

  • Updates the values at the specified paths in the dictionary without overwriting other keys at this location.

    Declaration

    Swift

    func updateChildValues(_ values: [AnyHashable : Any])

    Objective-C

    - (void)updateChildValues:(nonnull NSDictionary *)values;

    Parameters

    values

    A dictionary of the keys to change and their new values

  • The same as update: with a block that is called once the update has been committed to the Firebase Database servers

    Declaration

    Swift

    func updateChildValues(_ values: [AnyHashable : Any], withCompletionBlock block: @escaping (Error?, FIRDatabaseReference) -> Void)

    Objective-C

    - (void)updateChildValues:(nonnull NSDictionary *)values
          withCompletionBlock:
              (nonnull void (^)(NSError *_Nullable,
                                FIRDatabaseReference *_Nonnull))block;

    Parameters

    values

    A dictionary of the keys to change and their new values

    block

    The block that is triggered after the update has been written on the Firebase Database servers

  • 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. - parameter: eventType The type of event to listen for. - parameter: block The block that should be called with initial data and updates. It is passed the data as a FIRDataSnapshot. - returns: A handle used to unregister this block later using removeObserverWithHandle:

    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.

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

  • Removes all observers at the current reference, but does not remove any observers at child references. removeAllObservers must be called again for each child reference where a listener was established to remove the observers.

    Declaration

    Swift

    func removeAllObservers()

    Objective-C

    - (void)removeAllObservers;
  • 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.