Docs Home → Realm

CRUD - Create - Swift SDK

On this page

Create a New Object

About The Examples On This Page
Create an Object
Initialize Objects with a Value
Create an Object with JSON
Create an Embedded Object
Create an Object with a Map Property
Create an Object with a MutableSet Property
Create an Object with an AnyRealmValue Property
Create an Object Asynchronously
Create an Asymmetric Object
Copy an Object to Another Realm

Realm is now Atlas Device SDK – Learn More

Create a New Object

About The Examples On This Page

The examples on this page use the following models:

Create an Object

Initialize Objects with a Value

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.

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

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

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:).

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

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

Create an Object with a Map Property

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"] = "Wiggly 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

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

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

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.

Create an Asymmetric Object

New in version 10.29.0.

You can only create an AsymmetricObject using create(_ type:, value:). When you create an AsymmetricObject, it syncs unidirectionally via Data Ingest to the Atlas database linked to your Atlas App Services App. You cannot access an AsymmetricObject locally, add it to or remove it from a realm, or query for it.

@MainActor
func useRealm(_ asymmetricRealm: Realm, _ user: User) async {
    try! asymmetricRealm.write {
        asymmetricRealm.create(WeatherSensor.self,
                               value: [ "_id": ObjectId.generate(),
                                        "deviceId": "WX1278UIT",
                                        "temperatureInFahrenheit": 66.7,
                                        "barometricPressureInHg": 29.65,
                                        "windSpeedInMph": 2
                                        ])
    }
}

You can create AsymmetricObjects for a realm initialized with a Flexible Sync configuration. For more information, see: Open a Synced Realm for Flexible Sync.

Copy an Object to Another Realm

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.

← CRUD - Swift SDK CRUD - Read - Swift SDK →