Work with Lists of Data on Apple platforms

Get a FIRDatabaseReference

To read or write data from the database, you need an instance of FIRDatabaseReference:

var ref: DatabaseReference!

ref = Database.database().reference()

@property (strong, nonatomic) FIRDatabaseReference *ref;

self.ref = [[FIRDatabase database] reference];

Reading and writing lists

Append to a list of data

Use the childByAutoId method to append data to a list in multiuser applications. The childByAutoId method generates a unique key every time a new child is added to the specified Firebase reference. By using these auto-generated keys for each new element in the list, several clients can add children to the same location at the same time without write conflicts. The unique key generated by childByAutoId is based on a timestamp, so list items are automatically ordered chronologically.

You can use the reference to the new data returned by the childByAutoId method to get the value of the child's auto-generated key or set data for the child. Calling getKey on a childByAutoId reference returns the auto-generated key.

You can use these auto-generated keys to simplify flattening your data structure. For more information, see the data fan-out example.

Listen for child events

Child events are triggered in response to specific operations that happen to the children of a node from an operation such as a new child added through the childByAutoId method or a child being updated through the updateChildValues method.

Each of these together can be useful for listening to changes to a specific node in a database. For example, a social blogging app might use these methods together to monitor activity in the comments of a post, as shown below:

// Listen for new comments in the Firebase database
commentsRef.observe(.childAdded, with: { (snapshot) -> Void in
  self.comments.append(snapshot)
  self.tableView.insertRows(
    at: [IndexPath(row: self.comments.count - 1, section: self.kSectionComments)],
    with: UITableView.RowAnimation.automatic
  )
})
// Listen for deleted comments in the Firebase database
commentsRef.observe(.childRemoved, with: { (snapshot) -> Void in
  let index = self.indexOfMessage(snapshot)
  self.comments.remove(at: index)
  self.tableView.deleteRows(
    at: [IndexPath(row: index, section: self.kSectionComments)],
    with: UITableView.RowAnimation.automatic
  )
})

// Listen for new comments in the Firebase database
[_commentsRef
              observeEventType:FIRDataEventTypeChildAdded
              withBlock:^(FIRDataSnapshot *snapshot) {
                [self.comments addObject:snapshot];
                [self.tableView insertRowsAtIndexPaths:@[
                  [NSIndexPath indexPathForRow:self.comments.count - 1 inSection:kSectionComments]
                ]
                                      withRowAnimation:UITableViewRowAnimationAutomatic];
              }];
// Listen for deleted comments in the Firebase database
[_commentsRef
 observeEventType:FIRDataEventTypeChildRemoved
 withBlock:^(FIRDataSnapshot *snapshot) {
   int index = [self indexOfMessage:snapshot];
   [self.comments removeObjectAtIndex:index];
   [self.tableView deleteRowsAtIndexPaths:@[[NSIndexPath indexPathForRow:index inSection:kSectionComments]]
                         withRowAnimation:UITableViewRowAnimationAutomatic];
 }];

Listen for value events

While listening for child events is the recommended way to read lists of data, there are situations listening for value events on a list reference is useful.

Attaching a FIRDataEventTypeValue observer to a list of data will return the entire list of data as a single DataSnapshot, which you can then loop over to access individual children.

Even when there is only a single match for the query, the snapshot is still a list; it just contains a single item. To access the item, you need to loop over the result:

_commentsRef.observe(.value) { snapshot in
  for child in snapshot.children {
    ...
  }
}

[_commentsRef
              observeEventType:FIRDataEventTypeValue
              withBlock:^(FIRDataSnapshot *snapshot) {
                // Loop over children
                NSEnumerator *children = [snapshot children];
                FIRDataSnapshot *child;
                while (child = [children nextObject]) {
                  // ...
                }
              }];

This pattern can be useful when you want to fetch all children of a list in a single operation, rather than listening for additional child added events.

Sorting and filtering data

You can use the Realtime Database FIRDatabaseQuery class to retrieve data sorted by key, by value, or by the value of a child. You can also filter the sorted result to a specific number of results or a range of keys or values.

Sort data

To retrieve sorted data, start by specifying one of the order-by methods to determine how results are ordered:

You can only use one order-by method at a time. Calling an order-by method multiple times in the same query throws an error.

The following example demonstrates how you could retrieve a list of a user's top posts sorted by their star count:

// My top posts by number of stars
let myTopPostsQuery = ref.child("user-posts").child(getUid()).queryOrdered(byChild: "starCount")

// My top posts by number of stars
FIRDatabaseQuery *myTopPostsQuery = [[[self.ref child:@"user-posts"]
                                      child:[super getUid]]
                                     queryOrderedByChild:@"starCount"];

This query retrieves the user's posts from the path in the database based on their user ID, ordered by the number of stars each post has received. This technique of using IDs as index keys is called data fan out, you can read more about it in Structure Your Database.

The call to the queryOrderedByChild method specifies the child key to order the results by. In this example, posts are sorted by the value of the "starCount" child in each post. Queries can also be ordered by nested children, in case you have data that looks like this:

"posts": {
  "ts-functions": {
    "metrics": {
      "views" : 1200000,
      "likes" : 251000,
      "shares": 1200,
    },
    "title" : "Why you should use TypeScript for writing Cloud Functions",
    "author": "Doug",
  },
  "android-arch-3": {
    "metrics": {
      "views" : 900000,
      "likes" : 117000,
      "shares": 144,
    },
    "title" : "Using Android Architecture Components with Firebase Realtime Database (Part 3)",
    "author": "Doug",
  }
},

In this case, we can order our list elements by values nested under the metrics key by specifying the relative path to the nested child in our queryOrderedByChild call.

 
let postsByMostPopular = ref.child("posts").queryOrdered(byChild: "metrics/views")

 
FIRDatabaseQuery *postsByMostPopular = [[ref child:@"posts"] queryOrderedByChild:@"metrics/views"];

For more information on how other data types are ordered, see How query data is ordered.

Filtering data

To filter data, you can combine any of the limit or range methods with an order-by method when constructing a query.

Unlike the order-by methods, you can combine multiple limit or range functions. For example, you can combine the queryStartingAtValue and queryEndingAtValue methods to limit the results to a specified range of values.

Limit the number of results

You can use the queryLimitedToFirst and queryLimitedToLast methods to set a maximum number of children to be synced for a given callback. For example, if you use queryLimitedToFirst to set a limit of 100, you initially only receive up to 100 FIRDataEventTypeChildAdded callbacks. If you have fewer than 100 items stored in your Firebase database, an FIRDataEventTypeChildAdded callback fires for each item.

As items change, you receive FIRDataEventTypeChildAdded callbacks for items that enter the query and FIRDataEventTypeChildRemoved callbacks for items that drop out of it so that the total number stays at 100.

The following example demonstrates how an example blogging app might retrieve a list of the 100 most recent posts by all users:

// Last 100 posts, these are automatically the 100 most recent
// due to sorting by push() keys
let recentPostsQuery = (ref?.child("posts").queryLimited(toFirst: 100))!

// Last 100 posts, these are automatically the 100 most recent
// due to sorting by push() keys
FIRDatabaseQuery *recentPostsQuery = [[self.ref child:@"posts"] queryLimitedToFirst:100];

Filter by key or value

You can use queryStartingAtValue, queryStartingAfterValue, queryEndingAtValue, queryEndingBeforeValue, and queryEqualToValue to choose arbitrary starting, ending, and equivalence points for queries. This can be useful for paginating data or finding items with children that have a specific value.

How query data is ordered

This section explains how data is sorted by each of the order-by methods in the FIRDatabaseQuery class.

queryOrderedByKey

When using queryOrderedByKey to sort your data, data is returned in ascending order by key.

1. Children with a key that can be parsed as a 32-bit integer come first, sorted in ascending order.
2. Children with a string value as their key come next, sorted lexicographically in ascending order.

queryOrderedByValue

When using queryOrderedByValue, children are ordered by their value. The ordering criteria are the same as in queryOrderedByChild, except the value of the node is used instead of the value of a specified child key.

queryOrderedByChild

When using queryOrderedByChild, data that contains the specified child key is ordered as follows:

1. Children with a nil value for the specified child key come first.
2. Children with a value of false for the specified child key come next. If multiple children have a value of false, they are sorted lexicographically by key.
3. Children with a value of true for the specified child key come next. If multiple children have a value of true, they are sorted lexicographically by key.
4. Children with a numeric value come next, sorted in ascending order. If multiple children have the same numerical value for the specified child node, they are sorted by key.
5. Strings come after numbers and are sorted lexicographically in ascending order. If multiple children have the same value for the specified child node, they are ordered lexicographically by key.
6. Objects come last and are sorted lexicographically by key in ascending order.

Detach listeners

Observers don't automatically stop syncing data when you leave a ViewController. If an observer isn't properly removed, it continues to sync data to local memory and will retain any objects captured in the event handler closure, which can cause memory leaks. When an observer is no longer needed, remove it by passing the associated FIRDatabaseHandle to the removeObserverWithHandle method.

When you add a callback block to a reference, a FIRDatabaseHandle is returned. These handles can be used to remove the callback block.

If multiple listeners have been added to a database reference, each listener is called when an event is raised. In order to stop syncing data at that location, you must remove all observers at a location by calling the removeAllObservers method.

Calling removeObserverWithHandle or removeAllObservers on a listener does not automatically remove listeners registered on its child nodes; you must also be keep track of those references or handles to remove them.

Next Steps

• Learn how to structure data
• Store data offline