Navigation

Collections - iOS SDK

Realm has several types to represent groups of objects, which we call collections. A collection is an object that contains zero or more instances of one Realm type. Realm collections are homogenous: all objects in a collection are of the same type.

You can filter and sort any collection using Realm Database's query engine. Collections are live, so they always reflect the current state of the realm instance on the current thread. You can also listen for changes in the collection by subscribing to collection notifications.

The Swift SDK has the following collections:

  1. Results, a class representing objects retrieved from queries.
  2. List, a class representing to-many relationships in models.
  3. MutableSet, a class representing a to-many relationship.
  4. Map, a class representing an associative array of key-value pairs with unique keys.
  5. LinkingObjects, a class representing inverse relationships in models.
  6. RealmCollection, a protocol defining the common interface of any Realm collection.
  7. AnyRealmCollection, a type-erased class that can forward calls to a concrete Realm collection like Results, List or LinkingObjects.

A Results collection represents the lazily-evaluated results of a query operation. Results are immutable: you cannot add or remove elements to or from the results collection. Results have an associated query that determines their contents.

Tip
See also:

A List represents a to-many relationship between two Realm types. Lists are mutable: within a write transaction, you can add and remove elements to and from a list. Lists are not associated with a query and are usually declared as a property of an object model.

A LinkingObjects collection represents an inverse relationship between two Realm types. You cannot directly add or remove items from a LinkingObjects collection.

All collection types conform to the RealmCollection protocol. This protocol inherits from CollectionType, so you can use a Realm collection as you would any other standard library collections.

Using the RealmCollection protocol, you can write generic code that can operate on any Realm collection:

func operateOn<C: RealmCollection>(collection: C) {
// Collection could be either Results or List
print("operating on collection containing \(collection.count) objects")
}

To store a collection as a property or variable without needing to know the concrete collection type, Swift's type system requires a type-erased wrapper like AnyRealmCollection:

class ViewController {
// let collection: RealmCollection
// ^
// error: protocol 'RealmCollection' can only be used
// as a generic constraint because it has Self or
// associated type requirements
//
// init<C: RealmCollection>(collection: C) where C.ElementType == MyModel {
// self.collection = collection
// }
let collection: AnyRealmCollection<MyModel>
init<C: RealmCollection>(collection: C) where C.ElementType == MyModel {
self.collection = AnyRealmCollection(collection)
}
}

Like live objects, Realm collections are usually live:

  • Live results collections always reflect the current results of the associated query.
  • Live lists always reflect the current state of the relationship on the realm instance.

There are two cases when a collection is not live:

  • The collection is unmanaged. For example, a List property of a Realm object that has not been added to a realm yet or that has been copied from a realm is not live.
  • The collection is frozen.

Combined with collection notifications, live collections enable clean, reactive code. For example, suppose your view displays the results of a query. You can keep a reference to the results collection in your view class, then read the results collection as needed without having to refresh it or validate that it is up-to-date.

Important
Indexes may change

Since results update themselves automatically, do not store the positional index of an object in the collection or the count of objects in a collection. The stored index or count value could be outdated by the time you use it.

Realm Database only runs a query when you actually request the results of that query. This lazy evaluation enables you to write elegant, highly performant code for handling large data sets and complex queries. You can use this fact to chain queries together.

As a result of lazy evaluation, you do not need any special mechanism to limit query results with Realm Database. For example, if your query matches thousands of objects, but you only want to load the first ten, simply access only the first ten elements of the results collection.

Thanks to lazy evaluation, the common task of pagination becomes quite simple. For example, suppose you have a results collection associated with a query that matches thousands of objects in your realm. You display one hundred objects per page. To advance to any page, simply access the elements of the results collection starting at the index that corresponds to the target page.

  • A Realm collection is a homogenous container of zero or more instances of one Realm type.
  • Collections are live (auto-updating) unless they are frozen or they are not part of a realm.
  • Lazy evaluation of results collections means there is no need to design a special query to get limited or paginated results. Perform the query and read from the results collection as needed.
Give Feedback

On this page

  • Overview
  • Collection Types
  • Results
  • List
  • LinkingObjects
  • RealmCollection
  • AnyRealmCollection
  • Collections are Live
  • Results are Lazily Evaluated
  • Limiting Query Results
  • Pagination
  • Summary