Docs Menu

Object Models & Schemas - Swift SDK

On this page

  • Property Attributes
  • Persisted Property Attributes
  • Objective-C Dynamic Property Attributes
  • Primary Keys
  • Indexes
  • Relationships
  • Build View Models with Realm
  • Swift Structs
  • Model Inheritance
  • Summary

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.

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.

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.

See also:

Our Supported Property Types page contains a property declaration cheatsheet.

Changed in version 10.10.0: This property declaration information is for versions of the SDK before 10.10.0.

Declare dynamic App Services 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.

Changed in version 10.8.0: RealmProperty replaces RealmOptional

See also:

Our Supported Property Types page contains a property declaration cheatsheet.

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.

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.

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.

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.

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:

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)

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

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.

  • 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.
←  Schema Versions & Migrations - Swift SDKApplication Services - Swift SDK →
Give Feedback
© 2022 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.