realm-swift Documentation

Technical Documentation: realm/realm-swift

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

About Realm Database

Realm is a mobile database that runs directly inside phones, tablets or wearables.
This repository holds the source code for the iOS, macOS, tvOS & watchOS versions of Realm Swift & Realm Objective-C.

Why Use Realm Copy Chapter

• Intuitive to Developers: Realm’s object-oriented data model is simple to learn, doesn’t need an ORM, and lets you write less code.
• Built for Mobile: Realm is fully-featured, lightweight, and efficiently uses memory, disk space, and battery life.
• Designed for Offline Use: Realm’s local database persists data on-disk, so apps work as well offline as they do online.

Object-Oriented: Streamline Your Code Copy Chapter

Realm was built for mobile developers, with simplicity in mind. The idiomatic, object-oriented data model can save you thousands of lines of code.

// Define your models like regular Swift classes
class Dog: Object {
    @Persisted var name: String
    @Persisted var age: Int
}
class Person: Object {
    @Persisted(primaryKey: true) var _id: String
    @Persisted var name: String
    @Persisted var age: Int
    // Create relationships by pointing an Object field to another Class
    @Persisted var dogs: List<Dog>
}
// Use them like regular Swift objects
let dog = Dog()
dog.name = "Rex"
dog.age = 1
print("name of dog: \(dog.name)")

// Get the default Realm
let realm = try! Realm()
// Persist your data easily with a write transaction
try! realm.write {
    realm.add(dog)
}

Live Objects: Build Reactive Apps Copy Chapter

Realm’s live objects mean data updated anywhere is automatically updated everywhere.

// Open the default realm.
let realm = try! Realm()

var token: NotificationToken?

let dog = Dog()
dog.name = "Max"

// Create a dog in the realm.
try! realm.write {
    realm.add(dog)
}

//  Set up the listener & observe object notifications.
token = dog.observe { change in
    switch change {
    case .change(let properties):
        for property in properties {
            print("Property '\(property.name)' changed to '\(property.newValue!)'");
        }
    case .error(let error):
        print("An error occurred: (error)")
    case .deleted:
        print("The object was deleted.")
    }
}

// Update the dog's name to see the effect.
try! realm.write {
    dog.name = "Wolfie"
}

SwiftUI Copy Section

Realm integrates directly with SwiftUI, updating your views so you don't have to.

struct ContactsView: View {
    @ObservedResults(Person.self) var persons

    var body: some View {
        List {
            ForEach(persons) { person in
                Text(person.name)
            }
            .onMove(perform: $persons.move)
            .onDelete(perform: $persons.remove)
        }.navigationBarItems(trailing:
            Button("Add") {
                $persons.append(Person())
            }
        )
    }
}

Fully Encrypted Copy Chapter

Data can be encrypted in-flight and at-rest, keeping even the most sensitive data secure.

// Generate a random encryption key
var key = Data(count: 64)
_ = key.withUnsafeMutableBytes { (pointer: UnsafeMutableRawBufferPointer) in
    guard let baseAddress = pointer.baseAddress else {
        fatalError("Failed to obtain base address")
    }
    SecRandomCopyBytes(kSecRandomDefault, 64, baseAddress)
}

// Add the encryption key to the config and open the realm
let config = Realm.Configuration(encryptionKey: key)
let realm = try Realm(configuration: config)

// Use the Realm as normal
let dogs = realm.objects(Dog.self).filter("name contains 'Fido'")

Getting Started Copy Chapter

We support installing Realm via Swift Package Manager, CocoaPods, Carthage, or by importing a dynamic XCFramework.

For more information, see our Quick Start.

Documentation Copy Chapter

The documentation can be found in the docs/ directory.

The API reference can be generated from source using
jazzy by running sh build.sh docs from the root of this repository.

Getting Help Copy Chapter

• Need help with your code?: Look for previous questions with therealm tag on Stack Overflow or ask a new question. For general discussion that might be considered too broad for Stack Overflow, use the Community Forum.
• Have a bug to report? Open a GitHub issue. If possible, include the version of Realm, a full log, the Realm file, and a project that shows the issue.
• Have a feature request? Open a GitHub issue. Tell us what the feature should do and why you want the feature.

Building Realm Copy Chapter

In case you don't want to use the precompiled version, you can build Realm yourself from source.

Prerequisites:

• Building Realm requires Xcode 15.3 or newer.
• Building Realm documentation requires jazzy

Once you have all the necessary prerequisites, building Realm just takes a single command: sh build.sh build.
You'll need an internet connection the first time you build Realm to download the core binary.
This will produce Realm.xcframework and RealmSwift.xcframework in build/Release/.

Run sh build.sh help to see all the actions you can perform (build ios/osx, generate docs, test, etc.).

Contributing Copy Chapter

See CONTRIBUTING.md for more details!

Code of Conduct Copy Chapter

This project adheres to the MongoDB Code of Conduct.
By participating, you are expected to uphold this code. Please report
unacceptable behavior to [email protected].

License Copy Chapter

Realm Objective-C & Realm Swift are published under the Apache 2.0 license.
Realm Core is also published under the Apache 2.0 license and is available
here.

Feedback Copy Chapter

If you use Realm and are happy with it, please consider sending out a tweet mentioning @realm to share your thoughts!

And if you don't like it, please let us know what you would like improved, so we can fix it!

Overview (`docs/README.md`) Copy Section

Realm SDK for Swift

Use the Realm SDK for Swift to develop iOS, macOS, watchOS and tvOS
apps in Swift and Objective-C.

Get Started with the Swift SDK Copy Chapter

These docs contain minimal-explanation code examples of how to work
with the Swift SDK.

To get started with SwiftUI, see: SwiftUI Quick Start

Install the Swift SDK Copy Section

Use Swift Package Manager, CocoaPods, or Carthage to
Install the SDK for iOS, macOS, tvOS, and watchOS in your project.

Import RealmSwift in your project files to get started.

Define an Object Schema Copy Section

Use Swift to idiomatically define an object schema.

Open a Database Copy Section

The SDK's database - Realm - stores objects in files on your
device. Or you can open an in-memory database which does not
create a file.

Configure and open a database to specify the options for your database file.

Read and Write Data Copy Section

• Create, read, update, and delete objects from the device database.
• Filter data using the SDK's type-safe .where syntax, or construct an NSPredicate.

React to Changes Copy Section

Live objects mean that your data is always up-to-date.
You can register a notification handler
to watch for changes and perform some logic, such as updating
your UI. Or in SwiftUI, use the Swift property wrappers
to update Views when data changes.

Realm SwiftUI Copy Chapter

The Swift SDK offers property wrappers and convenience
features designed to make it easier to work with SwiftUI.
For example View code that demonstrates common SwiftUI
patterns, check out the SwiftUI documentation.

struct SearchableDogsView: View {
    @ObservedResults(Dog.self) var dogs
    @State private var searchFilter = ""

    var body: some View {
        NavigationView {
            // The list shows the dogs in the realm.
            List {
                ForEach(dogs) { dog in
                    DogRow(dog: dog)
                }
            }
            .searchable(text: $searchFilter,
                        collection: $dogs,
                        keyPath: \.name) {
                ForEach(dogs) { dogsFiltered in
                    Text(dogsFiltered.name).searchCompletion(dogsFiltered.name)
                }
            }
        }
    }
}

Generating API Reference Docs Copy Chapter

You can generate the API docs locally by running sh build.sh docs from the root of this repository.
This requires installation of jazzy.
You will find the output in docs/swift_output/ and docs/objc_output/.

Overview (`examples/README.md`) Copy Section

Realm Examples

Included in this folder are sample iOS/OSX apps using Realm.

iOS (Objective-C) Copy Chapter

The following examples are located in the ios/objc/RealmExamples.xcodeproj project:

Simple Copy Section

This app covers several introductory concepts about Realm. Without any UI distractions, just a little console output.

TableView Copy Section

This app demonstrates how Realm can be the data source for UITableViews.

You can add rows by tapping the add button and remove rows by swiping right-to-left.

The application also demonstrates how to import data in a background thread.

GroupedTableView Copy Section

A sample app to demonstrate how to use Realm to populate a table view with sections.

Migration Copy Section

This example showcases Realm's migration features.

REST Copy Section

Using data from FourSquare, this example demonstrates how to populate a Realm with external json data.

Encryption Copy Section

This simple app shows how to use an encrypted realm.

Backlink Copy Section

This simple app demonstrates how to define models with inverse relationships using -linkingObjectsOfClass:forProperty:.

Installation Instructions

1. Download the macOS version of the Realm Mobile Platform.
2. Run a local instance of the Realm Mobile Platform.
3. Open the Realm Object Server Dashboard in your browser by visiting 'http://localhost:9080'.
4. Create a user account with the email '[email protected]' and the password 'password'.
5. Build the Draw app and deploy it to iOS devices on the same network as your Mac.

iOS (Swift) Copy Chapter

In the ios/swift/RealmExamples.xcodeproj project, you will find the following examples:

GettingStarted.playground Copy Section

This is a Swift Playground that goes over a few Realm basics.

Simple Copy Section

This app covers several introductory concepts about Realm. Without any UI distractions, just a little console output.

TableView Copy Section

This app demonstrates how Realm can be the data source for UITableViews.

You can add rows by tapping the add button and remove rows by swiping right-to-left.

The application also demonstrates how to import data in a background thread.

GroupedTableView Copy Section

A sample app to demonstrate how to use Realm to populate a table view with sections.

Migration Copy Section

This example showcases Realm's migration features.

Encryption Copy Section

This simple app shows how to use an encrypted realm.

Backlink Copy Section

This simple app demonstrates how to define models with inverse relationships using linkingObjectsOfClass(_:forProperty:).

Projections Copy Section

This app demonstrates how to define Projection on Realm Object and how to use it in SwiftUI application.

AppClip / AppClipParent Copy Section

These two targets demonstrate how to use Realm to persist data between an App Clip and its parent.

Example Usage

For the purpose of this example, the app clip invocation and parent application download is simulated by running each target.

For more information on complete App Clip flow see: Responding to invocations and Launch Experience.

Note: When testing App Group Entitlements on MacOS (including the iOS simulator), containerURL(forSecurityApplicationGroupIdentifier:) will always return the shared directory URL, even when the group identifier is invalid. Be sure to test on physical devices with non-simulated iOS for expected security behavior. See Return Value.

OSX (Objective-C) Copy Chapter

In the osx/objc/RealmExamples.xcodeproj project, you will find the following examples:

JSONImport Copy Section

This is a small OS X command-line program which demonstrates how to import data from JSON into a Realm.

Open the project in Xcode, and press "Run" to build and run the program. It will write output to the console.

Installation Examples Copy Chapter

The installation/ directory contains example Xcode projects demonstrating how
to install Realm Objective-C and Realm Swift from all available methods defined
in https://www.mongodb.com/docs/atlas/device-sdks/sdk/swift/install/#install-realm-for-ios--macos--tvos--and-watchos.

tvOS (Objective-C) Copy Chapter

DownloadCache Copy Section

A tvOS app that demonstrates how to use Realm to store data and display data from a REST API.

PreloadedData Copy Section

A tvOS app that demonstrates how to use a Realm file included in your app bundle.

tvOS (Swift) Copy Chapter

DownloadCache Copy Section

A tvOS app that demonstrates how to use Realm to store data and display data from a REST API.

PreloadedData Copy Section

A tvOS app that demonstrates how to use a Realm file included in your app bundle.

Overview (`plugin/README.md`) Copy Section

Realm Plugin

The Realm Plugin for Xcode adds several useful features for developing with Realm:

1. A LLDB script which adds support for inspecting the property values of
   persisted RLMObjects in the debugger pane.
2. File templates for RLMObject subclasses.
3. A menu item in Xcode's 'File' menu to quickly launch the Realm Browser.
   Note that this item will only appear in Xcode 7 and in unsigned versions of
   Xcode 8 or later (not recommended).

To install the Realm Plugin, open RealmPlugin.xcodeproj and Build. This will
prompt for your password. After building the plugin, restart Xcode.

Overview (`examples/ios/swift/Migration/README.md`) Copy Section

Migration Examples

The Migration project shows several examples of migrations and migration blocks.

The purpose of this example is to provide a more in depth view of certain problems and pitfalls users might face when
migrations get more complex and the number of versions increases.

How to use the example Copy Chapter

You can build and run the project as is. Migrations from all prior version to the current version will be checked:

• v0 -> v5
• v1 -> v5
• v2 -> v5
• v3 -> v5
• v4 -> v5

The files to look at are located in the Examples folder. Every file contains an extract of everything necessary for
this version (schema version, objects, migration and migration checks).

If you want to compare older versions among each other (i.e. v2 -> v3) you can do so by enabling the schema version, for example:

• Deactivate version 5 by setting #define SCHEMA_VERSION_5 1 to #define SCHEMA_VERSION_5 0 in Example_v5.h.
• Activate version 3 by seting #define SCHEMA_VERSION_3 0 to #define SCHEMA_VERSION_3 1 in Example_v3.h.

Example Projects (`docs/example-projects.md`) Copy Section

Realm SDK Example Projects

Explore engineering and expert-provided example projects to learn best
practices and common development patterns for the Swift SDK.

Install (`docs/install.md`) Copy Section

Install the SDK for iOS, macOS, tvOS, and watchOS

Overview Copy Chapter

Realm SDK for Swift enables you to build iOS, macOS, tvOS,
and watchOS applications using either the Swift or Objective-C programming
languages. This page details how to install the SDK in your project and get
started.

Prerequisites Copy Chapter

Before getting started, ensure your development environment
meets the following prerequisites:

• Your project uses an Xcode version and minimum OS version listed in the
  OS Support section of this page.
• Reflection is enabled in your project. The Swift SDK uses reflection to
  determine your model's properties. Your project must not set
  SWIFT_REFLECTION_METADATA_LEVEL = none, or the SDK cannot see properties
  in your model. Reflection is enabled by default if your project does
  not specifically set a level for this setting.

Installation Copy Chapter

You can use SwiftPM, CocoaPods, or Carthage to add the
Swift SDK to your project.

Tip:
The SDK uses Realm Core database for device data persistence. When you
install the Swift SDK, the package names reflect Realm naming.

Swiftpm

Add Package Dependency

In Xcode, select File > Add Packages....

Specify the Repository

Copy and paste the following into the search/input box.

https://github.com/realm/realm-swift.git

Specify Options

In the options for the realm-swift package, we recommend setting
the Dependency Rule to Up to Next Major Version,
and enter the current Realm Swift SDK version . Then, click Add Package.

Select the Package Products

Version changed: 10.49.3
Instead of adding both, only add one package.

Select either RealmSwift or Realm, then click Add Package.

• If you use Swift or Swift and Objective-C APIs, add RealmSwift.
• If you use only Objective-C APIs, add Realm.

(Optional) Build RealmSwift as a Dynamic Framework

To use the Privacy Manifest supplied by the SDK, build RealmSwift
as a dynamic framework. If you build RealmSwift as a static
framework, you must supply your own Privacy Manifest.

To build RealmSwift as a dynamic framework:

1. In your project Targets, select your build target.
2. Go to the General tab.
3. Expand the Frameworks and Libraries element.
4. For the RealmSwift framework, change the
   Embed option from "Do Not Embed" to "Embed & Sign."

Now, Xcode builds RealmSwift dynamically, and can provide the
SDK-supplied Privacy Manifest.

Cocoapods

If you are installing with CocoaPods, you need CocoaPods 1.10.1 or later.

Update the CocoaPods repositories

On the command line, run pod repo update to ensure
CocoaPods can access the latest available Realm versions.

Initialize CocoaPods for Your Project

If you do not already have a Podfile for your project,
run pod init in the root directory of your project to
create a Podfile for your project. A Podfile allows you
to specify project dependencies to CocoaPods.

Add the SDK as a Dependency in Your Podfile

Objective-C

Add the line pod 'Realm', '~>10' to your main and test
targets.

Add the line use_frameworks! as well if it is not
already there.

When done, your Podfile should look something like this:

# Uncomment the next line to define a global platform for your project
# platform :ios, '11.0'

target 'MyDeviceSDKProject' do
# Comment the next line if you don't want to use dynamic frameworks
use_frameworks!

# Pods for MyDeviceSDKProject
pod 'Realm', '~>10'

target 'MyRealmProjectTests' do
   inherit! :search_paths
   # Pods for testing
   pod 'Realm', '~>10'
end

end

Swift

Add the line use_frameworks! if it is not
already there.

Add the line pod 'RealmSwift', '~>10' to your main and test
targets.

When done, your Podfile should look something like this:

platform :ios, '12.0'

target 'MyDeviceSDKProject' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!

  # Pods for MyDeviceSDKProject
  pod 'RealmSwift', '~>10'

end

Install the Dependencies

From the command line, run pod install to fetch the
dependencies.

Use the CocoaPods-Generated File

Use the CocoaPods-Generated .xcworkspace File

CocoaPods generates an .xcworkspace file for you. This
file has all of the dependencies configured. From now on,
open this file -- not the .xcodeproj file -- to work
on your project.

Carthage

If you are installing with Carthage, you need Carthage 0.33 or later.

Add the SDK as a Dependency in Your Cartfile

Add the SDK as a dependency by appending the line github "realm/realm-swift" to your Cartfile.

You can create a Cartfile or append to an existing one by
running the following command in your project directory:

echo 'github "realm/realm-swift"' >> Cartfile

Install the Dependencies

From the command line, run carthage update --use-xcframeworks
to fetch the dependencies.

Add the Frameworks to Your Project

Carthage places the built dependencies in the Carthage/Build
directory.

Open your project's xcodeproj file in Xcode. Go to
the Project Navigator panel and click your application
name to open the project settings editor. Select the
General tab.

In Finder, open the Carthage/Build/ directory. Drag the
RealmSwift.xcframework and Realm.xcframework files
found in that directory to the Frameworks,
Libraries, and Embedded Content section of your
project's General settings.

Dynamic Framework

Download and Extract the Framework

Download the latest release of the Swift SDK and extract the zip.

Copy Framework(s) Into Your Project

Drag Realm.xcframework and RealmSwift.xcframework (if using)
to the File Navigator of your Xcode project. Select the
Copy items if needed checkbox and press Finish.

Tip:
If using the Objective-C API within a Swift project, we
recommend you include both Realm Swift and Realm Objective-C in your
project. Within your Swift files, you can access the Swift API and
all required wrappers. Using the RealmSwift API in mixed
Swift/Objective-C projects is possible because the vast majority of
RealmSwift types are directly aliased from their Objective-C
counterparts.

Import the SDK Copy Chapter

Tip:
The SDK uses Realm Core database for device data persistence. When you
import the Swift SDK, the package names reflect Realm naming.

Add the following line at the top of your source files to use the SDK:

Objective-C

#include <Realm/Realm.h>

Swift

import RealmSwift

App Download File Size Copy Chapter

The SDK should only add around 5 to 8 MB to your app's download
size. The releases we distribute are significantly larger because they
include support for the iOS, watchOS and tvOS simulators, some debug symbols,
and bitcode, all of which are stripped by the App Store automatically when
apps are downloaded.

Troubleshooting Copy Chapter

If you have build issues after using one of these methods to install
the SDK, see our troubleshooting guidelines
for information about resolving those issues.

OS Support Copy Chapter

Important:
There are special considerations when using the SDK with
tvOS. See Build for tvOS for more information.

Xcode 15 Copy Section

Version changed: 10.50.0
Minimum required Xcode version is 15.1

Xcode 14 Copy Section

Version changed: 10.50.0
Removed support for Xcode 14.

Swift SDK version 10.50.0 drops support for Xcode 14. For v10.49.3 and earlier,
these Xcode 14 requirements apply:

• Xcode version 14.1 or higher.
• When using Xcode 14, a target of iOS 11.0 or higher, macOS 10.13 or higher, tvOS 11.0 or higher, or watchOS 4.0 or higher.

Swift Concurrency Support Copy Chapter

The Swift SDK supports Swift's concurrency-related language features.
For best practices on using the Swift SDK's concurrency features, refer
to the documentation below.

Async/Await Support Copy Section

Starting with Realm Swift SDK Versions 10.15.0 and 10.16.0, many of the
Realm APIs support the Swift async/await syntax. Projects must
meet these requirements:

If your app accesses Realm in an async/await context, mark the code
with @MainActor to avoid threading-related crashes.

For more information about async/await support in the Swift SDK, refer
to Swift Concurrency: Async/Await APIs.

Actor Support Copy Section

The Swift SDK supports actor-isolated realm instances. For more information,
refer to Use Realm with Actors - Swift SDK.

Apple Privacy Manifest Copy Chapter

Version changed: 10.49.3
Build RealmSwift as a dynamic framework to include the Privacy Manifest.

Apple requires apps that use RealmSwift to provide a privacy manifest
containing details about the SDK's data collection and use practices. The
bundled manifest file must be included when submitting new apps or app updates
to the App Store. For more details about Apple's requirements, refer to
Upcoming third-party SDK requirements
on the Apple Developer website.

Starting in Swift SDK version 10.46.0, the SDK ships with privacy manifests
for Realm and RealmSwift. Each package contains its own privacy manifest
with Apple's required API disclosures and the reasons for using those APIs.

You can view the privacy manifests in each package, or in the realm-swift
GitHub repository:

• Realm: https://github.com/realm/realm-swift/blob/master/Realm/PrivacyInfo.xcprivacy
• RealmSwift: https://github.com/realm/realm-swift/blob/master/RealmSwift/PrivacyInfo.xcprivacy

To include these manifests in a build target that uses RealmSwift, you must
build RealmSwift as a dynamic framework. For details, refer to the Swift
Package Manager Installation instructions step
(Optional) Build RealmSwift as a Dynamic Framework.

The Swift SDK does not include analytics code in builds for the App Store.

You may need to add additional disclosures to your app's privacy manifest
detailing your data collection and use practices when using these APIs.

For more information, refer to Apple's
Privacy manifest files documentation.

Guides Logging (`docs/guides/logging.md`) Copy Section

Logging - Swift SDK

You can set or change your app's log level when developing or debugging
your application. You might want to change the log level to log different
amounts of data depending on your development needs.

Set or Change the Realm Log Level Copy Chapter

You can set the level of detail reported by the Realm Swift SDK. Set the
log level for the default logger with Logger.shared.level:

Logger.shared.level = .trace

The RLMLogLevel enum represents the different levels of logging you can configure.

You can change the log level to increase or decrease verbosity at different
points in your code.

// Set a log level that isn't too verbose
Logger.shared.level = .warn

// Later, when trying to debug something, change the log level for more verbosity
Logger.shared.level = .trace

Turn Off Logging Copy Chapter

The default log threshold level for the Realm Swift SDK is .info. This
displays some information in the console. You can disable logging entirely
by setting the log level to .off:

Logger.shared.level = .off

Customize the Logging Function Copy Chapter

Initialize an instance of a Logger and define the function to use for logging.

// Create an instance of `Logger` and define the log function to invoke.
let logger = Logger(level: .detail) { level, message in
    // You may pass log information to a logging service, or
    // you could simply print the logs for debugging. Define
    // the log function that makes sense for your application.
    print("REALM DEBUG: \(Date.now) \(level) \(message) \n")
}

Tip:
To diagnose and troubleshoot errors while developing your application, set the
log level to debug or trace. For production deployments, decrease the
log level for improved performance.

You can set a logger as the default logger for your app with Logger.shared.
After you set the default logger, you can change the log level during the app
lifecycle as needed.

let logger = Logger(level: .info) { level, message in
    // You may pass log information to a logging service, or
    // you could simply print the logs for debugging. Define
    // the log function that makes sense for your application.
    print("REALM DEBUG: \(Date.now) \(level) \(message) \n")
}

// Set a logger as the default
Logger.shared = logger

// After setting a default logger, you can change
// the log level at any point during the app lifecycle
Logger.shared.level = .debug

Guides Quick Start (`docs/guides/quick-start.md`) Copy Section

Quick Start - Swift SDK

This Quick Start demonstrates how to use Realm with the Realm Swift SDK.
Before you begin, ensure you have installed the Swift SDK.

Seealso:
If your app uses SwiftUI, check out the SwiftUI Quick Start.

Import Realm Copy Chapter

Near the top of any Swift file that uses Realm, add the following import
statement:

import RealmSwift

Define Your Object Model Copy Chapter

For a local realm, you can define your object model directly in code.

class Todo: Object {
   @Persisted(primaryKey: true) var _id: ObjectId
   @Persisted var name: String = ""
   @Persisted var status: String = ""
   @Persisted var ownerId: String

   convenience init(name: String, ownerId: String) {
       self.init()
       self.name = name
       self.ownerId = ownerId
   }
}

Open a Realm Copy Chapter

In a local realm, the simplest option to open a realm
is to use the default realm with no configuration parameter:

// Open the default realm
let realm = try! Realm()

You can also specify a Realm.Configuration
parameter to open a realm at a specific file URL, in-memory, or with a
subset of classes.

For more information, see: Configure and Open a Realm.

Create, Read, Update, and Delete Objects Copy Chapter

Once you have opened a realm, you can modify it and its objects
in a write transaction block.

To create a new Todo object, instantiate the Todo class and add it to the realm in a write block:

let todo = Todo(name: "Do laundry", ownerId: user.id)
try! realm.write {
    realm.add(todo)
}

You can retrieve a live collection of all todos in the realm:

// Get all todos in the realm
let todos = realm.objects(Todo.self)

You can also filter that collection using where:

let todosInProgress = todos.where {
    $0.status == "InProgress"
}
print("A list of all todos in progress: \(todosInProgress)")

To modify a todo, update its properties in a write transaction block:

// All modifications to a realm must happen in a write block.
let todoToUpdate = todos[0]
try! realm.write {
    todoToUpdate.status = "InProgress"
}

Finally, you can delete a todo:

// All modifications to a realm must happen in a write block.
let todoToDelete = todos[0]
try! realm.write {
    // Delete the Todo.
    realm.delete(todoToDelete)
}

Watch for Changes Copy Chapter

You can watch a realm, collection, or object for changes with the observe method.

// Retain notificationToken as long as you want to observe
let notificationToken = todos.observe { (changes) in
    switch changes {
    case .initial: break
        // Results are now populated and can be accessed without blocking the UI
    case .update(_, let deletions, let insertions, let modifications):
        // Query results have changed.
        print("Deleted indices: ", deletions)
        print("Inserted indices: ", insertions)
        print("Modified modifications: ", modifications)
    case .error(let error):
        // An error occurred while opening the Realm file on the background worker thread
        fatalError("\(error)")
    }
}

Be sure to retain the notification token returned by observe as
long as you want to continue observing. When you are done observing,
invalidate the token to free the resources:

// Invalidate notification tokens when done observing
notificationToken.invalidate()

Guides Swift Concurrency (`docs/guides/swift-concurrency.md`) Copy Section

Swift Concurrency - Swift SDK

Swift's concurrency system provides built-in support for writing asynchronous
and parallel code in a structured way. For a detailed overview of the
Swift concurrency system, refer to the Swift Programming Language Concurrency
topic.

While the considerations on this page broadly apply to using realm with
Swift concurrency features, Realm Swift SDK version 10.39.0 adds support
for using Realm with Swift Actors. You can use Realm isolated to a single
actor or use Realm across actors.

Realm's actor support simplifies using Realm in a MainActor and background actor
context, and supersedes much of the advice on this page regarding concurrency
considerations. For more information, refer to Use Realm with Actors - Swift SDK.

Realm Concurrency Caveats Copy Chapter

As you implement concurrency features in your app, consider this caveat
about Realm's threading model and Swift concurrency threading behaviors.

Suspending Execution with Await Copy Section

Anywhere you use the Swift keyword await marks a possible suspension
point in the execution of your code. With Swift 5.7, once your code suspends,
subsequent code might not execute on the same thread. This means that
anywhere you use await in your code, the subsequent code could be
executed on a different thread than the code that precedes or follows it.

This is inherently incompatible with Realm's live object paradigm. Live objects, collections, and realm instances are
thread-confined: that is, they are only valid on the thread on which
they were created. Practically speaking, this means you cannot pass live
instances to other threads. However, Realm offers several
mechanisms for sharing objects across threads. These mechanisms typically require
your code to do some explicit handling to safely pass data across threads.

You can use some of these mechanisms, such as frozen objects or the ThreadSafeReference, to safely use Realm objects and instances
across threads with the await keyword. You can also avoid
threading-related issues by marking any asynchronous Realm code with
@MainActor to ensure your apps always execute this code on the main
thread.

As a general rule, keep in mind that using Realm in an await context
without incorporating threading protection may yield inconsistent behavior.
Sometimes, the code may succeed. In other cases, it may throw an error
related to writing on an incorrect thread.

Perform Background Writes Copy Section

A commonly-requested use case for asynchronous code is to perform write
operations in the background without blocking the main thread.

Realm has two APIs that allow for performing asynchronous writes:

• The writeAsync()
  API allows for performing async writes using Swift completion handlers.
• The asyncWrite()
  API allows for performing async writes using Swift async/await syntax.

Both of these APIs allow you to add, update, or delete objects in the
background without using frozen objects or passing a thread-safe reference.

With the writeAsync() API, waiting to obtain the write lock and
committing a transaction occur in the background. The write block itself
runs on the calling thread. This provides thread-safety without requiring
you to manually handle frozen objects or passing references across threads.

However, while the write block itself is executed, this does block new
transactions on the calling thread. This means that a large write using
the writeAsync() API could block small, quick writes while it executes.

The asyncWrite() API suspends the calling task while waiting for its
turn to write rather than blocking the thread. In addition, the actual
I/O to write data to disk is done by a background worker thread. For small
writes, using this function on the main thread may block the main thread
for less time than manually dispatching the write to a background thread.

For more information, including code examples, refer to: Perform a Background Write.

Tasks and TaskGroups Copy Chapter

Swift concurrency provides APIs to manage Tasks
and TaskGroups. The Swift concurrency
documentation
defines a task as a unit of work that can be run asynchronously as part of
your program. Task allows you to specifically define a unit of asynchronous
work. TaskGroup lets you define a collection of Tasks to execute as a unit
under the parent TaskGroup.

Tasks and TaskGroups provide the ability to yield the thread to other
important work or to cancel a long-running task that could be blocking
other operations. To get these benefits, you might be tempted to use Tasks
and TaskGroups to manage realm writes in the background.

However, the thread-confined constraints described in Suspending
Execution with Await above apply in
the Task context. If your Task contains await points, subsequent code
might run or resume on a different thread and violate Realm's thread confinement.

You must annotate functions that you run in a Task context with @MainActor
to ensure code that accesses Realm only runs on the main thread. This negates
some of the benefits of using Tasks, and may mean this is not a good design
choice for apps that use Realm unless you are using Tasks solely for
networking activities like managing users.

Actor Isolation Copy Chapter

Seealso:
The information in this section is applicable to Realm SDK versions earlier
than 10.39.0. Starting in Realm Swift SDK version 10.39.0 and newer,
the SDK supports using Realm with Swift Actors and related async functionality.

For more information, refer to Use Realm with Actors - Swift SDK.

Actor isolation provides the perception of confining Realm access to a
dedicated actor, and therefore seems like a safe way to manage Realm
access in an asynchronous context.

However, using Realm in a non-@MainActor async function is currently
not supported.

In Swift 5.6, this would often work by coincidence. Execution after an
await would continue on whatever thread the awaited thing ran on.
Using await Realm() in an async function would result in the code
following that running on the main thread until your next call to an
actor-isolated function.

Swift 5.7 instead hops threads whenever changing actor isolation contexts.
An unisolated async function always runs on a background thread instead.

If you have code which uses await Realm() and works in 5.6, marking
the function as @MainActor will make it work with Swift 5.7. It will
function how it did - unintentionally - in 5.6.

Errors Related to Concurrency Code Copy Chapter

Most often, the error you see related to accessing Realm through concurrency
code is Realm accessed from incorrect thread. This is due to the
thread-isolation issues described on this page.

To avoid threading-related issues in code that uses Swift concurrency features:

• Upgrade to a version of the Realm Swift SDK that supports actor-isolated realms,
  and use this as an alternative to manually managing threading. For more
  information, refer to Use Realm with Actors - Swift SDK.
• Do not change execution contexts when accessing a realm. If you open a realm
  on the main thread to provide data for your UI, annotate subsequent functions
  where you access the realm asynchronously with @MainActor to ensure it
  always runs on the main thread. Remember that await marks a suspension
  point that could change to a different thread.
• Apps that do not use actor-isolated realms can use the writeAsync API to
  perform a background write. This manages realm
  access in a thread-safe way without requiring you to write specialized code
  to do it yourself. This is a special API that outsources aspects of the
  write process - where it is safe to do so - to run in an async context.
  Unless you are writing to an actor-isolated realm, you do not use this
  method with Swift's async/await syntax. Use this method synchronously
  in your code. Alternately, you can use the asyncWrite API with Swift's
  async/await syntax when awaiting writes to asynchronous realms.
• If you want to explicitly write concurrency code that is not actor-isolated
  where accessing a realm is done in a thread-safe way, you can explicitly
  pass instances across threads where
  applicable to avoid threading-related crashes. This does require a good
  understanding of Realm's threading model, as well as being mindful of
  Swift concurrency threading behaviors.

Sendable, Non-Sendable and Thread-Confined Types Copy Chapter

The Realm Swift SDK public API contains types that fall into three broad
categories:

• Sendable
• Not Sendable and not thread confined
• Thread-confined

You can share types that are not Sendable and not thread confined between
threads, but you must synchronize them.

Thread-confined types, unless frozen, are confined to an isolation context.
You cannot pass them between these contexts even with synchronization.

Guides Swiftui (`docs/guides/swiftui.md`) Copy Section

SwiftUI - Swift SDK

Overview Copy Chapter

The Realm Swift SDK offers features that integrate into SwiftUI.
This documentation provides an overview of those features.

• Quick Start
• Model Data
• Configure and Open a Realm
• React to Changes
• Pass Realm Data Between Views
• Write Data
• Filter Data
• Use Realm with SwiftUI Previews

Requirements Copy Chapter

• Xcode project using the SwiftUI "App" template. To use all of the Realm
  Swift SDK's SwiftUI features, the minimum iOS target is 15.0. Some features
  are compatible with older versions of iOS.
• Install the Swift SDK. Use the most recent version of
  the Realm Swift SDK to get all of the features and enhancements for SwiftUI.

Guides Test And Debug (`docs/guides/test-and-debug.md`) Copy Section

Test and Debug - Swift SDK

Testing Copy Chapter

Test Using a Default Realm Copy Section

The easiest way to use and test Realm-backed applications
is to use the default realm. To avoid overriding application data or
leaking state between tests, set the default realm to a new file for
each test.

// A base class which each of your Realm-using tests should inherit from rather
// than directly from XCTestCase
class TestCaseBase: XCTestCase {
    override func setUp() {
        super.setUp()

        // Use an in-memory Realm identified by the name of the current test.
        // This ensures that each test can't accidentally access or modify the data
        // from other tests or the application itself, and because they're in-memory,
        // there's nothing that needs to be cleaned up.
        Realm.Configuration.defaultConfiguration.inMemoryIdentifier = self.name
    }
}

Injecting Realm Instances Copy Section

Another way to test Realm-related code is to have all the
methods you'd like to test accept a realm instance as an argument. This
enables you to pass in different realms when running the app and when
testing it.

For example, suppose your app has a method to GET a user profile
from a JSON API. You want to test that the local profile is properly
created.

Simplify Testing with Class Projections Copy Section

Version added: 10.21.0

If you want to work with a subset of an object's properties for testing,
you can create a class projection.
A class projection is a model abstraction where you can pass through, rename,
or exclude realm object properties. While this feature simplifies view
model implementation, it also simplifies testing with Realm.

Example:
This example uses the object models
and the class projection from the
Define and Use Class Projections page.

In this example, we create a realm object using the full object model.
Then, we view retrieve the object as a class projection, working with
only a subset of its properties.

With this class projection, we don't need to access or account for
properties that we don't need to test.

swift Copy

func testWithProjection() {
    let realm = try! Realm()
    // Create a Realm object, populate it with values
    let jasonBourne = Person(value: ["firstName": "Jason",
                                                       "lastName": "Bourne",
                                                       "address": [
                                                        "city": "Zurich",
                                                        "country": "Switzerland"]])
    try! realm.write {
        realm.add(jasonBourne)
    }

    // Retrieve all class projections of the given type `PersonProjection`
    // and filter for the first class projection where the `firstName` property
    // value is "Jason"
    let person = realm.objects(PersonProjection.self).first(where: { $0.firstName == "Jason" })!
    // Verify that we have the correct PersonProjection
    XCTAssert(person.firstName == "Jason")
    // See that `homeCity` exists as a projection property
    // Although it is not on the object model
    XCTAssert(person.homeCity == "Zurich")

    // Change a value on the class projection
    try! realm.write {
        person.firstName = "David"
    }

    // Verify that the projected property's value has changed
    XCTAssert(person.firstName == "David")
}

Test Targets Copy Section

Don't link the Realm framework directly to your test target.
This can cause your tests to fail with an exception message "Object type
'YourObject' is not managed by the Realm." Unlinking Realm
from your test target should resolve this issue.

Compile your model class files in your application or framework targets;
don't add them to your unit test targets. Otherwise, those classes are
duplicated when testing, which can lead to difficult-to-debug issues.

Expose all the code that you need for testing to your unit test
targets. Use the public access modifier or @testable.

Since you're using Realm as a dynamic framework, you'll
need to make sure your unit test target can find Realm.
Add the parent path to RealmSwift.framework to your unit test's
"Framework Search Paths".

Debugging Copy Chapter

Debug Using Realm Studio Copy Section

Realm Studio enables you to open and edit local
realms. It supports Mac, Windows and Linux.

LLDB Copy Section

Debugging apps using Realm's Swift API must be done through
the LLDB console.

Although the LLDB script allows inspecting the contents of your realm
variables in Xcode's UI, this doesn't yet work for Swift. Those
variables will show incorrect data. Instead, use LLDB's po
command to inspect the contents of data stored in a realm.

Troubleshooting Copy Chapter

Resolve Build Issues Copy Section

Some developers experience build issues after installing the Realm Swift SDK via
CocoaPods or Carthage. Common causes of these issues include:

• Installation issues: Initial install failedUsing an unsupported version of the dependency manager
• Build tool issues: Build tools have stale cachesUpdating build tool versions
• Making changes to your project setup, such as: Adding a new targetSharing dependencies across targets

A fix that often clears these issues is to delete derived data
and clean the Xcode build folder.

Cocoapods

Reset the Cocoapods Integration State

Run these commands in the terminal, in the root of your project:

pod cache clean Realm
pod cache clean RealmSwift
pod deintegrate || rm -rf Pods
pod install --repo-update --verbose
# Assumes the default DerivedData location:
rm -rf ~/Library/Developer/Xcode/DerivedData

Clean the Xcode Build Folder

With your project open in Xcode, go to the Product drop-down menu,
and select Clean Build Folder.

Carthage

Reset Carthage-managed Dependency State

Run these commands in the terminal, in the root of your project:

rm -rf Carthage
# Assumes default DerivedData location:
rm -rf ~/Library/Developer/Xcode/DerivedData
carthage update

Clean the Xcode Build Folder

With your project open in Xcode, go to the Product drop-down menu,
and select Clean Build Folder.

Issues Opening Realm Before Loading the UI Copy Section

You may open a realm and immediately see crashes with error messages
related to properties being optional or required. Issues with your
object model can cause
these types of crashes. These errors occur after you open a realm,
but before you get to the UI.

Realm has a "schema discovery" phase when a realm opens on the device.
At this time, Realm examines the schema for any objects that it manages.
You can specify that a given realm should manage only a subset
of objects in your
application.

If you see errors related to properties during schema discovery, these are
likely due to schema issues and not issues with data from a specific object.
For example, you may see schema discovery errors if you define a to-one
relationship as required
instead of optional.

To debug these crashes, check the schema you've defined.

You can tell these are schema discovery issues because they occur before
the UI loads. This means that no UI element is attempting to incorrectly
use a property, and there aren't any objects in memory that could have
bad data. If you get errors related to properties after the UI loads,
this is probably not due to invalid schema. Instead, those errors are
likely a result of incorrect, wrongly-typed or missing data.

No Properties are Defined for Model Copy Section

The Realm Swift SDK uses the Swift language reflection feature to determine
the properties in your model at runtime. If you get a crash similar to
the following, confirm that your project has not disabled reflection metadata:

Terminating app due to uncaught exception 'RLMException', reason: 'No properties are defined for 'ObjectName'.

If you set SWIFT_REFLECTION_METADATA_LEVEL = none, Realm cannot
discover children of types, such as properties and enums. Reflection is
enabled by default if your project does not specifically set a level for
this setting.

Bad Alloc/Not Enough Memory Available Copy Section

In iOS or iPad devices with little available memory, or where you have a
memory-intensive application that uses multiple realms or many notifications,
you may encounter the following error:

libc++abi: terminating due to an uncaught exception of type std::bad_alloc: std::bad_alloc

This error typically indicates that a resource cannot be allocated because
not enough memory is available.

If you are building for iOS 15+ or iPad 15+, you can add the
Extended Virtual Addressing Entitlement
to resolve this issue.

Add these keys to your Property List, and set the values to true:

<key>com.apple.developer.kernel.extended-virtual-addressing</key>
<true/>
<key>com.apple.developer.kernel.increased-memory-limit</key>
<true/>

Swift Package Target Cannot be Built Dynamically Copy Section

Version changed: 10.49.3

Swift SDK v10.49.3 changed the details for installing the package with
Swift Package Manager (SPM). When you update from an older version of the
package to v10.49.3 or newer, you may get a build error similar to:

Swift package target `Realm` is linked as a static library by `TargetName`
and `Realm`, but cannot be built dynamically because there is a package
product with the same name.

To resolve this error, unlink either the Realm or the RealmSwift
package from your build target. You can do this in Xcode by following these
steps:

1. In your project Targets, select your build target.
2. Go to the Build Phases tab.
3. Expand the Link Binary With Libraries element.
4. Select either Realm or RealmSwift, and click the Remove items
   (-) button to remove the unneeded binary. If you use Swift or Swift
   and Objective-C APIs, keep RealmSwift. If you use only Objective-C
   APIs, keep Realm.

Now your target should build without this error.

Guides Use Realm With Actors (`docs/guides/use-realm-with-actors.md`) Copy Section

Use Realm with Actors - Swift SDK

Starting with Realm Swift SDK version 10.39.0, Realm supports built-in
functionality for using Realm with Swift Actors. Realm's actor support
provides an alternative to managing threads or dispatch queues to perform
asynchronous work. You can use Realm with actors in a few different ways:

• Work with realm only on a specific actor with an actor-isolated realm
• Use Realm across actors based on the needs of your application

You might want to use an actor-isolated realm if you want to restrict all
realm access to a single actor. This negates the need to pass data across
the actor boundary, and can simplify data race debugging.

You might want to use realms across actors in cases where you want to
perform different types of work on different actors. For example, you might
want to read objects on the MainActor but use a background actor for large
writes.

For general information about Swift actors, refer to Apple's Actor
documentation.

Prerequisites Copy Chapter

To use Realm in a Swift actor, your project must:

• Use Realm Swift SDK version 10.39.0 or later
• Use Swift 5.8/Xcode 14.3

In addition, we strongly recommend enabling these settings in your project:

• SWIFT_STRICT_CONCURRENCY=complete: enables strict concurrency checking
• OTHER_SWIFT_FLAGS=-Xfrontend-enable-actor-data-race-checks: enables
  runtime actor data-race detection

About the Examples on This Page Copy Chapter

The examples on this page use the following model:

class Todo: Object {
    @Persisted(primaryKey: true) var _id: ObjectId
    @Persisted var name: String
    @Persisted var owner: String
    @Persisted var status: String
}

Open an Actor-Isolated Realm Copy Chapter

You can use the Swift async/await syntax to await opening a realm.

Initializing a realm with try await Realm() opens a MainActor-isolated
realm. Alternately, you can explicitly specify an actor when opening a
realm with the await syntax.

@MainActor
func mainThreadFunction() async throws {
    // These are identical: the async init produces a
    // MainActor-isolated Realm if no actor is supplied
    let realm1 = try await Realm()
    let realm2 = try await Realm(actor: MainActor.shared)

    try await useTheRealm(realm: realm1)
}

You can specify a default configuration or customize your configuration when
opening an actor-isolated realm:

@MainActor
func mainThreadFunction() async throws {
    let username = "Galadriel"

    // Customize the default realm config
    var config = Realm.Configuration.defaultConfiguration
    config.fileURL!.deleteLastPathComponent()
    config.fileURL!.appendPathComponent(username)
    config.fileURL!.appendPathExtension("realm")

    // Open an actor-isolated realm with a specific configuration
    let realm = try await Realm(configuration: config, actor: MainActor.shared)

    try await useTheRealm(realm: realm)
}

For more general information about configuring a realm, refer to
Configure & Open a Realm.

Define a Custom Realm Actor Copy Chapter

You can define a specific actor to manage Realm in asynchronous contexts.
You can use this actor to manage realm access and perform write operations.

/* Detailed source-code truncated for AI context efficiency. */

An actor-isolated realm may be used with either local or global actors.

// A simple example of a custom global actor
@globalActor actor BackgroundActor: GlobalActor {
    static var shared = BackgroundActor()
}

@BackgroundActor
func backgroundThreadFunction() async throws {
    // Explicitly specifying the actor is required for anything that is not MainActor
    let realm = try await Realm(actor: BackgroundActor.shared)
    try await realm.asyncWrite {
        _ = realm.create(Todo.self, value: [
            "name": "Pledge fealty and service to Gondor",
            "owner": "Pippin",
            "status": "In Progress"
        ])
    }
    // Thread-confined Realms would sometimes throw an exception here, as we
    // may end up on a different thread after an `await`
    let todoCount = realm.objects(Todo.self).count
    print("The number of Realm objects is: \(todoCount)")
}

@MainActor
func mainThreadFunction() async throws {
    try await backgroundThreadFunction()
}

Use a Realm Actor Synchronously in an Isolated Function Copy Section

When a function is confined to a specific actor, you can use the actor-isolated
realm synchronously.

func createObject(in actor: isolated RealmActor) async throws {
    // Because this function is isolated to this actor, you can use
    // realm synchronously in this context without async/await keywords
    try actor.realm.write {
        actor.realm.create(Todo.self, value: [
            "name": "Keep it secret",
            "owner": "Frodo",
            "status": "In Progress"
        ])
    }
    let taskCount = actor.count
    print("The actor currently has \(taskCount) tasks")
}

let actor = try await RealmActor()

try await createObject(in: actor)

Use a Realm Actor in Async Functions Copy Section

When a function isn't confined to a specific actor, you can use your Realm actor
with Swift's async/await syntax.

func createObject() async throws {
    // Because this function is not isolated to this actor,
    // you must await operations completed on the actor
    try await actor.createTodo(name: "Take the ring to Mount Doom", owner: "Frodo", status: "In Progress")
    let taskCount = await actor.count
    print("The actor currently has \(taskCount) tasks")
}

let actor = try await RealmActor()

try await createObject()

Write to an Actor-Isolated Realm Copy Chapter

Actor-isolated realms can use Swift async/await syntax for asynchronous
writes. Using try await realm.asyncWrite { ... } suspends the current task,
acquires the write lock without blocking the current thread, and then invokes
the block. Realm writes the data to disk on a background thread and resumes
the task when that completes.

This function from the example RealmActor defined above shows how you might
write to an actor-isolated realm:

func createTodo(name: String, owner: String, status: String) async throws {
    try await realm.asyncWrite {
        realm.create(Todo.self, value: [
            "_id": ObjectId.generate(),
            "name": name,
            "owner": owner,
            "status": status
        ])
    }
}

And you might perform this write using Swift's async syntax:

func createObject() async throws {
    // Because this function is not isolated to this actor,
    // you must await operations completed on the actor
    try await actor.createTodo(name: "Take the ring to Mount Doom", owner: "Frodo", status: "In Progress")
    let taskCount = await actor.count
    print("The actor currently has \(taskCount) tasks")
}

let actor = try await RealmActor()

try await createObject()

This does not block the calling thread while waiting to write. It does
not perform I/O on the calling thread. For small writes, this is safe to
use from @MainActor functions without blocking the UI. Writes that
negatively impact your app's performance due to complexity and/or platform
resource constraints may still benefit from being done on a background thread.

Asynchronous writes are only supported for actor-isolated Realms or in
@MainActor functions.

Pass Realm Data Across the Actor Boundary Copy Chapter

Realm objects are not Sendable,
and cannot cross the actor boundary directly. To pass Realm data across
the actor boundary, you have two options:

• Pass a ThreadSafeReference to or from the actor
• Pass other types that are Sendable, such as passing values directly
  or by creating structs to pass across actor boundaries

Pass a ThreadSafeReference Copy Section

You can create a ThreadSafeReference on an
actor where you have access to the object. In this case, we create a
ThreadSafeReference on the MainActor. Then, pass the ThreadSafeReference to the destination actor.

// We can pass a thread-safe reference to an object to update it on a different actor.
let todo = todoCollection.where {
    $0.name == "Arrive safely in Bree"
}.first!
let threadSafeReferenceToTodo = ThreadSafeReference(to: todo)
try await backgroundActor.deleteTodo(tsrToTodo: threadSafeReferenceToTodo)

On the destination actor, you must resolve() the reference within a
write transaction before you can use it. This retrieves a version of the
object local to that actor.

actor BackgroundActor {
    public func deleteTodo(tsrToTodo tsr: ThreadSafeReference<Todo>) throws {
        let realm = try! Realm()
        try realm.write {
            // Resolve the thread safe reference on the Actor where you want to use it.
            // Then, do something with the object.
            let todoOnActor = realm.resolve(tsr)
            realm.delete(todoOnActor!)
        }
    }
}

Important:
You must resolve a ThreadSafeReference exactly once. Otherwise,
the source realm remains pinned until the reference gets
deallocated. For this reason, ThreadSafeReference should be
short-lived.

If you may need to share the same realm object across actors more than
once, you may prefer to share the primary key
and query for it on
the actor where you want to use it. Refer to the "Pass a Primary Key
and Query for the Object on Another Actor" section on this page for an example.

Pass a Sendable Type Copy Section

While Realm objects are not Sendable, you can work around this by passing
Sendable types across actor boundaries. You can use a few strategies to
pass Sendable types and work with data across actor boundaries:

• Pass Sendable Realm types or primitive values instead of complete Realm objects
• Pass an object's primary key and query for the object on another actor
• Create a Sendable representation of your Realm object, such as a struct

Pass Sendable Realm Types and Primitive Values

If you only need a piece of information from the Realm object, such as a
String or Int, you can pass the value directly across actors instead
of passing the Realm object. For a full list of which Realm types are Sendable,
refer to Sendable, Non-Sendable and Thread-Confined Types.

@MainActor
func mainThreadFunction() async throws {
    // Create an object in an actor-isolated realm.
    // Pass primitive data to the actor instead of
    // creating the object here and passing the object.
    let actor = try await RealmActor()
    try await actor.createTodo(name: "Prepare fireworks for birthday party", owner: "Gandalf", status: "In Progress")

    // Later, get information off the actor-confined realm
    let todoOwner = await actor.getTodoOwner(forTodoNamed: "Prepare fireworks for birthday party")
}

Pass a Primary Key and Query for the Object on Another Actor

If you want to use a Realm object on another actor, you can share the
primary key and
query for it on the actor
where you want to use it.

// Execute code on a specific actor - in this case, the @MainActor
@MainActor
func mainThreadFunction() async throws {
    // Create an object off the main actor
    func createObject(in actor: isolated BackgroundActor) async throws -> ObjectId {
        let realm = try await Realm(actor: actor)
        let newTodo = try await realm.asyncWrite {
            return realm.create(Todo.self, value: [
                "name": "Pledge fealty and service to Gondor",
                "owner": "Pippin",
                "status": "In Progress"
            ])
        }

        // Share the todo's primary key so we can easily query for it on another actor
        return newTodo._id
    }

    // Initialize an actor where you want to perform background work
    let actor = BackgroundActor()
    let newTodoId = try await createObject(in: actor)
    let realm = try await Realm()
    let todoOnMainActor = realm.object(ofType: Todo.self, forPrimaryKey: newTodoId)
}

Create a Sendable Representation of Your Object

If you need to work with more than a simple value, but don't want the
overhead of passing around ThreadSafeReferences or querying objects on
different actors, you can create a struct or other Sendable representation
of your data to pass across the actor boundary.

For example, your actor might have a function that creates a struct
representation of the Realm object.

struct TodoStruct {
    var id: ObjectId
    var name, owner, status: String
}

func getTodoAsStruct(forTodoNamed name: String) -> TodoStruct {
    let todo = realm.objects(Todo.self).where {
        $0.name == name
    }.first!
    return TodoStruct(id: todo._id, name: todo.name, owner: todo.owner, status: todo.status)
}

Then, you can call a function to get the data as a struct on another actor.

@MainActor
func mainThreadFunction() async throws {
    // Create an object in an actor-isolated realm.
    let actor = try await RealmActor()
    try await actor.createTodo(name: "Leave the ring on the mantle", owner: "Bilbo", status: "In Progress")

    // Get information as a struct or other Sendable type.
    let todoAsStruct = await actor.getTodoAsStruct(forTodoNamed: "Leave the ring on the mantle")
}

Observe Notifications on a Different Actor Copy Chapter

You can observe notifications on an actor-isolated realm using Swift's
async/await syntax.

Calling await object.observe(on: Actor) or
await collection.observe(on: Actor) registers a block to be called
each time the object or collection changes.

The SDK asynchronously calls the block on the given actor's executor.

For write transactions performed on different threads or in different
processes, the SDK calls the block when the realm is (auto)refreshed
to a version including the changes. For local writes, the SDK calls the block
at some point in the future after the write transaction is committed.

Like other Realm notifications, you can
only observe objects or collections managed by a realm. You must retain the
returned token for as long as you want to watch for updates.

If you need to manually advance the state of an observed realm on the main
thread or on another actor, call await realm.asyncRefresh().
This updates the realm and outstanding objects managed by the Realm to point to
the most recent data and deliver any applicable notifications.

Observation Limitations Copy Section

You cannot call the .observe() method:

• During a write transaction
• When the containing realm is read-only
• On an actor-confined realm from outside the actor

Register a Collection Change Listener Copy Section

The SDK calls a collection notification block after each write transaction which:

• Deletes an object from the collection.
• Inserts an object into the collection.
• Modifies any of the managed properties of an object in the collection. This
  includes self-assignments that set a property to its existing value.

Important:
In collection notification handlers, always apply changes
in the following order: deletions, insertions, then
modifications. Handling insertions before deletions may
result in unexpected behavior.

These notifications provide information about the actor on which the change
occurred. Like non-actor-isolated collection notifications, they also provide
a change parameter that reports which objects are deleted, added, or
modified during the write transaction. This RealmCollectionChange
resolves to an array of index paths that you can pass to a UITableView's
batch update methods.

/* Detailed source-code truncated for AI context efficiency. */

Register an Object Change Listener Copy Section

The SDK calls an object notification block after each write transaction which:

• Deletes the object.
• Modifies any of the managed properties of the object. This includes
  self-assignments that set a property to its existing value.

The block is passed a copy of the object isolated to the requested actor,
along with information about what changed. This object can be safely used
on that actor.

By default, only direct changes to the object's properties produce notifications.
Changes to linked objects do not produce notifications. If a non-nil, non-empty
keypath array is passed in, only changes to the properties identified by those
keypaths produce change notifications. The keypaths may traverse link
properties to receive information about changes to linked objects.

/* Detailed source-code truncated for AI context efficiency. */

Guides Xcode Playgrounds (`docs/guides/xcode-playgrounds.md`) Copy Section

Use Realm in Xcode Playgrounds

Prerequisites Copy Chapter

You can only use Swift packages within Xcode projects that have at least one
scheme and target. To use Realm in Xcode Playgrounds, you must first have
an Xcode project where you have Installed the Swift SDK.

Create a Playground Copy Chapter

Within a project, go to File > New > Playground. Select the type of
Playground you want. For this example, we've used a Blank iOS
Playground.

Name and save the playground in the root of your
project. Be sure to add it to the project.

You should see your new Playground in your Project navigator.

Import Realm Copy Chapter

Add the following import statement to use Realm in the playground:

import RealmSwift

Experiment with Realm Copy Chapter

Experiment with Realm. For this example, we'll:

• Define a new Realm object type
• Create a new object of that type and write it to realm
• Query objects of the type, and filter them

class Drink: Object {
    @Persisted var name = ""
    @Persisted var rating = 0
    @Persisted var source = ""
    @Persisted var drinkType = ""
}

let drink = Drink(value: ["name": "Los Cabellos", "rating": 10, "source": "AeroPress", "drinkType": "Coffee"])

let realm = try! Realm(configuration: config)

try! realm.write {
    realm.add(drink)
}

let drinks = realm.objects(Drink.self)

let coffeeDrinks = drinks.where {
    $0.drinkType == "Coffee"
}

print(coffeeDrinks.first?.name)

Managing the Realm File in Your Playground Copy Chapter

When you work with a default realm
in a Playground, you might run into a situation where you need to delete the
realm. For example, if you are experimenting with an object type and add
properties to the object, you may get an error that you must migrate the
realm.

You can specify Realm.configuration details to open the file at a specific
path, and delete the realm if it exists at the path.

var config = Realm.Configuration()

config.fileURL!.deleteLastPathComponent()
config.fileURL!.appendPathComponent("playgroundRealm")
config.fileURL!.appendPathExtension("realm")

if Realm.fileExists(for: config) {
    try Realm.deleteFiles(for: config)
    print("Successfully deleted existing realm at path: \(config.fileURL!)")
} else {
    print("No file currently exists at path")
}

Alternately, you can open the realm in-memory only, or use the
deleteRealmIfMigrationNeeded
method to automatically delete a realm when migration is needed.

Guides Crud Create (`docs/guides/crud/create.md`) Copy Section

CRUD - Create - Swift SDK

Create a New Object Copy Chapter

About The Examples On This Page Copy Section

The examples on this page use the following models:

Objective-C

// DogToy.h
@interface DogToy : RLMObject
@property NSString *name;
@end

// Dog.h
@interface Dog : RLMObject
@property NSString *name;
@property int age;
@property NSString *color;

// To-one relationship
@property DogToy *favoriteToy;

@end

// Enable Dog for use in RLMArray
RLM_COLLECTION_TYPE(Dog)

// Person.h
// A person has a primary key ID, a collection of dogs, and can be a member of multiple clubs.
@interface Person : RLMObject
@property int _id;
@property NSString *name;

// To-many relationship - a person can have many dogs
@property RLMArray<Dog *><Dog> *dogs;

// Inverse relationship - a person can be a member of many clubs
@property (readonly) RLMLinkingObjects *clubs;
@end

RLM_COLLECTION_TYPE(Person)

// DogClub.h
@interface DogClub : RLMObject
@property NSString *name;
@property RLMArray<Person *><Person> *members;
@end

// Dog.m
@implementation Dog
@end

// DogToy.m
@implementation DogToy
@end

// Person.m
@implementation Person
// Define the primary key for the class
+ (NSString *)primaryKey {
    return @"_id";
}

// Define the inverse relationship to dog clubs
+ (NSDictionary *)linkingObjectsProperties {
    return @{
        @"clubs": [RLMPropertyDescriptor descriptorWithClass:DogClub.class propertyName:@"members"],
    };
}
@end

// DogClub.m
@implementation DogClub
@end

Swift

class DogToy: Object {
    @Persisted var name = ""
}

class Dog: Object {
    @Persisted var name = ""
    @Persisted var age = 0
    @Persisted var color = ""
    @Persisted var currentCity = ""
    @Persisted var citiesVisited: MutableSet<String>
    @Persisted var companion: AnyRealmValue

    // To-one relationship
    @Persisted var favoriteToy: DogToy?

    // Map of city name -> favorite park in that city
    @Persisted var favoriteParksByCity: Map<String, String>
}

class Person: Object {
    @Persisted(primaryKey: true) var id = 0
    @Persisted var name = ""

    // To-many relationship - a person can have many dogs
    @Persisted var dogs: List<Dog>

    // Embed a single object.
    // Embedded object properties must be marked optional.
    @Persisted var address: Address?

    convenience init(name: String, address: Address) {
        self.init()
        self.name = name
        self.address = address
    }
}

class Address: EmbeddedObject {
    @Persisted var street: String?
    @Persisted var city: String?
    @Persisted var country: String?
    @Persisted var postalCode: String?
}

Create an Object Copy Section

Objective-C

To add an object to a realm, instantiate it as you would any other
object and then pass it to -[RLMRealm addObject:] inside
of a write transaction.

// Get the default realm.
// You only need to do this once per thread.
RLMRealm *realm = [RLMRealm defaultRealm];

// Instantiate the class.
Dog *dog = [[Dog alloc] init];
dog.name = @"Max";
dog.age = 5;

// Open a thread-safe transaction.
[realm transactionWithBlock:^() {
    // Add the instance to the realm.
    [realm addObject:dog];
}];

Swift

To add an object to a realm, instantiate it as you would any other
object and then pass it to Realm.add(_:update:)
inside of a write transaction.

// Instantiate the class and set its values.
let dog = Dog()
dog.name = "Rex"
dog.age = 10

// Get the default realm. You only need to do this once per thread.
let realm = try! Realm()
// Open a thread-safe transaction.
try! realm.write {
    // Add the instance to the realm.
    realm.add(dog)
}

Initialize Objects with a Value Copy Section

You can initialize an object by passing an initializer value to
Object.init(value:).
The initializer value can be a key-value coding
compliant object, a dictionary, or an array containing one element for
each managed property.

Note:
When using an array as an initializer value, you must include all
properties in the same order as they are defined in the model.

Objective-C

// (1) Create a Dog object from a dictionary
Dog *myDog = [[Dog alloc] initWithValue:@{@"name" : @"Pluto", @"age" : @3}];

// (2) Create a Dog object from an array
Dog *myOtherDog = [[Dog alloc] initWithValue:@[@"Pluto", @3]];

RLMRealm *realm = [RLMRealm defaultRealm];

// Add to the realm with transaction
[realm transactionWithBlock:^() {
    [realm addObject:myDog];
    [realm addObject:myOtherDog];
}];

Swift

// (1) Create a Dog object from a dictionary
let myDog = Dog(value: ["name": "Pluto", "age": 3])

// (2) Create a Dog object from an array
let myOtherDog = Dog(value: ["Fido", 5])

let realm = try! Realm()
// Add to the realm inside a transaction
try! realm.write {
    realm.add([myDog, myOtherDog])
}

You can even initialize related or
embedded objects by nesting initializer
values:

Objective-C

// Instead of using pre-existing dogs...
Person *aPerson = [[Person alloc]
    initWithValue:@[@123, @"Jane", @[aDog, anotherDog]]];

// ...we can create them inline
Person *anotherPerson = [[Person alloc]
    initWithValue:@[@123, @"Jane", @[@[@"Buster", @5], @[@"Buddy", @6]]]];

Swift

// Instead of using pre-existing dogs...
let aPerson = Person(value: [123, "Jane", [aDog, anotherDog]])

// ...we can create them inline
let anotherPerson = Person(value: [123, "Jane", [["Buster", 5], ["Buddy", 6]]])

Some Property Types are Only Mutable in a Write Transaction

Some property types are only mutable in a write transaction. For example,
you can instantiate an object with a MutableSet
property, but you can only set that property's value in a write transaction.
You cannot initialize the object with a value for that property unless
you do so inside a write transaction.

Create an Object with JSON Copy Section

Realm does not directly support JSON, but you can use
JSONSerialization.jsonObject(with:options:) to
convert JSON into a value that you can pass to
Realm.create(_:value:update:).

Objective-C

// Specify a dog toy in JSON
NSData *data = [@"{\"name\": \"Tennis ball\"}" dataUsingEncoding: NSUTF8StringEncoding];
RLMRealm *realm = [RLMRealm defaultRealm];

// Insert from NSData containing JSON
[realm transactionWithBlock:^{
    id json = [NSJSONSerialization JSONObjectWithData:data options:0 error:NULL];
    [DogToy createInRealm:realm withValue:json];
}];

Swift

// Specify a dog toy in JSON
let data = "{\"name\": \"Tennis ball\"}".data(using: .utf8)!
let realm = try! Realm()
// Insert from data containing JSON
try! realm.write {
    let json = try! JSONSerialization.jsonObject(with: data, options: [])
    realm.create(DogToy.self, value: json)
}

Nested objects or arrays in the JSON map to to-one or to-many relationships.

The JSON property names and types must match the destination
object schema exactly. For example:

• float properties must be initialized with float-backed NSNumbers.
• Date and Data properties cannot be inferred from strings. Convert them to the appropriate type before passing to Realm.create(_:value:update:).
• Required properties cannot be null or missing in the JSON.

Realm ignores any properties in the JSON not defined in the
object schema.

Tip:
If your JSON schema doesn't exactly align with your Realm objects,
consider using a third-party framework to transform your JSON. There
are many model mapping frameworks that work with Realm.
See a partial list in the realm-swift repository.

Create an Embedded Object Copy Section

To create an embedded object, assign an instance of the embedded object
to a parent object's property:

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];
[realm transactionWithBlock:^{
    Address *address = [[Address alloc] init];
    address.street = @"123 Fake St.";
    address.city = @"Springfield";
    address.country = @"USA";
    address.postalCode = @"90710";

    Contact *contact = [Contact contactWithName:@"Nick Riviera"];

    // Assign the embedded object property
    contact.address = address;

    [realm addObject:contact];

    NSLog(@"Added contact: %@", contact);
}];

Swift

// Open the default realm
let realm = try! Realm()

try! realm.write {
    let address = Address()
    address.street = "123 Fake St"
    address.city = "Springfield"
    address.country = "USA"
    address.postalCode = "90710"
    let contact = Person(name: "Nick Riviera", address: address)
    realm.add(contact)
}

Create an Object with a Map Property Copy Section

When you create an object that has a map property, you can set the values for keys in a few ways:

• Set keys and values on the object and then add the object to the realm
• Set the object's keys and values directly inside a write transaction
• Use key-value coding to set or update keys and values inside a write transaction

let realm = try! Realm()
// Record a dog's name and current city
let dog = Dog()
dog.name = "Wolfie"
dog.currentCity = "New York"
// Set map values
dog.favoriteParksByCity["New York"] = "Domino Park"
// Store the data in a realm
try! realm.write {
    realm.add(dog)
    // You can also set map values inside a write transaction
    dog.favoriteParksByCity["Chicago"] = "Wrigley Field"
    dog.favoriteParksByCity.setValue("Bush Park", forKey: "Ottawa")
}

Realm disallows the use of . or $ characters in map keys.
You can use percent encoding and decoding to store a map key that contains
one of these disallowed characters.

// Percent encode . or $ characters to use them in map keys
let mapKey = "New York.Brooklyn"
let encodedMapKey = "New York%2EBrooklyn"

Create an Object with a MutableSet Property Copy Section

You can create objects that contain MutableSet properties as you would any Realm object, but you
can only mutate a MutableSet within a write transaction. This means you can
only set the value(s) of a mutable set property within a write transaction.

let realm = try! Realm()

// Record a dog's name and current city
let dog = Dog()
dog.name = "Maui"
dog.currentCity = "New York"

// Store the data in a realm. Add the dog's current city
// to the citiesVisited MutableSet
try! realm.write {
    realm.add(dog)
    // You can only mutate the MutableSet in a write transaction.
    // This means you can't set values at initialization, but must do it during a write.
    dog.citiesVisited.insert(dog.currentCity)
}

// You can also add multiple items to the set.
try! realm.write {
    dog.citiesVisited.insert(objectsIn: ["Boston", "Chicago"])
}

print("\(dog.name) has visited: \(dog.citiesVisited)")

Create an Object with an AnyRealmValue Property Copy Section

When you create an object with an AnyRealmValue property, you must specify the type of the value you store in
the property. The Realm Swift SDK provides an AnyRealmValue enum that iterates through all of the types the
AnyRealmValue can store.

Later, when you read an AnyRealmValue,
you must check the type before you do anything with the value.

// Create a Dog object and then set its properties
let myDog = Dog()
myDog.name = "Rex"
// This dog has no companion.
// You can set the field's type to "none", which represents `nil`
myDog.companion = .none

// Create another Dog whose companion is a cat.
// We don't have a Cat object, so we'll use a string to describe the companion.
let theirDog = Dog()
theirDog.name = "Wolfie"
theirDog.companion = .string("Fluffy the Cat")

// Another dog might have a dog as a companion.
// We do have an object that can represent that, so we can specify the
// type is a Dog object, and even set the object's value.
let anotherDog = Dog()
anotherDog.name = "Fido"
// Note: this sets Spot as a companion of Fido, but does not set
// Fido as a companion of Spot. Spot has no companion in this instance.
anotherDog.companion = .object(Dog(value: ["name": "Spot"]))

// Add the dogs to the realm
let realm = try! Realm()
try! realm.write {
    realm.add([myDog, theirDog, anotherDog])
}
// After adding these dogs to the realm, we now have 4 dog objects.
let dogs = realm.objects(Dog.self)
XCTAssertEqual(dogs.count, 4)

Create an Object Asynchronously Copy Chapter

You can use Swift concurrency features to write asynchronously to an
actor-isolated realm.

This function from the example RealmActor defined on the
Use Realm with Actors page shows how you might
write to an actor-isolated realm:

func createTodo(name: String, owner: String, status: String) async throws {
    try await realm.asyncWrite {
        realm.create(Todo.self, value: [
            "_id": ObjectId.generate(),
            "name": name,
            "owner": owner,
            "status": status
        ])
    }
}

And you might perform this write using Swift's async syntax:

func createObject() async throws {
    // Because this function is not isolated to this actor,
    // you must await operations completed on the actor
    try await actor.createTodo(name: "Take the ring to Mount Doom", owner: "Frodo", status: "In Progress")
    let taskCount = await actor.count
    print("The actor currently has \(taskCount) tasks")
}

let actor = try await RealmActor()

try await createObject()

This operation does not block or perform I/O on the calling thread. For
more information about writing to realm using Swift concurrency features,
refer to Use Realm with Actors - Swift SDK.

Copy an Object to Another Realm Copy Chapter

Objective-C

To copy an object from one realm to another, pass the original
object to +[RLMObject createInRealm:withValue:]:

RLMRealmConfiguration *configuration = [RLMRealmConfiguration defaultConfiguration];
configuration.inMemoryIdentifier = @"first realm";
RLMRealm *realm = [RLMRealm realmWithConfiguration:configuration error:nil];

[realm transactionWithBlock:^{
    Dog *dog = [[Dog alloc] init];
    dog.name = @"Wolfie";
    dog.age = 1;
    [realm addObject:dog];
}];

// Later, fetch the instance we want to copy
Dog *wolfie = [[Dog objectsInRealm:realm where:@"name == 'Wolfie'"] firstObject];

// Open the other realm
RLMRealmConfiguration *otherConfiguration = [RLMRealmConfiguration defaultConfiguration];
otherConfiguration.inMemoryIdentifier = @"second realm";
RLMRealm *otherRealm = [RLMRealm realmWithConfiguration:otherConfiguration error:nil];
[otherRealm transactionWithBlock:^{
    // Copy to the other realm
    Dog *wolfieCopy = [[wolfie class] createInRealm:otherRealm withValue:wolfie];
    wolfieCopy.age = 2;

    // Verify that the copy is separate from the original
    XCTAssertNotEqual(wolfie.age, wolfieCopy.age);
}];

Swift

To copy an object from one realm to another, pass the original
object to Realm.create(_:value:update:)::

let realm = try! Realm(configuration: Realm.Configuration(inMemoryIdentifier: "first realm"))

try! realm.write {
    let dog = Dog()
    dog.name = "Wolfie"
    dog.age = 1
    realm.add(dog)
}

// Later, fetch the instance we want to copy
let wolfie = realm.objects(Dog.self).first(where: { $0.name == "Wolfie" })!

// Open the other realm
let otherRealm = try! Realm(configuration: Realm.Configuration(inMemoryIdentifier: "second realm"))
try! otherRealm.write {
    // Copy to the other realm
    let wolfieCopy = otherRealm.create(type(of: wolfie), value: wolfie)
    wolfieCopy.age = 2

    // Verify that the copy is separate from the original
    XCTAssertNotEqual(wolfie.age, wolfieCopy.age)
}

Important:
The create methods do not support handling cyclical object
graphs. Do not pass in an object containing relationships involving
objects that refer back to their parents, either directly or
indirectly.

Guides Crud Crud (`docs/guides/crud/crud.md`) Copy Section

CRUD - Swift SDK

Write Transactions Copy Chapter

Realm uses a highly efficient storage engine
to persist objects. You can create objects in a realm,
update objects in a realm, and eventually delete
objects from a realm. Because these operations modify the
state of the realm, we call them writes.

Realm handles writes in terms of transactions. A
transaction is a list of read and write operations that
Realm treats as a single indivisible operation. In other
words, a transaction is all or nothing: either all of the
operations in the transaction succeed or none of the
operations in the transaction take effect.

All writes must happen in a transaction.

A realm allows only one open transaction at a time. Realm
blocks other writes on other threads until the open
transaction is complete. Consequently, there is no race
condition when reading values from the realm within a
transaction.

When you are done with your transaction, Realm either
commits it or cancels it:

• When Realm commits a transaction, Realm writes
  all changes to disk.
• When Realm cancels a write transaction or an operation in
  the transaction causes an error, all changes are discarded
  (or "rolled back").

Run a Transaction Copy Section

The Swift SDK represents each transaction as a callback function
that contains zero or more read and write operations. To run
a transaction, define a transaction callback and pass it to
the realm's write method. Within this callback, you are
free to create, read, update, and delete on the realm. If
the code in the callback throws an exception when Realm runs
it, Realm cancels the transaction. Otherwise, Realm commits
the transaction immediately after the callback.

Important:
Since transactions block each other, it is best to avoid
opening transactions on both the UI thread and a
background thread. If a background transaction
blocks your UI thread's transaction, your app may appear
unresponsive.

Example:
The following code shows how to run a transaction with
the realm's write method. If the code in the callback
throws an exception, Realm cancels the transaction.
Otherwise, Realm commits the transaction.

Objective-C

objectivec Copy

// Open the default realm.
RLMRealm *realm = [RLMRealm defaultRealm];

// Open a thread-safe transaction.
[realm transactionWithBlock:^() {
    // ... Make changes ...
    // Realm automatically cancels the transaction in case of exception.
    // Otherwise, Realm automatically commits the transaction at the
    // end of the code block.
}];

Swift

swift Copy

// Open the default realm.
let realm = try! Realm()

// Prepare to handle exceptions.
do {
    // Open a thread-safe transaction.
    try realm.write {
        // Make any writes within this code block.
        // Realm automatically cancels the transaction
        // if this code throws an exception. Otherwise,
        // Realm automatically commits the transaction
        // after the end of this code block.
    }
} catch let error as NSError {
    // Failed to write to realm.
    // ... Handle error ...
}

Interface-Driven Writes Copy Chapter

Realm always delivers notifications asynchronously, so they
never block the UI thread. However, there are situations when the UI
must reflect changes instantly. If you update the UI directly at the
same time as the write, the eventual notification could double that
update. This could lead to your app crashing due to inconsistent state
between the UI and the backing data store. To avoid this, you can write
without sending a notification to a specific handler. We call this type
of transaction an interface-driven write.

Example:
Say we decide to manage a table view's data source manually, because
our app design requires an instantaneous response to UI-driven table
updates. As soon as a user adds an item to the table view, we insert
it to our data source, which writes to the realm but also
immediately kicks off the animation. However, when Realm
delivers the change notification for this insertion a little later,
it indicates that an object has been added. But we already updated
the table view for it! Rather than writing complicated code to handle
this case, we can use interface-driven writes to prevent a specific
notification handler from firing for that specific write.

Interface-driven writes, also known as silent writes, are especially
useful when using fine-grained collection notifications. While you use
interface-driven writes for the current user's updates and update the UI
immediately, the sync process can use standard notifications to update
the UI.

Guides Crud Delete (`docs/guides/crud/delete.md`) Copy Section

CRUD - Delete - Swift SDK

Delete Realm Objects Copy Chapter

Deleting Realm Objects must occur within write transactions. For
more information about write transactions, see: Transactions.

If you want to delete the Realm file itself, see: Delete a Realm.

Important:
You cannot access or modify an object after you have deleted it from
a realm. If you try to use a deleted object, Realm throws an
error.

About The Examples On This Page Copy Section

The examples on this page use the following models:

Objective-C

// DogToy.h
@interface DogToy : RLMObject
@property NSString *name;
@end

// Dog.h
@interface Dog : RLMObject
@property NSString *name;
@property int age;
@property NSString *color;

// To-one relationship
@property DogToy *favoriteToy;

@end

// Enable Dog for use in RLMArray
RLM_COLLECTION_TYPE(Dog)

// Person.h
// A person has a primary key ID, a collection of dogs, and can be a member of multiple clubs.
@interface Person : RLMObject
@property int _id;
@property NSString *name;

// To-many relationship - a person can have many dogs
@property RLMArray<Dog *><Dog> *dogs;

// Inverse relationship - a person can be a member of many clubs
@property (readonly) RLMLinkingObjects *clubs;
@end

RLM_COLLECTION_TYPE(Person)

// DogClub.h
@interface DogClub : RLMObject
@property NSString *name;
@property RLMArray<Person *><Person> *members;
@end

// Dog.m
@implementation Dog
@end

// DogToy.m
@implementation DogToy
@end

// Person.m
@implementation Person
// Define the primary key for the class
+ (NSString *)primaryKey {
    return @"_id";
}

// Define the inverse relationship to dog clubs
+ (NSDictionary *)linkingObjectsProperties {
    return @{
        @"clubs": [RLMPropertyDescriptor descriptorWithClass:DogClub.class propertyName:@"members"],
    };
}
@end

// DogClub.m
@implementation DogClub
@end

Swift

class Dog: Object {
    @Persisted var name = ""
    @Persisted var age = 0
    @Persisted var color = ""
    @Persisted var currentCity = ""
    @Persisted var citiesVisited: MutableSet<String>
    @Persisted var companion: AnyRealmValue

    // Map of city name -> favorite park in that city
    @Persisted var favoriteParksByCity: Map<String, String>
}

Delete an Object Copy Section

Objective-C

To delete an object from a realm, pass the object to
-[RLMRealm deleteObject:]
inside of a write transaction.

[realm transactionWithBlock:^() {
    // Delete the instance from the realm.
    [realm deleteObject:dog];
}];

Swift

To delete an object from a realm, pass the object to
Realm.delete(_:)
inside of a write transaction.

// Previously, we've added a dog object to the realm.
let dog = Dog(value: ["name": "Max", "age": 5])

let realm = try! Realm()
try! realm.write {
    realm.add(dog)
}

// Delete the instance from the realm.
try! realm.write {
    realm.delete(dog)
}

Delete Multiple Objects Copy Section

Swift

Version added: 10.19.0

To delete a collection of objects from a realm, pass the
collection to Realm.delete(_:)
inside of a write transaction.

let realm = try! Realm()
try! realm.write {
    // Find dogs younger than 2 years old.
    let puppies = realm.objects(Dog.self).where {
        $0.age < 2
    }

    // Delete the objects in the collection from the realm.
    realm.delete(puppies)
}

Swift Nspredicate

To delete a collection of objects from a realm, pass the
collection to Realm.delete(_:)
inside of a write transaction.

let realm = try! Realm()
try! realm.write {
    // Find dogs younger than 2 years old.
    let puppies = realm.objects(Dog.self).filter("age < 2")

    // Delete the objects in the collection from the realm.
    realm.delete(puppies)
}

Objective-C

To delete a collection of objects from a realm, pass the
collection to -[Realm deleteObjects:]
inside of a write transaction.

RLMRealm *realm = [RLMRealm defaultRealm];

[realm transactionWithBlock:^() {
    // Find dogs younger than 2 years old.
    RLMResults<Dog *> *puppies = [Dog objectsInRealm:realm where:@"age < 2"];

    // Delete all objects in the collection from the realm.
    [realm deleteObjects:puppies];
}];

Delete an Object and Its Related Objects Copy Section

Sometimes, you want to delete related objects when you delete the parent
object. We call this a chaining delete. Realm does not delete
the related objects for you. If you do not delete the objects yourself,
they remain orphaned in your realm. Whether or not this is a problem
depends on your application's needs.

The best way to delete dependent objects is to iterate through
the dependencies and delete them before deleting the parent object.

Objective-C

[realm transactionWithBlock:^() {
    // Delete Ali's dogs.
    [realm deleteObjects:[ali dogs]];
    // Delete Ali.
    [realm deleteObject:ali];
}];

Swift

let person = realm.object(ofType: Person.self, forPrimaryKey: 1)!
try! realm.write {
    // Delete the related collection
    realm.delete(person.dogs)
    realm.delete(person)
}

Delete All Objects of a Specific Type Copy Section

Objective-C

To delete all objects of a given object type from a realm, pass
the result of [+[YourRealmObjectClass
allObjectsInRealm:]]
to -[Realm deleteObjects:]
inside of a write transaction. Replace YourRealmObjectClass
with your Realm object class name.

RLMRealm *realm = [RLMRealm defaultRealm];

[realm transactionWithBlock:^() {
    // Delete all instances of Dog from the realm.
    RLMResults<Dog *> *allDogs = [Dog allObjectsInRealm:realm];
    [realm deleteObjects:allDogs];
}];

Swift

To delete all objects of a given object type from a realm, pass
the result of Realm.objects(_)
for the type you wish to delete to Realm.delete(_:)
inside of a write transaction.

let realm = try! Realm()

try! realm.write {
    // Delete all instances of Dog from the realm.
    let allDogs = realm.objects(Dog.self)
    realm.delete(allDogs)
}

Delete All Objects in a Realm Copy Section

Objective-C

To delete all objects from the realm, call [-[RLMRealm
deleteAllObjects]]
inside of a write transaction. This clears the realm of all object
instances but does not affect the realm's schema.

RLMRealm *realm = [RLMRealm defaultRealm];

[realm transactionWithBlock:^() {
    // Delete all objects from the realm.
    [realm deleteAllObjects];
}];

Swift

To delete all objects from the realm, call
Realm.deleteAll() inside of a
write transaction. This clears the realm of all object instances
but does not affect the realm's schema.

let realm = try! Realm()

try! realm.write {
    // Delete all objects from the realm.
    realm.deleteAll()
}

Delete Map Keys/Values Copy Section

You can delete map entries in a few ways:

• Use removeObject(for:) to remove the key and the value
• If the dictionary's value is optional, you can set the value of the key to
  nil to keep the key.

let realm = try! Realm()

// Find the dog we want to update
let wolfie = realm.objects(Dog.self).where {
    $0.name == "Wolfie"
}.first!

// Delete an entry
try! realm.write {
    // Use removeObject(for:)
    wolfie.favoriteParksByCity.removeObject(for: "New York")
    // Or assign `nil` to delete non-optional values.
    // If the value type were optional (e.g. Map<String, String?>)
    // this would assign `nil` to that entry rather than deleting it.
    wolfie.favoriteParksByCity["New York"] = nil
}
XCTAssertNil(wolfie.favoriteParksByCity["New York"])

Delete MutableSet Elements Copy Section

You can delete specific elements from a MutableSet, or clear all of the elements from the set.
If you are working with multiple sets, you can also remove elements in one
set from the other set; see: Update a MutableSet Property.

let realm = try! Realm()

// Record a dog's name and list of cities he has visited.
let dog = Dog()
dog.name = "Maui"
let dogCitiesVisited = ["New York", "Boston", "Toronto"]
try! realm.write {
    realm.add(dog)
    dog.citiesVisited.insert(objectsIn: dogCitiesVisited)
}
XCTAssertEqual(dog.citiesVisited.count, 3)

// Later... we decide the dog didn't really visit Toronto
// since the plane just stopped there for a layover.
// Remove the element from the set.
try! realm.write {
    dog.citiesVisited.remove("Toronto")
}
XCTAssertEqual(dog.citiesVisited.count, 2)

// Or, in the case where the person entered the data for
// the wrong dog, remove all elements from the set.
try! realm.write {
    dog.citiesVisited.removeAll()
}
XCTAssertEqual(dog.citiesVisited.count, 0)

Delete the Value of an AnyRealmValue Copy Section

To delete the value of an AnyRealmValue, set it to .none.

let realm = try! Realm()

// Wolfie's companion is "Fluffy the Cat", represented by a string.
// Fluffy has gone to visit friends for the summer, so Wolfie has no companion.
let wolfie = realm.objects(Dog.self).where {
    $0.name == "Wolfie"
}.first!

try! realm.write {
    // You cannot set an AnyRealmValue to nil; you must set it to `.none`, instead.
    wolfie.companion = .none
}

Delete an Object Asynchronously Copy Chapter

You can use Swift concurrency features to asynchronously delete objects
using an actor-isolated realm.

This function from the example RealmActor defined on the
Use Realm with Actors page shows how you might
delete an object in an actor-isolated realm:

func deleteTodo(id: ObjectId) async throws {
    try await realm.asyncWrite {
        let todoToDelete = realm.object(ofType: Todo.self, forPrimaryKey: id)
        realm.delete(todoToDelete!)
    }
}

And you might perform this deletion using Swift's async syntax:

let actor = try await RealmActor()
let todoId = await actor.getObjectId(forTodoNamed: "Keep Mr. Frodo safe from that Gollum")

try await actor.deleteTodo(id: todoId)
let updatedTodoCount = await actor.count
if updatedTodoCount == todoCount - 1 {
    print("Successfully deleted the todo")
}

This operation does not block or perform I/O on the calling thread. For
more information about writing to realm using Swift concurrency features,
refer to Use Realm with Actors.

Guides Crud Filter Data (`docs/guides/crud/filter-data.md`) Copy Section

Filter Data - Swift SDK

Overview Copy Chapter

To filter data in your realm, you can leverage
Realm's query engine.

Version added: 10.19.0

The Realm Swift Query API offers an
idiomatic way for Swift developers to query data. Use Swift-style syntax
to query a realm with the benefits of auto-completion and
type safety. The Realm Swift Query API does not replace the NSPredicate
Query API in newer SDK versions; instead, you can use either.

For SDK versions prior to 10.19.0, or for Objective-C developers,
Realm's query engine supports NSPredicate Query.

About the Examples on This Page Copy Chapter

The examples in this page use a simple data set for a
task list app. The two Realm object types are Project
and Task. A Task has a name, assignee's name, and
completed flag. There is also an arbitrary number for
priority -- higher is more important -- and a count of
minutes spent working on it. Finally, a Task can have one
or more string labels and one or more integer ratings.

A Project has zero or more Tasks.

See the schema for these two classes, Project and
Task, below:

Objective-C

// Task.h
@interface Task : RLMObject
@property NSString *name;
@property bool isComplete;
@property NSString *assignee;
@property int priority;
@property int progressMinutes;
@end
RLM_COLLECTION_TYPE(Task)
// Task.m
@implementation Task
@end

// Project.h
@interface Project : RLMObject
@property NSString *name;
@property RLMArray<Task> *tasks;
@end
// Project.m
@implementation Project
@end

Swift

class Task: Object {
    @Persisted var name = ""
    @Persisted var isComplete = false
    @Persisted var assignee: String?
    @Persisted var priority = 0
    @Persisted var progressMinutes = 0
    @Persisted var labels: MutableSet<String>
    @Persisted var ratings: MutableSet<Int>
}

class Project: Object {
    @Persisted var name = ""
    @Persisted var tasks: List<Task>
}

You can set up the realm for these examples with the following code:

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];
[realm transactionWithBlock:^() {
    // Add projects and tasks here
}];

RLMResults *tasks = [Task allObjectsInRealm:realm];
RLMResults *projects = [Project allObjectsInRealm:realm];

Swift

let realm = try! Realm()
try! realm.write {
    // Add tasks and projects here.
    let project = Project()
    project.name = "New Project"
    let task = Task()
    task.assignee = "Alex"
    task.priority = 5
    project.tasks.append(task)
    realm.add(project)
    // ...
}
let tasks = realm.objects(Task.self)
let projects = realm.objects(Project.self)

Realm Swift Query API Copy Chapter

Version added: 10.19.0
For SDK versions older than 10.19.0, use the NSPredicate query API.

You can build a filter with Swift-style syntax using the .where
Realm Swift query API:

let realmSwiftQuery = projects.where {
    ($0.tasks.progressMinutes > 1) && ($0.tasks.assignee == "Ali")
}

This query API constructs an NSPredicate
to perform the query. It gives developers a type-safe idiomatic API to
use directly, and abstracts away the NSPredicate construction.

The .where API takes a callback that evaluates to true or false. The
callback receives an instance of the type being queried, and you can
leverage the compiler to statically check that you are creating valid queries
that reference valid properties.

In the examples on this page, we use the $0 shorthand to reference
the variable passed into the callback.

Operators Copy Section

There are several types of operators available to query a
Realm collection. Queries
work by evaluating an operator expression for every
object in the collection being
queried. If the expression resolves to true, Realm
Database includes the object in the results collection.

Comparison Operators

You can use Swift comparison operators with the Realm Swift
Query API (==, !=, >, >=, <, <=).

Example:
The following example uses the query engine's
comparison operators to:

• Find high priority tasks by comparing the value of the priority property value with a threshold number, above which priority can be considered high.
• Find long-running tasks by seeing if the progressMinutes property is at or above a certain value.
• Find unassigned tasks by finding tasks where the assignee property is equal to null.

swift Copy

let highPriorityTasks = tasks.where {
    $0.priority > 5
}
print("High-priority tasks: \(highPriorityTasks.count)")

let longRunningTasks = tasks.where {
    $0.progressMinutes >= 120
}
print("Long running tasks: \(longRunningTasks.count)")

let unassignedTasks = tasks.where {
    $0.assignee == nil
}
print("Unassigned tasks: \(unassignedTasks.count)")

Collections

You can query for values within a collection using the .contains operators.
You can search for individual values by element, or search within a range.

Example:

• Find tasks where the labels MutableSet collection property contains "quick win".
• Find tasks where the progressMinutes property is within a given range of minutes.

swift Copy

let quickWinTasks = tasks.where {
    $0.labels.contains("quick win")
}
print("Tasks labeled 'quick win': \(quickWinTasks.count)")

let progressBetween30and60 = tasks.where {
    $0.progressMinutes.contains(30...60)
}
print("Tasks with progress between 30 and 60 minutes: \(progressBetween30and60.count)")

Find tasks where the labels MutableSet collection property contains any of the elements in the given array: "quick win" or "bug".

swift Copy

let quickWinOrBugTasks = tasks.where {
    $0.labels.containsAny(in: ["quick win", "bug"])
}
print("Tasks labeled 'quick win' or 'bug': \(quickWinOrBugTasks.count)")

Version added: 10.23.0
:The IN operator

The Realm Swift Query API now supports the IN operator. Evaluates to true if the property referenced by the expression contains the value.

Example:
Find tasks assigned to specific teammates Ali or Jamie by seeing if the assignee property is in a list of names.

swift Copy

let taskAssigneeInAliOrJamie = tasks.where {
    let assigneeNames = ["Ali", "Jamie"]
    return $0.assignee.in(assigneeNames)
}
print("Tasks IN Ali or Jamie: \(taskAssigneeInAliOrJamie.count)")

Logical Operators

You can make compound queries using Swift logical operators (&&, !,
||).

Example:
We can use the query language's logical operators to find
all of Ali's completed tasks. That is, we find all tasks
where the assignee property value is equal to 'Ali' AND
the isComplete property value is true:

swift Copy

let aliComplete = tasks.where {
    ($0.assignee == "Ali") && ($0.isComplete == true)
}
print("Ali's complete tasks: \(aliComplete.count)")

String Operators

You can compare string values using these string operators.
Regex-like wildcards allow more flexibility in search.

Note:
You can use the following options with string operators:

• .caseInsensitive for case insensitivity. $0.name.contains("f", options: .caseInsensitive)
• .diacriticInsensitive for diacritic insensitivity: Realm treats
  special characters as the base character (e.g. é -> e). $0.name.contains("e", options: .diacriticInsensitive)

Example:
The following example uses the query engine's string operators to find:

• Projects with a name starting with the letter 'e'
• Projects with names that contain 'ie'
• Projects with an assignee property whose value is similar to Al?x
• Projects that contain e-like characters with diacritic insensitivity

swift Copy

// Use the .caseInsensitive option for case-insensitivity.
let startWithE = projects.where {
    $0.name.starts(with: "e", options: .caseInsensitive)
}
print("Projects that start with 'e': \(startWithE.count)")

let containIe = projects.where {
    $0.name.contains("ie")
}
print("Projects that contain 'ie': \(containIe.count)")

let likeWildcard = tasks.where {
    $0.assignee.like("Al?x")
}
print("Tasks with assignees like Al?x: \(likeWildcard.count)")

// Use the .diacriticInsensitive option for diacritic insensitivity: contains 'e', 'E', 'é', etc.
let containElike = projects.where {
    $0.name.contains("e", options: .diacriticInsensitive)
}
print("Projects that contain 'e', 'E', 'é', etc.: \(containElike.count)")

Note:
String sorting and case-insensitive queries are only supported for
character sets in 'Latin Basic', 'Latin Supplement', 'Latin Extended
A', and 'Latin Extended B' (UTF-8 range 0-591).

Geospatial Operators

Version added: 10.47.0

Use the geoWithin operator to query geospatial data with one of the
SDK's provided shapes:

• GeoCircle
• GeoBox
• GeoPolygon

This operator evaluates to true if:

• An object has a geospatial data "shape" containing a String property
  with the value of Point and a List containing a longitude/latitude
  pair.
• The longitude/latitude of the persisted object falls within the geospatial
  query shape.

let companiesInSmallCircle = realm.objects(Geospatial_Company.self).where {
    $0.location.geoWithin(smallCircle!)
}
print("Number of companies in small circle: \(companiesInSmallCircle.count)")

For more information about querying geospatial data, refer to
Query Geospatial Data.

Aggregate Operators

You can apply an aggregate operator to a collection property
of a Realm object. Aggregate operators traverse a
collection and reduce it
to a single value.

Example:
We create a couple of filters to show different facets of
the data:

• Projects with average tasks priority above 5.
• Projects that contain only low-priority tasks below 5.
• Projects where all tasks are high-priority above 5.
• Projects that contain more than 5 tasks.
• Long running projects.

swift Copy

let averageTaskPriorityAbove5 = projects.where {
    $0.tasks.priority.avg > 5
}
print("Projects with average task priority above 5: \(averageTaskPriorityAbove5.count)")

let allTasksLowerPriority = projects.where {
    $0.tasks.priority.max < 5
}
print("Projects where all tasks are lower priority: \(allTasksLowerPriority.count)")

let allTasksHighPriority = projects.where {
    $0.tasks.priority.min > 5
}
print("Projects where all tasks are high priority: \(allTasksHighPriority.count)")

let moreThan5Tasks = projects.where {
    $0.tasks.count > 5
}
print("Projects with more than 5 tasks: \(moreThan5Tasks.count)")

let longRunningProjects = projects.where {
    $0.tasks.progressMinutes.sum > 100
}
print("Long running projects: \(longRunningProjects.count)")

Set Operators

A set operator uses specific rules to determine whether
to pass each input collection object to the output
collection by applying a given query expression to every element of
a given list property of
the object.

Example:
Running the following queries in projects collections returns:

• Projects where a set of string labels contains any of "quick win", "bug".
• Projects where any element in a set of integer ratings is greater than 3.

swift Copy

let projectsWithGivenLabels = projects.where {
    $0.tasks.labels.containsAny(in: ["quick win", "bug"])
}
print("Projects with quick wins: \(projectsWithGivenLabels.count)")

let projectsWithRatingsOver3 = projects.where {
    $0.tasks.ratings > 3
}
print("Projects with any ratings over 3: \(projectsWithRatingsOver3.count)")

Subqueries Copy Section

You can iterate through a collection property with another query using a
subquery. To form a subquery, you must wrap the expression in parentheses
and immediately follow it with the .count aggregator.

(<query>).count > n

If the expression does not produce a valid subquery, you'll get an
exception at runtime.

Example:
Running the following query on a projects collection returns projects
with tasks that have not been completed by a user named Alex.

swift Copy

let subquery = projects.where {
            ($0.tasks.isComplete == false && $0.tasks.assignee == "Alex").count > 0
}
print("Projects with incomplete tasks assigned to Alex: \(subquery.count)")

NSPredicate Queries Copy Chapter

You can build a filter with NSPredicate:

Objective-C

NSPredicate *predicate = [NSPredicate predicateWithFormat:@"progressMinutes > %@ AND name == %@", @1, @"Ali"];

Swift

let predicate = NSPredicate(format: "progressMinutes > 1 AND name == %@", "Ali")

Expressions Copy Section

Filters consist of expressions in an NSPredicate. An expression consists of
one of the following:

• The name (keypath) of a property of the object currently being evaluated.
• An operator and up to two argument expression(s).
• A value, such as a string ('hello') or a number (5).

Dot Notation Copy Section

When referring to an object property, you can use dot notation to refer
to child properties of that object. You can even refer to the properties of
embedded objects and relationships with dot notation.

For example, consider a query on an object with a workplace property that
refers to a Workplace object. The Workplace object has an embedded object
property, address. You can chain dot notations to refer to the zipcode
property of that address:

workplace.address.zipcode == 10012

Substitutions Copy Section

You can use the following substitutions in your predicate format strings:

• %@ to specify values
• %K to specify keypaths

Objective-C

[NSPredicate predicateWithFormat:@"%K > %@ AND %K == %@", @"progressMinutes", @1, @"name", @"Ali"];

Swift

NSPredicate(format: "%K > %@ AND %K == %@", "progressMinutes", NSNumber(1), "name", "Ali")

Operators Copy Section

There are several types of operators available to filter a
Realm collection. Filters
work by evaluating an operator expression for every
object in the collection being
filtered. If the expression resolves to true, Realm
Database includes the object in the results collection.

Comparison Operators

The most straightforward operation in a search is to compare
values.

Important:
The type on both sides of the operator must be equivalent. For
example, comparing an ObjectId with string will result in a precondition failure with a
message like:

text Copy

"Expected object of type object id for property 'id' on object of type
'User', but received: 11223344556677889900aabb (Invalid value)"

You can compare any numeric type with any other numeric type.

Example:
The following example uses the query engine's
comparison operators to:

• Find high priority tasks by comparing the value of the priority property value with a threshold number, above which priority can be considered high.
• Find long-running tasks by seeing if the progressMinutes property is at or above a certain value.
• Find unassigned tasks by finding tasks where the assignee property is equal to null.
• Find tasks assigned to specific teammates Ali or Jamie by seeing if the assignee property is in a list of names.

Objective-C

objectivec Copy

NSLog(@"High priority tasks: %lu",
      [[tasks objectsWithPredicate:[NSPredicate predicateWithFormat:@"priority > %@", @5]] count]);

NSLog(@"Short running tasks: %lu",
      [[tasks objectsWhere:@"progressMinutes between {1, 15}"] count]);

NSLog(@"Unassigned tasks: %lu",
      [[tasks objectsWhere:@"assignee == nil"] count]);

NSLog(@"Ali or Jamie's tasks: %lu",
      [[tasks objectsWhere:@"assignee IN {'Ali', 'Jamie'}"] count]);

NSLog(@"Tasks with progress between 30 and 60 minutes: %lu",
      [[tasks objectsWhere:@"progressMinutes BETWEEN {30, 60}"] count]);

Swift

swift Copy

let highPriorityTasks = tasks.filter("priority > 5")
print("High priority tasks: \(highPriorityTasks.count)")

let longRunningTasks = tasks.filter("progressMinutes > 120")
print("Long running tasks: \(longRunningTasks.count)")

let unassignedTasks = tasks.filter("assignee == nil")
print("Unassigned tasks: \(unassignedTasks.count)")

let aliOrJamiesTasks = tasks.filter("assignee IN {'Ali', 'Jamie'}")
print("Ali or Jamie's tasks: \(aliOrJamiesTasks.count)")

let progressBetween30and60 = tasks.filter("progressMinutes BETWEEN {30, 60}")
print("Tasks with progress between 30 and 60 minutes: \(progressBetween30and60.count)")

Logical Operators

You can make compound predicates using logical operators.

Example:
We can use the query language's logical operators to find
all of Ali's completed tasks. That is, we find all tasks
where the assignee property value is equal to 'Ali' AND
the isComplete property value is true:

Objective-C

objectivec Copy

NSLog(@"Ali's complete tasks: %lu",
  [[tasks objectsWhere:@"assignee == 'Ali' AND isComplete == true"] count]);

Swift

swift Copy

let aliComplete = tasks.filter("assignee == 'Ali' AND isComplete == true")
print("Ali's complete tasks: \(aliComplete.count)")

String Operators

You can compare string values using these string operators.
Regex-like wildcards allow more flexibility in search.

Note:
You can use the following modifiers with the string operators:

• [c] for case insensitivity. [NSPredicate predicateWithFormat: @"name CONTAINS[c] 'f'"]``NSPredicate(format: "name CONTAINS[c] 'f'")
• [d] for diacritic insensitivity: Realm treats special characters as the base character (e.g. é -> e). [NSPredicate predicateWithFormat: @"name CONTAINS[d] 'e'"]``NSPredicate(format: "name CONTAINS[d] 'e'")

Example:
We use the query engine's string operators to find
projects with a name starting with the letter 'e' and
projects with names that contain 'ie':

Objective-C

objectivec Copy

// Use [c] for case-insensitivity.
NSLog(@"Projects that start with 'e': %lu",
  [[projects objectsWhere:@"name BEGINSWITH[c] 'e'"] count]);

NSLog(@"Projects that contain 'ie': %lu",
  [[projects objectsWhere:@"name CONTAINS 'ie'"] count]);

Swift

swift Copy

// Use [c] for case-insensitivity.
let startWithE = projects.filter("name BEGINSWITH[c] 'e'")
print("Projects that start with 'e': \(startWithE.count)")

let containIe = projects.filter("name CONTAINS 'ie'")
print("Projects that contain 'ie': \(containIe.count)")

// [d] for diacritic insensitivty: contains 'e', 'E', 'é', etc.
let containElike = projects.filter("name CONTAINS[cd] 'e'")
print("Projects that contain 'e', 'E', 'é', etc.: \(containElike.count)")

Note:
String sorting and case-insensitive queries are only supported for
character sets in 'Latin Basic', 'Latin Supplement', 'Latin Extended
A', and 'Latin Extended B' (UTF-8 range 0-591).

Geospatial Operators

Version added: 10.47.0

You can perform a geospatial query using the IN operator with one
of the SDK's provided shapes:

• GeoCircle
• GeoBox
• GeoPolygon

This operator evaluates to true if:

• An object has a geospatial data "shape" containing a String property
  with the value of Point and a List containing a longitude/latitude
  pair.
• The longitude/latitude of the persisted object falls within the geospatial
  query shape.

let filterArguments = NSMutableArray()
filterArguments.add(largeBox)
let companiesInLargeBox = realm.objects(Geospatial_Company.self)
    .filter(NSPredicate(format: "location IN %@", argumentArray: filterArguments as? [Any]))
print("Number of companies in large box: \(companiesInLargeBox.count)")

For more information about querying geospatial data, refer to
Query Geospatial Data.

Aggregate Operators

You can apply an aggregate operator to a collection property
of a Realm object. Aggregate operators traverse a
collection and reduce it
to a single value.

Example:
We create a couple of filters to show different facets of
the data:

• Projects with average tasks priority above 5.
• Long running projects.

Objective-C

objectivec Copy

NSLog(@"Projects with average tasks priority above 5: %lu",
      [[projects objectsWhere:@"[email protected] > 5"] count]);

NSLog(@"Projects where all tasks are lower priority: %lu",
      [[projects objectsWhere:@"[email protected] < 5"] count]);

NSLog(@"Projects where all tasks are high priority: %lu",
      [[projects objectsWhere:@"[email protected] > 5"] count]);

NSLog(@"Projects with more than 5 tasks: %lu",
      [[projects objectsWhere:@"tasks.@count > 5"] count]);

NSLog(@"Long running projects: %lu",
      [[projects objectsWhere:@"[email protected] > 100"] count]);

Swift

swift Copy

let averageTaskPriorityAbove5 = projects.filter("[email protected] > 5")
print("Projects with average task priority above 5: \(averageTaskPriorityAbove5.count)")

let allTasksLowerPriority = projects.filter("[email protected] < 5")
print("Projects where all tasks are lower priority: \(allTasksLowerPriority.count)")

let allTasksHighPriority = projects.filter("[email protected] > 5")
print("Projects where all tasks are high priority: \(allTasksHighPriority.count)")

let moreThan5Tasks = projects.filter("tasks.@count > 5")
print("Projects with more than 5 tasks: \(moreThan5Tasks.count)")

let longRunningProjects = projects.filter("[email protected] > 100")
print("Long running projects: \(longRunningProjects.count)")

Set Operators

A set operator uses specific rules to determine whether
to pass each input collection object to the output
collection by applying a given predicate to every element of
a given list property of
the object.

Example:
We use the query engine's set operators to find:

• Projects with no complete tasks.
• Projects with any top priority tasks.

Objective-C

objectivec Copy

NSLog(@"Projects with no complete tasks: %lu",
  [[projects objectsWhere:@"NONE tasks.isComplete == true"] count]);

NSLog(@"Projects with any top priority tasks: %lu",
  [[projects objectsWhere:@"ANY tasks.priority == 10"] count]);

Swift

swift Copy

let noCompleteTasks = projects.filter("NONE tasks.isComplete == true")
print("Projects with no complete tasks: \(noCompleteTasks.count)")

let anyTopPriorityTasks = projects.filter("ANY tasks.priority == 10")
print("Projects with any top priority tasks: \(anyTopPriorityTasks.count)")

Subqueries Copy Section

You can iterate through a collection property with another query using the
SUBQUERY() predicate function. SUBQUERY() has the following signature:

SUBQUERY(<collection>, <variableName>, <predicate>)

• collection: the name of the list property to iterate through
• variableName: a variable name of the current element to use in the subquery
• predicate: a string that contains the subquery predicate. You can use the
  variable name specified by variableName to refer to the currently iterated
  element.

Example:
Running the following filter on a projects collection returns projects
with tasks that have not been completed by a user named Alex.

Objective-C

objectivec Copy

NSPredicate *predicate = [NSPredicate predicateWithFormat:
                          @"SUBQUERY(tasks, $task, $task.isComplete == %@ AND $task.assignee == %@).@count > 0",
                          @NO,
                          @"Alex"];
NSLog(@"Projects with incomplete tasks assigned to Alex: %lu",
  [[projects objectsWithPredicate:predicate] count]);

Swift

swift Copy

let predicate = NSPredicate(
    format: "SUBQUERY(tasks, $task, $task.isComplete == false AND $task.assignee == %@).@count > 0", "Alex")
print("Projects with incomplete tasks assigned to Alex: \(projects.filter(predicate).count)")

Guides Crud React To Changes (`docs/guides/crud/react-to-changes.md`) Copy Section

React to Changes - Swift SDK

All Realm objects are live objects, which means they
automatically update whenever they're modified. Realm emits a
notification event whenever any property changes. You can register a
notification handler to listen for these notification events, and update
your UI with the latest data.

This page shows how to manually register notification listeners in Swift.
Realm SDK for Swift offers SwiftUI property wrappers to make it easy to
automatically update the UI when data changes. For more about how to use
the SwiftUI property wrappers to react to changes, refer to
Observe an Object.

Register a Realm Change Listener Copy Chapter

You can register a notification handler on an entire realm. Realm calls the notification
handler whenever any write transaction involving that Realm is
committed. The handler receives no information about the change.

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];

// Observe realm notifications. Keep a strong reference to the notification token
// or the observation will stop.
RLMNotificationToken *token = [realm addNotificationBlock:^(RLMNotification  _Nonnull notification, RLMRealm * _Nonnull realm) {
    // `notification` is an enum specifying what kind of notification was emitted.
    // ... update UI ...
}];

// ...

// Later, explicitly stop observing.
[token invalidate];

Swift

let realm = try! Realm()

// Observe realm notifications. Keep a strong reference to the notification token
// or the observation will stop.
let token = realm.observe { notification, realm in
    // `notification` is an enum specifying what kind of notification was emitted
    viewController.updateUI()
}

// ...

// Later, explicitly stop observing.
token.invalidate()

Register a Collection Change Listener Copy Chapter

You can register a notification handler on a collection within a
realm.

Realm notifies your handler:

• After first retrieving the collection.
• Whenever a write transaction adds, changes, or removes objects in the collection.

Notifications describe the changes since the prior notification with
three lists of indices: the indices of the objects that were deleted,
inserted, and modified.

Important:
In collection notification handlers, always apply changes
in the following order: deletions, insertions, then
modifications. Handling insertions before deletions may
result in unexpected behavior.

Collection notifications provide a change parameter that reports which
objects are deleted, added, or modified during the write transaction. This
RealmCollectionChange
resolves to an array of index paths that you can pass to a UITableView's
batch update methods.

Important:
This example of a collection change listener does not support
high-frequency updates. Under an intense workload, this collection
change listener may cause the app to throw an exception.

Objective-C

/* Detailed source-code truncated for AI context efficiency. */

Swift

/* Detailed source-code truncated for AI context efficiency. */

Register an Object Change Listener Copy Chapter

You can register a notification handler on a specific object
within a realm. Realm notifies your handler:

• When the object is deleted.
• When any of the object's properties change.

The handler receives information about what fields changed
and whether the object was deleted.

Objective-C

@interface Dog : RLMObject
@property NSString *name;
@property int age;
@end

@implementation Dog
@end

RLMNotificationToken *objectNotificationToken = nil;

void objectNotificationExample() {
    Dog *dog = [[Dog alloc] init];
    dog.name = @"Max";
    dog.age = 3;
    
    // Open the default realm
    RLMRealm *realm = [RLMRealm defaultRealm];
    [realm transactionWithBlock:^{
        [realm addObject:dog];
    }];

    // Observe object notifications. Keep a strong reference to the notification token
    // or the observation will stop. Invalidate the token when done observing.
    objectNotificationToken = [dog addNotificationBlock:^(BOOL deleted, NSArray<RLMPropertyChange *> * _Nullable changes, NSError * _Nullable error) {
        if (error != nil) {
            NSLog(@"An error occurred: %@", [error localizedDescription]);
            return;
        }
        if (deleted) {
            NSLog(@"The object was deleted.");
            return;
        }
        NSLog(@"Property %@ changed to '%@'",
              changes[0].name,
              changes[0].value);
    }];

    // Now update to trigger the notification
    [realm transactionWithBlock:^{
        dog.name = @"Wolfie";
    }];

}

Swift

// Define the dog class.
class Dog: Object {
    @Persisted var name = ""
}

var objectNotificationToken: NotificationToken?

func objectNotificationExample() {
    let dog = Dog()
    dog.name = "Max"

    // Open the default realm.
    let realm = try! Realm()
    try! realm.write {
        realm.add(dog)
    }
    // Observe object notifications. Keep a strong reference to the notification token
    // or the observation will stop. Invalidate the token when done observing.
    objectNotificationToken = dog.observe { change in
        switch change {
        case .change(let object, let properties):
            for property in properties {
                print("Property '\(property.name)' of object \(object) changed to '\(property.newValue!)'")
            }
        case .error(let error):
            print("An error occurred: \(error)")
        case .deleted:
            print("The object was deleted.")
        }
    }

    // Now update to trigger the notification
    try! realm.write {
        dog.name = "Wolfie"
    }
}

Register a Key Path Change Listener Copy Chapter

Version added: 10.12.0

In addition to registering a notification handler on an object
or collection, you can pass an optional string keyPaths parameter to specify the key path or
key paths to watch.

Example:
```
/* Detailed source-code truncated for AI context efficiency. */

>

> Version added: 10.14.0

You can `observe`
a partially type-erased [PartialKeyPath](https://developer.apple.com/documentation/swift/partialkeypath)
on `Objects` or `RealmCollections`.

```swift
objectNotificationToken = dog.observe(keyPaths: [\Dog.favoriteToy, \Dog.age], { change in

When you specify keyPaths, only changes to those
keyPaths trigger notification blocks. Any other changes do not trigger
notification blocks.

Example:
Consider a Dog object where one of its properties is a list of
siblings:

swift Copy

class Dog: Object {
    @Persisted var name = ""
    @Persisted var siblings: List<Dog>
    @Persisted var age: Int?
}

If you pass siblings as a keyPath to observe, any insertion,
deletion, or modification to the siblings list would trigger a
notification. However, a change to someSibling.name would not trigger
a notification, unless you explicitly observed ["siblings.name"].

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.

Realm Collections Copy Section

When you observe key paths on the various collection types, expect these
behaviors:

• LinkingObjects:
  Observing a property of the LinkingObject triggers a notification for a
  change to that property, but does not trigger notifications for changes to
  its other properties. Insertions or deletions to the list or the object
  that the list is on trigger a notification.
• Lists:
  Observing a property of the list's object will triggers a notification for
  a change to that property, but does not trigger notifications for changes
  to its other properties. Insertions or deletions to the list or the object
  that the list is on trigger a notification.
• Map:
  Observing a property of the map's object triggers a notification for a change
  to that property, but does not trigger notifications for changes to its other
  properties. Insertions or deletions to the Map or the object that the map is
  on trigger a notification. The change parameter reports, in the form of
  keys within the map, which key-value pairs are added, removed, or modified
  during each write transaction.
• MutableSet:
  Observing a property of a MutableSet's object triggers a notification
  for a change to that property, but does not trigger notifications for changes
  to its other properties. Insertions or deletions to the MutableSet or the
  object that the MutableSet is on trigger a notification.
• Results:
  Observing a property of the Result triggers a notification for a change to
  that property, but does not trigger notifications for changes to its other
  properties. Insertions or deletions to the Result trigger a notification.

Write Silently Copy Chapter

You can write to a realm without sending a notification to a
specific observer by passing the observer's notification token in an
array to realm.write(withoutNotifying:_):

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];

// Observe realm notifications
RLMNotificationToken *token = [realm addNotificationBlock:^(RLMNotification  _Nonnull notification, RLMRealm * _Nonnull realm) {
    // ... handle update
}];

// Later, pass the token in an array to the realm's `-transactionWithoutNotifying:block:` method.
// Realm will _not_ notify the handler after this write.
[realm transactionWithoutNotifying:@[token] block:^{
   // ... write to realm
}];

// Finally
[token invalidate];

Swift

let realm = try! Realm()

// Observe realm notifications
let token = realm.observe { notification, realm in
    // ... handle update
}

// Later, pass the token in an array to the realm.write(withoutNotifying:)
// method to write without sending a notification to that observer.
try! realm.write(withoutNotifying: [token]) {
    // ... write to realm
}

// Finally
token.invalidate()

Stop Watching for Changes Copy Chapter

Observation stops when the token returned by an observe call becomes
invalid. You can explicitly invalidate a token by calling its
invalidate() method.

Important:
Notifications stop if the token is in a local variable that goes out
of scope.

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];

// Observe and obtain token
RLMNotificationToken *token = [realm addNotificationBlock:^(RLMNotification  _Nonnull notification, RLMRealm * _Nonnull realm) {
    /* ... */
}];

// Stop observing
[token invalidate];

Swift

let realm = try! Realm()

// Observe and obtain token
let token = realm.observe { notification, realm in /* ... */ }

// Stop observing
token.invalidate()

Key-value Observation Copy Chapter

Key-value Observation Compliance Copy Section

Realm objects are key-value observing (KVO)
compliant
for most properties:

• Almost all managed (non-ignored) properties on Object subclasses
• The invalidated property on Object and List

You cannot observe LinkingObjects properties via Key-value observation.

Important:
You cannot add an object to a realm (with realm.add(obj) or similar
methods) while it has any registered observers.

Managed vs. Unmanaged KVO Considerations Copy Section

Observing the properties of unmanaged instances of Object subclasses
works like any other dynamic property.

Observing the properties of managed objects works differently. With
realm-managed objects, the value of a property may change when:

• You assign to it
• The realm is refreshed, either manually with realm.refresh() or
  automatically on a runloop thread
• You begin a write transaction after changes on another thread

Realm applies changes made in the write transaction(s) on other threads
at once. Observers see Key-value observation notifications at once.
Intermediate steps do not trigger KVO notifications.

Example:
Say your app performs a write transaction that increments a property
from 1 to 10. On the main thread, you get a single notification of a
change directly from 1 to 10. You won't get notifications for every
incremental change between 1 and 10.

Avoid modifying managed Realm objects from within
observeValueForKeyPath(_:ofObject:change:context:). Property values
can change when not in a write transaction, or as part of beginning a
write transaction.

Observing Realm Lists Copy Section

Observing changes made to Realm List properties is simpler than
NSMutableArray properties:

• You don't have to mark List properties as dynamic to observe them.
• You can call modification methods on List directly. Anyone observing
  the property that stores it gets a notification.

You don't need to use mutableArrayValueForKey(_:), although realm
does support this for code compatibility.

Seealso:
Examples of using Realm with ReactiveCocoa from Objective-C,
and ReactKit from Swift.

React to Changes on a Different Actor Copy Chapter

You can observe notifications on a different actor. Calling
await object.observe(on: Actor) or
await collection.observe(on: Actor) registers a block to be called each
time the object or collection changes.

/* Detailed source-code truncated for AI context efficiency. */

For more information about change notifications on another actor,
refer to Observe Notifications on a Different Actor.

React to Changes to a Class Projection Copy Chapter

Like other realm objects, you can react to changes
to a class projection. When you register a class projection change listener,
you see notifications for changes made through the class projection object
directly. You also see notifications for changes to the underlying object's
properties that project through the class projection object.

Properties on the underlying object that are not @Projected in the
class projection do not generate notifications.

This notification block fires for changes in:

• Person.firstName property of the class projection's underlying
  Person object, but not changes to Person.lastName or
  Person.friends.
• PersonProjection.firstName property, but not another class projection
  that uses the same underlying object's property.

let realm = try! Realm()
let projectedPerson = realm.objects(PersonProjection.self).first(where: { $0.firstName == "Jason" })!
let token = projectedPerson.observe(keyPaths: ["firstName"], { change in
    switch change {
    case .change(let object, let properties):
        for property in properties {
            print("Property '\(property.name)' of object \(object) changed to '\(property.newValue!)'")
        }
    case .error(let error):
        print("An error occurred: \(error)")
    case .deleted:
        print("The object was deleted.")
    }
})

// Now update to trigger the notification
try! realm.write {
    projectedPerson.firstName = "David"
}

Notification Delivery Copy Chapter

Notification delivery can vary depending on:

• Whether or not the notification occurs within a write transaction
• The relative threads of the write and the observation

When your application relies on the timing of notification delivery, such
as when you use notifications to update a UITableView, it's important
to understand the specific behaviors for your application code's context.

Perform Writes Only on a Different Thread than the Observing Thread Copy Section

Reading an observed collection or object from inside a change notification
always accurately tells you what has changed in the collection passed to
the callback since the last time the callback was invoked.

Reading collections or objects outside of change notifications always gives
you the exact same values you saw in the most recent change notification
for that object.

Reading objects other than the observed one inside a change notification
may see a different value prior to the notification for that change being
delivered. Realm refresh brings the entire realm from 'old version' to
'latest version' in one operation. However, there might have been multiple
change notifications fired between 'old version' and 'latest version'. Inside
a callback, you may see changes that have pending notifications.

Writes on different threads eventually become visible on the observing
thread. Explicitly calling refresh() blocks until the writes made on
other threads are visible and the appropriate notifications have been sent.
If you call refresh() within a notification callback, it's a no-op.

Perform Writes on the Observing Thread, Outside of Notifications Copy Section

At the start of the write transaction all behaviors above apply to this
context. Additionally, you can expect to always see the latest version of
the data.

Inside a write transaction, the only changes you see are those you've made
so far within the write transaction.

Between committing a write transaction and the next set of change
notifications being sent, you can see the changes you made in the write
transaction, but no other changes. Writes made on different threads do
not become visible until you receive the next set of notifications.
Performing another write on the same thread sends notifications for the
previous write first.

Perform Writes Inside of Notifications Copy Section

When you perform writes within notifications, you see many of the same
behaviors above, with a few exceptions.

Callbacks invoked before the one that performed a write behave normally.
While Realm invokes change callbacks in a stable order, this is not strictly
the order in which you added the observations.

If beginning the write refreshes the realm, which can happen if another
thread is making writes, this triggers recursive notifications. These
nested notifications report the changes made since the last call to the
callback. For callbacks before the one making the write, this means the
inner notification reports only the changes made after the ones already
reported in the outer notification. If the callback making the write tries
to write again in the inner notification, Realm throws an exception.
The callbacks after the one making the write get a single notification for
both sets of changes.

After the callback completes the write and returns, Realm does not invoke
any of the subsequent callbacks as they no longer have any changes to report.
Realm provides a notification later for the write as if the write had happened
outside of a notification.

If beginning the write doesn't refresh the realm, the write happens as
usual. However, Realm invokes the subsequent callbacks in an inconsistent
state. They continue to report the original change information, but the
observed object/collection now includes the changes from the write made
in the previous callback.

If you try to perform manual checks and write handling to get more fine-grained
notifications from within a write transaction, you can get notifications
nested more than two levels deep. An example of a manual write handling is
checking realm.isInWriteTransaction, and if so making changes, calling
realm.commitWrite() and then realm.beginWrite(). The nested
notifications and potential for error make this manual manipulation
error-prone and difficult to debug.

You can use the writeAsync API to sidestep complexity
if you don't need fine-grained change information from inside your write block.
Observing an async write similar to this provides notifications even if the
notification happens to be delivered inside a write transaction:

let token = dog.observe(keyPaths: [\Dog.age]) { change in
   guard case let .change(dog, _) = change else { return }
   dog.realm!.writeAsync {
      dog.isPuppy = dog.age < 2
   }
}

However, because the write is async the realm may have changed between the
notification and when the write happens. In this case, the change information
passed to the notification may no longer be applicable.

Updating a UITableView Based on Notifications Copy Section

If you only update a UITableView via notifications, in the time between
a write transaction and the next notification arriving, the TableView's
state is out of sync with the data. The TableView could have a pending update
scheduled, which can appear to cause delayed or inconsistent updates.

You can address these behaviors in a few ways.

The following examples use this very basic UITableViewController.

/* Detailed source-code truncated for AI context efficiency. */

Update the UITableView Directly Without a Notification

Updating the UITableView directly without waiting for a notification
provides the most responsive UI. This code updates the TableView immediately
instead of requiring hops between threads, which add a small amount of
lag to each update. The downside is that it requires frequent manual
updates to the view.

func delete(at index: Int) throws {
    try realm.write(withoutNotifying: [notificationToken]) {
        realm.delete(results[index])
    }
    tableView.deleteRows(at: [IndexPath(row: index, section: 0)], with: .automatic)
}

Force a Refresh After a Write

Forcing a refresh() after a write provides the notifications from the
write immediately rather than on a future run of the run loop. There's no
window for the TableView to read out-of-sync values.

The downside is that this means things we recommend doing in the background,
such as writing, rerunning the query and re-sorting the results, happen
on the main thread. When these operations are computationally expensive,
this can cause delays on the main thread.

func delete(at index: Int) throws {
    try realm.write {
        realm.delete(results[index])
    }
    realm.refresh()
}

Perform the Write on a Background Thread

Performing a write on a background thread blocks the main thread for the
least amount of time. However, the code to perform a write on the background
requires more familiarity with Realm's threading model and Swift DispatchQueue
usage. Since the write doesn't happen on the main thread, the main thread
never sees the write before the notifications arrive.

func delete(at index: Int) throws {
    func delete(at index: Int) throws {
        @ThreadSafe var object = results[index]
        DispatchQueue.global().async {
            guard let object = object else { return }
            let realm = object.realm!
            try! realm.write {
                if !object.isInvalidated {
                    realm.delete(object)
                }
            }
        }
    }
}

Change Notification Limits Copy Chapter

Changes in nested documents deeper than four levels down do not trigger
change notifications.

If you have a data structure where you need to listen for changes five
levels down or deeper, workarounds include:

• Refactor the schema to reduce nesting.
• Add something like "push-to-refresh" to enable users to manually refresh data.

In the Swift SDK, you can also use
key path filtering to work
around this limitation. This feature is not available in the other SDKs.

Guides Crud Read (`docs/guides/crud/read.md`) Copy Section

CRUD - Read - Swift SDK

Read from a Realm Copy Chapter

A read from a realm generally consists of the following
steps:

• Get all objects of a certain type from the realm.
• Optionally, filter the results.
• Optionally, sort the results.
• Alternately, get all objects of a certain type, divided into
  sections. As with regular results, you can
  filter and sort sectioned results.

Query, filter, and sort operations return either a results or
SectionedResults collection. These
collections are live, meaning they always contain the latest
results of the associated query.

Read Characteristics Copy Section

When you design your app's data access patterns around the
following three key characteristics of reads in Realm,
you can be confident you are reading data as
efficiently as possible.

Results Are Not Copies

Results to a query are not copies of your data: modifying
the results of a query will modify the data on disk
directly. This memory mapping also means that results are
live: that is, they always reflect the current state on
disk.

See also: Collections are Live.

Results Are Lazy

Realm only runs a query when you actually request the
results of that query. This lazy evaluation enables you to write
elegant, highly performant code for handling large data sets and complex
queries. You can chain several filter and sort operations without requiring extra work to process the
intermediate state.

References Are Retained

One benefit of Realm's object model is that
Realm automatically retains all of an object's
relationships as direct
references, so you can traverse your graph of relationships
directly through the results of a query.

A direct reference, or pointer, allows you to access a
related object's properties directly through the reference.

Other databases typically copy objects from database storage
into application memory when you need to work with them
directly. Because application objects contain direct
references, you are left with a choice: copy the object
referred to by each direct reference out of the database in
case it's needed, or just copy the foreign key for each
object and query for the object with that key if it's
accessed. If you choose to copy referenced objects into
application memory, you can use up a lot of resources for
objects that are never accessed, but if you choose to only
copy the foreign key, referenced object lookups can cause
your application to slow down.

Realm bypasses all of this using zero-copy
live objects. Realm object accessors point
directly into database storage using memory mapping, so there is no
distinction between the objects in Realm and the results
of your query in application memory. Because of this, you can traverse
direct references across an entire realm from any query result.

Limiting Query Results Copy Section

As a result of lazy evaluation, you do not need any special mechanism to
limit query results with Realm. For example, if your query
matches thousands of objects, but you only want to load the first ten,
simply access only the first ten elements of the results collection.

Pagination Copy Section

Thanks to lazy evaluation, the common task of pagination becomes quite
simple. For example, suppose you have a results collection associated
with a query that matches thousands of objects in your realm. You
display one hundred objects per page. To advance to any page, simply
access the elements of the results collection starting at the index that
corresponds to the target page.

Read Realm Objects Copy Chapter

About The Examples On This Page Copy Section

The examples on this page use the following models:

Objective-C

// DogToy.h
@interface DogToy : RLMObject
@property NSString *name;
@end

// Dog.h
@interface Dog : RLMObject
@property NSString *name;
@property int age;
@property NSString *color;

// To-one relationship
@property DogToy *favoriteToy;

@end

// Enable Dog for use in RLMArray
RLM_COLLECTION_TYPE(Dog)

// Person.h
// A person has a primary key ID, a collection of dogs, and can be a member of multiple clubs.
@interface Person : RLMObject
@property int _id;
@property NSString *name;

// To-many relationship - a person can have many dogs
@property RLMArray<Dog *><Dog> *dogs;

// Inverse relationship - a person can be a member of many clubs
@property (readonly) RLMLinkingObjects *clubs;
@end

RLM_COLLECTION_TYPE(Person)

// DogClub.h
@interface DogClub : RLMObject
@property NSString *name;
@property RLMArray<Person *><Person> *members;
@end

// Dog.m
@implementation Dog
@end

// DogToy.m
@implementation DogToy
@end

// Person.m
@implementation Person
// Define the primary key for the class
+ (NSString *)primaryKey {
    return @"_id";
}

// Define the inverse relationship to dog clubs
+ (NSDictionary *)linkingObjectsProperties {
    return @{
        @"clubs": [RLMPropertyDescriptor descriptorWithClass:DogClub.class propertyName:@"members"],
    };
}
@end

// DogClub.m
@implementation DogClub
@end

Swift

/* Detailed source-code truncated for AI context efficiency. */

Find a Specific Object by Primary Key Copy Section

Objective-C

If you know the primary key for
a given object, you can look it up directly with
+[RLMObject objectForPrimaryKey:].

// Get a specific person from the default realm
Person *specificPerson = [Person objectForPrimaryKey:@12345];

Swift

If you know the primary key for a given
object, you can look it up directly with
Realm.object(ofType:forPrimaryKey:).

let realm = try! Realm()

let specificPerson = realm.object(ofType: Person.self, forPrimaryKey: 12345)

Query All Objects of a Given Type Copy Section

Objective-C

To query for objects of a given type in a realm, pass the realm
instance to +[YourRealmObjectClass allObjectsInRealm:].
Replace YourRealmObjectClass with your Realm object class
name. This returns an RLMResults object representing all objects of the
given type in the realm.

RLMRealm *realm = [RLMRealm defaultRealm];

RLMResults *dogs = [Dog allObjectsInRealm:realm];
RLMResults *people = [Person allObjectsInRealm:realm];

Swift

To query for objects of a given type in a realm, pass the metatype
instance YourClassName.self to Realm.objects(_).
This returns a Results object
representing all objects of the given type in the realm.

let realm = try! Realm()
// Access all dogs in the realm
let dogs = realm.objects(Dog.self)

Filter Queries Based on Object Properties Copy Section

A filter selects a subset of results based on the value(s) of one or
more object properties. Realm provides a full-featured
query engine that you can use to define filters.

Swift

Version added: 10.19.0

To use the Realm Swift Query API,
call .where with a closure that
contains a query expression as an argument.

let realm = try! Realm()
// Access all dogs in the realm
let dogs = realm.objects(Dog.self)

// Query by age
let puppies = dogs.where {
    $0.age < 2
}

// Query by person
let dogsWithoutFavoriteToy = dogs.where {
    $0.favoriteToy == nil
}

// Query by person's name
let dogsWhoLikeTennisBalls = dogs.where {
    $0.favoriteToy.name == "Tennis ball"
}

Swift Nspredicate

To filter, call Results.filter(_:)
with a query predicate.

let realm = try! Realm()
// Access all dogs in the realm
let dogs = realm.objects(Dog.self)

// Filter by age
let puppies = dogs.filter("age < 2")

// Filter by person
let dogsWithoutFavoriteToy = dogs.filter("favoriteToy == nil")

// Filter by person's name
let dogsWhoLikeTennisBalls = dogs.filter("favoriteToy.name == 'Tennis ball'")

Objective-C

To filter, call -[RLMResults objectsWhere:]
with a query predicate.

RLMRealm *realm = [RLMRealm defaultRealm];

// Access all dogs in the realm
RLMResults *dogs = [Dog allObjectsInRealm:realm];

// Filter by age
RLMResults *puppies = [dogs objectsWhere:@"age < 2"];

// Filter by favorite toy
RLMResults *dogsWithoutFavoriteToy = [dogs objectsWhere:@"favoriteToy == nil"];

// Filter by favorite toy's name
RLMResults *dogsWhoLikeTennisBalls = [dogs objectsWhere:@"favoriteToy.name == %@", @"Tennis ball"];

Tip:
To filter a query based on a property of an embedded object or a related object, use dot-notation as if it were
in a regular, nested object.

Filter on Object ID Properties Copy Section

The types in your predicate must match the types of the
properties. Avoid comparing
ObjectId properties to strings, as
Realm does not automatically convert strings to ObjectIds.

Swift

Version added: 10.19.0

The Realm Swift Query API's built-in type safety simplifies writing a
query with an ObjectId:

let realm = try! Realm()

let dogToys = realm.objects(DogToy.self)

// Get specific user by ObjectId id
let specificToy = dogToys.where {
    $0.id == ObjectId("11223344556677889900aabb")
}

Swift Nspredicate

The following example shows the correct and incorrect way to write a
query with an ObjectId given the following Realm object:

let realm = try! Realm()

let dogToys = realm.objects(DogToy.self)

// Get specific toy by ObjectId id
let specificToy = dogToys.filter("id = %@", ObjectId("11223344556677889900aabb")).first

// WRONG: Realm will not convert the string to an object id
// users.filter("id = '11223344556677889900aabb'") // not ok
// users.filter("id = %@", "11223344556677889900aabb") // not ok

Query a Relationship Copy Section

You can query through a relationship the same way you would access a
member of a regular Swift or Objective-C object.

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];

// Establish a relationship
Dog *dog = [[Dog alloc] init];
dog.name = @"Rex";
dog.age = 10;

Person *person = [[Person alloc] init];
person._id = 12345;
[person.dogs addObject:dog];

[realm transactionWithBlock:^() {
    [realm addObject:person];
}];

// Later, query the specific person
Person *specificPerson = [Person objectForPrimaryKey:@12345];

// Access directly through a relationship
NSLog(@"# dogs: %lu", [specificPerson.dogs count]);
NSLog(@"First dog's name: %@", specificPerson.dogs[0].name);

Swift

let realm = try! Realm()

// Establish a relationship
let dog = Dog()
dog.name = "Rex"
dog.age = 10

let person = Person()
person.id = 12345
person.dogs.append(dog)

try! realm.write {
    realm.add(person)
}

// Later, query the specific person
let specificPerson = realm.object(ofType: Person.self, forPrimaryKey: 12345)

// Access directly through a relationship
let specificPersonDogs = specificPerson!.dogs
let firstDog = specificPersonDogs[0]
print("# dogs: \(specificPersonDogs.count)")
print("First dog's name: \(firstDog.name)")

Query an Inverse Relationship Copy Section

You can query through an inverse relationship the same way you would
access a member of a regular Swift or Objective-C object.

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];

// Establish a relationship
Person *person = [[Person alloc] init];
person._id = 12345;

DogClub *club = [[DogClub alloc] init];
club.name = @"Pooch Pals";
[club.members addObject:person];

[realm transactionWithBlock:^() {
    [realm addObject:club];
}];

// Later, query the specific person
Person *specificPerson = [Person objectForPrimaryKey:@12345];
    
// Access directly through an inverse relationship
NSLog(@"# memberships: %lu", [specificPerson.clubs count]);
NSLog(@"First club's name: %@", [specificPerson.clubs[0] name]);

Swift

let realm = try! Realm()

// Establish an inverse relationship
let person = Person()
person.id = 12345

let club = DogClub()
club.name = "Pooch Pals"
club.members.append(person)

try! realm.write {
    realm.add(club)
}

// Later, query the specific person
let specificPerson = realm.object(ofType: Person.self, forPrimaryKey: 12345)

// Access directly through an inverse relationship
let clubs = specificPerson!.clubs
let firstClub = clubs[0]
print("# memberships: \(clubs.count)")
print("First club's name: \(firstClub.name)")

Query a Collection on Embedded Object Properties Copy Section

Use dot notation to filter or sort a collection of objects based on an embedded object
property value:

Note:
It is not possible to query embedded objects directly. Instead,
access embedded objects through a query for the parent object type.

Swift

Version added: 10.19.0

// Open the default realm
let realm = try! Realm()

// Get all contacts in Los Angeles, sorted by street address
let losAngelesPeople = realm.objects(Person.self)
    .where {
        $0.address.city == "Los Angeles"
    }
    .sorted(byKeyPath: "address.street")
print("Los Angeles Person: \(losAngelesPeople)")

Swift Nspredicate

// Open the default realm
let realm = try! Realm()

// Get all people in Los Angeles, sorted by street address
let losAngelesPeople = realm.objects(Person.self)
    .filter("address.city = %@", "Los Angeles")
    .sorted(byKeyPath: "address.street")
print("Los Angeles Person: \(losAngelesPeople)")

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];
RLMResults<Contact *> *losAngelesContacts = [Contact objectsInRealm:realm where:@"address.city = %@", @"Los Angeles"];

losAngelesContacts = [losAngelesContacts sortedResultsUsingKeyPath:@"address.street" ascending:YES]; 
NSLog(@"Los Angeles Contacts: %@", losAngelesContacts);

Query a Map Property Copy Section

You can iterate and check the values of a realm map
as you would a standard Dictionary:

let realm = try! Realm()

let dogs = realm.objects(Dog.self)

// Find dogs who have favorite parks
let dogsWithFavoriteParks = dogs.where {
    $0.favoriteParksByCity.count >= 1
}

for dog in dogsWithFavoriteParks {
    // Check if an entry exists
    if dog.favoriteParksByCity.keys.contains("Chicago") {
        print("\(dog.name) has a favorite park in Chicago")
    }

    // Iterate over entries
    for element in dog.favoriteParksByCity {
        print("\(dog.name)'s favorite park in \(element.key) is \(element.value)")
    }
}

Query a MutableSet Property Copy Section

You can query a MutableSet to check if
it contains an element. If you are working with multiple sets, you can
check for the intersection of two sets, or check whether one set is a subset
of the other set.

let realm = try! Realm()

// Find dogs who have visited New York
let newYorkDogs = realm.objects(Dog.self).where {
    $0.citiesVisited.contains("New York")
}

// Get some information about the cities they have visited
for dog in newYorkDogs {
    print("Cities \(dog.name) has visited: \(dog.citiesVisited)")
}

// Check whether two dogs have visited some of the same cities.
// Use "intersects" to find out whether the values of the two sets share common elements.
let isInBothCitiesVisited = (dog.citiesVisited.intersects(dog2.citiesVisited))
print("The two dogs have visited some of the same cities: \(isInBothCitiesVisited)")
// Prints "The two dogs have visited some of the same cities: true"

// Or you can check whether a set is a subset of another set. In this example,
// the first dog has visited "New York" and "Toronto", while dog2 has visited both of
// those but also "Toronto" and "Boston".
let isSubset = (dog.citiesVisited.isSubset(of: dog2.citiesVisited))
print("\(dog.name)'s set of cities visited is a subset of \(dog2.name)'s: \(isSubset)")
// Prints "Maui's set of cities visited is a subset of Lita's: true"

Read and Query AnyRealmValue Property Copy Section

When you read an AnyRealmValue property, check the value's type before doing
anything with it. The Realm Swift SDK provides an AnyRealmValue enum that iterates through all of the types the
AnyRealmValue can store.

let realm = try! Realm()

let dogs = realm.objects(Dog.self)

for dog in dogs {
    // Verify the type of the ``AnyRealmProperty`` when attempting to get it. This
    // returns an object whose property contains the matched type.

    // If you only care about one type, check for that type.
    if case let .string(companion) = dog.companion {
        print("\(dog.name)'s companion is: \(companion)")
        // Prints "Wolfie's companion is: Fluffy the Cat"
    }

    // Or if you want to do something with multiple types of data
    // that could be in the value, switch on the type.
    switch dog.companion {
    case .string:
        print("\(dog.name)'s companion is: \(dog.companion)")
        // Prints "Wolfie's companion is: string("Fluffy the Cat")
    case .object:
        print("\(dog.name)'s companion is: \(dog.companion)")
        // Prints "Fido's companion is: object(Dog { name = Spot })"
    case .none:
        print("\(dog.name) has no companion")
        // Prints "Rex has no companion" and "Spot has no companion"
    default:
        print("\(dog.name)'s companion is another type.")
    }
}

You can compare these mixed value types:

• Numeric: int, bool, float, double, decimal
• Byte-based: string, binary
• Time-based: timestamp, objectId

When using the AnyRealmValue mixed data type, keep these things in mind:

• equals queries match on value and type
• not equals queries match objects with either different values or
  different types
• realm converts comparable numeric properties where possible. For example,
  in a mixed type field, 1 matches all of 1.0, 1, and true.
• String properties do not match numeric queries. For example, in a mixed
  type field, 1 does not match "1". "1" does not match 1, 1.0, or true.

Query Geospatial Data Copy Section

Version added: 10.47.0

The Swift SDK provides several shapes to simplify querying
geospatial data. You can use the
GeoCircle, GeoBox, and GeoPolygon shapes to set the boundaries for
your geospatial data queries.

The SDK provides two specialized non-persistable data types to define shapes:

• GeoPoint: A struct that represents the coordinates of a point formed by
  a pair of doubles consisting of these values: Latitude: ranges between -90 and 90 degrees, inclusive.Longitude: ranges between -180 and 180 degrees, inclusive.
• RLMDistance: A helper struct to represent and convert a distance.

Define Geospatial Shapes

Geocircle

A GeoCircle is a circular shape whose bounds originate from a central
GeoPoint, and has a size corresponding to a radius measured in
radians. You can use the SDK's convenience RLMDistance data type to
easily work with radii in different units.

RLMDistance enables you to specify the radius distance for your geo shapes
in one of four units:

• .degrees
• .kilometers
• .miles
• .radians

You can optionally use the supplied convenience methods to convert a
measurement to a different distance units.

// You can create a GeoCircle radius measured in radians.
// This radian distance corresponds with 0.25 degrees.
let smallCircle = GeoCircle(center: (47.3, -121.9), radiusInRadians: 0.004363323)

// You can also create a GeoCircle radius measured with a Distance.
// You can specify a Distance in .degrees, .kilometers, .miles, or .radians.
let largeCircle = GeoCircle(center: GeoPoint(latitude: 47.8, longitude: -122.6)!, radius: Distance.kilometers(44.4)!)

Geobox

A GeoBox is a rectangular shape whose bounds are determined by
coordinates for a bottom-left and a top-right corner.

let largeBox = GeoBox(bottomLeft: (47.3, -122.7), topRight: (48.1, -122.1))

let smallBoxBottomLeft = GeoPoint(latitude: 47.5, longitude: -122.4)!
let smallBoxTopRight = GeoPoint(latitude: 47.9, longitude: -121.8)
let smallBox = GeoBox(bottomLeft: smallBoxBottomLeft, topRight: smallBoxTopRight!)

Geopolygon

A GeoPolygon is a polygon shape whose bounds consist of an outer
ring, and 0 or more inner holes to exclude from the geospatial query.

A polygon's outer ring must contain at least three segments. The last
and the first GeoPoint must be the same, which indicates a closed
polygon. This means that it takes at least four GeoPoint values to
construct a polygon.

Inner holes in a GeoPolygon must be entirely contained within the
outer ring.

Holes have the following restrictions:

• Holes may not cross. The boundary of a hole may not intersect both the
  interior and the exterior of any other hole.
• Holes may not share edges. If a hole contains an edge AB, then no other
  hole may contain it.
• Holes may share vertices. However, no vertex may appear twice in a
  single hole.
• No hole may be empty.
• Only one nesting is allowed.

// Create a basic polygon
let basicPolygon = GeoPolygon(outerRing: [
    (48.0, -122.8),
    (48.2, -121.8),
    (47.6, -121.6),
    (47.0, -122.0),
    (47.2, -122.6),
    (48.0, -122.8)
])

// Create a polygon with one hole
let outerRing: [GeoPoint] = [
    GeoPoint(latitude: 48.0, longitude: -122.8)!,
    GeoPoint(latitude: 48.2, longitude: -121.8)!,
    GeoPoint(latitude: 47.6, longitude: -121.6)!,
    GeoPoint(latitude: 47.0, longitude: -122.0)!,
    GeoPoint(latitude: 47.2, longitude: -122.6)!,
    GeoPoint(latitude: 48.0, longitude: -122.8)!
]

let hole: [GeoPoint] = [
    GeoPoint(latitude: 47.8, longitude: -122.6)!,
    GeoPoint(latitude: 47.7, longitude: -122.2)!,
    GeoPoint(latitude: 47.4, longitude: -122.6)!,
    GeoPoint(latitude: 47.6, longitude: -122.5)!,
    GeoPoint(latitude: 47.8, longitude: -122.6)!
]

let polygonWithOneHole = GeoPolygon(outerRing: outerRing, holes: [hole])

// Add a second hole to the polygon
let hole2: [GeoPoint] = [
    GeoPoint(latitude: 47.55, longitude: -122.05)!,
    GeoPoint(latitude: 47.55, longitude: -121.9)!,
    GeoPoint(latitude: 47.3, longitude: -122.1)!,
    GeoPoint(latitude: 47.55, longitude: -122.05)!
]

let polygonWithTwoHoles = GeoPolygon(outerRing: outerRing, holes: [hole, hole2])

Query with Geospatial Shapes

You can then use these shapes in a geospatial query. You can query geospatial
data in three ways:

• Using the .geoWithin() operator with the type-safe Realm Swift Query API
• Using a .filter() with RQL
• Using a .filter() with an NSPredicate query

The examples below show the results of queries using these two Company
objects:

let company1 = Geospatial_Company()
company1.location = CustomGeoPoint(47.68, -122.35)

let company2 = Geospatial_Company(CustomGeoPoint(47.9, -121.85))

Geocircle

let companiesInSmallCircle = realm.objects(Geospatial_Company.self).where {
    $0.location.geoWithin(smallCircle!)
}
print("Number of companies in small circle: \(companiesInSmallCircle.count)")

let companiesInLargeCircle = realm.objects(Geospatial_Company.self)
    .filter("location IN %@", largeCircle)
print("Number of companies in large circle: \(companiesInLargeCircle.count)")

Geobox

let companiesInSmallBox = realm.objects(Geospatial_Company.self).where {
    $0.location.geoWithin(smallBox)
}
print("Number of companies in small box: \(companiesInSmallBox.count)")

let filterArguments = NSMutableArray()
filterArguments.add(largeBox)
let companiesInLargeBox = realm.objects(Geospatial_Company.self)
    .filter(NSPredicate(format: "location IN %@", argumentArray: filterArguments as? [Any]))
print("Number of companies in large box: \(companiesInLargeBox.count)")

Geopolygon

let companiesInBasicPolygon = realm.objects(Geospatial_Company.self).where {
    $0.location.geoWithin(basicPolygon!)
}
print("Number of companies in basic polygon: \(companiesInBasicPolygon.count)")

let companiesInPolygonWithTwoHoles = realm.objects(Geospatial_Company.self).where {
    $0.location.geoWithin(polygonWithTwoHoles!)
}
print("Number of companies in polygon with two holes: \(companiesInPolygonWithTwoHoles.count)")

Query a Custom Persistable Property Copy Section

When you use type projection to map unsupported
types to supported types, accessing those properties is often based on the
persisted type.

Queries on Realm Objects

When working with projected types, queries operate on the persisted type.
However, you can use the mapped types interchangeably with the persisted
types in arguments in most cases. The exception is queries on embedded
objects.

Tip:
Projected types support sorting and aggregates where
the persisted type supports them.

let akcClub = realm.objects(Club.self).where {
    $0.name == "American Kennel Club"
}.first!
// You can use type-safe expressions to check for equality
XCTAssert(akcClub.url == URL(string: "https://akc.org")!)

let clubs = realm.objects(Club.self)
// You can use the persisted property type in NSPredicate query expressions
let akcByUrl = clubs.filter("url == 'https://akc.org'").first!
XCTAssert(akcByUrl.name == "American Kennel Club")

Queries on Embedded Objects

You can query embedded types on the supported property types within the
object using memberwise equality.

Object link properties support equality comparisons, but do not support
memberwise comparisons. You can query embedded objects for memberwise
equality on all primitive types. You cannot perform memberwise comparison
on objects and collections.

Dynamic APIs

Because the schema has no concept of custom type mappings, reading data via
any of the dynamic APIs gives the underlying persisted type. Realm does
support writing mapped types via a dynamic API, and converts the projected
type to the persisted type.

The most common use of the dynamic APIs is migration. You can write projected
types during migration, and Realm converts the projected type to the persisted
type. However, reading data during a migration gives the underlying persisted
type.

Read an Object Asynchronously Copy Chapter

When you use an actor-isolated realm, you can use Swift concurrency features
to asynchronously query objects.

let actor = try await RealmActor()

// Read objects in functions isolated to the actor and pass primitive values to the caller
func getObjectId(in actor: isolated RealmActor, forTodoNamed name: String) async -> ObjectId {
    let todo = actor.realm.objects(Todo.self).where {
        $0.name == name
    }.first!
    return todo._id
}
let objectId = await getObjectId(in: actor, forTodoNamed: "Keep it safe")

If you need to manually advance the state of an observed realm on the main
thread or an actor-isolated realm, call await realm.asyncRefresh().
This updates the realm and outstanding objects managed by the Realm to point to
the most recent data and deliver any applicable notifications.

For more information about working with realm using Swift concurrency features,
refer to Use Realm with Actors - Swift SDK.

Sort Query Results Copy Chapter

A sort operation allows you to configure the order in which Realm
Database returns queried objects. You can sort based on one or more
properties of the objects in the results collection. Realm only
guarantees a consistent order of results if you explicitly sort them.

Objective-C

To sort, call -[RLMResults
sortedResultsUsingKeyPath:ascending:]
with the desired key path to sort by.

RLMRealm *realm = [RLMRealm defaultRealm];

RLMResults *dogs = [Dog allObjectsInRealm:realm];

// Sort dogs by name
RLMResults *dogsSorted = [dogs sortedResultsUsingKeyPath:@"name" ascending:NO];

// You can also sort on the members of linked objects. In this example,
// we sort the dogs by their favorite toys' names.
RLMResults *dogsSortedByFavoriteToyName = [dogs sortedResultsUsingKeyPath:@"favoriteToy.name" ascending:YES];

Swift

Version added: 10.11.0

You can sort using the type-safe keyPath by calling
Results.sorted(by: ) with the
keyPath name and optional sort order:

let realm = try! Realm()
// Access all dogs in the realm
let dogs = realm.objects(Dog.self)

// Sort by type-safe keyPath
let dogsSorted = dogs.sorted(by: \.name)

To sort using the older API, call Results.sorted(byKeyPath:ascending:)
with the desired key path to sort by.

let realm = try! Realm()
// Access all dogs in the realm
let dogs = realm.objects(Dog.self)

let dogsSorted = dogs.sorted(byKeyPath: "name", ascending: false)

// You can also sort on the members of linked objects. In this example,
// we sort the dogs by their favorite toys' names.
let dogsSortedByFavoriteToyName = dogs.sorted(byKeyPath: "favoriteToy.name")

Tip:
To sort a query based on a property of an embedded object or a related object, use dot-notation as if it
were in a regular, nested object.

Note:
String sorting and case-insensitive queries are only supported for
character sets in 'Latin Basic', 'Latin Supplement', 'Latin Extended
A', and 'Latin Extended B' (UTF-8 range 0-591).

Section Query Results Copy Chapter

You can split results into individual sections. Each section corresponds
to a key generated from a property on the object it represents.

For example, you might add a computed variable to your object to get the
first letter of the name property:

// Computed variable that is not persisted, but only
// used to section query results.
var firstLetter: String {
    return name.first.map(String.init(_:)) ?? ""
}

Then, you can create a SectionedResults
type-safe collection for that object, and use it to retrieve objects sectioned
by that computed variable:

var dogsByFirstLetter: SectionedResults<String, Dog>

dogsByFirstLetter = realm.objects(Dog.self).sectioned(by: \.firstLetter, ascending: true)

You can get a count of the sections, get a list of keys, or access an individual
ResultSection by index:

let realm = try! Realm()

var dogsByFirstLetter: SectionedResults<String, Dog>

dogsByFirstLetter = realm.objects(Dog.self).sectioned(by: \.firstLetter, ascending: true)

// You can get a count of the sections in the SectionedResults
let sectionCount = dogsByFirstLetter.count

// Get an array containing all section keys for objects that match the query.
let sectionKeys = dogsByFirstLetter.allKeys
// This example realm contains 4 dogs, "Rex", "Wolfie", "Fido", "Spot".
// Prints ["F", "R", "S", "W"]
print(sectionKeys)

// Get a specific key by index position
let sectionKey = dogsByFirstLetter[0].key
// Prints "Key for index 0: F"
print("Key for index 0: \(sectionKey)")

// You can access Results Sections by the index of the key you want in SectionedResults.
// "F" is the key at index position 0. When we access this Results Section, we get dogs whose name begins with "F".
let dogsByF = dogsByFirstLetter[0]
// Prints "Fido"
print(dogsByF.first?.name)

You can also section using a callback. This enables you to section a
collection of primitives, or have more control over how the section key is
generated.

let realm = try! Realm()
let results = realm.objects(Dog.self)
let sectionedResults = results.sectioned(by: { String($0.name.first!) },
                                         sortDescriptors: [SortDescriptor.init(keyPath: "name", ascending: true)])
let sectionKeys = sectionedResults.allKeys

You can observe
SectionedResults and ResultsSection instances, and both conform to
ThreadConfined.

Aggregate Data Copy Chapter

You can use Realm's aggregation operators for sophisticated queries
against list properties.

Swift

Version added: 10.19.0

let realm = try! Realm()

let people = realm.objects(Person.self)

// People whose dogs' average age is 5
people.where {
    $0.dogs.age.avg == 5
}

// People with older dogs
people.where {
    $0.dogs.age.min > 5
}

// People with younger dogs
people.where {
    $0.dogs.age.max < 2
}

// People with many dogs
people.where {
    $0.dogs.count > 2
}

// People whose dogs' ages combined > 10 years
people.where {
    $0.dogs.age.sum > 10
}

Swift Nspredicate

let realm = try! Realm()

let people = realm.objects(Person.self)

// People whose dogs' average age is 5
people.filter("[email protected] == 5")

// People with older dogs
people.filter("[email protected] > 5")

// People with younger dogs
people.filter("[email protected] < 2")

// People with many dogs
people.filter("dogs.@count > 2")

// People whose dogs' ages combined > 10 years
people.filter("[email protected] > 10")

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];

RLMResults *people = [Person allObjectsInRealm:realm];

// People whose dogs' average age is 5
[people objectsWhere:@"[email protected] == 5"];

// People with older dogs
[people objectsWhere:@"[email protected] > 5"];

// People with younger dogs
[people objectsWhere:@"[email protected] < 2"];

// People with many dogs
[people objectsWhere:@"dogs.@count > 2"];

// People whose dogs' ages combined > 10 years
[people objectsWhere:@"[email protected] > 10"];

Chain Queries Copy Chapter

Because results are lazily evaluated, you
can chain several queries together. Unlike traditional databases, this
does not require a separate trip to the database for each successive
query.

Example:
To get a result set for tan dogs, and tan dogs whose names start with
'B', chain two queries like this:

Swift

Version added: 10.19.0

swift Copy

let realm = try! Realm()
let tanDogs = realm.objects(Dog.self).where {
    $0.color == "tan"
}
let tanDogsWithBNames = tanDogs.where {
    $0.name.starts(with: "B")
}

Swift Nspredicate

swift Copy

let realm = try! Realm()
let tanDogs = realm.objects(Dog.self).filter("color = 'tan'")
let tanDogsWithBNames = tanDogs.filter("name BEGINSWITH 'B'")

Objective-C

objectivec Copy

RLMRealm *realm = [RLMRealm defaultRealm];
RLMResults<Dog *> *tanDogs = [Dog objectsInRealm:realm where:@"color = 'tan'"];
RLMResults<Dog *> *tanDogsWithBNames = [tanDogs objectsWhere:@"name BEGINSWITH 'B'"];

Query Class Projections Copy Chapter

To query for class projections in a
realm, pass the metatype instance YourProjectionName.self to
Realm.objects(_).
This returns a Results object
representing all of the class projection objects in the realm.

// Retrieve all class projections of the given type `PersonProjection`
let people = realm.objects(PersonProjection.self)
// Use projection data in your view
print(people.first?.firstName)
print(people.first?.homeCity)
print(people.first?.firstFriendsName)

Tip:
Don't do derived queries on top of class projection results. Instead, run a
query against the Realm object directly and then project the result. If you
try to do a derived query on top of class projection results, querying a
field with the same name and type as the original object works, but querying
a field with a name or type that isn't in the original object fails.

Guides Crud Threading (`docs/guides/crud/threading.md`) Copy Section

Threading - Swift SDK

To make your iOS and tvOS apps fast and responsive, you must
balance the computing time needed to lay out the visuals and
handle user interactions with the time needed to process
your data and run your business logic. Typically, app
developers spread this work across multiple threads: the
main or UI thread for all of the user interface-related
work, and one or more background threads to compute heavier
workloads before sending it to the UI thread for
presentation. By offloading heavy work to background
threads, the UI thread can remain highly responsive
regardless of the size of the workload. But it can be
notoriously difficult to write thread-safe, performant, and
maintainable multithreaded code that avoids issues like
deadlocking and race conditions. Realm aims to
simplify this for you.

Seealso:
As of 10.26.0, Realm provides async write methods to perform background
writes. See: Perform a Background Write. With
async write, you don't need to pass a thread-safe reference or frozen objects
across threads.

This page describes how to manually manage realm files and objects across threads.
Realm also supports using a Swift actor
to manage realm access using Swift concurrency features. For an overview
of Realm's actor support, refer to Use Realm with Actors - Swift SDK.

Three Rules to Follow Copy Chapter

Before exploring Realm's tools for multithreaded apps, you need to
understand and follow these three rules:

Realm's Multiversion Concurrency Control (MVCC)
architecture eliminates the need to lock for read operations. The values you
read will never be corrupted or in a partially-modified state. You can freely
read from the same Realm file on any thread without the need for locks or
mutexes. Unnecessarily locking would be a performance bottleneck since each
thread might need to wait its turn before reading.

You can write to a Realm file from any thread, but there can be only one
writer at a time. Consequently, synchronous write transactions block each
other. A synchronous write on the UI thread may result in your app appearing
unresponsive while it waits for a write on a background thread to complete.

Live objects, collections, and realm instances are
thread-confined: that is, they are only valid on the
thread on which they were created. Practically speaking,
this means you cannot pass live instances to other
threads. However, Realm offers several mechanisms for
sharing objects across threads.

Perform a Background Write Copy Chapter

Version added: 10.26.0

You can add, modify, or delete objects in the background using
writeAsync.

With writeAsync, you don't need to pass a thread-safe reference or frozen objects
across threads. Instead, call realm.writeAsync. You can provide
a completion block for the method to execute on the source thread after
the write completes or fails.

Things to consider when performing background writes:

• Async writes block closing or invalidating the realm
• You can explicitly commit or cancel transactions

let realm = try! Realm()

// Query for a specific person object on the main thread
let people = realm.objects(Person.self)
let thisPerson = people.where {
    $0.name == "Dachary"
}.first

// Perform an async write to add dogs to that person's dog list.
// No need to pass a thread-safe reference or frozen object.
realm.writeAsync {
    thisPerson?.dogs.append(objectsIn: [
        Dog(value: ["name": "Ben", "age": 13]),
        Dog(value: ["name": "Lita", "age": 9]),
        Dog(value: ["name": "Maui", "age": 1])
    ])
} onComplete: { _ in
    // Confirm the three dogs were successfully added to the person's dogs list
    XCTAssertEqual(thisPerson!.dogs.count, 3)
    // Query for one of the dogs we added and see that it is present
    let dogs = realm.objects(Dog.self)
    let benDogs = dogs.where {
        $0.name == "Ben"
    }
    XCTAssertEqual(benDogs.count, 1)
}

Wait for Async Writes to Complete Copy Section

The SDK provides a Bool to signal whether the realm is currently
performing an async write. The
isPerformingAsynchronousWriteOperations
variable becomes true after a call to one of:

• writeAsync
• beginAsyncWrite
• commitAsyncWrite

It remains true until all scheduled async write operations have completed.
While this is true, this blocks closing or invalidating the realm.

Commit or Cancel an Async Write Copy Section

To complete an async write, you or the SDK must call either:

• commitAsyncWrite
• cancelAsyncWrite

When you use the writeAsync method, the SDK handles committing or
canceling the transaction. This provides the convenience of the async write
without the need to manually keep state tied to the scope of the object.
However, while in the writeAsync block, you can explicitly call
commitAsyncWrite or cancelAsyncWrite. If you return without
calling one of these methods, writeAsync either:

• Commits the write after executing the instructions in the write block
• Returns an error

In either case, this completes the writeAsync operation.

For more control over when to commit or cancel the async write transaction,
use the beginAsyncWrite method. When you use this method, you must
explicitly commit the transactions. Returning without committing an async
write cancels the transaction. beginAsyncWrite returns an ID that you
can pass to cancelAsyncWrite.

commitAsyncWrite asynchronously commits a write transaction. This is
the step that persists the data to the realm. commitAsyncWrite can
take an onComplete block. . This block executes on the source thread
once the commit completes or fails with an error.

Calling commitAsyncWrite immediately returns. This allows the caller
to proceed while the SDK performs the I/O on a background thread. This method
returns an ID that you can pass to cancelAsyncWrite. This cancels the
pending invocation of the completion block. It does not cancel the commit
itself.

You can group sequential calls to commitAsyncWrite. Batching these calls
improves write performance; particularly when the batched transactions are
small. To permit grouping transactions, set the isGroupingAllowed
parameter to true.

You can call cancelAsyncWrite on either beginAsyncWrite or
commitAsyncWrite. When you call it on beginAsyncWrite, this cancels
the entire write transaction. When you call it on commitAsyncWrite, this
cancels only an onComplete block you may have passed to
commitAsyncWrite. It does not cancel the commit itself. You need the ID
of the beginAsyncWrite or the commitAsyncWrite you want to cancel.

Communication Across Threads Copy Chapter

To access the same Realm file from different threads, you must instantiate a
realm instance on every thread that needs access. As long as you specify the same
configuration, all realm instances will map to the same file on disk.

One of the key rules when working with Realm in a multithreaded
environment is that objects are thread-confined: you cannot access the
instances of a realm, collection, or object that originated on other threads.
Realm's Multiversion Concurrency Control (MVCC)
architecture means that there could be many active versions of an object at any
time. Thread-confinement ensures that all instances in that thread are of the
same internal version.

When you need to communicate across threads, you have several options depending
on your use case:

• To modify an object on two threads, query
  for the object on both threads.
• To react to changes made on any thread, use Realm's
  notifications.
• To see changes that happened on another thread in the current thread's realm
  instance, refresh your realm instance.
• To send a fast, read-only view of the object to other threads,
  "freeze" the object.
• To keep and share many read-only views of the object in your app, copy
  the object from the realm.
• To share an instance of a realm or specific object with another thread or
  across actor boundaries, share a thread-safe reference to the realm instance or object. For more
  information, refer to Pass a ThreadSafeReference.

Create a Serial Queue to use Realm on a Background Thread Copy Section

When using Realm on a background thread, create a serial queue. Realm
does not support using realms in concurrent queues, such as the global()
queue.

// Initialize a serial queue, and
// perform realm operations on it
let serialQueue = DispatchQueue(label: "serial-queue")
serialQueue.async {
    let realm = try! Realm(configuration: .defaultConfiguration, queue: serialQueue)
    // Do something with Realm on the non-main thread
}

Pass Instances Across Threads Copy Section

Instances of Realm, Results, List, and managed Objects
are thread-confined. That means you may only use them on the thread
where you created them. However, Realm provides a mechanism called
thread-safe references that allows you to copy an instance
created on one thread to another thread.

Sendable Conformance

Version added: 10.20.0
@ThreadSafe wrapper and ThreadSafeReference conform to Sendable

If you are using Swift 5.6 or higher, both the @ThreadSafe property wrapper and
ThreadSafeReference
conform to Sendable.

Use the @ThreadSafe Wrapper

Version added: 10.17.0

You can pass thread-confined instances to another thread as follows:

1. Use the @ThreadSafe property wrapper to declare a variable that references the original object. By definition, @ThreadSafe-wrapped variables are always optional.
2. Pass the @ThreadSafe-wrapped variable to the other thread.
3. Use the @ThreadSafe-wrapped variable as you would any optional. If the referenced object is removed from the realm, the referencing variable becomes nil.

let realm = try! Realm()

let person = Person(name: "Jane")
try! realm.write {
    realm.add(person)
}

// Create thread-safe reference to person
@ThreadSafe var personRef = person

// @ThreadSafe vars are always optional. If the referenced object is deleted,
// the @ThreadSafe var will be nullified.
print("Person's name: \(personRef?.name ?? "unknown")")

// Pass the reference to a background thread
DispatchQueue(label: "background", autoreleaseFrequency: .workItem).async {
    let realm = try! Realm()
    try! realm.write {
        // Resolve within the transaction to ensure you get the
        // latest changes from other threads. If the person
        // object was deleted, personRef will be nil.
        guard let person = personRef else {
            return // person was deleted
        }
        person.name = "Jane Doe"
    }
}

Another way to work with an object on another thread is to query for it
again on that thread. But if the object does not have a primary
key, it is not trivial to
query for it. You can use the @ThreadSafe wrapper on any object,
regardless of whether it has a primary key.

Example:
The following example shows how to use @ThreadSafe on a function
parameter. This is useful for functions that may run asynchronously
or on another thread.

Tip:
If your app accesses Realm in an async/await context, mark the code
with @MainActor to avoid threading-related crashes.

Use ThreadSafeReference (Legacy Swift / Objective-C)

Before Realm Swift SDK version 10.17.0 or in Objective-C, you can pass
thread-confined instances to another thread as follows:

1. Initialize a ThreadSafeReference with the thread-confined object.
2. Pass the reference to the other thread or queue.
3. Resolve the reference on the other thread's realm by calling Realm.resolve(_:). Use the returned object as normal.

Important:
You must resolve a ThreadSafeReference exactly once. Otherwise,
the source realm remains pinned until the reference gets
deallocated. For this reason, ThreadSafeReference should be
short-lived.

let person = Person(name: "Jane")
let realm = try! Realm()

try! realm.write {
    realm.add(person)
}

// Create thread-safe reference to person
let personRef = ThreadSafeReference(to: person)

// Pass the reference to a background thread
DispatchQueue(label: "background", autoreleaseFrequency: .workItem).async {
    let realm = try! Realm()
    try! realm.write {
        // Resolve within the transaction to ensure you get the latest changes from other threads
        guard let person = realm.resolve(personRef) else {
            return // person was deleted
        }
        person.name = "Jane Doe"
    }
}

Another way to work with an object on another thread is to query for it
again on that thread. But if the object does not have a primary
key, it is not trivial to
query for it. You can use ThreadSafeReference on any object,
regardless of whether it has a primary key. You can also use it with
lists and results.

The downside is that ThreadSafeReference requires some boilerplate.
You must remember to wrap everything in a DispatchQueue with a
properly-scoped autoreleaseFrequency so the objects do not linger on
the background thread. So, it can be helpful to make a convenience extension
to handle the boilerplate as follows:

extension Realm {
    func writeAsync<T: ThreadConfined>(_ passedObject: T, errorHandler: @escaping ((_ error: Swift.Error) -> Void) = { _ in return }, block: @escaping ((Realm, T?) -> Void)) {
        let objectReference = ThreadSafeReference(to: passedObject)
        let configuration = self.configuration
        DispatchQueue(label: "background", autoreleaseFrequency: .workItem).async {
            do {
                let realm = try Realm(configuration: configuration)
                try realm.write {
                    // Resolve within the transaction to ensure you get the latest changes from other threads
                    let object = realm.resolve(objectReference)
                    block(realm, object)
                }
            } catch {
                errorHandler(error)
            }
        }
    }
}

This extension adds a writeAsync() method to the Realm class. This
method passes an instance to a background thread for you.

Example:
Suppose you made an email app and want to delete all read emails in
the background. You can now do it with two lines of code. Note that
the closure runs on the background thread and receives its own
version of both the realm and passed object:

swift Copy

let realm = try! Realm()
let readEmails = realm.objects(Email.self).where {
    $0.read == true
}
realm.writeAsync(readEmails) { (realm, readEmails) in
    guard let readEmails = readEmails else {
        // Already deleted
        return
    }
    realm.delete(readEmails)
}

Use the Same Realm Across Threads Copy Section

You cannot share realm instances across threads.

To use the same Realm file across threads, open a different realm
instance on each thread. As long as you use the same
configuration, all Realm
instances will map to the same file on disk.

Refreshing Realms Copy Section

When you open a realm, it reflects the most recent successful write
commit and remains on that version until it is refreshed. This means
that the realm will not see changes that happened on another thread
until the next refresh. A realm on the UI thread -- more precisely,
on any event loop thread -- automatically refreshes itself at
the beginning of that thread's loop. However, you must manually refresh
realm instances that do not exist on loop threads or that have
auto-refresh disabled.

Objective-C

if (![realm autorefresh]) {
    [realm refresh]
}

Swift

if (!realm.autorefresh) {
   // Manually refresh
   realm.refresh()
}

Frozen Objects Copy Section

Live, thread-confined objects work fine in most cases.
However, some apps -- those based on reactive, event
stream-based architectures, for example -- need to send
immutable copies around to many threads for processing
before ultimately ending up on the UI thread. Making a deep
copy every time would be expensive, and Realm does not allow
live instances to be shared across threads. In this case,
you can freeze and thaw objects, collections, and realms.

Freezing creates an immutable view of a specific object,
collection, or realm. The frozen object, collection, or realm still
exists on disk, and does not need to be deeply copied when passed around
to other threads. You can freely share the frozen object across threads
without concern for thread issues. When you freeze a realm, its child
objects also become frozen.

Tip:
Realm does not currently support using thaw() with Swift Actors.
To work with Realm data across actor boundaries, use
ThreadSafeReference instead of frozen objects. For more information,
refer to Pass a ThreadSafeReference.

Frozen objects are not live and do not automatically update.
They are effectively snapshots of the object state at the
time of freezing. Thawing an object returns a live version of the frozen
object.

Objective-C

// Get an immutable copy of the realm that can be passed across threads
RLMRealm *frozenRealm = [realm freeze];

RLMResults *dogs = [Dog allObjectsInRealm:realm];

// You can freeze collections
RLMResults *frozenDogs = [dogs freeze];

// You can still read from frozen realms
RLMResults *frozenDogs2 = [Dog allObjectsInRealm:frozenRealm];

Dog *dog = [dogs firstObject];

// You can freeze objects
Dog *frozenDog = [dog freeze];

// To modify frozen objects, you can thaw them
// You can thaw collections
RLMResults *thawedDogs = [dogs thaw];

// You can thaw objects
Dog *thawedDog = [dog thaw];

// You can thaw frozen realms
RLMRealm *thawedRealm = [realm thaw];

Swift

let realm = try! Realm()

// Get an immutable copy of the realm that can be passed across threads
let frozenRealm = realm.freeze()

assert(frozenRealm.isFrozen)

let people = realm.objects(Person.self)

// You can freeze collections
let frozenPeople = people.freeze()

assert(frozenPeople.isFrozen)

// You can still read from frozen realms
let frozenPeople2 = frozenRealm.objects(Person.self)

assert(frozenPeople2.isFrozen)

let person = people.first!

assert(!person.realm!.isFrozen)

// You can freeze objects
let frozenPerson = person.freeze()

assert(frozenPerson.isFrozen)
// Frozen objects have a reference to a frozen realm
assert(frozenPerson.realm!.isFrozen)

When working with frozen objects, an attempt to do any of
the following throws an exception:

• Opening a write transaction on a frozen realm.
• Modifying a frozen object.
• Adding a change listener to a frozen realm, collection, or object.

You can use isFrozen to check if the object is frozen. This is always
thread-safe.

Objective-C

if ([realm isFrozen]) {
    // ...
}

Swift

if (realm.isFrozen) {
    // ...
}

Frozen objects remain valid as long as the live realm that
spawned them stays open. Therefore, avoid closing the live
realm until all threads are done with the frozen objects.
You can close a frozen realm before the live realm is closed.

Important:
Caching too many frozen objects can have a negative
impact on the realm file size. "Too many" depends on your
specific target device and the size of your Realm
objects. If you need to cache a large number of versions,
consider copying what you need out of the realm instead.

Modify a Frozen Object

To modify a frozen object, you must thaw the object. Alternately, you can
query for it on an unfrozen realm, then modify it. Calling thaw
on a live object, collection, or realm returns itself.

Thawing an object or collection also thaws the realm it references.

// Read from a frozen realm
let frozenPeople = frozenRealm.objects(Person.self)

// The collection that we pull from the frozen realm is also frozen
assert(frozenPeople.isFrozen)

// Get an individual person from the collection
let frozenPerson = frozenPeople.first!

// To modify the person, you must first thaw it
// You can also thaw collections and realms
let thawedPerson = frozenPerson.thaw()

// Check to make sure this person is valid. An object is
// invalidated when it is deleted from its managing realm,
// or when its managing realm has invalidate() called on it.
assert(thawedPerson?.isInvalidated == false)

// Thawing the person also thaws the frozen realm it references
assert(thawedPerson!.realm!.isFrozen == false)

// Let's make the code easier to follow by naming the thawed realm
let thawedRealm = thawedPerson!.realm!

// Now, you can modify the todo
try! thawedRealm.write {
   thawedPerson!.name = "John Michael Kane"
}

Append to a Frozen Collection

When you append to a frozen collection,
you must thaw both the collection and the object that you want to append.
In this example, we query for two objects in a frozen Realm:

• A Person object that has a List property
  of Dog objects
• A Dog object

We must thaw both objects before we can append the Dog to
the Dog List collection on the Person. If we thaw only the Person object
but not the Dog, Realm throws an error.

The same rule applies when passing frozen objects across threads. A common
case might be calling a function on a background thread to do some work
instead of blocking the UI.

// Get a copy of frozen objects.
// Here, we're getting them from a frozen realm,
// but you might also be passing them across threads.
let frozenTimmy = frozenRealm.objects(Person.self).where {
    $0.name == "Timmy"
}.first!
let frozenLassie = frozenRealm.objects(Dog.self).where {
    $0.name == "Lassie"
}.first!
// Confirm the objects are frozen.
assert(frozenTimmy.isFrozen == true)
assert(frozenLassie.isFrozen == true)
// Thaw the frozen objects. You must thaw both the object
// you want to append and the collection you want to append it to.
let thawedTimmy = frozenTimmy.thaw()
let thawedLassie = frozenLassie.thaw()
let realm = try! Realm()
try! realm.write {
    thawedTimmy?.dogs.append(thawedLassie!)
}
XCTAssertEqual(thawedTimmy?.dogs.first?.name, "Lassie")

Realm's Threading Model in Depth Copy Chapter

Realm provides safe, fast, lock-free, and concurrent access
across threads with its Multiversion Concurrency
Control (MVCC)
architecture.

Compared and Contrasted with Git Copy Section

If you are familiar with a distributed version control
system like Git, you may already
have an intuitive understanding of MVCC. Two fundamental
elements of Git are:

• Commits, which are atomic writes.
• Branches, which are different versions of the commit history.

Similarly, Realm has atomically-committed writes in the form
of transactions. Realm also has many
different versions of the history at any given time, like
branches.

Unlike Git, which actively supports distribution and
divergence through forking, a realm only has one true latest
version at any given time and always writes to the head of
that latest version. Realm cannot write to a previous
version. This means your data converges on one
latest version of the truth.

Internal Structure Copy Section

A realm is implemented using a B+ tree data structure. The top-level node represents a
version of the realm; child nodes are objects in that
version of the realm. The realm has a pointer to its latest
version, much like how Git has a pointer to its HEAD commit.

Realm uses a copy-on-write technique to ensure
isolation and
durability.
When you make changes, Realm copies the relevant part of the
tree for writing. Realm then commits the changes in two
phases:

• Realm writes changes to disk and verifies success.
• Realm then sets its latest version pointer to point to the newly-written version.

This two-step commit process guarantees that even if the
write failed partway, the original version is not corrupted
in any way because the changes were made to a copy of the
relevant part of the tree. Likewise, the realm's root
pointer will point to the original version until the new
version is guaranteed to be valid.

Example:
The following diagram illustrates the commit process:

1. The realm is structured as a tree. The realm has a pointer
   to its latest version, V1.

2. When writing, Realm creates a new version V2 based on V1.
   Realm makes copies of objects for modification (A 1,
   C 1), while links to unmodified objects continue to
   point to the original versions (B, D).

3. After validating the commit, Realm updates the
   pointer to the new latest version, V2. Realm then discards
   old nodes no longer connected to the tree.

ealm uses zero-copy techniques
like memory mapping to handle data. When you read a value
from the realm, you are virtually looking at the value on
the actual disk, not a copy of it. This is the basis for
live objects. This is also why a realm
head pointer can be set to point to the new version after
the write to disk has been validated.

Summary Copy Chapter

• Realm enables simple and safe multithreaded code when you follow
  these rules: don't lock to readavoid writes on the UI thread if you
  write on background threads, and don't pass live objects to other threads.
• There is a proper way to share objects across threads for each use case.
• In order to see changes made on other threads in your realm
  instance, you must manually refresh realm instances that do
  not exist on "loop" threads or that have auto-refresh disabled.
• For apps based on reactive, event-stream-based architectures, you can
  freeze objects, collections, and realms in order to pass
  shallow copies around efficiently to different threads for processing.
• Realm's multiversion concurrency control (MVCC)
  architecture is similar to Git's. Unlike Git, Realm has
  only one true latest version for each realm.
• Realm commits in two stages to guarantee isolation and durability.

Sendable, Non-Sendable and Thread-Confined Types Copy Chapter

The Realm Swift SDK public API contains types that fall into three broad
categories:

• Sendable
• Not Sendable and not thread confined
• Thread-confined

You can share types that are not Sendable and not thread confined between
threads, but you must synchronize them.

Thread-confined types, unless frozen, are confined to an isolation context.
You cannot pass them between these contexts even with synchronization.

Guides Crud Update (`docs/guides/crud/update.md`) Copy Section

CRUD - Update - Swift SDK

Update Realm Objects Copy Chapter

Updates to Realm Objects must occur within write transactions. For
more information about write transactions, see: Transactions.

About The Examples On This Page Copy Section

The examples on this page use the following models:

Objective-C

// DogToy.h
@interface DogToy : RLMObject
@property NSString *name;
@end

// Dog.h
@interface Dog : RLMObject
@property NSString *name;
@property int age;
@property NSString *color;

// To-one relationship
@property DogToy *favoriteToy;

@end

// Enable Dog for use in RLMArray
RLM_COLLECTION_TYPE(Dog)

// Person.h
// A person has a primary key ID, a collection of dogs, and can be a member of multiple clubs.
@interface Person : RLMObject
@property int _id;
@property NSString *name;

// To-many relationship - a person can have many dogs
@property RLMArray<Dog *><Dog> *dogs;

// Inverse relationship - a person can be a member of many clubs
@property (readonly) RLMLinkingObjects *clubs;
@end

RLM_COLLECTION_TYPE(Person)

// DogClub.h
@interface DogClub : RLMObject
@property NSString *name;
@property RLMArray<Person *><Person> *members;
@end

// Dog.m
@implementation Dog
@end

// DogToy.m
@implementation DogToy
@end

// Person.m
@implementation Person
// Define the primary key for the class
+ (NSString *)primaryKey {
    return @"_id";
}

// Define the inverse relationship to dog clubs
+ (NSDictionary *)linkingObjectsProperties {
    return @{
        @"clubs": [RLMPropertyDescriptor descriptorWithClass:DogClub.class propertyName:@"members"],
    };
}
@end

// DogClub.m
@implementation DogClub
@end

Swift

class Dog: Object {
    @Persisted var name = ""
    @Persisted var age = 0
    @Persisted var color = ""
    @Persisted var currentCity = ""
    @Persisted var citiesVisited: MutableSet<String>
    @Persisted var companion: AnyRealmValue

    // Map of city name -> favorite park in that city
    @Persisted var favoriteParksByCity: Map<String, String>
}

class Person: Object {
    @Persisted(primaryKey: true) var id = 0
    @Persisted var name = ""

    // To-many relationship - a person can have many dogs
    @Persisted var dogs: List<Dog>

    // Embed a single object.
    // Embedded object properties must be marked optional.
    @Persisted var address: Address?
}

class Address: EmbeddedObject {
    @Persisted var street: String?
    @Persisted var city: String?
    @Persisted var country: String?
    @Persisted var postalCode: String?
}

Update an Object Copy Section

You can modify properties of a Realm object inside of a write
transaction in the same way that you would update any other Swift or
Objective-C object.

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];
// Open a thread-safe transaction.
[realm transactionWithBlock:^{
    // Get a dog to update.
    Dog *dog = [[Dog allObjectsInRealm: realm] firstObject];

    // Update some properties on the instance.
    // These changes are saved to the realm.
    dog.name = @"Wolfie";
    dog.age += 1;
}];

Swift

let realm = try! Realm()

// Get a dog to update
let dog = realm.objects(Dog.self).first!

// Open a thread-safe transaction
try! realm.write {
    // Update some properties on the instance.
    // These changes are saved to the realm
    dog.name = "Wolfie"
    dog.age += 1
}

Tip:
To update a property of an embedded object or a related object, modify the property with
dot-notation or bracket-notation as if it were in a regular, nested
object.

Update Properties with Key-value Coding Copy Section

Object, Result, and List all conform to
key-value coding.
This can be useful when you need to determine which property to update
at runtime.

Applying KVC to a collection is a great way to update objects in bulk.
Avoid the overhead of iterating over a collection while creating
accessors for every item.

let realm = try! Realm()

let allDogs = realm.objects(Dog.self)

try! realm.write {
    allDogs.first?.setValue("Sparky", forKey: "name")
    // Move the dogs to Toronto for vacation
    allDogs.setValue("Toronto", forKey: "currentCity")
}

You can also add values for embedded objects or relationships this
way. In this example, we add a collection to an object's list property:

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];

[realm transactionWithBlock:^() {
    // Create a person to take care of some dogs.
    Person *ali = [[Person alloc] initWithValue:@{@"_id": @1, @"name": @"Ali"}];
    [realm addObject:ali];

    // Find dogs younger than 2.
    RLMResults<Dog *> *puppies = [Dog objectsInRealm:realm where:@"age < 2"];

    // Batch update: give all puppies to Ali.
    [ali setValue:puppies forKey:@"dogs"];
}];

Swift

let realm = try! Realm()
try! realm.write {
    // Create a person to take care of some dogs.
    let person = Person(value: ["id": 1, "name": "Ali"])
    realm.add(person)

    let dog = Dog(value: ["name": "Rex", "age": 1])
    realm.add(dog)

    // Find dogs younger than 2.
    let puppies = realm.objects(Dog.self).filter("age < 2")

    // Give all puppies to Ali.
    person.setValue(puppies, forKey: "dogs")

}

Upsert an Object Copy Section

An upsert either inserts or updates an object depending on whether
the object already exists. Upserts require the data model to have a
primary key.

Objective-C

To upsert an object, call -[RLMRealm addOrUpdateObject:].

RLMRealm *realm = [RLMRealm defaultRealm];
[realm transactionWithBlock:^{
    Person *jones = [[Person alloc] initWithValue:@{@"_id": @1234, @"name": @"Jones"}];
    // Add a new person to the realm. Since nobody with ID 1234
    // has been added yet, this adds the instance to the realm.
    [realm addOrUpdateObject:jones];
    
    Person *bowie = [[Person alloc] initWithValue:@{@"_id": @1234, @"name": @"Bowie"}];
    // Judging by the ID, it's the same person, just with a different name.
    // This overwrites the original entry (i.e. Jones -> Bowie).
    [realm addOrUpdateObject:bowie];
}];

Swift

To upsert an object, call Realm.add(_:update:)
with the second parameter, update policy, set to .modified.

let realm = try! Realm()
try! realm.write {
    let person1 = Person(value: ["id": 1234, "name": "Jones"])
    // Add a new person to the realm. Since nobody with ID 1234
    // has been added yet, this adds the instance to the realm.
    realm.add(person1, update: .modified)

    let person2 = Person(value: ["id": 1234, "name": "Bowie"])
    // Judging by the ID, it's the same person, just with a
    // different name. When `update` is:
    // - .modified: update the fields that have changed.
    // - .all: replace all of the fields regardless of
    //   whether they've changed.
    // - .error: throw an exception if a key with the same
    //   primary key already exists.
    realm.add(person2, update: .modified)
}

You can also partially update an object by passing the primary key and a
subset of the values to update:

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];
[realm transactionWithBlock:^{
    // Only update the provided values.
    // Note that the "name" property will remain the same
    // for the person with primary key "_id" 123.
    [Person createOrUpdateModifiedInRealm:realm
        withValue:@{@"_id": @123, @"dogs": @[@[@"Buster", @5]]}];
}];

Swift

let realm = try! Realm()
try! realm.write {
    // Use .modified to only update the provided values.
    // Note that the "name" property will remain the same
    // for the person with primary key "id" 123.
    realm.create(Person.self,
                 value: ["id": 123, "dogs": [["Buster", 5]]],
                 update: .modified)
}

Update a Map/Dictionary Copy Section

You can update a realm map as you would a
standard Dictionary:

let realm = try! Realm()

// Find the dog we want to update
let wolfie = realm.objects(Dog.self).where {
    $0.name == "Wolfie"
}.first!

print("Wolfie's favorite park in New York is: \(wolfie.favoriteParksByCity["New York"])")
XCTAssertTrue(wolfie.favoriteParksByCity["New York"] == "Domino Park")

// Update values for keys, or add values if the keys do not currently exist
try! realm.write {
    wolfie.favoriteParksByCity["New York"] = "Washington Square Park"
    wolfie.favoriteParksByCity.updateValue("A Street Park", forKey: "Boston")
    wolfie.favoriteParksByCity.setValue("Little Long Pond", forKey: "Seal Harbor")
}

XCTAssertTrue(wolfie.favoriteParksByCity["New York"] == "Washington Square Park")

Update a MutableSet Property Copy Section

You can insert elements into a MutableSet during write transactions to add them to the
property. If you are working with multiple sets, you can also insert or
remove set elements contained in one set from the other set. Alternately,
you can mutate a set to contain only the common elements from both.

let realm = try! Realm()

// Record a dog's name, current city, and store it to the cities visited.
let dog = Dog()
dog.name = "Maui"
dog.currentCity = "New York"
try! realm.write {
    realm.add(dog)
    dog.citiesVisited.insert(dog.currentCity)
}

// Update the dog's current city, and add it to the set of cities visited.
try! realm.write {
    dog.currentCity = "Toronto"
    dog.citiesVisited.insert(dog.currentCity)
}
XCTAssertEqual(dog.citiesVisited.count, 2)

// If you're operating with two sets, you can insert the elements from one set into another set.
// The dog2 set contains one element that isn't present in the dog set.
try! realm.write {
    dog.citiesVisited.formUnion(dog2.citiesVisited)
}
XCTAssertEqual(dog.citiesVisited.count, 3)

// Or you can remove elements that are present in the second set. This removes the one element
// that we added above from the dog2 set.
try! realm.write {
    dog.citiesVisited.subtract(dog2.citiesVisited)
}
XCTAssertEqual(dog.citiesVisited.count, 2)

// If the sets contain common elements, you can mutate the set to only contain those common elements.
// In this case, the two sets contain no common elements, so this set should now contain 0 items.
try! realm.write {
    dog.citiesVisited.formIntersection(dog2.citiesVisited)
}
XCTAssertEqual(dog.citiesVisited.count, 0)

Update an AnyRealmValue Property Copy Section

You can update an AnyRealmValue property through assignment, but you must
specify the type of the value when you assign it. The Realm Swift SDK
provides an AnyRealmValue enum that
iterates through all of the types the AnyRealmValue can store.

let realm = try! Realm()

// Get a dog to update
let rex = realm.objects(Dog.self).where {
    $0.name == "Rex"
}.first!

try! realm.write {
    // As with creating an object with an AnyRealmValue, you must specify the
    // type of the value when you update the property.
    rex.companion = .object(Dog(value: ["name": "Regina"]))
}

Update an Embedded Object Property Copy Section

To update a property in an embedded object, modify the property in a
write transaction. If the embedded object is null, updating an embedded
object property has no effect.

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];
[realm transactionWithBlock: ^{
    Contact *contact = [Contact objectInRealm:realm
                                forPrimaryKey:[[RLMObjectId alloc] initWithString:@"5f481c21f634a1f4eeaa7268" error:nil]];
    contact.address.street = @"Hollywood Upstairs Medical College";
    contact.address.city = @"Los Angeles";
    contact.address.postalCode = @"90210";
    NSLog(@"Updated contact: %@", contact);
}];

Swift

// Open the default realm
let realm = try! Realm()

let idOfPersonToUpdate = 123

// Find the person to update by ID
guard let person = realm.object(ofType: Person.self, forPrimaryKey: idOfPersonToUpdate) else {
    print("Person \(idOfPersonToUpdate) not found")
    return
}

try! realm.write {
    // Update the embedded object directly through the person
    // If the embedded object is null, updating these properties has no effect
    person.address?.street = "789 Any Street"
    person.address?.city = "Anytown"
    person.address?.postalCode = "12345"
    print("Updated person: \(person)")
}

Overwrite an Embedded Object Copy Section

To overwrite an embedded object, reassign the embedded object property
of a party to a new instance in a write transaction.

Objective-C

RLMRealm *realm = [RLMRealm defaultRealm];
[realm transactionWithBlock: ^{
    Contact *contact = [Contact objectInRealm:realm
                                forPrimaryKey:[[RLMObjectId alloc] initWithString:@"5f481c21f634a1f4eeaa7268" error:nil]];
    Address *newAddress = [[Address alloc] init];
    newAddress.street = @"Hollywood Upstairs Medical College";
    newAddress.city = @"Los Angeles";
    newAddress.country = @"USA";
    newAddress.postalCode = @"90210";
    contact.address = newAddress;
    NSLog(@"Updated contact: %@", contact);
}];

Swift

// Open the default realm
let realm = try! Realm()

let idOfPersonToUpdate = 123

// Find the person to update by ID
guard let person = realm.object(ofType: Person.self, forPrimaryKey: idOfPersonToUpdate) else {
    print("Person \(idOfPersonToUpdate) not found")
    return
}

try! realm.write {
    let newAddress = Address()
    newAddress.street = "789 Any Street"
    newAddress.city = "Anytown"
    newAddress.country = "USA"
    newAddress.postalCode = "12345"

    // Overwrite the embedded object
    person.address = newAddress
    print("Updated person: \(person)")
}

Update an Object Asynchronously Copy Chapter

You can use Swift concurrency features to asynchronously update objects
using an actor-isolated realm.

This function from the example RealmActor defined on the
Use Realm with Actors page shows how you might
update an object in an actor-isolated realm:

func updateTodo(_id: ObjectId, name: String, owner: String, status: String) async throws {
    try await realm.asyncWrite {
        realm.create(Todo.self, value: [
            "_id": _id,
            "name": name,
            "owner": owner,
            "status": status
        ], update: .modified)
    }
}

And you might perform this update using Swift's async syntax:

let actor = try await RealmActor()

// Read objects in functions isolated to the actor and pass primitive values to the caller
func getObjectId(in actor: isolated RealmActor, forTodoNamed name: String) async -> ObjectId {
    let todo = actor.realm.objects(Todo.self).where {
        $0.name == name
    }.first!
    return todo._id
}
let objectId = await getObjectId(in: actor, forTodoNamed: "Keep it safe")

try await actor.updateTodo(_id: objectId, name: "Keep it safe", owner: "Frodo", status: "Completed")

This operation does not block or perform I/O on the calling thread. For
more information about writing to realm using Swift concurrency features,
refer to Use Realm with Actors - Swift SDK.

Update Properties through Class Projections Copy Chapter

Change Class Projection Properties Copy Section

You can make changes to a class projection's properties in a write transaction.

// Retrieve all class projections of the given type `PersonProjection`
// and filter for the first class projection where the `firstName` property
// value is "Jason"
let person = realm.objects(PersonProjection.self).first(where: { $0.firstName == "Jason" })!
// Update class projection property in a write transaction
try! realm.write {
    person.firstName = "David"
}

Guides Model Data Change An Object Model (`docs/guides/model-data/change-an-object-model.md`) Copy Section

Change an Object Model - Swift SDK

Overview Copy Chapter

When you update your object schema, you must increment the schema version
and perform a migration.

Seealso:
This page provides general Swift and Objective-C migration examples.
If you are using Realm with SwiftUI, see the SwiftUI-specific
migration examples.

If your schema update adds optional properties or removes properties,
Realm can perform the migration automatically. You only need to
increment the schemaVersion.

For more complex schema updates, you must also manually specify the migration logic
in a migrationBlock. This might include changes such as:

• Adding required properties that must be populated with default values
• Combining fields
• Renaming a field
• Changing a field's type
• Converting from an object to an embedded object

Tip:
When developing or debugging your application, you may prefer to delete
the realm instead of migrating it. Use the
deleteRealmIfMigrationNeeded
flag to delete the database automatically when a schema mismatch would
require a migration.

Never release an app to production with this flag set to true.

Schema Version Copy Chapter

A schema version identifies the state of a Realm Schema at some point in time. Realm tracks the schema
version of each realm and uses it to map the objects in each realm
to the correct schema.

Schema versions are integers that you may include
in the realm configuration when you open a realm. If a client
application does not specify a version number when it opens a realm then
the realm defaults to version 0.

Important:
Migrations must update a realm to a higher schema version.
Realm will throw an error if a client application opens
a realm with a schema version that is lower than the realm's
current version or if the specified schema version is the same as the
realm's current version but includes different object
schemas.

Migrations Copy Section

Local migrations have access to the existing
Realm Schema, version, and objects and define logic that
incrementally updates the realm to its new schema version.
To perform a local migration you must specify a new schema
version that is higher than the current version and provide
a migration function when you open the out-of-date realm.

In iOS, you can update underlying data to reflect schema changes using
manual migrations. During such a
manual migration, you can define new and deleted properties when they
are added or removed from your schema.

Automatically Update Schema Copy Chapter

Add a Property Copy Section

Realm can automatically migrate added
properties, but you must specify an updated schema version when you make
these changes.

Note:
Realm does not automatically set values for new required
properties. You must use a migration block to set default values for
new required properties. For new optional properties, existing records
can have null values. This means you don't need a migration block when
adding optional properties.

Example:
A realm using schema version 1 has a Person object type
that has first name, last name, and age properties:

Objective-C

objectivec Copy

// In the first version of the app, the Person model
// has separate fields for first and last names,
// and an age property.
@interface Person : RLMObject
@property NSString *firstName;
@property NSString *lastName;
@property int age;
@end

@implementation Person
+ (NSArray<NSString *> *)requiredProperties {
    return @[@"firstName", @"lastName", @"age"];
}
@end

Swift

swift Copy

// In the first version of the app, the Person model
// has separate fields for first and last names,
// and an age property.
class Person: Object {
    @Persisted var firstName = ""
    @Persisted var lastName = ""
    @Persisted var age = 0
}

The developer decides that the Person class needs an email field and updates
the schema.

Objective-C

objectivec Copy

// In a new version, you add a property
// on the Person model.
@interface Person : RLMObject
@property NSString *firstName;
@property NSString *lastName;
// Add a new "email" property.
@property NSString *email;
// New properties can be migrated
// automatically, but must update the schema version.
@property int age;
@end

@implementation Person
+ (NSArray<NSString *> *)requiredProperties {
    return @[@"firstName", @"lastName", @"email", @"age"];
}
@end

Swift

swift Copy

// In a new version, you add a property
// on the Person model.
class Person: Object {
    @Persisted var firstName = ""
    @Persisted var lastName = ""
    // Add a new "email" property.
    @Persisted var email: String?
    // New properties can be migrated
    // automatically, but must update the schema version.
    @Persisted var age = 0

}

Realm automatically migrates the realm to conform to
the updated Person schema. But the developer must set the realm's
schema version to 2.

Objective-C

objectivec Copy

// When you open the realm, specify that the schema
// is now using a newer version.
RLMRealmConfiguration *config = [[RLMRealmConfiguration alloc] init];
// Set the new schema version
config.schemaVersion = 2;
// Use this configuration when opening realms
[RLMRealmConfiguration setDefaultConfiguration:config];
RLMRealm *realm = [RLMRealm defaultRealm];

Swift

swift Copy

// When you open the realm, specify that the schema
// is now using a newer version.
let config = Realm.Configuration(
    schemaVersion: 2)
// Use this configuration when opening realms
Realm.Configuration.defaultConfiguration = config
let realm = try! Realm()

Delete a Property Copy Section

To delete a property from a schema, remove the property from the object's class
and set a schemaVersion of the realm's configuration object. Deleting a property
will not impact existing objects.

Example:
A realm using schema version 1 has a Person object type
that has first name, last name, and age properties:

Objective-C

objectivec Copy

// In the first version of the app, the Person model
// has separate fields for first and last names,
// and an age property.
@interface Person : RLMObject
@property NSString *firstName;
@property NSString *lastName;
@property int age;
@end

@implementation Person
+ (NSArray<NSString *> *)requiredProperties {
    return @[@"firstName", @"lastName", @"age"];
}
@end

Swift

swift Copy

// In the first version of the app, the Person model
// has separate fields for first and last names,
// and an age property.
class Person: Object {
    @Persisted var firstName = ""
    @Persisted var lastName = ""
    @Persisted var age = 0
}

The developer decides that the Person does not need the age field and updates the schema.

Objective-C

objectivec Copy

// In a new version, you remove a property
// on the Person model.
@interface Person : RLMObject
@property NSString *firstName;
@property NSString *lastName;
// Remove the "age" property.
// @property int age;
// Removed properties can be migrated
// automatically, but must update the schema version.
@end

@implementation Person
+ (NSArray<NSString *> *)requiredProperties {
    return @[@"firstName", @"lastName"];
}
@end

Swift

swift Copy

// In a new version, you remove a property
// on the Person model.
class Person: Object {
    @Persisted var firstName = ""
    @Persisted var lastName = ""
    // Remove the "age" property.
    // @Persisted var age = 0
    // Removed properties can be migrated
    // automatically, but must update the schema version.

}

Realm automatically migrates the realm to conform to
the updated Person schema. But the developer must set the realm's
schema version to 2.

Objective-C

objectivec Copy

// When you open the realm, specify that the schema
// is now using a newer version.
RLMRealmConfiguration *config = [[RLMRealmConfiguration alloc] init];
// Set the new schema version
config.schemaVersion = 2;
// Use this configuration when opening realms
[RLMRealmConfiguration setDefaultConfiguration:config];
RLMRealm *realm = [RLMRealm defaultRealm];

Swift

swift Copy

// When you open the realm, specify that the schema
// is now using a newer version.
let config = Realm.Configuration(
    schemaVersion: 2)
// Use this configuration when opening realms
Realm.Configuration.defaultConfiguration = config
let realm = try! Realm()

Tip:
SwiftUI developers may see an error that a migration is required when they
add or delete properties. This is related to the lifecycle in SwiftUI.
The Views are laid out, and then the .environment modifier sets the
config.

To resolve a migration error in these circumstances, pass
Realm.Configuration(schemaVersion: <Your Incremented Version>)
into the ObservedResults constructor.

Manually Migrate Schema Copy Chapter

For more complex schema updates, Realm requires a manual
migration for old instances of a given object to the new schema.

Rename a Property Copy Section

To rename a property during a migration, use the
Migration.renameProperty(onType:from:to:)
method.

Realm applies any new nullability or indexing settings
during the rename operation.

Example:
Rename age to yearsSinceBirth within a migrationBlock.

Objective-C

objectivec Copy

RLMRealmConfiguration *config = [[RLMRealmConfiguration alloc] init];
config.schemaVersion = 2;
config.migrationBlock = ^(RLMMigration * _Nonnull migration, uint64_t oldSchemaVersion) {
    if (oldSchemaVersion < 2) {
        // Rename the "age" property to "yearsSinceBirth".
        // The renaming operation should be done outside of calls to `enumerateObjects(ofType: _:)`.
        [migration renamePropertyForClass:[Person className] oldName:@"age" newName:@"yearsSinceBirth"];
    }
};

Swift

swift Copy

let config = Realm.Configuration(
    schemaVersion: 2,
    migrationBlock: { migration, oldSchemaVersion in
        if oldSchemaVersion < 2 {
            // Rename the "age" property to "yearsSinceBirth".
            // The renaming operation should be done outside of calls to `enumerateObjects(ofType: _:)`.
            migration.renameProperty(onType: Person.className(), from: "age", to: "yearsSinceBirth")
        }
    })

Modify Properties Copy Section

Tip:
You can use the deleteRealmIfMigrationNeeded
method to delete the realm if it would require a migration. This can
be useful during development when you need to iterate quickly and don't
want to perform the migration.

To define custom migration logic, set the migrationBlock
property of the Configuration when opening a realm.

The migration block receives a Migration object that you can use to perform the migration. You
can use the Migration object's enumerateObjects(ofType:_:)
method to iterate over and update all instances of a given
Realm type in the realm.

Example:
A realm using schema version 1 has a Person object type
that has separate fields for first and last names:

Objective-C

objectivec Copy

// In the first version of the app, the Person model
// has separate fields for first and last names,
// and an age property.
@interface Person : RLMObject
@property NSString *firstName;
@property NSString *lastName;
@property int age;
@end

@implementation Person
+ (NSArray<NSString *> *)requiredProperties {
    return @[@"firstName", @"lastName", @"age"];
}
@end

Swift

swift Copy

// In the first version of the app, the Person model
// has separate fields for first and last names,
// and an age property.
class Person: Object {
    @Persisted var firstName = ""
    @Persisted var lastName = ""
    @Persisted var age = 0
}

The developer decides that the Person class should use a combined
fullName field instead of the separate firstName and
lastName fields and updates the schema.

To migrate the realm to conform to the updated Person schema,
the developer sets the realm's schema version to 2 and
defines a migration function to set the value of fullName based
on the existing firstName and lastName properties.

Objective-C

objectivec Copy

// In version 2, the Person model has one
// combined field for the full name and age as a Int.
// A manual migration will be required to convert from
// version 1 to this version.
@interface Person : RLMObject
@property NSString *fullName;
@property int age;
@end

@implementation Person
+ (NSArray<NSString *> *)requiredProperties {
    return @[@"fullName", @"age"];
}
@end

objectivec Copy

RLMRealmConfiguration *config = [[RLMRealmConfiguration alloc] init];
// Set the new schema version
config.schemaVersion = 2;
config.migrationBlock = ^(RLMMigration * _Nonnull migration, uint64_t oldSchemaVersion) {
    if (oldSchemaVersion < 2) {
        // Iterate over every 'Person' object stored in the Realm file to
        // apply the migration
        [migration enumerateObjects:[Person className]
                            block:^(RLMObject * _Nullable oldObject, RLMObject * _Nullable newObject) {
            // Combine name fields into a single field
            newObject[@"fullName"] = [NSString stringWithFormat:@"%@ %@",
                                        oldObject[@"firstName"],
                                        oldObject[@"lastName"]];
        }];
    }
};

// Tell Realm to use this new configuration object for the default Realm
[RLMRealmConfiguration setDefaultConfiguration:config];

// Now that we've told Realm how to handle the schema change, opening the realm
// will automatically perform the migration
RLMRealm *realm = [RLMRealm defaultRealm];

Swift

swift Copy

// In version 2, the Person model has one
// combined field for the full name and age as a Int.
// A manual migration will be required to convert from
// version 1 to this version.
class Person: Object {
    @Persisted var fullName = ""
    @Persisted var age = 0
}

swift Copy

// In application(_:didFinishLaunchingWithOptions:)
let config = Realm.Configuration(
    schemaVersion: 2, // Set the new schema version.
    migrationBlock: { migration, oldSchemaVersion in
        if oldSchemaVersion < 2 {
            // The enumerateObjects(ofType:_:) method iterates over
            // every Person object stored in the Realm file to apply the migration
            migration.enumerateObjects(ofType: Person.className()) { oldObject, newObject in
                // combine name fields into a single field
                let firstName = oldObject!["firstName"] as? String
                let lastName = oldObject!["lastName"] as? String
                newObject!["fullName"] = "\(firstName!) \(lastName!)"
            }
        }
    }
)

// Tell Realm to use this new configuration object for the default Realm
Realm.Configuration.defaultConfiguration = config

// Now that we've told Realm how to handle the schema change, opening the file
// will automatically perform the migration
let realm = try! Realm()

Later, the developer decides that the age field should be of type String
rather than Int and updates the schema.

To migrate the realm to conform to the updated Person schema,
the developer sets the realm's schema version to 3 and
adds a conditional to the migration function so that the function defines
how to migrate from any previous version to the new one.

Objective-C

objectivec Copy

// In version 3, the Person model has one
// combined field for the full name and age as a String.
// A manual migration will be required to convert from
// version 2 to this version.
@interface Person : RLMObject
@property NSString *fullName;
@property NSString *age;
@end

@implementation Person
+ (NSArray<NSString *> *)requiredProperties {
    return @[@"fullName", @"age"];
}
@end

objectivec Copy

RLMRealmConfiguration *config = [[RLMRealmConfiguration alloc] init];
// Set the new schema version
config.schemaVersion = 3;
config.migrationBlock = ^(RLMMigration * _Nonnull migration, uint64_t oldSchemaVersion) {
    if (oldSchemaVersion < 2) {
        // Previous Migration.
        [migration enumerateObjects:[Person className]
                            block:^(RLMObject * _Nullable oldObject, RLMObject * _Nullable newObject) {
            newObject[@"fullName"] = [NSString stringWithFormat:@"%@ %@",
                                        oldObject[@"firstName"],
                                        oldObject[@"lastName"]];
        }];
    }
    if (oldSchemaVersion < 3) {
        // New Migration
        [migration enumerateObjects:[Person className]
                            block:^(RLMObject * _Nullable oldObject, RLMObject * _Nullable newObject) {
            // Make age a String instead of an Int
            newObject[@"age"] = [oldObject[@"age"] stringValue];
        }];
    }
};

// Tell Realm to use this new configuration object for the default Realm
[RLMRealmConfiguration setDefaultConfiguration:config];

// Now that we've told Realm how to handle the schema change, opening the realm
// will automatically perform the migration
RLMRealm *realm = [RLMRealm defaultRealm];

Swift

swift Copy

// In version 3, the Person model has one
// combined field for the full name and age as a String.
// A manual migration will be required to convert from
// version 2 to this version.
 class Person: Object {
    @Persisted var fullName = ""
    @Persisted var age = "0"
 }

swift Copy

// In application(_:didFinishLaunchingWithOptions:)
let config = Realm.Configuration(
    schemaVersion: 3, // Set the new schema version.
    migrationBlock: { migration, oldSchemaVersion in
        if oldSchemaVersion < 2 {
            // Previous Migration.
            migration.enumerateObjects(ofType: Person.className()) { oldObject, newObject in
                let firstName = oldObject!["firstName"] as? String
                let lastName = oldObject!["lastName"] as? String
                newObject!["fullName"] = "\(firstName!) \(lastName!)"
            }
        }
        if oldSchemaVersion < 3 {
            // New Migration.
            migration.enumerateObjects(ofType: Person.className()) { oldObject, newObject in
                // Make age a String instead of an Int
                newObject!["age"] = "\(oldObject!["age"] ?? 0)"
            }
        }
    }
)

// Tell Realm to use this new configuration object for the default Realm
Realm.Configuration.defaultConfiguration = config

// Now that we've told Realm how to handle the schema change, opening the file
// will automatically perform the migration
let realm = try! Realm()

Tip:
Avoid nesting or otherwise skipping if (oldSchemaVersion < X) statements
in migration blocks. This ensures that all updates can be applied in the correct order,
no matter which schema version a client starts from. The goal is to define
migration logic which can transform data from any outdated schema version to
match the current schema.

Convert from Object to EmbeddedObject Copy Section

Embedded objects cannot exist
independently of a parent object. When changing an Object to an
EmbeddedObject, the migration block must ensure that every embedded
object has exactly one backlink to a parent object. Having no backlinks
or multiple backlinks raises the following exceptions:

At least one object does not have a backlink (data would get lost).

At least one object does have multiple backlinks.

Seealso:
Define an Embedded Object Property

Additional Migration Examples Copy Chapter

Please check out the additional migration examples on the
realm-swift repo.

Guides Model Data Model Data (`docs/guides/model-data/model-data.md`) Copy Section

Model Data - Swift SDK

Object Types & Schemas Copy Chapter

Realm applications model data as objects composed of
field-value pairs that each contain one or more supported data types.

Realm objects are regular Swift or Objective-C classes, but
they also bring a few additional features like live queries. The Swift SDK memory maps Realm objects directly to
native Swift or Objective-C objects, which means there's no need to use
a special data access library, such as an ORM. Instead, you can work with Realm objects
as you would any other class instance.

Every Realm object conforms to a specific object type, which is
essentially a class that defines the properties
and relationships for objects of that type.
Realm guarantees that all objects in a realm conform to
the schema for their object type and validates objects whenever they're
created, modified, or deleted.

Example:
The following schema defines a Dog object type with a string name,
optional string breed, date of birth, and primary key ID.

Objective-C

objectivec Copy

// A dog has an _id primary key, a string name, an optional
// string breed, and a date of birth.
@interface Dog : RLMObject
@property RLMObjectId *_id;
@property NSString *name;
@property NSString *breed;
@property NSDate *dateOfBirth;
@end

@implementation Dog
+ (NSString *)primaryKey {
    return @"_id";
}

+ (NSArray<NSString *> *)requiredProperties {
    return @[
        @"_id", @"name", @"dateOfBirth"
    ];
}
@end

Swift

swift Copy

// A dog has an _id primary key, a string name, an optional
// string breed, and a date of birth.
class Dog: Object {
    @Persisted(primaryKey: true) var _id: ObjectId
    @Persisted var name = ""
    @Persisted var breed: String?
    @Persisted var dateOfBirth = Date()
}

Realm Schema Copy Section

A realm schema is a list of valid object schemas that a realm may contain. Every Realm object must
conform to an object type that's included in its realm's schema.

By default, the Swift SDK automatically adds all classes in your project
that derive from RLMObject or
RLMEmbeddedObject to the
realm schema.

Tip:
To control which classes Realm adds to a realm schema, see
Provide a Subset of Classes to a Realm.

If a realm already contains data when you open it,
Realm validates each object to ensure that an object
schema was provided for its type and that it meets all of the
constraints specified in the schema.

Tip:
For code examples that show how to configure and open a realm in the
Swift SDK, see Configure & Open a Realm - Swift SDK.

Model Inheritance Copy Section

You can subclass Realm 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

Tip:
Check out the code samples for working
around these limitations.

Version added: 10.10.0While you can't mix and property declarations
within a class, you can mix the notation styles across base and subclasses.
For example, a base class could have a property,
and a subclass could have an property, with
both persisted. However, the property would be ignored if
the property were within the same base or subclass.

Swift Structs Copy Section

Realm 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:

• Live data
• Reactive APIs
• Low memory footprint of data
• Good operation performance
• Lazy and cheap access to partial data
• Lack of data serialization/deserialization
• Keeping potentially complex object graphs synchronized

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)

Properties Copy Chapter

Your Realm object model is a collection of properties. On the most basic level,
when you create your model, your declarations give Realm information about
each property:

• The data type and whether the property is optional or required
• Whether Realm should store or ignore the property
• Whether the property is a primary key or should be indexed

Properties are also the mechanism for establishing relationships between Realm object types.

The Realm Swift SDK uses reflection to determine the properties
in your models at runtime. Your project must not set
SWIFT_REFLECTION_METADATA_LEVEL = none, or Realm cannot discover
children of types, such as properties and enum cases. Reflection is enabled
by default if your project does not specifically set a level for this setting.

View Models with Realm Copy Chapter

Version added: 10.21.0

You can work with a subset of your Realm object's properties
by creating a class projection. A class projection is a class that passes
through or transforms some or all of your Realm object's
properties. Class projection enables you to build view models that use an
abstraction of your object model. This simplifies using and testing Realm objects
in your application.

With class projection, you can use a subset of your object's properties
directly in the UI or transform them. When you use a class projection for
this, you get all the benefits of Realm's live objects:

• The class-projected object live updates
• You can observe it for changes
• You can apply changes directly to the properties in write transactions

Seealso:
Define a Class Projection

Relationships Copy Chapter

Realm doesn't use bridge tables or explicit joins to define
relationships as you would in a relational database. Realm
handles relationships through embedded objects or reference properties to
other Realm objects. You read from and write to these
properties directly. This makes querying relationships as performant as
querying against any other property.

Realm supports to-one, to-many, and inverse
relationships.

To-One Relationship Copy Section

A to-one relationship means that an object relates to one other object.
You define a to-one relationship for an object type in its object
schema. Specify a property where the type is the related Realm
object type. For example, a dog might have a to-one relationship with
a favorite toy.

Tip:
To learn how to define a to-one relationship, see
Define a To-One Relationship Property.

To-Many Relationship Copy Section

A to-many relationship means that an object relates to more than one
other object. In Realm, a to-many relationship is a list of
references to other objects. For example, a person might have many dogs.

A List represents the to-many
relationship between two Realm
types. Lists are mutable: within a write transaction, you can add and
remove elements to and from a list. Lists are not associated with a
query and are usually declared as a property of an object model.

Tip:
To learn how to define a to-many relationship, see
Define a To-Many Relationship Property.

Inverse Relationship Copy Section

Relationship definitions in Realm are unidirectional. An
inverse relationship links an object back to an object that refers
to it. You must explicitly define a property in the object's model as an
inverse relationship. Inverse relationships can link back to objects in
a to-one or to-many relationship.

A LinkingObjects collection
represents the inverse relationship
between two Realm types. You cannot directly add or remove
items from a LinkingObjects collection.

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.

For example, consider a task tracker with the to-many relationship "User has
many Tasks". This does not automatically create the inverse relationship
"Task belongs to User". To create the inverse relationship, add a User
property on the Task that points back to the task's owner. When you specify
the inverse relationship from task to user, you can query on that. If you
don't specify the inverse relationship, you must run a separate query to
look up the user to whom the task is assigned.

Important:
You cannot manually set the value of an inverse relationship property.
Instead, Realm updates implicit relationships when you add
or remove an object in the relationship.

Relationships can be many-to-one or many-to-many. So following inverse
relationships can result in zero, one, or many objects.

Tip:
To learn how to define an inverse relationship, see
Define an Inverse Relationship Property.

Guides Model Data Object Models (`docs/guides/model-data/object-models.md`) Copy Section

Define a Realm Object Model - Swift SDK

Define a New Object Type Copy Chapter

Objective-C

You can define a Realm object by deriving from the
RLMObject or
RLMEmbeddedObject class. The name of the
class becomes the table name in the realm, and properties of the
class persist in the database. This makes it as easy to work with
persisted objects as it is to work with regular Objective-C
objects.

// A dog has an _id primary key, a string name, an optional
// string breed, and a date of birth.
@interface Dog : RLMObject
@property RLMObjectId *_id;
@property NSString *name;
@property NSString *breed;
@property NSDate *dateOfBirth;
@end

@implementation Dog
+ (NSString *)primaryKey {
    return @"_id";
}

+ (NSArray<NSString *> *)requiredProperties {
    return @[
        @"_id", @"name", @"dateOfBirth"
    ];
}
@end

Swift

You can define a Realm object by deriving from the
Object or
EmbeddedObject
class. The name of the class becomes the table name in the realm,
and properties of the class persist in the database. This makes it
as easy to work with persisted objects as it is to work with
regular Swift objects.

// A dog has an _id primary key, a string name, an optional
// string breed, and a date of birth.
class Dog: Object {
    @Persisted(primaryKey: true) var _id: ObjectId
    @Persisted var name = ""
    @Persisted var breed: String?
    @Persisted var dateOfBirth = Date()
}

Note:
Class names are limited to a maximum of 57 UTF-8 characters.

Declare Properties Copy Chapter

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. 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.

Persisted Property Attributes Copy Section

Version added: 10.10.0The declaration style replaces the ,
, and declaration notations from older
versions of the SDK. For an older version of the SDK, see:
.

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.

Seealso:
Our Supported Property Types
page contains a property declaration cheatsheet.

Objective-C Dynamic Property Attributes Copy Section

Version changed: 10.10.0This property declaration information is for versions of the SDK before
10.10.0.

Declare dynamic Realm 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.

Version changed: 10.8.0
RealmProperty replaces RealmOptional

Seealso:
Our Supported Property Types
page contains a property declaration cheatsheet.

Tip:
For reference on which types Realm supports for use as
properties, see Supported Property Types.

Swift

When declaring non-generic properties, use the @Persisted annotation.
The @Persisted attribute turns Realm model properties into accessors
for the underlying database data.

Objective-C

Declare properties on your object type as you would on a normal
Objective-C interface.

In order to use your interface in a Realm array, pass your
interface name to the RLM_COLLECTION_TYPE() macro. You can put this
at the bottom of your interface's header file. The
RLM_COLLECTION_TYPE() macro creates a protocol that allows you to
tag RLMArray with your type:

// Task.h
@interface Task : RLMObject
@property NSString *description;
@end

// Define an RLMArray<Task> type
RLM_COLLECTION_TYPE(Task)

// User.h
// #include "Task.h"
@interface User : RLMObject
@property NSString *name;
// Use RLMArray<Task> to have a list of tasks
// Note the required double tag (<Task *><Task>)
@property RLMArray<Task *><Task> *tasks;
@end

Swift Pre 10.10.0

When declaring non-generic properties, use the @objc dynamic var annotation. The @objc dynamic var attribute turns Realm
model properties into accessors for the underlying database data.
If the class is declared as @objcMembers (Swift 4 or later),
you can declare properties as dynamic var without @objc.

To declare properties of generic types LinkingObjects,
List, and RealmProperty, use let. Generic properties
cannot be represented in the Objective‑C runtime, which
Realm uses for dynamic dispatch of dynamic
properties.

Note:
Property names are limited to a maximum of 63 UTF-8 characters.

Specify an Optional/Required Property Copy Section

Swift

You can declare properties as optional or required (non-optional) using
standard Swift syntax.

class Person: Object {
    // Required string property
    @Persisted var name = ""

    // Optional string property
    @Persisted var address: String?

    // Required numeric property
    @Persisted var ageYears = 0

    // Optional numeric property
    @Persisted var heightCm: Float?
}

Objective-C

To declare a given property as required, implement the
requiredProperties
method and return an array of required property names.

@interface Person : RLMObject
// Required property - included in `requiredProperties`
// return value array
@property NSString *name;

// Optional string property - not included in `requiredProperties`
@property NSString *address;

// Required numeric property
@property int ageYears;

// Optional numeric properties use NSNumber tagged
// with RLMInt, RLMFloat, etc.
@property NSNumber<RLMFloat> *heightCm;
@end

@implementation Person
// Specify required pointer-type properties here.
// Implicitly required properties (such as properties
// of primitive types) do not need to be named here.
+ (NSArray<NSString *> *)requiredProperties {
    return @[@"name"];
}
@end

Swift Pre 10.10.0

Version changed: 10.8.0
RealmProperty replaces RealmOptional

You can declare String, Date, Data, and
ObjectId properties as
optional or required (non-optional) using standard Swift syntax.
Declare optional numeric types using the RealmProperty
type.

class Person: Object {
    // Required string property
    @objc dynamic var name = ""

    // Optional string property
    @objc dynamic var address: String?

    // Required numeric property
    @objc dynamic var ageYears = 0

    // Optional numeric property
    let heightCm = RealmProperty<Float?>()
}

RealmProperty supports Int, Float, Double, Bool,
and all of the sized versions of Int (Int8, Int16,
Int32, Int64).

Specify a Primary Key Copy Section

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 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.

Swift

Declare the property with primaryKey: true
on the @Persisted notation to set the model's primary key.

class Project: Object {
    @Persisted(primaryKey: true) var id = 0
    @Persisted var name = ""
}

Objective-C

Override +[RLMObject primaryKey] to
set the model's primary key.

@interface Project : RLMObject
@property NSInteger id; // Intended primary key
@property NSString *name;
@end

@implementation Project
// Return the name of the primary key property
+ (NSString *)primaryKey {
    return @"id";
}
@end

Swift Pre 10.10.0

Override Object.primaryKey()
to set the model's primary key.

class Project: Object {
    @objc dynamic var id = 0
    @objc dynamic var name = ""

    // Return the name of the primary key property
    override static func primaryKey() -> String? {
        return "id"
    }
}

Index a Property Copy Section

You can create an index on a given property of your model. Indexes speed up
queries using equality and IN operators. They make insert and update operation
speed slightly slower. Indexes use memory and take up more space in the realm
file. Each index entry is a minimum of 12 bytes. It's best to only add indexes
when optimizing the read performance for specific situations.

Realm supports indexing for string, integer, boolean, Date, UUID,
ObjectId, and AnyRealmValue properties.

Version added: 10.8.0
UUID and AnyRealmValue types

Swift

To index a property, declare the property with
indexed:true
on the @Persisted notation.

class Book: Object {
    @Persisted var priceCents = 0
    @Persisted(indexed: true) var title = ""
}

Objective-C

To index a property, override RLMObject indexedProperties
and return a list of indexed property names.

@interface Book : RLMObject
@property int priceCents;
@property NSString *title;
@end

@implementation Book
// Return a list of indexed property names
+ (NSArray *)indexedProperties {
    return @[@"title"];
}
@end

Swift Pre 10.10.0

To index a property, override
Object.indexedProperties()
and return a list of indexed property names.

class Book: Object {
    @objc dynamic var priceCents = 0
    @objc dynamic var title = ""

    // Return a list of indexed property names
    override static func indexedProperties() -> [String] {
        return ["title"]
    }
}

Ignore a Property Copy Section

Ignored properties behave exactly like normal properties. They can't be
used in queries and won't trigger Realm notifications. You can still
observe them using KVO.

Tip:
Realm automatically ignores read-only properties.

Swift

Deprecated:

If you don't want to save a field in your model to its realm,
leave the @Persisted notation off the property attribute.

Additionally, if you mix @Persisted and @objc dynamic
property declarations within a class, the @objc dynamic
properties will be ignored.

class Person: Object {
    // If some properties are marked as @Persisted,
    // any properties that do not have the @Persisted
    // annotation are automatically ignored.
    var tmpId = 0

    // The @Persisted properties are managed
    @Persisted var firstName = ""
    @Persisted var lastName = ""

    // Read-only properties are automatically ignored
    var name: String {
        return "\(firstName) \(lastName)"
    }

    // If you mix the pre-10.10 property declaration
    // syntax `@objc dynamic` with the 10.10+ @Persisted
    // annotation within a class, `@objc dynamic`
    // properties are ignored.
    @objc dynamic var email = ""
}

Objective-C

If you don't want to save a field in your model to its realm,
override +[RLMObject ignoredProperties]
and return a list of ignored property names.

@interface Person : RLMObject
@property NSInteger tmpId;
@property (readonly) NSString *name; // read-only properties are automatically ignored
@property NSString *firstName;
@property NSString *lastName;
@end

@implementation Person
+ (NSArray *)ignoredProperties {
    return @[@"tmpId"];
}
- (NSString *)name {
    return [NSString stringWithFormat:@"%@ %@", self.firstName, self.lastName];
}
@end

Swift Pre 10.10.0

If you don't want to save a field in your model to its realm,
override Object.ignoredProperties()
and return a list of ignored property names.

class Person: Object {
    @objc dynamic var tmpId = 0
    @objc dynamic var firstName = ""
    @objc dynamic var lastName = ""

    // Read-only properties are automatically ignored
    var name: String {
        return "\(firstName) \(lastName)"
    }

    // Return a list of ignored property names
    override static func ignoredProperties() -> [String] {
        return ["tmpId"]
    }
}

Declare Enum Properties Copy Section

Swift

Version changed: 10.10.0
Protocol is now PersistableEnum rather than RealmEnum.

You can use enums with @Persisted by marking them as complying with the
PersistableEnum
protocol. A PersistableEnum can be any RawRepresentable enum
whose raw type is a type that Realm supports.

// Define the enum
enum TaskStatusEnum: String, PersistableEnum {
    case notStarted
    case inProgress
    case complete
}

// To use the enum:
class Task: Object {
    @Persisted var name: String = ""
    @Persisted var owner: String?

    // Required enum property
    @Persisted var status = TaskStatusEnum.notStarted

    // Optional enum property
    @Persisted var optionalTaskStatusEnumProperty: TaskStatusEnum?
}

Swift Pre 10.10.0

Realm supports only Int-backed @objc enums.

// Define the enum
@objc enum TaskStatusEnum: Int, RealmEnum {
    case notStarted = 1
    case inProgress = 2
    case complete = 3
}

// To use the enum:
class Task: Object {
    @objc dynamic var name: String = ""
    @objc dynamic var owner: String?

    // Required enum property
    @objc dynamic var status = TaskStatusEnum.notStarted
    // Optional enum property
    let optionalTaskStatusEnumProperty = RealmProperty<TaskStatusEnum?>()
}

Seealso:
RealmEnum

Remap a Property Name Copy Section

Version added: 10.33.0

You can map the public name of a property in your object model to a different
private name to store in the realm.

Declare the name you want to use in your project as the @Persisted
property on the object model. Then, pass a dictionary containing the
public and private values for the property names via the
propertiesMapping() function.

In this example, firstName is the public property name we use in the code
throughout the project to perform CRUD operations. Using the propertiesMapping()
function, we map that to store values using the private property name
first_name in the realm.

class Person: Object {
    @Persisted var firstName = ""
    @Persisted var lastName = ""

    override class public func propertiesMapping() -> [String: String] {
        ["firstName": "first_name",
         "lastName": "last_name"]
    }
}

Define a Class Projection Copy Chapter

About These Examples Copy Section

The examples in this section use a simple data set. The two Realm object
types are Person and an embedded object Address. A Person has
a first and last name, an optional Address, and a list of friends
consisting of other Person objects. An Address has a city and country.

See the schema for these two classes, Person and Address, below:

class Person: Object {
    @Persisted var firstName = ""
    @Persisted var lastName = ""
    @Persisted var address: Address?
    @Persisted var friends = List<Person>()
}

class Address: EmbeddedObject {
    @Persisted var city: String = ""
    @Persisted var country = ""
}

How to Define a Class Projection Copy Section

Version added: 10.21.0

Define a class projection by creating a class of type Projection. Specify the Object
or EmbeddedObject base whose
properties you want to use in the class projection. Use the @Projected
property wrapper to declare a property that you want to project from a
@Persisted property on the base object.

Note:
When you use a List or a MutableSet in a class projection, the type in the
class projection should be ProjectedCollection.

class PersonProjection: Projection<Person> {
    @Projected(\Person.firstName) var firstName // Passthrough from original object
    @Projected(\Person.address?.city) var homeCity // Rename and access embedded object property through keypath
    @Projected(\Person.friends.projectTo.firstName) var firstFriendsName: ProjectedCollection<String> // Collection mapping
}

When you define a class projection, you can transform the original @Persisted
property in several ways:

• Passthrough: the property is the same name and type as the original object
• Rename: the property has the same type as the original object, but a
  different name
• Keypath resolution: use keypath resolution to access properties of the
  original object, including embedded object properties
• Collection mapping: Project lists or
  mutable sets of Object s or
  EmbeddedObject s as a collection of primitive values
• Exclusion: when you use a class projection, the underlying object's
  properties that are not @Projected through the class projection are
  excluded. This enables you to watch for changes to a class projection
  and not see changes for properties that are not part of the class
  projection.

Define Unstructured Data Copy Chapter

Version added: 10.51.0

Starting in SDK version 10.51.0, you can store collections of mixed data
within a AnyRealmValue property. You can use this feature to model complex data
structures, such as JSON, without having to define a
strict data model.

Unstructured data is data that doesn't easily conform to an expected
schema, making it difficult or impractical to model to individual
data classes. For example, your app might have highly variable data or dynamic
data whose structure is unknown at runtime.

Storing collections in a mixed property offers flexibility without sacrificing
functionality. And
you can work with them the same way you would a non-mixed
collection:

• You can nest mixed collections up to 100 levels.
• You can query on and react to changes on mixed collections.
• You can find and update individual mixed collection elements.

However, storing data in mixed collections is less performant than using a structured
schema or serializing JSON blobs into a single string property.

To model unstructured data in your app, define the appropriate properties in
your schema as AnyRealmValue types. You can then
set these AnyRealmValue properties as a list or a
dictionary collection of AnyRealmValue elements.
Note that AnyRealmValue cannot represent a MutableSet or an embedded
object.

Tip:

• Use a map of mixed data types when the type is unknown but each value will have a unique identifier.
• Use a list of mixed data types when the type is unknown but the order of
  objects is meaningful.

Guides Model Data Relationships (`docs/guides/model-data/relationships.md`) Copy Section

Model Relationships - Swift SDK

Declare Relationship Properties Copy Chapter

Define a To-One Relationship Property Copy Section

A to-one relationship maps one property to a single instance of
another object type. For example, you can model a person having at most
one companion dog as a to-one relationship.

Setting a relationship field to null removes the connection between objects.
Realm does not delete the referenced object, though, unless it is
an embedded object.

Important:
When you declare a to-one relationship in your object model, it must
be an optional property. If you try to make a to-one relationship
required, Realm throws an exception at runtime.

Objective-C

// Dog.h
@interface Dog : RLMObject
@property NSString *name;
// No backlink to person -- one-directional relationship
@end

// Define an RLMArray<Dog> type
RLM_COLLECTION_TYPE(Dog)

// Person.h
@interface Person : RLMObject
@property NSString *name;
// A person can have one dog
@property Dog *dog;
@end

// Dog.m
@implementation Dog
@end

// Person.m
@implementation Person
@end

Swift

class Person: Object {
    @Persisted var name: String = ""
    @Persisted var birthdate: Date = Date(timeIntervalSince1970: 1)

    // A person can have one dog
    @Persisted var dog: Dog?
}

class Dog: Object {
    @Persisted var name: String = ""
    @Persisted var age: Int = 0
    @Persisted var breed: String?
    // No backlink to person -- one-directional relationship
}

Seealso:
For more information about to-one relationships, see:
To-One Relationship.

Define a To-Many Relationship Property Copy Section

A to-many relationship maps one property to zero or more instances
of another object type. For example, you can model a person having any
number of companion dogs as a to-many relationship.

Objective-C

Use RLMArray tagged with your
target type to define your to-many relationship property.

Tip:
Remember to use the RLM_COLLECTION_TYPE() macro with your type
to declare the RLMArray protocol for your type.

// Dog.h
@interface Dog : RLMObject
@property NSString *name;
// No backlink to person -- one-directional relationship
@end

// Define an RLMArray<Dog> type
RLM_COLLECTION_TYPE(Dog)

// Person.h
@interface Person : RLMObject
@property NSString *name;
// A person can have many dogs
@property RLMArray<Dog *><Dog> *dogs;
@end

// Dog.m
@implementation Dog
@end

// Person.m
@implementation Person
@end

Swift

Use List tagged with your target
type to define your to-many relationship property.

class Person: Object {
    @Persisted var name: String = ""
    @Persisted var birthdate: Date = Date(timeIntervalSince1970: 1)

    // A person can have many dogs
    @Persisted var dogs: List<Dog>
}

class Dog: Object {
    @Persisted var name: String = ""
    @Persisted var age: Int = 0
    @Persisted var breed: String?
    // No backlink to person -- one-directional relationship
}

Seealso:
For more information about to-many relationships, see:
To-Many Relationship.

Define an Inverse Relationship Property Copy Section

An inverse relationship property is an automatic backlink
relationship. Realm automatically updates implicit
relationships whenever an object is added or removed in a corresponding
to-many list or to-one relationship property. You cannot manually set
the value of an inverse relationship property.

Swift

To define an inverse relationship, use LinkingObjects in your object model. The
LinkingObjects definition specifies the object type and
property name of the relationship that it inverts.

class User: Object {
    @Persisted(primaryKey: true) var _id: ObjectId
    @Persisted var _partition: String = ""
    @Persisted var name: String = ""

    // A user can have many tasks.
    @Persisted var tasks: List<Task>
}

class Task: Object {
    @Persisted(primaryKey: true) var _id: ObjectId
    @Persisted var _partition: String = ""
    @Persisted var text: String = ""

    // Backlink to the user. This is automatically updated whenever
    // this task is added to or removed from a user's task list.
    @Persisted(originProperty: "tasks") var assignee: LinkingObjects<User>
}

Objective-C

To define an inverse relationship, use
RLMLinkingObjects in your object model.
Override +[RLMObject linkingObjectProperties]
method in your class to specify the object type and property name
of the relationship that it inverts.

// Task.h
@interface Task : RLMObject
@property NSString *description;
@property (readonly) RLMLinkingObjects *assignees;
@end

// Define an RLMArray<Task> type
RLM_COLLECTION_TYPE(Task)

// User.h
@interface User : RLMObject
@property NSString *name;
@property RLMArray<Task *><Task> *tasks;
@end

// Task.m
@implementation Task
+ (NSDictionary *)linkingObjectsProperties {
    return @{
        @"assignees": [RLMPropertyDescriptor descriptorWithClass:User.class propertyName:@"tasks"],
    };
}
@end

// User.m
@implementation User
@end

Swift Pre 10.10.0

To define an inverse relationship, use LinkingObjects
in your object model. The LinkingObjects definition specifies
the object type and property name of the relationship that it inverts.

class User: Object {
    @objc dynamic var _id: ObjectId = ObjectId.generate()
    @objc dynamic var _partition: String = ""
    @objc dynamic var name: String = ""

    // A user can have many tasks.
    let tasks = List<Task>()

    override static func primaryKey() -> String? {
        return "_id"
    }
}

class Task: Object {
    @objc dynamic var _id: ObjectId = ObjectId.generate()
    @objc dynamic var _partition: String = ""
    @objc dynamic var text: String = ""

    // Backlink to the user. This is automatically updated whenever
    // this task is added to or removed from a user's task list.
    let assignee = LinkingObjects(fromType: User.self, property: "tasks")

    override static func primaryKey() -> String? {
        return "_id"
    }
}

Seealso:
For more information about inverse relationships, see:
Inverse Relationship.

Define an Embedded Object Property Copy Section

An embedded object exists as nested data inside of a single,
specific parent object. It inherits the lifecycle of its parent object
and cannot exist as an independent Realm object. Realm automatically
deletes embedded objects if their parent object is deleted or when
overwritten by a new embedded object instance.

Note:
When you delete a Realm object, any embedded objects referenced by
that object are deleted with it. If you want the referenced objects
to persist after the deletion of the parent object, your type should
not be an embedded object at all. Use a regular Realm object with a to-one relationship instead.

Objective-C

You can define an embedded object by deriving from the
RLMEmbeddedObject class. You can use your
embedded object in another model as you would any other type.

// Define an embedded object
@interface Address : RLMEmbeddedObject
@property NSString *street;
@property NSString *city;
@property NSString *country;
@property NSString *postalCode;
@end

// Enable Address for use in RLMArray
RLM_COLLECTION_TYPE(Address)

@implementation Address
@end

// Define an object with one embedded object
@interface Contact : RLMObject
@property NSString *name;

// Embed a single object.
@property Address *address;
@end

@implementation Contact
@end

// Define an object with an array of embedded objects
@interface Business : RLMObject
@property NSString *name;
// Embed an array of objects
@property RLMArray<Address *><Address> *addresses;
@end

Swift

You can define an embedded object by deriving from the
EmbeddedObject
class. You can use your embedded object in another model as you
would any other type.

class Person: Object {
    @Persisted(primaryKey: true) var id = 0
    @Persisted var name = ""

    // To-many relationship - a person can have many dogs
    @Persisted var dogs: List<Dog>

    // Inverse relationship - a person can be a member of many clubs
    @Persisted(originProperty: "members") var clubs: LinkingObjects<DogClub>

    // Embed a single object.
    // Embedded object properties must be marked optional.
    @Persisted var address: Address?

    convenience init(name: String, address: Address) {
        self.init()
        self.name = name
        self.address = address
    }
}

class DogClub: Object {
    @Persisted var name = ""
    @Persisted var members: List<Person>

    // DogClub has an array of regional office addresses.
    // These are embedded objects.
    @Persisted var regionalOfficeAddresses: List<Address>

    convenience init(name: String, addresses: [Address]) {
        self.init()
        self.name = name
        self.regionalOfficeAddresses.append(objectsIn: addresses)
    }
}

class Address: EmbeddedObject {
    @Persisted var street: String?
    @Persisted var city: String?
    @Persisted var country: String?
    @Persisted var postalCode: String?
}

Guides Model Data Supported Types (`docs/guides/model-data/supported-types.md`) Copy Section

Supported Types - Swift SDK

Collection Types Copy Chapter

Realm has several types to represent groups of objects,
which we call collections. A collection is an object that contains
zero or more instances of one Realm type. Realm collections are homogenous:
all objects in a collection are of the same type.

You can filter and sort any collection using Realm's
query engine. Collections are
live, so they always reflect the current state
of the realm instance on the current thread. You can also
listen for changes in the collection by subscribing to collection
notifications.

All collection types conform to the RealmCollection protocol. This protocol inherits from
CollectionType, so you can use
a Realm collection as you would any other standard library
collections.

Using the RealmCollection protocol, you can write generic code that can
operate on any Realm collection:

func operateOn<C: RealmCollection>(collection: C) {
    // Collection could be either Results or List
    print("operating on collection containing \(collection.count) objects")
}

Results and Sectioned Results Copy Section

The Swift SDK Results collection is
a class representing objects retrieved from queries. A
[Results collection represents the
lazily-evaluated results of a query operation. Results are immutable:
you cannot add or remove elements to or from the results collection.
Results have an associated query that determines their contents.

The Swift SDK also provides SectionedResults,
a type-safe collection which holds ResultsSection as its elements.
Each ResultSection is a results
collection that contains only objects that belong to a given section key.

For example, an app that includes a contact list might use SectionedResults
to display a list of contacts divided into sections, where each section
contains all the contacts whose first name starts with the given letter.
The ResultsSection whose key is "L" would contain "Larry", "Liam",
and "Lisa".

Seealso:
Reads

Collections as Properties Copy Section

The Swift SDK also offers several collection types you can use as properties
in your data model:

1. List, a class representing
   to-many relationships in models.
2. LinkingObjects, a class
   representing inverse relationships in models.
3. MutableSet, a class representing
   a to-many relationship.
4. Map, a class representing an associative array of key-value
   pairs with unique keys.
5. AnyRealmCollection, a type-erased class that can forward calls to a concrete Realm collection like Results, List or LinkingObjects.

Collections are Live Copy Section

Like live objects, Realm collections
are usually live:

• Live results collections always reflect the current results of the associated query.
• Live lists always reflect the current state of the relationship on the realm instance.

There are two cases when a collection is not live:

• The collection is unmanaged. For example, a List property of
  a Realm object that has not been added to a realm yet
  or that has been copied from a realm is not live.
• The collection is frozen.

Combined with collection notifications, live collections enable
clean, reactive code. For example, suppose your view displays the
results of a query. You can keep a reference to the results collection
in your view class, then read the results collection as needed without
having to refresh it or validate that it is up-to-date.

Important:
Since results update themselves automatically, do not
store the positional index of an object in the collection
or the count of objects in a collection. The stored index
or count value could be outdated by the time you use
it.

Supported Property Types Copy Chapter

You can use the following types to define your object model
properties.

Property Cheat Sheet Copy Section

Swift

Version changed: 10.10.0
@Persisted property declaration syntax

CGFloat properties are discouraged, as the type is not
platform independent.

To use Key-Value Coding with a user-defined object in the @Persisted
syntax, add the @objc attribute: @Persisted @objc var myObject: MyClass?

Setting Default Values

With the @Persisted property declaration syntax, you may see a
performance impact when setting default values for:

• List
• MutableSet
• Dictionary
• Decimal128
• UUID
• ObjectId

@Persisted var listProperty: List and @Persisted var listProperty = List() are both valid, and are functionally
equivalent. However, the second declaration will result in poorer
performance.

This is because the List is created when the parent object is
created, rather than lazily as needed. For most types, this is
a difference so small you can't measure it. For the types listed
here, you may see a performance impact when using the second
declaration style.

Objective-C

Additionally:

• Integral types int, NSInteger, long, long long

CGFloat properties are discouraged, as the type is not
platform independent.

Swift Pre 10.10.0

Version changed: 10.8.0
RealmProperty replaces RealmOptional

Additionally:

• EmbeddedObject-derived types
• Enum

You can use RealmProperty <T?> to
represent integers, doubles, and other types as optional.

CGFloat properties are discouraged, as the type is not
platform independent.

Unique Identifiers Copy Section

Version added: 10.8.0
UUID type

ObjectId is a 12-byte unique value. UUID is a
16-byte globally-unique value. You can index
both types, and use either as a primary key.

Note:
When declaring default values for @Persisted UUID or ObjectId property
attributes, both of these syntax types are valid:

• @Persisted var value: UUID
• @Persisted var value = UUID()

However, the second will result in poorer performance. This is because the
latter creates a new identifier that is never used any time an object is
read from the realm, while the former only creates them when needed.

@Persisted var id: ObjectId has equivalent behavior to @objc dynamic var _id = ObjectId.generate(). They both make random ObjectIds.

@Persisted var _id = ObjectId() has equivalent behavior to @objc dynamic var _id = ObjectId(). They both make zero-initialized ObjectIds.

Size Limitations Copy Section

Data and string properties cannot hold more than 16MB. To store
larger amounts of data, either:

• Break the data into 16MB chunks, or
• Store data directly on the file system and store paths to the files in the realm.

Realm throws a runtime exception if your app attempts to
store more than 16MB in a single property.

To avoid size limitations and a performance impact, it is best not to
store large blobs, such as image and video files, directly in a
realm. Instead, save the file to a file store and keep only the
location of the file and any relevant metadata in the realm.

AnyRealmCollection Copy Section

To store a collection as a property or variable without needing to know
the concrete collection type, Swift's type system requires a type-erased
wrapper like AnyRealmCollection:

class ViewController {
//    let collection: RealmCollection
//                    ^
//                    error: protocol 'RealmCollection' can only be used
//                    as a generic constraint because it has Self or
//                    associated type requirements
//
//    init<C: RealmCollection>(collection: C) where C.ElementType == MyModel {
//        self.collection = collection
//    }

    let collection: AnyRealmCollection<MyModel>

    init<C: RealmCollection & _ObjcBridgeable>(collection: C) where C.ElementType == MyModel {
        self.collection = AnyRealmCollection(collection)
    }
}

Mutable Set Copy Section

Version added: 10.8.0

A MutableSet
collection represents a to-many relationship
containing distinct values. A MutableSet supports the following types
(and their optional versions):

• Bool
• Data
• Date
• Decimal128
• Double
• Float
• Int
• Int8
• Int16
• Int32
• Int64
• Object
• ObjectId
• String
• UUID