FirebaseDatabase Framework Reference

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:).

Getting references to children locations


                    
                    
                    -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

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.

-childByAutoId
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 based on a client-generated timestamp so that the resulting list will be chronologically-sorted.
Declaration
Objective-C

- (nonnull FIRDatabaseReference *)childByAutoId;
Return Value

A FIRDatabaseReference for the generated location.

Writing data


                    
                    
                    -setValue:

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

Objective-C

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

Parameters


                                value

The value to be written.


                    
                    
                    -setValue:withCompletionBlock:

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

Declaration

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.


                    
                    
                    -setValue:andPriority:

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

Declaration

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.


                    
                    
                    -setValue:andPriority:withCompletionBlock:

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

Declaration

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.

-removeValue
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
Objective-C

- (void)removeValue;


                    
                    
                    -removeValueWithCompletionBlock:

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

Declaration

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.


                    
                    
                    -setPriority:

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

Objective-C

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

Parameters


                                priority

The priority to set at the specified location.


                    
                    
                    -setPriority:withCompletionBlock:

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

Declaration

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.


                    
                    
                    -updateChildValues:

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

Declaration

Objective-C

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

Parameters


                                values

A dictionary of the keys to change and their new values


                    
                    
                    -updateChildValues:withCompletionBlock:

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

Declaration

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

Attaching observers to read data


                    
                    
                    -observeEventType:withBlock:

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

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:

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

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

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

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

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

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:


                    
                    
                    -observeSingleEventOfType:withBlock:

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

Declaration

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.


                    
                    
                    -observeSingleEventOfType:andPreviousSiblingKeyWithBlock:

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

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.


                    
                    
                    -observeSingleEventOfType:withBlock:withCancelBlock:

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

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


                    
                    
                    -observeSingleEventOfType:andPreviousSiblingKeyWithBlock:withCancelBlock:

The cancelBlock will be called if you do not have permission to read data at this location.

Declaration

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


                    
                    
                    -getDataWithCompletionBlock:

getDataWithCompletionBlock: 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, falls back to a locally-cached value.

Declaration

Objective-C

- (void)getDataWithCompletionBlock:
    (void (^_Nonnull)(NSError *_Nullable, FIRDataSnapshot *_Nullable))block;

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.

Detaching observers


                    
                    
                    -removeObserverWithHandle:

Detach a block previously attached with observeEventType:withBlock:.

Declaration

Objective-C

- (void)removeObserverWithHandle:(FIRDatabaseHandle)handle;

Parameters


                                handle

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


                    
                    
                    -keepSynced:

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

Objective-C

- (void)keepSynced:(BOOL)keepSynced;

Parameters


                                keepSynced

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

-removeAllObservers
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
Objective-C

- (void)removeAllObservers;

Querying and limiting


                    
                    
                    -queryLimitedToFirst:

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

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:

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

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.


                    
                    
                    -queryOrderedByChild:

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

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
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
Objective-C

- (nonnull FIRDatabaseQuery *)queryOrderedByKey;
Return Value

A FIRDatabaseQuery instance, ordered by child keys.
-queryOrderedByPriority
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
Objective-C

- (nonnull FIRDatabaseQuery *)queryOrderedByPriority;
Return Value

A FIRDatabaseQuery instance, ordered by child priorities.


                    
                    
                    -queryStartingAtValue:

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

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:

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.

Declaration

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


                    
                    
                    -queryStartingAfterValue:

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

Declaration

Objective-C

- (nonnull FIRDatabaseQuery *)queryStartingAfterValue:
    (nullable id)startAfterValue;

Parameters


                                startAfterValue

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

Return Value

A FIRDatabaseQuery instance, limited to data with value greater than startAfterValue


                    
                    
                    -queryStartingAfterValue:childKey:

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

Declaration

Objective-C

- (nonnull FIRDatabaseQuery *)
    queryStartingAfterValue:(nullable id)startAfterValue
                   childKey:(nullable NSString *)childKey;

Parameters

`startAfterValue`	The lower bound, inclusive, for the value of data visible to the returned FIRDatabaseQuery
`childKey`	The lower bound, exclusive, for the key of nodes with value equal to startAfterValue

Return Value

A FIRDatabaseQuery instance, limited to data with value greater than or equal to startAfterValue, or equal to startAfterValue and with a key greater than childKey.


                    
                    
                    -queryEndingAtValue:

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

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:

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.

Declaration

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:

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

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:

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 with a key equal to childKey. There will be at most one node that matches because child keys are unique.

Declaration

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 key of nodes with the right value

Return Value

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

Managing presence


                    
                    
                    -onDisconnectSetValue:

Ensure the data at this location is set to the specified value when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).

onDisconnectSetValue: is especially useful for implementing “presence” systems, where a value should be changed or cleared when a user disconnects so that he appears “offline” to other users.

Declaration

Objective-C

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

Parameters


                                value

The value to be set after the connection is lost.


                    
                    
                    -onDisconnectSetValue:withCompletionBlock:

Ensure the data at this location is set to the specified value when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).

The completion block will be triggered when the operation has been successfully queued up on the Firebase Database servers

Declaration

Objective-C

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

Parameters

`value`	The value to be set after the connection is lost.
`block`	Block to be triggered when the operation has been queued up on the Firebase Database servers


                    
                    
                    -onDisconnectSetValue:andPriority:

Ensure the data at this location is set to the specified value and priority when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).

Declaration

Objective-C

- (void)onDisconnectSetValue:(nullable id)value
                 andPriority:(nonnull id)priority;

Parameters

`value`	The value to be set after the connection is lost.
`priority`	The priority to be set after the connection is lost.


                    
                    
                    -onDisconnectSetValue:andPriority:withCompletionBlock:

Ensure the data at this location is set to the specified value and priority when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).

The completion block will be triggered when the operation has been successfully queued up on the Firebase Database servers

Declaration

Objective-C

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

Parameters

`value`	The value to be set after the connection is lost.
`priority`	The priority to be set after the connection is lost.
`block`	Block to be triggered when the operation has been queued up on the Firebase Database servers

-onDisconnectRemoveValue
Ensure the data at this location is removed when the client is disconnected (due to closing the app, navigating to a new page, or network issues).

onDisconnectRemoveValue is especially useful for implementing “presence” systems.
Declaration
Objective-C

- (void)onDisconnectRemoveValue;


                    
                    
                    -onDisconnectRemoveValueWithCompletionBlock:

Ensure the data at this location is removed when the client is disconnected (due to closing the app, navigating to a new page, or network issues).

onDisconnectRemoveValueWithCompletionBlock: is especially useful for implementing “presence” systems.

Declaration

Objective-C

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

Parameters


                                block

Block to be triggered when the operation has been queued up on the Firebase Database servers


                    
                    
                    -onDisconnectUpdateChildValues:

Ensure the data has the specified child values updated when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).

Declaration

Objective-C

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

Parameters


                                values

A dictionary of child node keys and the values to set them to after the connection is lost.


                    
                    
                    -onDisconnectUpdateChildValues:withCompletionBlock:

Ensure the data has the specified child values updated when the client is disconnected (due to closing the browser, navigating to a new page, or network issues).

Declaration

Objective-C

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

Parameters

`values`	A dictionary of child node keys and the values to set them to after the connection is lost.
`block`	A block that will be called once the operation has been queued up on the Firebase Database servers

-cancelDisconnectOperations
Cancel any operations that are set to run on disconnect. If you previously called onDisconnectSetValue:, onDisconnectRemoveValue:, or onDisconnectUpdateChildValues:, and no longer want the values updated when the connection is lost, call cancelDisconnectOperations:
Declaration
Objective-C

- (void)cancelDisconnectOperations;


                    
                    
                    -cancelDisconnectOperationsWithCompletionBlock:

Cancel any operations that are set to run on disconnect. If you previously called onDisconnectSetValue:, onDisconnectRemoveValue:, or onDisconnectUpdateChildValues:, and no longer want the values updated when the connection is lost, call cancelDisconnectOperations:

Declaration

Objective-C

- (void)cancelDisconnectOperationsWithCompletionBlock:
    (nullable void (^)(NSError *_Nullable,
                       FIRDatabaseReference *_Nonnull))block;

Parameters


                                block

A block that will be triggered once the Firebase Database servers have acknowledged the cancel request.

Manual Connection Management

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

The Firebase Database client automatically maintains a persistent connection to the Firebase Database server, which will remain active indefinitely and reconnect when disconnected. However, the goOffline( ) and goOnline( ) methods may be used to manually control the client connection in cases where a persistent connection is undesirable.

While offline, the Firebase Database client will no longer receive data updates from the server. However, all database operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each operation performed locally will automatically be queued and retried upon reconnection to the Firebase Database server.

To reconnect to the Firebase Database server and begin receiving remote events, see goOnline( ). Once the connection is reestablished, the Firebase Database client will transmit the appropriate data and fire the appropriate events so that your client “catches up” automatically.

Note: Invoking this method will impact all Firebase Database connections.
Declaration
Objective-C

+ (void)goOffline;
+goOnline
Manually reestablish a connection to the Firebase Database server and enable automatic reconnection.

The Firebase Database client automatically maintains a persistent connection to the Firebase Database server, which will remain active indefinitely and reconnect when disconnected. However, the goOffline( ) and goOnline( ) methods may be used to manually control the client connection in cases where a persistent connection is undesirable.

This method should be used after invoking goOffline( ) to disable the active connection. Once reconnected, the Firebase Database client will automatically transmit the proper data and fire the appropriate events so that your client “catches up” automatically.

To disconnect from the Firebase Database server, see goOffline( ).

Note: Invoking this method will impact all Firebase Database connections.
Declaration
Objective-C

+ (void)goOnline;

Transactions


                    
                    
                    -runTransactionBlock:

Performs an optimistic-concurrency transactional update to the data at this location. Your block will be called with a FIRMutableData instance that contains the current data at this location. Your block should update this data to the value you wish to write to this location, and then return an instance of FIRTransactionResult with the new data.

If, when the operation reaches the server, it turns out that this client had stale data, your block will be run again with the latest data from the server.

When your block is run, you may decide to abort the transaction by returning [FIRTransactionResult abort].

Declaration

Objective-C

- (void)runTransactionBlock:
    (nonnull FIRTransactionResult *_Nonnull (^)(FIRMutableData *_Nonnull))block;

Parameters


                                block

This block receives the current data at this location and must return an instance of FIRTransactionResult


                    
                    
                    -runTransactionBlock:andCompletionBlock:

If, when the operation reaches the server, it turns out that this client had stale data, your block will be run again with the latest data from the server.

When your block is run, you may decide to abort the transaction by returning [FIRTransactionResult abort].

Declaration

Objective-C

- (void)runTransactionBlock:(nonnull FIRTransactionResult *_Nonnull (^)(
                                FIRMutableData *_Nonnull))block
         andCompletionBlock:
             (nonnull void (^)(NSError *_Nullable, BOOL,
                               FIRDataSnapshot *_Nullable))completionBlock;

Parameters

`block`	This block receives the current data at this location and must return an instance of FIRTransactionResult
`completionBlock`	This block will be triggered once the transaction is complete, whether it was successful or not. It will indicate if there was an error, whether or not the data was committed, and what the current value of the data at this location is.


                    
                    
                    -runTransactionBlock:andCompletionBlock:withLocalEvents:

If, when the operation reaches the server, it turns out that this client had stale data, your block will be run again with the latest data from the server.

When your block is run, you may decide to abort the transaction by return [FIRTransactionResult abort].

Since your block may be run multiple times, this client could see several immediate states that don’t exist on the server. You can suppress those immediate states until the server confirms the final state of the transaction.

Declaration

Objective-C

- (void)runTransactionBlock:(nonnull FIRTransactionResult *_Nonnull (^)(
                                FIRMutableData *_Nonnull))block
         andCompletionBlock:
             (nullable void (^)(NSError *_Nullable, BOOL,
                                FIRDataSnapshot *_Nullable))completionBlock
            withLocalEvents:(BOOL)localEvents;

Parameters

`block`	This block receives the current data at this location and must return an instance of FIRTransactionResult
`completionBlock`	This block will be triggered once the transaction is complete, whether it was successful or not. It will indicate if there was an error, whether or not the data was committed, and what the current value of the data at this location is.
`localEvents`	Set this to NO to suppress events raised for intermediate states, and only get events based on the final state of the transaction.

Retrieving String Representation

-description
Gets the absolute URL of this Firebase Database location.
Declaration
Objective-C

- (nonnull NSString *)description;
Return Value

The absolute URL of the referenced Firebase Database location.

Properties

parent
Gets a FIRDatabaseReference for the parent location. If this instance refers to the root of your Firebase Database, it has no parent, and therefore parent( ) will return null.
Declaration
Objective-C

@property (nonatomic, strong, readonly, nullable) FIRDatabaseReference *parent;
Return Value

A FIRDatabaseReference for the parent location.
root
Gets a FIRDatabaseReference for the root location
Declaration
Objective-C

@property (nonatomic, strong, readonly) FIRDatabaseReference *_Nonnull root;
Return Value

A new FIRDatabaseReference to root location.
key
Gets the last token in a Firebase Database location (e.g. ‘fred’ in https://SampleChat.firebaseIO-demo.com/users/fred)
Declaration
Objective-C

@property (nonatomic, strong, readonly, nullable) NSString *key;
Return Value

The key of the location this reference points to.
URL
Gets the URL for the Firebase Database location referenced by this FIRDatabaseReference.
Declaration
Objective-C

@property (nonatomic, strong, readonly) NSString *_Nonnull URL;
Return Value

The url of the location this reference points to.
database
Gets the FIRDatabase instance associated with this reference.
Declaration
Objective-C

@property (nonatomic, strong, readonly) FIRDatabase *_Nonnull database;
Return Value

The FIRDatabase object for this reference.