Protocols

The following protocols are available globally.

Identifiable

  • A protocol which defines a default identity for Realm Objects

    Declaring your Object subclass as conforming to this protocol will supply a default implementation for Identifiable‘s id which works for Realm Objects:

    // Automatically conforms to `Identifiable`
    class MyObjectType: Object, ObjectKeyIdentifiable {
        // ...
    }
    

    You can also manually conform to Identifiable if you wish, but note that using the object’s memory address does not work for managed objects.

    See more

    Declaration

    Swift

    @available(macOS 10.15, iOS 13, tvOS 13, watchOS 6, *)
    public protocol ObjectKeyIdentifiable : Identifiable

Combine

  • A type which can be passed to valuePublisher() or changesetPublisher().

    Declaration

    Swift

    @available(macOS 10.15, watchOS 6.0, iOS 13.0, iOSApplicationExtension 13.0, macOSApplicationExtension 10.15, tvOS 13.0, *)
    public protocol RealmSubscribable

RealmCollection protocol

Public API

  • A type which can be mapped to and from a type which Realm supports.

    To store types in a Realm which Realm doesn’t natively support, declare the type as conforming to either CustomPersistable or FailableCustomPersistable. This requires defining an associatedtype named PersistedType which indicates what Realm type this type will be mapped to, an initializer taking the PersistedType, and a property which returns the appropriate PersistedType. For example, to make URL persistable:

    // Not all strings are valid URLs, so this uses
    // FailableCustomPersistable to handle the case when the data
    // in the Realm isn't a valid URL.
    extension URL: FailableCustomPersistable {
        typealias PersistedType = String
        init?(persistedValue: String) {
            self.init(string: persistedValue)
        }
        var persistableValue: PersistedType {
            self.absoluteString
        }
    }
    

    After doing this, you can define properties using URL:

    class MyModel: Object {
        @Persisted var url: URL
        @Persisted var mapOfUrls: Map<String, URL>
    }
    

    PersistedType can be any of the primitive types supported by Realm or an EmbeddedObject subclass. EmbeddedObject subclasses can be used if you need to store more than one piece of data for your mapped type. For example, to store CGPoint:

    // Define the storage object. A type used for custom mappings
    // does not have to be used exclusively for custom mappings,
    // and more than one type can map to a single embedded object
    // type.
    class CGPointObject: EmbeddedObject {
        @Persisted var double: x
        @Persisted var double: y
    }
    
    // Define the mapping. This mapping isn't failable, as the
    // data stored in the Realm can always be interpreted as a
    // CGPoint.
    extension CGPoint: CustomPersistable {
        typealias PersistedType = CGPointObject
        init(persistedValue: CGPointObject) {
            self.init(x: persistedValue.x, y: persistedValue.y)
        }
        var persistableValue: PersistedType {
            CGPointObject(value: [x, y])
        }
    }
    
    class PointModel: Object {
        // Note that types which are mapped to embedded objects do
        // not have to be optional (but can be).
        @Persisted var point: CGPoint
        @Persisted var line: List<CGPoint>
    }
    

    Queries are performed on the persisted type and not the custom persistable type. Values passed into queries can be of either the persisted type or custom persistable type. For custom persistable types which map to embedded objects, memberwise equality will be used. For examples, realm.objects(PointModel.self).where { $0.point == CGPoint(x: 1, y: 2) } is equivalent to "point.x == 1 AND point.y == 2".

    See more

    Declaration

    Swift

    public protocol CustomPersistable : _CustomPersistable
  • A type which can be mapped to and from a type which Realm supports.

    This protocol is identical to CustomPersistable, except with init?(persistedValue:) instead of init(persistedValue:).

    FailableCustomPersistable types are force-unwrapped in non-Optional contexts, and collapsed to nil in Optional contexts. That is, if you have a value that can’t be converted to a URL, reading a @Persisted var url: URL property will throw an unwrapped failed exception, and reading from Persisted var url: URL? will return nil.

    See more

    Declaration

    Swift

    public protocol FailableCustomPersistable : _CustomPersistable
  • A type which has a custom representation in Realm events.

    By default, objects are serialized to JSON using built-in rules which include every property. If you wish to customize how a class is serialized in events, you can declare it as conforming to this protocol and define customEventRepresentation().

    See more

    Declaration

    Swift

    @objc(RLMCustomEventRepresentable)
    public protocol CustomEventRepresentable
  • Delegate which is used for subscribing to changes on a MongoCollection.watch() stream.

    See more

    Declaration

    Swift

    public protocol ChangeEventDelegate : AnyObject
  • An enum type which can be stored on a Realm Object.

    Only @objc enums backed by an Int can be stored on a Realm object, and the enum type must explicitly conform to this protocol. For example:

    @objc enum MyEnum: Int, RealmEnum {
       case first = 1
       case second = 2
       case third = 7
    }
    
    class MyModel: Object {
       @objc dynamic enumProperty = MyEnum.first
       let optionalEnumProperty = RealmOptional<MyEnum>()
    }
    

    Declaration

    Swift

    public protocol RealmEnum : RealmOptionalType, _RealmSchemaDiscoverable
  • A protocol describing types that can parameterize a RealmOptional.

    Declaration

    Swift

    public protocol RealmOptionalType : _ObjcBridgeable
  • An enum type which can be used with @Persisted and Realm Collections.

    Persisting an enum in Realm requires that it have a raw value and that the raw value by a type which Realm can store. The enum also has to be explicitly marked as conforming to this protocol as Swift does not let us do so implicitly.

    enum IntEnum: Int, PersistableEnum {
       case first = 1
       case second = 2
       case third = 7
    }
    enum StringEnum: String, PersistableEnum {
       case first = "a"
       case second = "b"
       case third = "g"
    }
    

    If the Realm contains a value which is not a valid member of the enum (such as if it was written by a different sync client which disagrees on which values are valid), optional enum properties will return nil, and non-optional properties will abort the process.

    Declaration

    Swift

    public protocol PersistableEnum : MinMaxType, RealmEnum, _PersistableInsideOptional, _RealmCollectionValueInsideOptional, CaseIterable, Comparable, RawRepresentable where Self.RawValue : Comparable
  • A type which can be indexed.

    This protocol is merely a tag and declaring additional types as conforming to it will simply result in runtime errors rather than compile-time errors.

    Declaration

    Swift

    @_marker
    public protocol _Indexable
  • A type which can be made the primary key of an object.

    This protocol is merely a tag and declaring additional types as conforming to it will simply result in runtime errors rather than compile-time errors.

    Declaration

    Swift

    @_marker
    public protocol _PrimaryKey

ProjectionOservable

Keypath Collection Aggregates

Notifications

  • Objects which can be feched from the Realm - Object or Projection

    Declaration

    Swift

    public protocol RealmFetchable : RealmCollectionValue
  • A type which can be stored in a Realm List, MutableSet, Map, or Results.

    Declaring additional types as conforming to this protocol will not make them actually work. Most of the logic for how to store values in Realm is not implemented in Swift and there is currently no extension mechanism for supporting more types.

    Declaration

    Swift

    public protocol RealmCollectionValue : _HasPersistedType, Hashable where Self.PersistedType : RealmCollectionValue
  • A protocol describing types that can parameterize a RealmPropertyType.

    Declaration

    Swift

    public protocol RealmPropertyType : _ObjcBridgeable, _RealmSchemaDiscoverable

MinMaxType

  • Types of properties which can be used with the minimum and maximum value APIs.

    See

    min(ofProperty:), max(ofProperty:)

    Declaration

    Swift

    @_marker
    public protocol MinMaxType

AddableType

  • Types of properties which can be used with the sum and average value APIs.

    See

    sum(ofProperty:), average(ofProperty:)

    Declaration

    Swift

    @_marker
    public protocol AddableType
  • Types of properties which can be directly sorted or distincted.

    See

    sum(ascending:), distinct()

    Declaration

    Swift

    @_marker
    public protocol SortableType
  • Types which have properties that can be sorted or distincted on.

    Declaration

    Swift

    @_marker
    public protocol KeypathSortable

ObservedResults

  • A type which can be used with @ObservedResults propperty wrapper. Children class of Realm Object or Projection. It’s made to specialize the init methods of ObservedResults.

    Declaration

    Swift

    @available(iOS 13.0, macOS 10.15, tvOS 13.0, watchOS 6.0, *)
    public protocol _ObservedResultsValue : RealmCollectionValue
  • Objects of types which conform to ThreadConfined can be managed by a Realm, which will make them bound to a thread-specific Realm instance. Managed objects must be explicitly exported and imported to be passed between threads.

    Managed instances of objects conforming to this protocol can be converted to a thread-safe reference for transport between threads by passing to the ThreadSafeReference(to:) constructor.

    Note that only types defined by Realm can meaningfully conform to this protocol, and defining new classes which attempt to conform to it will not make them work with ThreadSafeReference.

    See more

    Declaration

    Swift

    public protocol ThreadConfined