Object Models - 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.

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.

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 and Results with a mixture of parent and subclass

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)

Persisted 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.

Objective-C Dynamic Property Attributes

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 with dynamic var.

Use let to declare LinkingObjects, List, RealmOptional and RealmProperty. The Objective-C runtime cannot represent these generic properties.

Specify an Optional/Required Property

Specify a Primary Key

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.

Index a Property

You can create an index on a given property of your model. Indexes speed up queries using equality and IN operators. They make insert and update operation speed slightly slower. Indexes use memory and take up more space in the realm file. Each index entry is a minimum of 12 bytes. It's best to only add indexes when optimizing the read performance for specific situations.

Realm supports indexing for string, integer, boolean, Date, UUID, ObjectId, and AnyRealmValue properties.

Ignore a Property

Ignored properties behave exactly like normal properties. They can't be used in queries and won't trigger Realm notifications. You can still observe them using KVO.

Declare Enum Properties

Remap a Property Name

You can map the public name of a property in your object model to a different private name to store in the realm. You might want to do this if your Device Sync schema property names use snake case, for example, while your project uses Swift-idiomatic camel case.

Declare the name you want to use in your project as the @Persisted property on the object model. Then, pass a dictionary containing the public and private values for the property names via the propertiesMapping() function.

In this example, firstName is the public property name we use in the code throughout the project to perform CRUD operations. Using the propertiesMapping() function, we map that to store values using the private property name first_name in the realm. If we write to a synced realm, the Sync schema sees the values stored using the private property name first_name.

class Person: Object {
    @Persisted var firstName = ""
    @Persisted var lastName = ""
    
    override class public func propertiesMapping() -> [String: String] {
        ["firstName": "first_name",
         "lastName": "last_name"]
    }
}

About These Examples

The examples in this section use a simple data set. The two Realm object types are Person and an embedded object Address. A Person has a first and last name, an optional Address, and a list of friends consisting of other Person objects. An Address has a city and country.

See the schema for these two classes, Person and Address, below:

class Person: Object {
    @Persisted var firstName = ""
    @Persisted var lastName = ""
    @Persisted var address: Address?
    @Persisted var friends = List<Person>()
}
class Address: EmbeddedObject {
    @Persisted var city: String = ""
    @Persisted var country = ""
}

How to Define a Class Projection

Define a class projection by creating a class of type Projection. Specify the Object or EmbeddedObject base whose properties you want to use in the class projection. Use the @Projected property wrapper to declare a property that you want to project from a @Persisted property on the base object.

class PersonProjection: Projection<Person> {
    @Projected(\Person.firstName) var firstName // Passthrough from original object
    @Projected(\Person.address?.city) var homeCity // Rename and access embedded object property through keypath
    @Projected(\Person.friends.projectTo.firstName) var firstFriendsName: ProjectedCollection<String> // Collection mapping
}

When you define a class projection, you can transform the original @Persisted property in several ways:

• Passthrough: the property is the same name and type as the original object

• Rename: the property has the same type as the original object, but a different name

• Keypath resolution: use keypath resolution to access properties of the original object, including embedded object properties

• Collection mapping: Project lists or mutable sets of Object s or EmbeddedObject s as a collection of primitive values

• Exclusion: when you use a class projection, the underlying object's properties that are not @Projected through the class projection are excluded. This enables you to watch for changes to a class projection and not see changes for properties that are not part of the class projection.