SwiftData: The Ultimate Guide from iOS 17 to iOS 26

SwiftData is a declarative persistence framework that allows you to model and store your application's data in pure Swift. It uses Swift macros to transform ordinary classes into persistent models, eliminating the need for .xcdatamodeld files and code generation.

Key features:

SwiftData is not a complete replacement for Core Data, but rather a new API built on its foundations. The default storage format remains compatible with Core Data.

For new projects targeting iOS 17+, SwiftData is recommended. For existing projects or those requiring advanced features (batch operations, faulting), Core Data remains relevant.

Initial launch with fundamentals:

Major architecture evolution:

Stabilization and new features:

Transforming a class into a persistent model requires just one line:

The @Model macro automatically generates conformance to PersistentModel and Observable, allowing SwiftUI to react to changes.

ModelContainer manages persistent storage, while ModelContext represents the workspace for CRUD operations:

The .modelContainer modifier automatically configures the container and injects the context into the SwiftUI environment.

For more control, create the container manually:

The @Query macro transforms queries into reactive properties:

@Query parameters allow sorting, filtering, and limiting:

Basic operations are performed through ModelContext:

SwiftData natively supports:

The @Attribute macro allows configuring persistence behavior:

SwiftData supports one-to-one, one-to-many, and many-to-many relationships:

Available delete rules:

For computed or temporary properties:

For queries outside of SwiftUI, use FetchDescriptor:

The #Predicate macro offers compiled and type-safe filtering:

Combine multiple conditions with logical operators:

The #Expression macro allows performing calculations directly in queries:

The #Unique macro guarantees uniqueness and performs automatic upserts:

When inserting a Trip with the same name/startDate/endDate, SwiftData performs an update instead of creating a duplicate.

Create indexes on frequently filtered or sorted properties:

To preserve values after deletion (useful for History API):

Encapsulate each version of your schema:

Define the migration order and custom steps:

For complex transformations:

If your app is already in production without VersionedSchema:

Enable iCloud in your project and configure the container:

CloudKit database options:

CloudKit with SwiftData has constraints:

Enable logs for diagnostics:

@Query and ModelContext run on the MainActor. For heavy operations, this blocks the UI:

Create a dedicated actor for heavy operations:

Models are not Sendable. Use their identifiers:

History is enabled by default with DefaultStore. Use preserveValueOnDeletion to retain identifiers of deleted items:

iOS 18 allows replacing the SQLite backend with any storage system via the DataStore protocol:

Simplified example of a JSON-based store:

Inheritance is appropriate when:

Use the is keyword in predicates:

SwiftData stores all subtypes in a single table (Wide Table). This can impact performance with many different subclasses, very different properties between subclasses, or large data volumes.

For complex hierarchies, prefer composition with relationships.

Add these arguments in your scheme (Edit Scheme → Arguments):

Locate and inspect the data file:

Isolate SwiftData behind an abstraction:

Create a dedicated preview container:

Before iOS 26, modifications via @ModelActor didn't always trigger SwiftUI updates:

iOS 26 fixes this bug with backward compatibility to iOS 17.

Before iOS 26, using Codable properties in predicates didn't work:

Known bug: .cascade doesn't always delete children:

Possible but complex. Identifiers are not compatible. Recommended approach: progressive migration — keep Core Data for critical features, new models in SwiftData, migrate progressively as SwiftData matures.

SwiftData represents the future of persistence on Apple platforms. Despite its youth which translates to some limitations, the framework evolves rapidly and becomes increasingly viable for production applications. By mastering the concepts in this guide, you're ready to confidently adopt it in your projects.