Object Models & Schemas - Swift SDK
On this page
Realm Database applications model data as objects composed of field-value pairs that each contain one or more supported data types. Realm objects behave like regular Swift or Objective-C objects, but they also include additional features like real-time updating data views and reactive change event handlers.
Objects of the same class share an object schema that defines the fields and relationships of those objects. Every realm has a schema that consists of one or more object schemas describing the different forms of object that can be stored in that realm.
To learn how to define a Realm object in Swift or Objective-C, see Define a Realm Object Schema - Swift SDK.
Property Attributes
When you declare the property attributes of a class, you can specify whether or not those properties should be managed by the realm. Managed properties are stored or updated in the database. Conversely, ignored properties are not stored to the database. You can mix managed and ignored properties within a class.
The syntax to mark properties as managed or ignored varies depending on which version of the SDK you use.
Persisted Property Attributes
New in version 10.10.0: The @Persisted
declaration style replaces the @objc dynamic
,
RealmOptional
, and RealmProperty
declaration notations from older
versions of the SDK. For an older version of the SDK, see:
Objective-C Dynamic Property Attributes.
Declare model properties that you want to store to the database as
@Persisted
. This enables them to access the underlying database data.
When you declare any properties as @Persisted
within a class, the other
properties within that class are automatically ignored.
If you mix @Persisted
and @objc dynamic
property declarations within
a class definition, any property attributes marked as @objc dynamic
will
be ignored.
Our Supported Property Types page contains a property declaration cheatsheet.
Objective-C Dynamic Property Attributes
Changed in version 10.10.0: This property declaration information is for versions of the SDK before 10.10.0.
Declare dynamic Realm model properties in the Objective-C runtime. This enables them to access the underlying database data.
You can either:
- Use
@objc dynamic var
to declare individual properties - Use
@objcMembers
to declare a class. Then, declare individual properties withdynamic var
.
Use let
to declare LinkingObjects
, List
, RealmOptional
and
RealmProperty
. The Objective-C runtime cannot represent these
generic properties.
Changed in version 10.8.0: RealmProperty
replaces RealmOptional
Our Supported Property Types page contains a property declaration cheatsheet.
Primary Keys
You can designate a property as the primary key of your class.
Primary keys allow you to efficiently find, update, and upsert objects.
Primary keys are subject to the following limitations:
- You can define only one primary key per object model.
- Primary key values must be unique across all instances of an object in a realm. Realm Database throws an error if you try to insert a duplicate primary key value.
- Primary key values are immutable. To change the primary key value of an object, you must delete the original object and insert a new object with a different primary key value.
- Embedded objects cannot define a primary key.
Indexes
You can create an index on a given property of your model. Indexes speed up some queries, but have a negative impact on insert and update operation speed. Indexes also consume additional space on disk to store the actual index information.
To learn how to add an index to your Realm object, see Index a Property.
Relationships
Realm Database supports to-one, to-many, and inverse relationships. You can specify a relationship by adding a reference or list of references to the related Realm object as a property of your Realm object.
Inverse relationship properties contain the set of Realm objects that point to that object instance through a to-one or to-many relationship. Inverse relationships automatically update themselves with corresponding backlinks. You can find the same set of Realm objects with a manual query, but the inverse relationship field reduces boilerplate query code and capacity for error.
To learn how to add relationships to your Realm object, see Declare Relationship Properties.
For a more detailed explanation of relationships in Realm, see: Relationships - Swift SDK.
Build View Models with Realm
New in version 10.21.0.
You can work with a subset of your Realm Database object's properties by creating a class projection. A class projection is a class that can pass through or transform some or all of your realm object's properties. You can query a class projection, or observe it for changes.
Class projection enables you to create model abstractions for use in your view models. Class projection also simplifies testing with Realm Database.
Swift Structs
Realm Database does not support Swift structs as models for a variety of reasons. Realm's design focuses on “live” objects. This concept is not compatible with value type structs. By design, Realm provides features that are incompatible with these semantics, such as:
- Live data
- Reactive APIs
- Low memory footprint of data
- Good operation performance
- Lazy and cheap access to partial data
- Lack of data serialization/deserialization
- Keeping potentially complex object graphs synchronized
That said, it is sometimes useful to detach objects from their backing realm. This typically isn't an ideal design decision. Instead, developers use this as a workaround for temporary limitations in our library.
You can use key-value coding to initialize an unmanaged object as a copy of a managed object. Then, you can work with that unmanaged object like any other NSObject.
let standaloneModelObject = MyModel(value: persistedModelObject)
Model Inheritance
You can subclass Realm Database models to share behavior between classes, but there are limitations. In particular, Realm does not allow you to:
- Cast between polymorphic classes: subclass to subclass, subclass to parent, parent to subclass
- Query on multiple classes simultaneously: for example, "get all instances of parent class and subclass"
- Multi-class containers:
List
andResults
with a mixture of parent and subclass
Check out the code samples for working around these limitations.
New in version 10.10.0: While you can't mix @Persisted
and @objc dynamic
property declarations
within a class, you can mix the notation styles across base and subclasses.
For example, a base class could have a @Persisted var foo: Int
property,
and a subclass could have an @objc dynamic var bar = 0
property, with
both persisted. However, the @objc dynamic
property would be ignored if
the @Persisted
property were within the same base or subclass.
Summary
- Realm objects are of a type defined as you would any other class.
- The Realm object's schema defines the fields of the object and which fields are optional, which fields have a default value, which fields are indexed, and which fields are ignored.
- You can define to-one, to-many, and inverse relationships in your schema. Inverse relationships automatically form backlinks.
- Realm does not currently support structs. When required, create "in-memory copies" of Realm objects.
- Model inheritance is possible but significantly limited.