Navigation

Realms - iOS SDK

On this page

  • Realm vs Other Databases
  • Object Types & Schemas
  • Realm Schema
  • Realm Files
  • In-Memory Realms
  • File Size
  • Avoid Pinning Transactions
  • Consider iOS File Size Limitations
  • Threading
  • Dispatch Queues
  • App Download File Size
  • Default Realm
  • Synced Realms

Realms are the core data structure used to organize data in Realm Database. A realm is a collection of the objects that you use in your application, called Realm objects, as well as additional metadata that describe the objects.

Tip
Define a Realm Object

To define a Realm object, see Define a Realm Object Schema - iOS SDK. To open a realm, see Open a Local Realm.

The Realm data model is similar to both relational and document databases but has distinct differences from both. To underscore these differences, it's helpful to highlight what a realm is not:

A realm is not a single, application-wide database.
Applications based on other database systems generally store all of their data in a single database. Realm apps often split data across multiple realms to organize data more efficiently and to enforce access controls.
A realm is not a relational table.
Normalized tables in relational databases only store one type of information, such as street addresses or items in a store inventory. A realm can contain any number of object types that are relevant to a given domain.
A realm is not a collection of schemaless documents.
Document databases don't necessarily enforce a strict schema for the data in each collection. While similar to documents in form, every Realm object conforms to a schema for a specific object type in the realm. An object cannot contain a property that is not described by its schema.

Every Realm object conforms to a specific object type, which is essentially a class that defines the properties and relationships for objects of that type. Realm guarantees that all objects in a realm conform to the schema for their object type and validates objects whenever they're created, modified, or deleted.

Realm objects are basically regular Swift or Objective-C classes, but they also bring a few additional features like live queries. The iOS SDK memory maps Realm objects directly to native Swift or Objective-C objects, which means there's no need to use a special data access library, such as an ORM. Instead, you can work with Realm objects as you would any other class instance.

Example

The following schema defines a Dog object type with a string name, optional string breed, date of birth, and primary key ID.

Tip
Learn How to Define an Object Schema

For code examples that show how to define a Realm object schema in the iOS SDK, see Define a Realm Object Schema - iOS SDK.

A realm schema is a list of valid object schemas that a realm may contain. Every Realm object must conform to an object type that's included in its realm's schema.

By default, the iOS SDK automatically adds all classes in your project that derive from RLMObject or RLMEmbeddedObject to the realm schema.

Tip
Configure Your Realm Schema

To control which classes Realm adds to a realm schema, see Provide a Subset of Classes to a Realm.

If a realm already contains data when you open it, Realm Database validates each object to ensure that an object schema was provided for its type and that it meets all of the constraints specified in the schema.

Tip
Learn How to Work With a Realm

For code examples that show how to configure and open a realm in the iOS SDK, see Configure & Open a Realm - iOS SDK.

Realm Database stores a binary encoded version of every object and type in a realm in a single .realm file. The file is located at a specific path that you define when you open the realm.

Note
Auxiliary Realm Files

Realm Database creates a few additional files for each realm. These files are primarily for internal use and in general you can ignore them.

  • .realm.lock: The lock file enables synchronization between writes.
  • .realm.note: The note file is a named pipe for inter-thread and inter-process notifications.
  • .realm.management: The management directory contains internal state management files.
Warning
Use Caution When Deleting Realm Files

In some circumstances, such as a client reset scenario, you might need to delete a realm file and its auxiliary files.

If you delete a realm file or any of its auxiliary files while one or more instances of the realm are open, you might corrupt the realm or disrupt sync.

You may safely delete these files when all instances of a realm are closed. Before you delete a realm file, make sure that you back up any important objects as you will lose all unsynced data in the realm.

For guidance on deleting realm files, see Delete a Client Realm File.

You can also open a realm entirely in memory, which will not create a .realm file or its associated auxiliary files. Instead the SDK stores objects in memory while the realm is open and discards them immediately when all instances are closed.

Tip
Open an In-Memory Realm

To open an in-memory realm, see Open an In-Memory Realm.

Generally, Realm Database takes less space on disk than a comparable SQLite database. Unexpected file growth may be related to the Realm referring to outdated data.

Tip
See also:

If file size negatively impacts performance, you may want to compact the file: Compact a Realm.

Realm ties read transaction lifetimes to the memory lifetime of realm instances. Avoid "pinning" old Realm transactions. Use auto-refreshing realms, and wrap the use of Realm APIs from background threads in explicit autorelease pools.

A large realm file can impact the performance and reliability of your app. Any single realm file cannot be larger than the amount of memory your application would be allowed to map in iOS. This limit depends on the device and on how fragmented the memory space is at that point in time.

If you need to store more data, map it over multiple realm files.

Realm updates the version of your data that it accesses at the start of a run loop iteration. While this gives you a consistent view of your data, it has file size implications.

Imagine this scenario:

  • Thread A: Read some data from a realm, and then block the thread on a long-running operation.
  • Thread B: Write data on another thread.
  • Thread A: The version on the read thread isn't updated. Realm has to hold intermediate versions of the data, growing in file size with every write.

To avoid this issue, call invalidate() on the realm. This tells the realm that you no longer need the objects you've read so far. This frees realm from tracking intermediate versions of those objects. The next time you access it, realm will have the latest version of the objects.

You can also use these two methods to compact your Realm:

When accessing Realm using Grand Central Dispatch, you may see similar file growth. A dispatch queue's autorelease pool may not drain immediately upon executing your code. Realm cannot reuse intermediate versions of the data until the dispatch pool deallocates the realm object. Use an explicit autorelease pool when accessing realm from a dispatch queue.

Realm Database should only add around 5 to 8 MB to your app’s download size. The releases we distribute are significantly larger because they include support for the iOS, watchOS and tvOS simulators, some debug symbols, and bitcode, all of which are stripped by the App Store automatically when apps are downloaded.

Calling Realm() or RLMRealm opens the default realm. This method returns a realm object that maps to a file named default.realm. You can find this file:

  • iOS: in the Documents folder of your app
  • macOS: in the Application Support folder of your app

You can configure a realm to automatically synchronize data between many devices that each have their own local copy of the data. Synced realms use a different configuration than local-only realms and require a MongoDB Realm app to handle the synchronization process.

Applications can always create, modify, and delete synced realm objects locally, even when offline. Whenever a network connection is available, the Realm SDK opens a connection to an application server and syncs changes to and from other clients. The Realm sync protocol and server-side operational transforms guarantee that all fully synced instances of a realm see exactly the same data, even if some changes occurred offline and/or were receieved out of order.

Tip
Learn How to Configure and Use Sync

For more information on synced realms, including directions on how to set up sync in a MongoDB Realm app, see Realm Sync Overview.

For code examples that show how to work with a synced realm in the iOS SDK, see Sync Changes Between Devices - iOS SDK.

Give Feedback

On this page

  • Realm vs Other Databases
  • Object Types & Schemas
  • Realm Schema
  • Realm Files
  • In-Memory Realms
  • File Size
  • Avoid Pinning Transactions
  • Consider iOS File Size Limitations
  • Threading
  • Dispatch Queues
  • App Download File Size
  • Default Realm
  • Synced Realms