Realms - Swift SDK
On this page
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.
To define a Realm object, see Define a Realm Object Schema - Swift SDK. To open a realm, see Open a Realm Without Sync.
Realm vs Other Databases
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. 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.
Object Types & Schemas
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 Swift 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.
The following schema defines a Dog object type with a string name,
optional string breed, date of birth, and primary key ID.
For code examples that show how to define a Realm object schema in the Swift SDK, see Define a Realm Object Schema - Swift SDK.
Realm Schema
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 Swift SDK automatically adds all classes in your project that derive from RLMObject or RLMEmbeddedObject to the 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.
For code examples that show how to configure and open a realm in the Swift SDK, see Configure & Open a Realm - Swift SDK.
Realm Files
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.
Realm Database creates additional files for each realm. To learn more about these files, see Realm Database Internals.
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.
In-Memory Realms
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.
To open an in-memory realm, see Open an In-Memory Realm.
File Size
Generally, Realm Database takes less space on disk than a comparable SQLite database. Unexpected file growth may be related to App Services referring to outdated data.
Every production application should implement a shouldCompactOnLaunch callback to periodically reduce the realm file size. For more information about compacting a realm, see: Compact a Realm - Swift SDK.
Avoid Pinning Transactions
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.
Consider iOS File Size Limitations
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.
Threading
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:
- Set shouldCompactOnLaunch in the configuration
- Use writeCopy(toFile:encryptionKey:)
Dispatch Queues
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.
App Download File Size
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.
Default Realm
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
Synced Realms
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 an Atlas App Services backend 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 Atlas Device 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 received out of order.
For more information on synced realms, including directions on how to set up sync in a Realm app, see Atlas Device Sync Overview.
For code examples that show how to work with a synced realm in the Swift SDK, see Sync Changes Between Devices - Swift SDK.