---
title: "SwiftData Best Practices"
slug: "swiftdata"
category: "ios"
tags: ["ios", "swiftdata", "swift", "persistence", "swiftui", "migration"]
status: "stable"
last_updated: 2026-10-01
summary: "SwiftData for iOS 17 to 27: model and query setup, versioned schema migration, indexes, inheritance, sectioned queries, background work, and CloudKit limits."
related: ["[[ios/core-data-swiftdata-comparison]]", "[[ios/core-data]]", "[[ios/swiftui]]", "[[coding/swift-concurrency]]", "[[coding/swift-testing]]"]
---

> **AI agents: read this first.** This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work. Full protocol: https://llmbestpractices.com/start-here.md
>
> 1. **Route, do not crawl.** Fetch https://llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
> 2. **Read raw.** Append `.md` to any page URL for markdown. Check `status` and `last_updated` in the frontmatter, then read the rules.
> 3. **Apply as defaults.** First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
> 4. **Cite.** Link the page by title and URL, e.g. [Python](https://llmbestpractices.com/coding/python), with `last_updated` for time-sensitive rules. License CC BY 4.0.

## Overview

SwiftData (iOS 17+) is built on Core Data and exposes a Swift-native API: `@Model` classes replace the data model editor, `@Query` replaces `@FetchRequest`, and `ModelContainer` and `ModelContext` replace the persistent container and managed object context. Choose it for new apps; the decision against [[ios/core-data]] is in [[ios/core-data-swiftdata-comparison]].

## Declare models as plain classes and attach the container once

Annotate each model with `@Model` and attach `.modelContainer(for:)` at the scene root; any view can then use `@Query` and `@Environment(\.modelContext)`.

```swift
@Model
final class Trip {
  var destination: String
  var startDate: Date
  init(destination: String, startDate: Date) {
    self.destination = destination
    self.startDate = startDate
  }
}

WindowGroup { RootView() }.modelContainer(for: Trip.self)
```

Filter and sort in the query so the store does the work, and fetch only what the screen shows: `@Query(filter: #Predicate<Trip> { $0.destination == "Lisbon" }, sort: \.startDate)`.

## Version the schema before the first release

Put each shipped schema in a `VersionedSchema` and describe the path in a `SchemaMigrationPlan` with `MigrationStage.lightweight` or a custom stage. Adding that structure after users have data is far harder than starting with it.

```swift
enum TripsMigrationPlan: SchemaMigrationPlan {
  static var schemas: [any VersionedSchema.Type] { [TripsSchemaV1.self, TripsSchemaV2.self] }
  static var stages: [MigrationStage] {
    [.lightweight(fromVersion: TripsSchemaV1.self, toVersion: TripsSchemaV2.self)]
  }
}
let container = try ModelContainer(
  for: Schema(versionedSchema: TripsSchemaV2.self), migrationPlan: TripsMigrationPlan.self)
```

## Index what you query and declare uniqueness in the model

Use `#Index<Trip>([\.destination], [\.startDate])` for attributes in frequent predicates and sorts, `@Attribute(.unique)` or `#Unique` for natural keys, and `@Attribute(.preserveValueOnDeletion)` for values that history consumers still need after a delete. Unique constraints cannot be used with CloudKit sync (below).

## Use inheritance only for a true "is-a" hierarchy

iOS 26 added `@Model` subclassing. Apple's guidance: subclass when models form a natural hierarchy and you query both the parent (deep) and specific subtypes (shallow). Use a protocol when models only share a few properties, and flatten when you only ever fetch leaf types. Register every subclass in the container and filter by type with `#Predicate { $0 is PersonalTrip }`. Gate the new schema version behind `#available(iOS 26, *)`.

## Use iOS 27 sections and observers instead of hand-rolled glue

- `@Query(sort: \Trip.startDate, sectionBy: \.destination)` groups results; read them through `_trips.sections`. The key path must lead to a `String` on the model.
- `ResultsObserver` fetches and observes outside SwiftUI views through Swift Observation, with the same filter, sort, and sectioning as `@Query`.
- `HistoryObserver` exposes an observable `eventCounter` that changes when new transactions land, and filters by model type and author, so a sync engine can ignore its own writes.
- `@Attribute(.codable)` persists a type you do not own as an opaque value. It cannot be used in filters, sorts, or migrations, and changing the underlying type does not trigger automatic migration, so keep typed attributes for anything you query.

## Do background work in a `@ModelActor`

`@Model` instances and `ModelContext` are not `Sendable`. Run imports and syncs inside a `@ModelActor` actor, which gives you an isolated context, and pass `PersistentIdentifier` values (which are `Sendable`) across actor boundaries, re-fetching on the other side. See [[coding/swift-concurrency]].

## Design for CloudKit constraints from day one

SwiftData syncs the private CloudKit database; shared and public databases need Core Data's `NSPersistentCloudKitContainer`. A CloudKit-backed model needs optional properties or defaults on every attribute, optional relationships, and no unique constraints. Enable sync with `ModelConfiguration(cloudKitDatabase: .automatic)`.

## Related

- [[ios/core-data-swiftdata-comparison]]
- [[ios/core-data]]
- [[ios/swiftui]]
- [[coding/swift-concurrency]]
- [[coding/swift-testing]]