Realm

public final class Realm

A Realm instance (also referred to as a Realm) represents a Realm database.

Realms can either be stored on disk (see init(path:)) or in memory (see Configuration).

Realm instances are cached internally, and constructing equivalent Realm objects (for example, by using the same path or identifier) produces limited overhead.

If you specifically want to ensure a Realm instance is destroyed (for example, if you wish to open a Realm, check some property, and then possibly delete the Realm file and re-open it), place the code which uses the Realm within an autoreleasepool {} and ensure you have no other strong references to it.

Warning

Realm instances are not thread safe and cannot be shared across threads or dispatch queues. You must construct a new instance for each thread in which a Realm will be accessed. For dispatch queues, this means that you must construct a new instance in each block which is dispatched, as a queue is not guaranteed to run all of its blocks on the same thread.
  • Obtains an instance of the default Realm.

    The default Realm is persisted as default.realm under the Documents directory of your Application on iOS, and in your application’s Application Support directory on OS X.

    The default Realm is created using the default Configuration, which can be changed by setting the Realm.Configuration.defaultConfiguration property to a new value.

    Throws

    An NSError if the Realm could not be initialized.

    Declaration

    Swift

    public convenience init() throws
  • Obtains a Realm instance with the given configuration.

    Throws

    An NSError if the Realm could not be initialized.

    Declaration

    Swift

    public convenience init(configuration: Configuration) throws

    Parameters

    configuration

    A configuration value to use when creating the Realm.

  • Obtains a Realm instance persisted at a specified file URL.

    Throws

    An NSError if the Realm could not be initialized.

    Declaration

    Swift

    public convenience init(fileURL: URL) throws

    Parameters

    fileURL

    The local URL of the file the Realm should be saved at.

  • Asynchronously open a Realm and deliver it to a block on the given queue.

    Opening a Realm asynchronously will perform all work needed to get the Realm to a usable state (such as running potentially time-consuming migrations) on a background thread before dispatching to the given queue. In addition, synchronized Realms wait for all remote content available at the time the operation began to be downloaded and available locally.

    Note

    The returned Realm is confined to the thread on which it was created. Because GCD does not guarantee that queues will always use the same thread, accessing the returned Realm outside the callback block (even if accessed from callbackQueue) is unsafe.

    Declaration

    Swift

    public static func asyncOpen(configuration: Realm.Configuration = .defaultConfiguration,
                                     callbackQueue: DispatchQueue = .main,
                                     callback: @escaping (Realm?, Swift.Error?) -> Void)

    Parameters

    configuration

    A configuration object to use when opening the Realm.

    callbackQueue

    The dispatch queue on which the callback should be run.

    callback

    A callback block. If the Realm was successfully opened, an it will be passed in as an argument. Otherwise, a Swift.Error describing what went wrong will be passed to the block instead.

  • Performs actions contained within the given block inside a write transaction.

    If the block throws an error, the transaction will be canceled and any changes made before the error will be rolled back.

    Only one write transaction can be open at a time for each Realm file. Write transactions cannot be nested, and trying to begin a write transaction on a Realm which is already in a write transaction will throw an exception. Calls to write from Realm instances for the same Realm file in other threads or other processes will block until the current write transaction completes or is cancelled.

    Before beginning the write transaction, write updates the Realm instance to the latest Realm version, as if refresh() had been called, and generates notifications if applicable. This has no effect if the Realm was already up to date.

    Throws

    An NSError if the transaction could not be completed successfully. If block throws, the function throws the propagated ErrorType instead.

    Declaration

    Swift

    public func write(_ block: (() throws -> Void)) throws

    Parameters

    block

    The block containing actions to perform.

  • Begins a write transaction on the Realm.

    Only one write transaction can be open at a time for each Realm file. Write transactions cannot be nested, and trying to begin a write transaction on a Realm which is already in a write transaction will throw an exception. Calls to beginWrite from Realm instances for the same Realm file in other threads or other processes will block until the current write transaction completes or is cancelled.

    Before beginning the write transaction, beginWrite updates the Realm instance to the latest Realm version, as if refresh() had been called, and generates notifications if applicable. This has no effect if the Realm was already up to date.

    It is rarely a good idea to have write transactions span multiple cycles of the run loop, but if you do wish to do so you will need to ensure that the Realm participating in the write transaction is kept alive until the write transaction is committed.

    Declaration

    Swift

    public func beginWrite()
  • Commits all write operations in the current write transaction, and ends the transaction.

    After saving the changes and completing the write transaction, all notification blocks registered on this specific Realm instance are called synchronously. Notification blocks for Realm instances on other threads and blocks registered for any Realm collection (including those on the current thread) are scheduled to be called synchronously.

    You can skip notifiying specific notification blocks about the changes made in this write transaction by passing in their associated notification tokens. This is primarily useful when the write transaction is saving changes already made in the UI and you do not want to have the notification block attempt to re-apply the same changes.

    The tokens passed to this function must be for notifications for this Realm which were added on the same thread as the write transaction is being performed on. Notifications for different threads cannot be skipped using this method.

    Warning

    This method may only be called during a write transaction.

    Throws

    An NSError if the transaction could not be written due to running out of disk space or other i/o errors.

    Declaration

    Swift

    public func commitWrite(withoutNotifying tokens: [NotificationToken] = []) throws
  • Reverts all writes made in the current write transaction and ends the transaction.

    This rolls back all objects in the Realm to the state they were in at the beginning of the write transaction, and then ends the transaction.

    This restores the data for deleted objects, but does not revive invalidated object instances. Any Objects which were added to the Realm will be invalidated rather than becoming unmanaged.

    Given the following code:

    let oldObject = objects(ObjectType).first!
    let newObject = ObjectType()
    
    realm.beginWrite()
    realm.add(newObject)
    realm.delete(oldObject)
    realm.cancelWrite()
    

    Both oldObject and newObject will return true for isInvalidated, but re-running the query which provided oldObject will once again return the valid object.

    KVO observers on any objects which were modified during the transaction will be notified about the change back to their initial values, but no other notifcations are produced by a cancelled write transaction.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Swift

    public func cancelWrite()
  • Indicates whether the Realm is currently in a write transaction.

    Warning

    Do not simply check this property and then start a write transaction whenever an object needs to be created, updated, or removed. Doing so might cause a large number of write transactions to be created, degrading performance. Instead, always prefer performing multiple updates during a single transaction.

    Declaration

    Swift

    public var isInWriteTransaction: Bool
  • Adds or updates an existing object into the Realm.

    Only pass true to update if the object has a primary key. If no object exists in the Realm with the same primary key value, the object is inserted. Otherwise, the existing object is updated with any changed values.

    When added, all child relationships referenced by this object will also be added to the Realm if they are not already in it. If the object or any related objects are already being managed by a different Realm an error will be thrown. Instead, use one of the create functions to insert a copy of a managed object into a different Realm.

    The object to be added must be valid and cannot have been previously deleted from a Realm (i.e. isInvalidated must be false).

    Declaration

    Swift

    public func add(_ object: Object, update: Bool = false)

    Parameters

    object

    The object to be added to this Realm.

    update

    If true, the Realm will try to find an existing copy of the object (with the same primary key), and update it. Otherwise, the object will be added.

  • Adds or updates all the objects in a collection into the Realm.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Swift

    public func add<S: Sequence>(_ objects: S, update: Bool = false) where S.Iterator.Element: Object

    Parameters

    objects

    A sequence which contains objects to be added to the Realm.

    update

    If true, objects that are already in the Realm will be updated instead of added anew.

  • Creates or updates a Realm object with a given value, adding it to the Realm and returning it.

    You may only pass true to update if the object has a primary key. If no object exists in the Realm with the same primary key value, the object is inserted. Otherwise, the existing object is updated with any changed values.

    The value argument can be a Realm object, 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. Do not pass in a LinkingObjects instance, either by itself or as a member of a collection.

    If the object is being created, all required properties that were not defined with default values must be given initial values through the value argument. Otherwise, an Objective-C exception will be thrown.

    If the object is being updated, all properties defined in its schema will be set by copying from value using key-value coding. If the value argument does not respond to value(forKey:) for a given property name (or getter name, if defined), that value will remain untouched. Nullable properties on the object can be set to nil by using NSNull as the updated value, or (if you are passing in an instance of an Object subclass) setting the corresponding property on value to nil.

    If the value argument is an array, all properties must be present, valid and in the same order as the properties defined in the model.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Swift

    public func create<T: Object>(_ type: T.Type, value: Any = [:], update: Bool = false) -> T

    Parameters

    type

    The type of the object to create.

    value

    The value used to populate the object.

    update

    If true, the Realm will try to find an existing copy of the object (with the same primary key), and update it. Otherwise, the object will be added.

    Return Value

    The newly created object.

  • Deletes an object from the Realm. Once the object is deleted it is considered invalidated.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Swift

    public func delete(_ object: Object)

    Parameters

    object

    The object to be deleted.

  • Deletes zero or more objects from the Realm.

    Do not pass in a slice to a Results or any other auto-updating Realm collection type (for example, the type returned by the Swift suffix(_:) standard library method). Instead, make a copy of the objects to delete using Array(), and pass that instead. Directly passing in a view into an auto-updating collection may result in ‘index out of bounds’ exceptions being thrown.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Swift

    public func delete<S: Sequence>(_ objects: S) where S.Iterator.Element: Object

    Parameters

    objects

    The objects to be deleted. This can be a List<Object>, Results<Object>, or any other Swift Sequence whose elements are Objects (subject to the caveats above).

  • Deletes all objects from the Realm.

    Warning

    This method may only be called during a write transaction.

    Declaration

    Swift

    public func deleteAll()
  • Returns all objects of the given type stored in the Realm.

    Declaration

    Swift

    public func objects<Element: Object>(_ type: Element.Type) -> Results<Element>

    Parameters

    type

    The type of the objects to be returned.

    Return Value

    A Results containing the objects.

  • Retrieves the single instance of a given object type with the given primary key from the Realm.

    This method requires that primaryKey() be overridden on the given object class.

    Declaration

    Swift

    public func object<Element: Object, KeyType>(ofType type: Element.Type, forPrimaryKey key: KeyType) -> Element?

    Parameters

    type

    The type of the object to be returned.

    key

    The primary key of the desired object.

    Return Value

    An object of type type, or nil if no instance with the given primary key exists.

  • Adds a notification handler for changes made to this Realm, and returns a notification token.

    Notification handlers are called after each write transaction is committed, independent of the thread or process.

    Handler blocks are called on the same thread that they were added on, and may only be added on threads which are currently within a run loop. Unless you are specifically creating and running a run loop on a background thread, this will normally only be the main thread.

    Notifications can’t be delivered as long as the run loop is blocked by other activity. When notifications can’t be delivered instantly, multiple notifications may be coalesced.

    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.

    Declaration

    Swift

    public func observe(_ block: @escaping NotificationBlock) -> NotificationToken

    Parameters

    block

    A block which is called to process Realm notifications. It receives the following parameters: notification: the incoming notification; realm: the Realm for which the notification occurred.

    Return Value

    A token which must be held for as long as you wish to continue receiving change notifications.

  • Set this property to true to automatically update this Realm when changes happen in other threads.

    If set to true (the default), changes made on other threads will be reflected in this Realm on the next cycle of the run loop after the changes are committed. If set to false, you must manually call refresh() on the Realm to update it to get the latest data.

    Note that by default, background threads do not have an active run loop and you will need to manually call refresh() in order to update to the latest version, even if autorefresh is set to true.

    Even with this property enabled, you can still call refresh() at any time to update the Realm before the automatic refresh would occur.

    Notifications are sent when a write transaction is committed whether or not automatic refreshing is enabled.

    Disabling autorefresh on a Realm without any strong references to it will not have any effect, and autorefresh will revert back to true the next time the Realm is created. This is normally irrelevant as it means that there is nothing to refresh (as managed Objects, Lists, and Results have strong references to the Realm that manages them), but it means that setting autorefresh = false in application(_:didFinishLaunchingWithOptions:) and only later storing Realm objects will not work.

    Defaults to true.

    Declaration

    Swift

    public var autorefresh: Bool
  • Updates the Realm and outstanding objects managed by the Realm to point to the most recent data.

    Declaration

    Swift

    public func refresh() -> Bool

    Return Value

    Whether there were any updates for the Realm. Note that true may be returned even if no data actually changed.

  • Invalidates all Objects, Results, LinkingObjects, and Lists managed by the Realm.

    A Realm holds a read lock on the version of the data accessed by it, so that changes made to the Realm on different threads do not modify or delete the data seen by this Realm. Calling this method releases the read lock, allowing the space used on disk to be reused by later write transactions rather than growing the file. This method should be called before performing long blocking operations on a background thread on which you previously read data from the Realm which you no longer need.

    All Object, Results and List instances obtained from this Realm instance on the current thread are invalidated. Objects and Arrays cannot be used. Results will become empty. The Realm itself remains valid, and a new read transaction is implicitly begun the next time data is read from the Realm.

    Calling this method multiple times in a row without reading any data from the Realm, or before ever reading any data from the Realm, is a no-op. This method may not be called on a read-only Realm.

    Declaration

    Swift

    public func invalidate()
  • Writes a compacted and optionally encrypted copy of the Realm to the given local URL.

    The destination file cannot already exist.

    Note that if this method is called from within a write transaction, the current data is written, not the data from the point when the previous write transaction was committed.

    Throws

    An NSError if the copy could not be written.

    Declaration

    Swift

    public func writeCopy(toFile fileURL: URL, encryptionKey: Data? = nil) throws

    Parameters

    fileURL

    Local URL to save the Realm to.

    encryptionKey

    Optional 64-byte encryption key to encrypt the new file with.

  • Struct that describes the error codes within the Realm error domain. The values can be used to catch a variety of recoverable errors, especially those happening when initializing a Realm instance.

    let realm: Realm?
    do {
        realm = try Realm()
    } catch Realm.Error.incompatibleLockFile {
        print("Realm Browser app may be attached to Realm on device?")
    }
    
    See more

    Declaration

    Swift

    public struct Error
  • Performs the given Realm configuration’s migration block on a Realm at the given path.

    This method is called automatically when opening a Realm for the first time and does not need to be called explicitly. You can choose to call this method to control exactly when and how migrations are performed.

    Declaration

    Swift

    public static func performMigration(for configuration: Realm.Configuration = Realm.Configuration.defaultConfiguration) throws

    Parameters

    configuration

    The Realm configuration used to open and migrate the Realm.

  • Returns whether two Realm instances are equal.

    Declaration

    Swift

    public static func == (lhs: Realm, rhs: Realm) -> Bool
  • A Configuration instance describes the different options used to create an instance of a Realm.

    Configuration instances are just plain Swift structs. Unlike Realms and Objects, they can be freely shared between threads as long as you do not mutate them.

    Creating configuration values for class subsets (by setting the objectClasses property) can be expensive. Because of this, you will normally want to cache and reuse a single configuration value for each distinct configuration rather than creating a new value each time you open a Realm.

    See more

    Declaration

    Swift

    public struct Configuration
  • If the Realm is a partially synchronized Realm, fetch and synchronize the objects of a given object type that match the given query (in string format).

    The results will be returned asynchronously in the callback. Use Results.observe(_:) to be notified to changes to the set of synchronized objects.

    -warning: Partial synchronization is a tech preview. Its APIs are subject to change.

    Declaration

    Swift

    public func subscribe<T: Object>(to objects: T.Type, where: String,
                                         completion: @escaping (Results<T>?, Swift.Error?) -> Void)
  • Returns the same object as the one referenced when the ThreadSafeReference was first created, but resolved for the current Realm for this thread. Returns nil if this object was deleted after the reference was created.

    Warning

    A ThreadSafeReference object must be resolved at most once. Failing to resolve a ThreadSafeReference will result in the source version of the Realm being pinned until the reference is deallocated. An exception will be thrown if a reference is resolved more than once.

    Warning

    Cannot call within a write transaction.

    Note

    Will refresh this Realm if the source Realm was at a later version than this one.

    See

    ThreadSafeReference(to:)

    Declaration

    Swift

    public func resolve<Confined>(_ reference: ThreadSafeReference<Confined>) -> Confined?

    Parameters

    reference

    The thread-safe reference to the thread-confined object to resolve in this Realm.