Object

extension Object: ObservableObject
extension Object: _RealmCollectionValueInsideOptional
extension Object: ThreadConfined

Initializers

  • Creates an unmanaged instance of a Realm object.

    The value argument is used to populate the object. It can be a key-value coding compliant object, an array or dictionary returned from the methods in NSJSONSerialization, or an Array containing one element for each managed property. An exception will be thrown if any required properties are not present and those properties were not defined with default values.

    When passing in an Array as the value argument, all properties must be present, valid and in the same order as the properties defined in the model.

    Call add(_:) on a Realm instance to add an unmanaged object into that Realm.

    Declaration

    Swift

    public convenience init(value: Any)

    Parameters

    value

    The value used to populate the object.

Properties

  • The Realm which manages the object, or nil if the object is unmanaged.

    Declaration

    Swift

    public var realm: Realm? { get }
  • The object schema which lists the managed properties for the object.

    Declaration

    Swift

    public var objectSchema: ObjectSchema { get }
  • Indicates if the object can no longer be accessed because it is now invalid.

    An object can no longer be accessed if the object has been deleted from the Realm that manages it, or if invalidate() is called on that Realm. This property is key-value observable.

    Declaration

    Swift

    dynamic open override var isInvalidated: Bool { get }
  • A human-readable description of the object.

    Declaration

    Swift

    open override var description: String { get }

Object Customization

  • Override this method to specify the name of a property to be used as the primary key.

    Only properties of types String, Int, ObjectId and UUID can be designated as the primary key. Primary key properties enforce uniqueness for each value whenever the property is set, which incurs minor overhead. Indexes are created automatically for primary key properties.

    Warning

    This function is only applicable to legacy property declarations using @objc. When using @Persisted, use @Persisted(primaryKey: true) instead.

    Declaration

    Swift

    @objc
    open class func primaryKey() -> String?

    Return Value

    The name of the property designated as the primary key, or nil if the model has no primary key.

  • Override this method to specify the names of properties to ignore. These properties will not be managed by the Realm that manages the object.

    Warning

    This function is only applicable to legacy property declarations using @objc. When using @Persisted, any properties not marked with @Persisted are automatically ignored.

    Declaration

    Swift

    @objc
    open class func ignoredProperties() -> [String]

    Return Value

    An array of property names to ignore.

  • Returns an array of property names for properties which should be indexed.

    Only string, integer, boolean, Date, and NSDate properties are supported.

    Warning

    This function is only applicable to legacy property declarations using @objc. When using @Persisted, use @Persisted(indexed: true) instead.

    Declaration

    Swift

    @objc
    open class func indexedProperties() -> [String]

    Return Value

    An array of property names.

  • Override this method to specify a map of public-private property names. This will set a different persisted property name on the Realm, and allows using the public name for any operation with the property. (Ex: Queries, Sorting, …). This very helpful if you need to map property names from your Device Sync JSON schema to local property names.

    class Person: Object {
        @Persisted var firstName: String
        @Persisted var birthDate: Date
        @Persisted var age: Int
    
        override class public func propertiesMapping() -> [String : String] {
            ["firstName": "first_name",
             "birthDate": "birth_date"]
        }
    }
    

    Note

    Only property that have a different column name have to be added to the properties mapping dictionary.

    Note

    In a migration block, when enumerating an old property with a public/private name, you will have to use the old column name instead of the public one to retrieve the property value.
    let migrationBlock = { migration, oldSchemaVersion in
        migration.enumerateObjects(ofType: "Person", { oldObj, newObj in
           let oldPropertyValue = oldObj!["first_name"] as! String
           // Use this value in migration
        })
    }
    

    This has to be done as well when renaming a property.

    let migrationBlock = { migration, oldSchemaVersion in
        migration.renameProperty(onType: "Person", from: "first_name", to: "complete_name")
    }
    

    Declaration

    Swift

    open override class func propertiesMapping() -> [String : String]

    Return Value

    A dictionary of public-private property names.

Key-Value Coding & Subscripting

  • Returns or sets the value of the property with the given name.

    Declaration

    Swift

    @objc
    open subscript(key: String) -> Any? { get set }

Notifications

  • Registers a block to be called each time the object changes.

    The block will be asynchronously called after each write transaction which deletes the object or modifies any of the managed properties of the object, including self-assignments that set a property to its existing value.

    For write transactions performed on different threads or in different processes, the block will be called when the managing Realm is (auto)refreshed to a version including the changes, while for local write transactions it will be called at some point in the future after the write transaction is committed.

    If no key paths are given, the block will be executed on any insertion, modification, or deletion for all object first-level properties of the object. Object notifications are shallow by default, any nested property modification will not trigger a notification, unless the key path to that property is specified. If a key path or key paths are provided, then the block will be called for changes which occur only on the provided key paths. For example, if:

    class Dog: Object {
        @Persisted var name: String
        @Persisted var adopted: Bool
        @Persisted var siblings: List<Dog>
    }
    
    // ... where `dog` is a managed Dog object.
    dog.observe(keyPaths: ["adopted"], { changes in
       // ...
    })
    
    • The above notification block fires for changes to the adopted property, but not for any changes made to name.
    • If the observed key path were ["siblings"], then any insertion, deletion, or modification to the siblings list will trigger the block. A change to someSibling.name would not trigger the block (where someSibling is an element contained in siblings)
    • If the observed key path were ["siblings.name"], then any insertion or deletion to the siblings list would trigger the block. For objects contained in the siblings list, only modifications to their name property will trigger the block.

    Note

    Multiple notification tokens on the same object which filter for separate key paths do not filter exclusively. If one key path change is satisfied for one notification token, then all notification token blocks for that object will execute.

    If no queue is given, notifications are delivered via the standard run loop, and so can’t be delivered while the run loop is blocked by other activity. If a queue is given, notifications are delivered to that queue instead. When notifications can’t be delivered instantly, multiple notifications may be coalesced into a single notification.

    Unlike with List and Results, there is no “initial” callback made after you add a new notification block.

    Only objects which are managed by a Realm can be observed in this way. You must retain the returned token for as long as you want updates to be sent to the block. To stop receiving updates, call invalidate() on the token.

    It is safe to capture a strong reference to the observed object within the callback block. There is no retain cycle due to that the callback is retained by the returned token and not by the object itself.

    Warning

    This method cannot be called during a write transaction, or when the containing Realm is read-only.

    Declaration

    Swift

    public func observe<T: RLMObjectBase>(keyPaths: [String]? = nil,
                                          on queue: DispatchQueue? = nil,
                                          _ block: @escaping (ObjectChange<T>) -> Void) -> NotificationToken

    Parameters

    keyPaths

    Only properties contained in the key paths array will trigger the block when they are modified. If nil, notifications will be delivered for any property change on the object. String key paths which do not correspond to a valid a property will throw an exception. See description above for more detail on linked properties.

    queue

    The serial dispatch queue to receive notification on. If nil, notifications are delivered to the current thread.

    block

    The block to call with information about changes to the object.

    Return Value

    A token which must be held for as long as you want updates to be delivered.

  • Registers a block to be called each time the object changes.

    The block will be asynchronously called after each write transaction which deletes the object or modifies any of the managed properties of the object, including self-assignments that set a property to its existing value.

    For write transactions performed on different threads or in different processes, the block will be called when the managing Realm is (auto)refreshed to a version including the changes, while for local write transactions it will be called at some point in the future after the write transaction is committed.

    If no key paths are given, the block will be executed on any insertion, modification, or deletion for all object first-level properties of the object. Object notifications are shallow by default, any nested property modification will not trigger a notification, unless the key path to that property is specified. If a key path or key paths are provided, then the block will be called for changes which occur only on the provided key paths. For example, i

    class Dog: Object {
        @Persisted var name: String
        @Persisted var adopted: Bool
        @Persisted var siblings: List<Dog>
    }
    
    // ... where `dog` is a managed Dog object.
    dog.observe(keyPaths: [\Dog.adopted], { changes in
       // ...
    })
    
    • The above notification block fires for changes to the adopted property, but not for any changes made to name.
    • If the observed key path were [\Dog.siblings], then any insertion, deletion, or modification to the siblings list will trigger the block. A change to someSibling.name would not trigger the block (where someSibling is an element contained in siblings)
    • If the observed key path were [\Dog.siblings.name], then any insertion or deletion to the siblings list would trigger the block. For objects contained in the siblings list, only modifications to their name property will trigger the block.

    Note

    Multiple notification tokens on the same object which filter for separate key paths do not filter exclusively. If one key path change is satisfied for one notification token, then all notification token blocks for that object will execute.

    If no queue is given, notifications are delivered via the standard run loop, and so can’t be delivered while the run loop is blocked by other activity. If a queue is given, notifications are delivered to that queue instead. When notifications can’t be delivered instantly, multiple notifications may be coalesced into a single notification.

    Unlike with List and Results, there is no “initial” callback made after you add a new notification block.

    Only objects which are managed by a Realm can be observed in this way. You must retain the returned token for as long as you want updates to be sent to the block. To stop receiving updates, call invalidate() on the token.

    It is safe to capture a strong reference to the observed object within the callback block. There is no retain cycle due to that the callback is retained by the returned token and not by the object itself.

    Warning

    This method cannot be called during a write transaction, or when the containing Realm is read-only.

    Declaration

    Swift

    public func observe<T: ObjectBase>(keyPaths: [PartialKeyPath<T>],
                                       on queue: DispatchQueue? = nil,
                                       _ block: @escaping (ObjectChange<T>) -> Void) -> NotificationToken

    Parameters

    keyPaths

    Only properties contained in the key paths array will trigger the block when they are modified. If nil, notifications will be delivered for any property change on the object. See description above for more detail on linked properties.

    queue

    The serial dispatch queue to receive notification on. If nil, notifications are delivered to the current thread.

    block

    The block to call with information about changes to the object.

    Return Value

    A token which must be held for as long as you want updates to be delivered.

  • Registers a block to be called each time the object changes.

    The block will be asynchronously called on the given actor’s executor after each write transaction which deletes the object or modifies any of the managed properties of the object, including self-assignments that set a property to its existing value. The block is passed a copy of the object isolated to the requested actor which can be safely used on that actor along with information about what changed.

    For write transactions performed on different threads or in different processes, the block will be called when the managing Realm is (auto)refreshed to a version including the changes, while for local write transactions it will be called at some point in the future after the write transaction is committed.

    Only objects which are managed by a Realm can be observed in this way. You must retain the returned token for as long as you want updates to be sent to the block. To stop receiving updates, call invalidate() on the token.

    By default, only direct changes to the object’s properties will produce notifications, and not changes to linked objects. Note that this is different from collection change notifications. If a non-nil, non-empty keypath array is passed in, only changes to the properties identified by those keypaths will produce change notifications. The keypaths may traverse link properties to receive information about changes to linked objects.

    Warning

    This method cannot be called during a write transaction, or when the containing Realm is read-only.

    Declaration

    Swift

    @available(macOS 10.15, tvOS 13.0, iOS 13.0, watchOS 6.0, *)
    @_unsafeInheritExecutor
    public func observe<A: Actor, T: Object>(
        keyPaths: [String]? = nil, on actor: A,
        _ block: @Sendable @escaping (isolated A, ObjectChange<T>) -> Void
    ) async -> NotificationToken

    Parameters

    actor

    The actor to isolate notifications to.

    block

    The block to call with information about changes to the object.

    Return Value

    A token which must be held for as long as you want updates to be delivered.

  • Registers a block to be called each time the object changes.

    The block will be asynchronously called on the given actor’s executor after each write transaction which deletes the object or modifies any of the managed properties of the object, including self-assignments that set a property to its existing value. The block is passed a copy of the object isolated to the requested actor which can be safely used on that actor along with information about what changed.

    For write transactions performed on different threads or in different processes, the block will be called when the managing Realm is (auto)refreshed to a version including the changes, while for local write transactions it will be called at some point in the future after the write transaction is committed.

    Only objects which are managed by a Realm can be observed in this way. You must retain the returned token for as long as you want updates to be sent to the block. To stop receiving updates, call invalidate() on the token.

    By default, only direct changes to the object’s properties will produce notifications, and not changes to linked objects. Note that this is different from collection change notifications. If a non-nil, non-empty keypath array is passed in, only changes to the properties identified by those keypaths will produce change notifications. The keypaths may traverse link properties to receive information about changes to linked objects.

    Warning

    This method cannot be called during a write transaction, or when the containing Realm is read-only.

    Declaration

    Swift

    @available(macOS 10.15, tvOS 13.0, iOS 13.0, watchOS 6.0, *)
    @_unsafeInheritExecutor
    public func observe<A: Actor, T: Object>(
        keyPaths: [PartialKeyPath<T>], on actor: A,
        _ block: @Sendable @escaping (isolated A, ObjectChange<T>) -> Void
    ) async -> NotificationToken

    Parameters

    actor

    The actor to isolate notifications to.

    block

    The block to call with information about changes to the object.

    Return Value

    A token which must be held for as long as you want updates to be delivered.

Comparison

  • Returns whether two Realm objects are the same.

    Objects are considered the same if and only if they are both managed by the same Realm and point to the same underlying object in the database.

    Note

    Equality comparison is implemented by isEqual(_:). If the object type is defined with a primary key, isEqual(_:) behaves identically to this method. If the object type is not defined with a primary key, isEqual(_:) uses the NSObject behavior of comparing object identity. This method can be used to compare two objects for database equality whether or not their object type defines a primary key.

    Declaration

    Swift

    public func isSameObject(as object: Object?) -> Bool

    Parameters

    object

    The object to compare the receiver to.

  • Indicates if this object is frozen.

    See

    Object.freeze()

    Declaration

    Swift

    public var isFrozen: Bool { get }
  • Returns a frozen (immutable) snapshot of this object.

    The frozen copy is an immutable object which contains the same data as this object currently contains, but will not update when writes are made to the containing Realm. Unlike live objects, frozen objects can be accessed from any thread.

    Warning

    Holding onto a frozen object for an extended period while performing write transaction on the Realm may result in the Realm file growing to large sizes. See Realm.Configuration.maximumNumberOfActiveVersions for more information.

    Warning

    This method can only be called on a managed object.

    Declaration

    Swift

    public func freeze() -> Self
  • Returns a live (mutable) reference of this object.

    This method creates a managed accessor to a live copy of the same frozen object. Will return self if called on an already live object.

    Declaration

    Swift

    public func thaw() -> `Self`?