Persisted

@propertyWrapper
public struct Persisted<Value> where Value : _Persistable
extension Persisted: Decodable where Value: Decodable
extension Persisted: Encodable where Value: Encodable
extension Persisted: OptionalCodingWrapper where Value: ExpressibleByNilLiteral

@Persisted is used to declare properties on Object subclasses which should be managed by Realm.

Example of usage:

class MyModel: Object {
    // A basic property declaration. A property with no
    // default value supplied will default to `nil` for
    // Optional types, zero for numeric types, false for Bool,
    // an empty string/data, and a new random value for UUID
    // and ObjectID.
    @Persisted var basicIntProperty: Int

    // Custom default values can be specified with the
    // standard Swift syntax
    @Persisted var intWithCustomDefault: Int = 5

    // Properties can be indexed by passing `indexed: true`
    // to the initializer.
    @Persisted(indexed: true) var indexedString: String

    // Properties can set as the class's primary key by
    // passing `primaryKey: true` to the initializer
    @Persisted(primaryKey: true) var _id: ObjectId

    // List and set properties should always be declared
    // with `: List` rather than `= List()`
    @Persisted var listProperty: List<Int>
    @Persisted var setProperty: MutableSet<MyObject>

    // LinkingObjects properties require setting the source
    // object link property name in the initializer
    @Persisted(originProperty: "outgoingLink")
    var incomingLinks: LinkingObjects<OtherModel>

    // Properties which are not marked with @Persisted will
    // be ignored entirely by Realm.
    var ignoredProperty = true
}

Int, Bool, String, ObjectId and Date properties can be indexed by passing indexed: true to the initializer. Indexing a property improves the performance of equality queries on that property, at the cost of slightly worse write performance. No other operations currently use the index.

A property can be set as the class’s primary key by passing primaryKey: true to the initializer. Compound primary keys are not supported, and setting more than one property as the primary key will throw an exception at runtime. Only Int, String, UUID and ObjectID properties can be made the primary key, and when using MongoDB Realm, the primary key must be named _id. The primary key property can only be mutated on unmanaged objects, and mutating it on an object which has been added to a Realm will throw an exception.

Properties can optionally be given a default value using the standard Swift syntax. If no default value is given, a value will be generated on first access: nil for all Optional types, zero for numeric types, false for Bool, an empty string/data, and a new random value for UUID and ObjectID. List and MutableSet properties should not be defined by setting them to a default value of an empty List/MutableSet. Doing so will work, but will result in worse performance when accessing objects managed by a Realm. Similarly, ObjectID properties should not be initialized to ObjectID.generate(), as doing so will result in extra ObjectIDs being generated and then discarded when reading from a Realm.

If a class has at least one @Persisted property, all other properties will be ignored by Realm. This means that they will not be persisted and will not be usable in queries and other operations such as sorting and aggregates which require a managed property.

@Persisted cannot be used anywhere other than as a property on an Object or EmbeddedObject subclass and trying to use it in other places will result in runtime errors.

  • Declares a property which is lazily initialized to the type’s default value.

    Declaration

    Swift

    public init()
  • Declares a property which defaults to the given value.

    Declaration

    Swift

    public init(wrappedValue value: Value)

Available where Value: Decodable

Available where Value: Encodable

Available where Value.PersistedType: _Indexable

Available where Value.PersistedType: _PrimaryKey

Available where Value: LinkingObjectsProtocol

  • Declares a LinkingObjects property with the given origin property name.

    • param originProperty: The name of the property on the linking object type which links to this object.

    Declaration

    Swift

    public init(originProperty: String)