Navigation

Collections

Overview

One of the fundamental building blocks when working with any database is the collection. A Realm collection is an object that contains zero or more instances of one Realm type. Realm collections are homogenous, i.e. 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.

Realm Database has two kinds of collections: lists and results.

List Collections

A list collection represents a to-many relationship between two Realm types. Lists are mutable: within a write transaction, you can add and remove elements on a list. Lists are not associated with a query.

Results Collections

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

Collections are Live

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 three cases when a collection is not live:

  • The collection is unmanaged, e.g. a List property of a Realm object that has not been added to a realm yet or that has been copied from a realm.
  • The collection is frozen.
  • The collection is part of a snapshot.

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.

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.

Results are Lazily Evaluated

Realm Database only runs a query when you actually request the results of that query, e.g. by accessing elements of the results collection. This lazy evaluation enables you to write elegant, highly performant code for handling large data sets and complex queries.

Limiting Query Results

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.

List vs. Results

When you need a collection, you can use the following rule of thumb to determine whether a list or a results collection is appropriate:

To understand these different use cases, consider whether you should be able to add or remove objects directly. Lists allow you to add and remove objects directly, because you control the relationships. Results collections do not allow you to add or remove objects directly, because their contents are determined by a query.

Example

Consider a Realm type called Person with a field called emails that is a collection of strings representing email addresses. You control this data. Your application needs to add and remove email addresses from your Person instances. Therefore, use a list to define the field type of emails.

On the other hand, when you query the realm for all Persons over the age of 25, it would not make sense for you to add or remove Persons directly to the resulting collection. The contents of that collection only change when the query matches a different set of Persons. Therefore, Realm Database gives you a results collection.

Inverse one-to-many relationship property exception

Since Realm Database automatically determines the contents of implicit inverse relationship collections, you may not add or remove objects from such a collection directly. Therefore, the type of such a one-to-many relationship property is actually a results collection, not a list.

Summary

  • A Realm collection is a homogenous container of zero or more instances of one Realm type.
  • Collections are live, i.e. auto-updating, unless you have frozen them 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.
  • There are two main kinds of collection: lists and results. Lists define the to-many relationships of your Realm types, while results represent the lazily-loaded output of a read operation.
←   Relationships Migrations  →