Navigation

Collections - .NET SDK

On this page

  • Overview
  • Lists
  • Querying Lists
  • Results Collections
  • Results are Lazily Evaluated
  • Working wth Collections
  • Collections are Live
  • Limiting Query Results
  • Pagination
  • Summary

One of the fundamental building blocks when working with any database is the collection. A Realm collection implements IList<T>, and contains zero or more instances of a Realm type. Like a C# List, a Realm collection is 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.

Realm Database has two kinds of collections: Lists and Results.

Realm objects can contain lists of any supported data type. You create a collection by defining a getter-only property of type IList<T>, where T can be any data type (except other collections).

Deleting an object from the database will remove it from any lists where it existed. Therefore, a list of objects will never contain null objects. However, lists of primitive types can contain null values. If you do not want to allow null values in a list, then either use non-nullable types in the list declaration (for example, use IList<double> instead of IList<double?>), or add the [Required] attribute if the list contains nullable reference types, such as string or byte[].

Important
Not Supported with Sync

Local-only Realm Databases support collections of nullable (optional) values, but Sync does not.

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.

You cannot use Linq to query against a Realm Dictionary. Instead, use a string query:

// Find all Inventory items that have a name of "Prickly Pear"
var certainCacti = realm.All<Inventory>().Filter("Plants.Name == 'Prickly Pear'");
// Find all Inventory items that have a name of "Prickly Pear"
var greenPlants = realm.All<Inventory>().Filter("Plants.Color CONTAINS[c] 'Green'");

A results collection represents the lazily-evaluated results of a query operation. Unlike a List, results are immutable: you cannot add or remove elements on the results collection. This is because the contents of a results collection are determined by a query against the database.

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.

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, however, when a collection is not live:

  • The collection is unmanaged: 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.

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.

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 and therefore are 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.
Give Feedback

On this page

  • Overview
  • Lists
  • Querying Lists
  • Results Collections
  • Results are Lazily Evaluated
  • Working wth Collections
  • Collections are Live
  • Limiting Query Results
  • Pagination
  • Summary