SwiftData on Andrew Bancroft

Pre-populate a SwiftData Persistent Store

Thu, 15 Jun 2023 00:00:00 +0000

Building Blocks

These three building blocks will get you there:

A ModelContainer instance
One or more instances of your @Model class(es)
Inserting those model instances into your ModelContainer’s mainContext

Let’s take those building blocks one at a time.

Initialize a `ModelContainer`

Suppose that you’ve got a SwiftData model called Item that looks something like this:

@Model
final class Item {
    var timestamp: Date
    
    init(timestamp: Date) {
        self.timestamp = timestamp
    }
}

To pre-populate your SwiftData persistent store with instances of Item, you need to initialize a ModelContainer. A ModelContainer manages everything about where SwiftData will store instances of your Item class.

This code will initialize a ModelContainer that tells SwiftData to persist instances of Item to permanent storage:

do {
    let container = try ModelContainer(
        for: Item.self)
		//...more code to come
} catch {
    fatalError("Failed to create container")
}

If you’d like SwiftData to persist instances of Item in memory instead, this code will do it:

do {
    let container = try ModelContainer(
        for: Item.self, ModelConfiguration(inMemory: true)
    )
		//...more code to come
} catch {
    fatalError("Failed to create container")
}

A ModelContainer with an in-memory ModelConfiguration will not retain any Item instances that you save whenever someone re-launches your app. That being the case, using an in-memory ModelConfiguration is more suited for unit testing, or for supplying data to your Xcode previews.

Initialize instances of your `@Model` class(es)

Once you configure a ModelContainer, you need some instances of your @Model class to insert into the SwiftData persistent store.

If you just need a few instances to seed your persistent store with, you can initialize them manually like this:

let items = [
    Item(timestamp: Date()),
    Item(timestamp: Date()),
	Item(timestamp: Date())
]

If you need more than a few instances, you may opt to decode instances of your @Model class from something like a CSV file, a JSON file, or a property list that you include with your application’s main bundle.

Insert those model instances into your `ModelContainer`’s `mainContext`

The last step is to insert those instances of your model into your ModelContainer’s mainContext.

This code loops over an array of Item instances and inserts them into your SwiftData persistent store:

1
2
3

for item in items {
    container.mainContext.insert(object: item)
}

Where do you write all this code?

You may be reading the building block code above and think, “Wait…where do I write all this code?”

The answer depends on what you’re trying to do.

Are you trying to pre-populate your SwiftData persistent store for your production app?
Are you trying to pre-populate the persistent store for an Xcode preview?
Are you trying to pre-populate it for your unit tests?

For your production app

In this scenario, you can create a new Swift file to put your code in. A name like SwiftDataAppContainer could work just fine. It’s also fine to add the code to your “AppName”App.swift file where you initialize your SwiftUI App instance.

ModelContainer’s initializer can throw, but you can’t just write a do-catch statement globally. You may consider wrapping the container creation code in a closure, and running that closure immediately by adding () to the end of the closure expression:

@MainActor
let appContainer: ModelContainer = {
    do {
        let container = try ModelContainer(for: Item.self)
        //...
				return container // this line wasn't in any of the examples above
    } catch {
        fatalError("Failed to create container")
    }
}() // The "()" here runs the closure immediately

You need to annotate the appContainer declaration with the @MainActor attribute because container’s mainContext is annotated with the @MainActor attribute. You’ll get a compiler error like this if you don’t:

Main actor-isolated property ‘mainContext’ can not be referenced from a non-isolated context

Once you add @MainActor to the appContainer, you’re likely to see a warning if you’re using Swift 5.9:

Stored property ‘sharedModelContainer’ within struct cannot have a global actor; this is an error in Swift 6

To silence this warning and prepare your app for Swift 6, you can move where you add @MainActor from the appContainer to the App declaration:

@main
@MainActor
struct TrySwiftDataApp: App {    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Now you can modify your SwiftUI view, or one of your app instance’s WindowGroups to have a model container:

@main
@MainActor
struct TrySwiftDataApp: App {    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .modelContainer(appContainer)
    }
}

Pre-populating your SwiftData persistent store for an app that you plan to publish to the App Store comes with a special consideration: You’ve got to handle the case where someone has already launched your app and the data store pre-population code has already done its work.

In other words, you probably only want to pre-populate your persistent store on “first launch”.

To prevent the persistent store from being pre-populated over and over again, do a check to make sure the store is empty before you start inserting model instances into the mainContext:

// Make sure the persistent store is empty. If it's not, return the non-empty container.
var itemFetchDescriptor = FetchDescriptor<Item>()
itemFetchDescriptor.fetchLimit = 1

guard try container.mainContext.fetch(itemFetchDescriptor).count == 0 else { return container }

You can keep things efficient by setting the FetchDescriptor instance’s fetchLimit to 1. In other words, you don’t need to fetch every Item instance from the persistent store to decide whether the store is empty or not.

As long as the count of items that fetch returns is 0, you can rest assured that the persistent store is empty and pre-populate it. If that’s not the case, the guard’s else branch will run and return the non-empty ModelContainer instance.

Here’s the full code example with that check included:

@MainActor
let appContainer: ModelContainer = {
    do {
        let container = try ModelContainer(for: Item.self)
        
        // Make sure the persistent store is empty. If it's not, return the non-empty container.
        var itemFetchDescriptor = FetchDescriptor<Item>()
        itemFetchDescriptor.fetchLimit = 1
        
        guard try container.mainContext.fetch(itemFetchDescriptor).count == 0 else { return container }
        
        // This code will only run if the persistent store is empty.
        let items = [
            Item(timestamp: Date()),
            Item(timestamp: Date()),
            Item(timestamp: Date())
        ]
        
        for item in items {
            container.mainContext.insert(object: item)
        }
        
        return container
    } catch {
        fatalError("Failed to create container")
    }
}()

For an Xcode preview

If you’re trying to pre-populate a SwiftData persistent store for an Xcode preview of your SwiftUI view, you can create a new Swift file to put your code in and name it something like SwiftDataPreviewContainer.

In this file, you can write code that’s similar to the code you’d write for your production app but with a couple of changes:

You don’t need to check for an empty store, because
You’re going to initialize the ModelContainer with an in-memory store

Here’s the full code example of what the preview container could look like:

@MainActor
let previewContainer: ModelContainer = {
    do {
        let container = try ModelContainer(
            for: Item.self, ModelConfiguration(inMemory: true)
        )
        
        let items = [
            Item(timestamp: Date()),
            Item(timestamp: Date()),
            Item(timestamp: Date())
        ]
        
        for item in items {
            container.mainContext.insert(object: item)
        }
        
        return container
    } catch {
        fatalError("Failed to create container")
    }
}()

Then you can (in theory) use the new #Preview macro if you’re using Xcode 15 or above:

#Preview {
    ContentView()
        .modelContainer(previewContainer)
}

I wrote, “in theory” because there’s a bug (as of June 14, 2023) with Xcode that causes the preview to crash when you use this macro.

As a workaround — or if you’re not using Xcode 15 — you can embed this model creation code inside of a custom PreviewProvider type:

struct ContentView_Previews: PreviewProvider {
    static let previewContainer: ModelContainer = {
        do {
            let container = try ModelContainer(
                for: Item.self, ModelConfiguration(inMemory: true)
            )
            
            let items = [
                Item(timestamp: Date()),
                Item(timestamp: Date()),
                Item(timestamp: Date())
            ]
            
            for item in items {
                container.mainContext.insert(object: item)
            }
            
            return container
        } catch {
            fatalError("Failed to create container")
        }
    }()
    
    static var previews: some View {
        ContentView()
            .modelContainer(previewContainer)
    }
}

For your unit tests

Pre-populating your SwiftData persistent store for your unit tests is similar to doing so for your Xcode previews, in that (depending on what you’re testing), you probably don’t need to check for an empty persistent store before pre-populating it, and you’ll likely benefit from using an in-memory store.

Here’s what you need to do:

Mark your XCTestCase class as a @MainActor:

1
2

@MainActor
final class TrySwiftDataTests: XCTestCase { ... }

Add a stored property to your XCTestCase that will hold your ModelContainer:

`1`	`var testContainer: ModelContainer?`

Set the testContainer property inside the setUpWithError function:

override func setUpWithError() throws {
// Put setup code here. This method is called before the invocation of each test method in the class.

    self.testContainer = {
        do {
            let container = try ModelContainer(
                for: Item.self, ModelConfiguration(inMemory: true)
            )
            
            let items = [
                Item(timestamp: Date()),
                Item(timestamp: Date()),
                Item(timestamp: Date())
            ]
            
            for item in items {
                container.mainContext.insert(object: item)
            }
            
            return container
        } catch {
            fatalError("Failed to create container")
        }
    }()
}

Use the testContainer in any tests that need it:

func testExample() throws {        
    let fetchDescriptor = FetchDescriptor<Item>()
    
    let result = try testContainer?.mainContext.fetch(fetchDescriptor)
    
    XCTAssertEqual(result?.count, 3)
}

Add SwiftData to an Existing App

Thu, 08 Jun 2023 00:00:00 +0000

System Configuration

First things first: you need the following before you can get started with SwiftData…

You need to install Xcode 15 on your Mac.
You need to set your app’s minimum deployment target to macOS 14, iOS 17, tvOS 17, or watchOS 10.
Your app needs to use SwiftUI – SwiftData does not work with Storyboard apps. If you have a Storyboard app with some SwiftUI views integrated in, you can use SwiftData with those SwiftUI views. In that situation, it may be best to stick with Core Data to keep data persistence simple and consistent.

Essential Pieces of SwiftData

Once you configure your Mac, you need to understand these essential pieces of SwiftData:

The SwiftData import (import SwiftData)
The @Model macro
The .modelContainer() View modifier
The @Query property wrapper
The @Environment(\.modelContext) property wrapper

Import SwiftData

Before you can use SwiftData in a Swift file, you must write import SwiftData at the top of that file.

The `@Model` macro

Persisting data starts with defining a data model.

This model needs to be a Swift class.

Whenever you start a brand new Xcode project and select the option to use SwiftData for the storage of your app’s data, Xcode automatically includes an Item file.

In this file, Apple includes the following code:

import Foundation
import SwiftData

@Model
final class Item {
    var timestamp: Date
    
    init(timestamp: Date) {
        self.timestamp = timestamp
    }
}

On line 4, the @Model macro gives the Item class all the powers it needs to let you save instances of it in a persistent store.

Curious to see what @Model does? Right-click it, and select Expand Macro. Here’s what you’ll see:

It’s not critical to understand the @Model macro in detail. It’s OK to trust it to set up everything your model class needs to work with SwiftData. What you need to do is annotate any classes in your app that you want to persist in a data store with @Model.

The `.modelContainer()` View modifier

Once you’ve annotated all your model classes with @Model, you need to modify your SwiftUI view – or even an entire WindowGroup – with a container that can store instances of all your model classes.

Whenever you start a brand new Xcode project and select the option to use SwiftData for storage of your app’s data, Xcode automatically writes this code in your “AppName"App Swift file:

import SwiftUI
import SwiftData

@main
struct TrySwiftDataApp: App {

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .modelContainer(for: Item.self)
    }
}

If you have multiple model classes that you want to put into the container, replace .modelContainer(for: Item.self) with an array like this:

...
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
        .modelContainer(for: [ModelClass1.self, ModelClass2.self])
    }
...

The `@Query` property wrapper

After you modify your view or WindowGroup with a modelContainer, you need to get data from the container into your view. That’s where the @Query property wrapper comes in.

Suppose this was your SwiftData model:

@Model
final class Item {
    var timestamp: Date
    
    init(timestamp: Date) {
        self.timestamp = timestamp
    }
}

If you want to create a list of Items that you’ve stored with SwiftData, you’d write

`1`	`@Query private var items: [Item]`

Then in your view’s body, you could create a list out of the items variable:

1
2
3

List(items) { item in
    Text("Item at \(item.timestamp)")
}

That’s the most basic way to get data out of a SwiftData persistent store. But how do you put data in – or for that matter, update it or delete it from the persistent store?

The `@Environment(\.modelContext)` property wrapper

Suppose again that this was your SwiftData model:

@Model
final class Item {
    var timestamp: Date
    
    init(timestamp: Date) {
        self.timestamp = timestamp
    }
}

Any time you need to insert or delete data with SwiftData, add a line of code like this to your SwiftUI view:

`1`	`@Environment(\.modelContext) private var modelContext`

With modelContext, you can add data to your SwiftData store like this:

1
2

let newItem = Item(timestamp: Date())
modelContext.insert(newItem)

If you want to delete data, this code will do it:

1
2
3

for index in offsets {
    modelContext.delete(items[index])
}

What about updating data?

In most cases, you don’t need to do anything extra. modelContext has an autosave feature. When it’s enabled, modelContext saves when system events, such as your app entering the foreground or background, occur. It also saves periodically while your app is running. No extra code required!

modelContext does have a save() method that you can call if your app needs to do something like send data from SwiftData over to another system process, or share it with another person’s device. In situations like these, call modelContext.save() before you perform the action.

Wrapping Up

That takes care of adding SwiftData to one of your existing apps! There’s always more to explore, so @ me on Twitter to continue the conversation.