Navigation

Reads

Overview

You can, of course, easily read back the data that you have stored in Realm Database. The standard data access pattern across MongoDB Realm SDKs is to find, filter, and sort objects, in that order. To get the best performance from MongoDB Realm as your app grows and your queries become more complex, design your app’s data access patterns around a solid understanding of Realm Database read characteristics.

Read from Realm Database

A read from a realm generally consists of the following steps:

All query, filter, and sort operations return a results collection. The results collections are live, meaning they always contain the latest results of the associated query.

Note

Open a realm to use the examples on this page. To learn how to open a realm, read the Quick Start doc.

About the examples on this page

The examples on this page use the data model of a project management app that has two Realm object types: Project and Task. A Project has zero or more Tasks.

See the schema for these two classes, Project and Task, below:

const TaskSchema = {
  name: "Task",
  properties: {
    name: "string",
    isComplete: "bool",
    priority: "int",
    progressMinutes: "int",
    assignee: "string?"
  }
};

const ProjectSchema = {
  name: "Project",
  properties: {
    name: "string",
    tasks: "Task[]"
  }
};

Get All Objects

The first step of any read is to get all objects of a certain type in a realm. With this results collection, you can operate on all instances on a type or filter and sort to refine the results.

Example

In order to access all instances of Project and Task, use the following syntax:

// Query realm for all instances of the "Project" type.
const projects = realm.objects("Project");

// Query realm for all instances of the "Task" type.
const tasks = realm.objects("Task");

Filter Results

A filter selects a subset of results based on the value(s) of one or more object properties. Realm Database provides a full-featured query engine you can use to define filters. The most common use case is to find objects where a certain property matches a certain value. Additionally, you can compare strings, aggregate over collections of numbers, and use logical operators to build up complex queries.

Example

In the following example, we use the query engine’s comparison operators to:

  • Find high priority tasks by comparing the value of the priority property value with a threshold number, above which priority can be considered high.
  • Find just-started or short-running tasks by seeing if the progressMinutes property falls within a certain range.
  • Find unassigned tasks by finding tasks where the assignee property is equal to null.
  • Find tasks assigned to specific teammates Ali or Jamie by seeing if the assignee property is in a list of names.
console.log("Number of high priority tasks: "
  + tasks.filtered("priority > 5").length);

console.log(
  "Number of just-started or short-running tasks: " +
    tasks.filtered("1 <= progressMinutes && progressMinutes < 10").length
);

console.log("Number of unassigned tasks: "
  + tasks.filtered("assignee == null").length);

Sort Results

A sort operation allows you to configure the order in which Realm Database returns queried objects. You can sort based on one or more properties of the objects in the results collection.

Realm Database only guarantees a consistent order of results when the results are sorted.

Example

The following code sorts the projects by name in reverse alphabetical order (i.e. “descending” order).

const projects = realm.objects("Project");

// Sort projects by name in ascending order
let projectsSorted = projects.sorted("name");

// Sort projects by name in descending order
projectsSorted = projects.sorted("name", true);

const tasks = realm.objects("Task");

// Sort by priority in descending order and then by name alphabetically
let tasksSorted = tasks.sorted([["priority", true], ["name", false]]);

// You can also sort on the members of linked objects. In this example,
// we sort the dogs by dog's owner's name.
const dogs = realm.objects("Dog");
dogs = dogs.sorted("owner.name");

Read Characteristics

When you design your app’s data access patterns around the following three key characteristics of reads in Realm Database, you can be confident you are reading data as efficiently as possible.

Results Are Not Copies

Results to a query are not copies of your data: modifying the results of a query will modify the data on disk directly. This memory mapping also means that results are live: that is, they always reflect the current state on disk.

See also: Collections are Live.

Results Are Lazy

Realm Database defers execution of a query until you access the results. You can chain several filter and sort operations without requiring extra work to process the intermediate state.

See also: Results are Lazily Evaluated.

References Are Retained

One benefit of Realm Database’s object model is that Realm Database automatically retains all of an object’s relationships as direct references, so you can traverse your graph of relationships directly through the results of a query.

A direct reference, or pointer, allows you to access a related object’s properties directly through the reference.

Other databases typically copy objects from database storage into application memory when you need to work with them directly. Because application objects contain direct references, you are left with a choice: copy the object referred to by each direct reference out of the database in case it’s needed, or just copy the foreign key for each object and query for the object with that key if it’s accessed. If you choose to copy referenced objects into application memory, you can use up a lot of resources for objects that are never accessed, but if you choose to only copy the foreign key, referenced object lookups can cause your application to slow down.

Realm Database bypasses all of this using zero-copy live objects. Realm object accessors point directly into database storage using memory mapping, so there is no distinction between the objects in Realm Database and the results of your query in application memory. Because of this, you can traverse direct references across an entire realm from any query result.

Summary

  • To read from Realm Database, first get all objects of a certain type from the realm, then filter using the query engine, then (optionally) sort the results.
  • When you read, the results are not copies. Instead, through memory mapping, results point directly to the version on disk.
  • Queries are lazily-evaluated.