SwiftData for iOS Engineers (2026): Schemas, Predicates, Migration

A real @Model schema with relationships

This is what an actual production schema looks like — not a Person/Pet toy. A note-taking app with notebooks, notes, and tags:

import SwiftData
import Foundation

@Model
final class Notebook {
    @Attribute(.unique) var id: UUID
    var name: String
    var createdAt: Date

    // Cascade — deleting the notebook deletes all notes
    @Relationship(deleteRule: .cascade, inverse: \Note.notebook)
    var notes: [Note] = []

    init(id: UUID = UUID(), name: String) {
        self.id = id
        self.name = name
        self.createdAt = .now
    }
}

@Model
final class Note {
    @Attribute(.unique) var id: UUID
    var title: String
    var body: String
    var updatedAt: Date

    // Inverse declared on Notebook side
    var notebook: Notebook?

    // Many-to-many — deleting a tag does NOT delete notes
    @Relationship(deleteRule: .nullify, inverse: \Tag.notes)
    var tags: [Tag] = []

    // Stored externally — large blob
    @Attribute(.externalStorage) var attachment: Data?

    init(id: UUID = UUID(), title: String, body: String) {
        self.id = id
        self.title = title
        self.body = body
        self.updatedAt = .now
    }
}

@Model
final class Tag {
    @Attribute(.unique) var name: String
    var notes: [Note] = []

    init(name: String) { self.name = name }
}

Two specifics that matter: @Attribute(.unique) creates a database-level unique constraint (insert collisions throw); @Attribute(.externalStorage) stores blobs on disk outside the .sqlite file — the same mechanic Core Data calls 'allowsExternalBinaryDataStorage'.

#Predicate: what compiles and what doesn't

The #Predicate macro (SE-0420) compiles a closure into an NSPredicate at compile time. The constraint: only a specific subset of Swift compiles. This is the rule that trips up senior engineers coming from Core Data:

// COMPILES — KeyPaths, literals, comparison operators
let recent = #Predicate<Note> { note in
    note.updatedAt > Date.now.addingTimeInterval(-7 * 86400)
}

// COMPILES — string contains, optional binding
let matches = #Predicate<Note> { note in
    note.title.localizedStandardContains("swift")
}

// COMPILES — relationship traversal + nil check
let untagged = #Predicate<Note> { note in
    note.tags.isEmpty && note.notebook != nil
}

// DOES NOT COMPILE — captured function call
func isStale(_ d: Date) -> Bool { d < .now.addingTimeInterval(-86400) }
let stale = #Predicate<Note> { note in
    isStale(note.updatedAt)  // ← Cannot capture function
}

// DOES NOT COMPILE — @Transient property reference
// (any property without storage cannot be in a predicate)

// USAGE
let descriptor = FetchDescriptor<Note>(
    predicate: recent,
    sortBy: [SortDescriptor(\.updatedAt, order: .reverse)]
)
descriptor.fetchLimit = 50
descriptor.propertiesToFetch = [\.id, \.title, \.updatedAt]

let notes = try modelContext.fetch(descriptor)

SE-0420 (github.com/swiftlang/swift-evolution) is the proposal; the fetchLimit + propertiesToFetch tuning is what stops your 50k-row launch from being a hang report. WWDC23 'Model your schema with SwiftData' (developer.apple.com/videos/play/wwdc2023/10195) covers the predicate grammar at 11:30.

Schema migration: VersionedSchema + SchemaMigrationPlan

Production migrations require both a versioned schema and a migration plan. Lightweight changes (adding an optional property, renaming via @Attribute(originalName:)) need only a versioned schema; custom migrations need a stage with willMigrate/didMigrate closures.

// VERSION 1 — initial release
enum SchemaV1: VersionedSchema {
    static var versionIdentifier = Schema.Version(1, 0, 0)
    static var models: [any PersistentModel.Type] {
        [Notebook.self, Note.self]
    }

    @Model final class Note {
        @Attribute(.unique) var id: UUID
        var title: String
        var body: String
        // ... no updatedAt
        init(id: UUID, title: String, body: String) {
            self.id = id; self.title = title; self.body = body
        }
    }
}

// VERSION 2 — added updatedAt, renamed body -> content
enum SchemaV2: VersionedSchema {
    static var versionIdentifier = Schema.Version(2, 0, 0)
    static var models: [any PersistentModel.Type] {
        [Notebook.self, Note.self]
    }

    @Model final class Note {
        @Attribute(.unique) var id: UUID
        var title: String
        @Attribute(originalName: "body") var content: String
        var updatedAt: Date  // new
        init(id: UUID, title: String, content: String) {
            self.id = id; self.title = title; self.content = content
            self.updatedAt = .now
        }
    }
}

// MIGRATION PLAN
enum AppMigrationPlan: SchemaMigrationPlan {
    static var schemas: [any VersionedSchema.Type] {
        [SchemaV1.self, SchemaV2.self]
    }

    static var stages: [MigrationStage] {
        [migrateV1toV2]
    }

    static let migrateV1toV2 = MigrationStage.custom(
        fromVersion: SchemaV1.self,
        toVersion: SchemaV2.self,
        willMigrate: { context in
            // Backfill updatedAt for existing rows
            let notes = try context.fetch(FetchDescriptor<SchemaV1.Note>())
            for note in notes {
                note.setValue(forKey: "updatedAt", to: Date.now)
            }
            try context.save()
        },
        didMigrate: { _ in /* post-migration validation */ }
    )
}

// CONTAINER SETUP
let container = try ModelContainer(
    for: SchemaV2.self,
    migrationPlan: AppMigrationPlan.self,
    configurations: ModelConfiguration(schema: Schema(versionedSchema: SchemaV2.self))
)

WWDC23 'Migrate your app to SwiftData' at developer.apple.com/videos/play/wwdc2023/10189 walks through both lightweight and custom migrations starting at 9:00. The pattern that bit production teams in iOS 17.0–17.2: lightweight migrations that included a unique constraint change silently dropped rows. Always test migrations against a real production database snapshot, not just synthetic fixtures.

CloudKit sync container setup

CloudKit sync via SwiftData looks like one configuration line, but it has constraints the documentation hides:

// In your App struct
@main
struct NotesApp: App {
    let container: ModelContainer

    init() {
        do {
            let config = ModelConfiguration(
                "CloudNotes",
                schema: Schema([Notebook.self, Note.self, Tag.self]),
                cloudKitDatabase: .private("iCloud.com.example.Notes")
            )
            container = try ModelContainer(
                for: Notebook.self, Note.self, Tag.self,
                configurations: config
            )
        } catch {
            fatalError("ModelContainer init: \(error)")
        }
    }

    var body: some Scene {
        WindowGroup { ContentView() }
            .modelContainer(container)
    }
}

The constraints CloudKit imposes on your schema:

• All properties must be optional or have a default value. CloudKit cannot synthesise a value for an existing record after a schema migration, so non-optional non-default properties will fail to load on a peer device.
• No @Attribute(.unique) under iOS 17.0–17.3. The unique constraint silently failed during initial sync. Fixed in iOS 17.4 (release notes: developer.apple.com/documentation/ios-ipados-release-notes/ios-ipados-17_4-release-notes). If your deployment target is iOS 17.0+, enforce uniqueness in app code.
• @Relationship inverse must be declared — both sides — for CloudKit to translate the relationship to a CKReference correctly.
• Schema must match the CloudKit container schema. First run of the app pushes the schema; subsequent migrations require a CloudKit Dashboard 'Deploy to Production' click.

Performance: where SwiftData costs you and how to fix it

Three performance failure modes show up in production SwiftData apps:

1. @Query without fetchLimit blocks the main thread on launch. The reactive @Query property wrapper materializes the full result set on view appearance. On a table with 50,000 rows, this is a 200–600ms hang on iPhone 13 — long enough to surface in MetricKit hang reports. The fix: pass an explicit FetchDescriptor with fetchLimit and propertiesToFetch.
2. Predicate translation surprises. #Predicate compiles to NSPredicate; some Swift expressions translate cleanly, others fall back to in-memory evaluation. The compiler does not warn — you find out from a Time Profiler trace. Mitigation: profile predicates that touch relationships or string operations; if they're slow, restructure to use indexed properties.
3. CloudKit sync amplification on background launch. Background launches with CloudKit-enabled SwiftData can trigger a sync sweep that runs concurrent with limited background-execution time. Apps that crashed-on-launch in iOS 17.0–17.3 typically had this pattern. Fix: gate CloudKit sync behind a foreground-only flag or use the iOS 17.4+ behavior where the framework itself defers heavy sync to foreground.

// FAST — bounded, only the fields needed
let desc = FetchDescriptor<Note>(
    predicate: #Predicate { $0.notebook?.id == notebookID },
    sortBy: [SortDescriptor(\.updatedAt, order: .reverse)]
)
desc.fetchLimit = 50
desc.propertiesToFetch = [\.id, \.title, \.updatedAt]

// SLOW — unbounded, full row materialisation
@Query(sort: \.updatedAt, order: .reverse)
var notes: [Note]

// MEDIUM — bounded but loads all properties
@Query(
    filter: #Predicate<Note> { $0.notebook?.id == someID },
    sort: \.updatedAt,
    order: .reverse
)
var notes: [Note]

WWDC24 'What's new in SwiftData' at developer.apple.com/videos/play/wwdc2024/10137 covers performance tuning starting at 14:00. The Instruments SwiftData lane (Xcode 16+) is the canonical profiling surface.

When to keep Core Data: a decision matrix

SwiftData is the default for new code. Three cases keep you on Core Data in 2026: