dpearson2699/swift-ios-skills / skills/swiftdata
swiftdata
VerifiedImplement, review, or improve data persistence using SwiftData. Use when defining @Model classes with @Attribute, @Relationship, @Transient, #Unique, or #Index; when querying with @Query, #Predicate, FetchDescriptor, or SortDescriptor; when configuring ModelContainer and ModelContext for SwiftUI or background work with @ModelActor; when planning schema migrations with VersionedSchema and SchemaMigrationPlan; when setting up CloudKit sync with ModelConfiguration; or when coexisting with or migrating from Core Data.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.4 KB |
| evals/evals.json | config | 3.8 KB |
| references/core-data-coexistence.md | markdown | 10.7 KB |
| references/indexing.md | markdown | 2.0 KB |
| references/predicate-pitfalls.md | markdown | 2.7 KB |
| references/swiftdata-advanced.md | markdown | 24.2 KB |
| references/swiftdata-queries.md | markdown | 18.0 KB |
references/swiftdata-queries.md
View on GitHub# SwiftData Queries Reference
Deep reference for all `@Query` initializer variants, FetchDescriptor options,
sort descriptors, sectioned queries, dynamic query switching, background fetch
patterns, and aggregate queries.
---
## Contents
- [`@Query Initializer Variants`](#query-initializer-variants)
- [FetchDescriptor Deep Dive](#fetchdescriptor-deep-dive)
- [Complex Sort Descriptors](#complex-sort-descriptors)
- [Sectioned Queries Pattern](#sectioned-queries-pattern)
- [Dynamic Query Switching](#dynamic-query-switching)
- [Background Fetch Patterns with `@ModelActor`](#background-fetch-patterns-with-modelactor)
- [Aggregate Queries](#aggregate-queries)
- [Enumerate for Large Datasets](#enumerate-for-large-datasets)
## `@Query` Initializer Variants
`@Query` is a SwiftUI property wrapper (`DynamicProperty`) that automatically
fetches and observes persistent model data. All variants are `@MainActor`.
### Basic (No Filter, No Sort)
```swift
// Fetch all, default order
@Query private var trips: [Trip]
// With animation
@Query(animation: .default) private var trips: [Trip]
// With transaction
@Query(transaction: Transaction(animation: .spring)) private var trips: [Trip]
```
### Filter + SortDescriptor Array
```swift
@Query(
filter: #Predicate<Trip> { $0.isFavorite == true },
sort: [SortDescriptor(\.startDate, order: .reverse)]
)
private var favoriteTrips: [Trip]
// With animation
@Query(
filter: #Predicate<Trip> { $0.isFavorite == true },
sort: [SortDescriptor(\.startDate, order: .reverse)],
animation: .default
)
private var favoriteTrips: [Trip]
```
### Filter + KeyPath Sort
```swift
@Query(
filter: #Predicate<Trip> { $0.destination != "" },
sort: \.startDate,
order: .forward
)
private var upcomingTrips: [Trip]
// With optional key path sort
@Query(
sort: \.endDate, // KeyPath<Trip, Date?> -- optional sort key
order: .reverse
)
private var tripsByEndDate: [Trip]
```
### FetchDescriptor
```swift
static var recentDescriptor: FetchDescriptor<Trip> {
let now = Date()
var d = FetchDescriptor<Trip>(
predicate: #Predicate { $0.startDate > now },
sortBy: [SortDescriptor(\.startDate)]
)
d.fetchLimit = 10
return d
}
@Query(RecentTripsView.recentDescriptor) private var recentTrips: [Trip]
// With animation
@Query(RecentTripsView.recentDescriptor, animation: .default)
private var recentTrips: [Trip]
```
### Query Properties
| Property | Type | Description |
|----------|------|-------------|
| `wrappedValue` | `Result` (typically `[Element]`) | Most recent fetched results |
| `modelContext` | `ModelContext` | The context used for fetching |
| `fetchError` | `(any Error)?` | Error from most recent fetch, if any |
Access `fetchError` to detect query failures:
```swift
struct TripListView: View {
@Query private var trips: [Trip]
var body: some View {
Group {
if let error = $trips.fetchError {
ContentUnavailableView("Fetch Error",
systemImage: "exclamationmark.triangle",
description: Text(error.localizedDescription))
} else {
List(trips) { trip in
Text(trip.name)
}
}
}
}
}
```
---
## FetchDescriptor Deep Dive
### Full Property Reference
```swift
var descriptor = FetchDescriptor<Trip>()
```
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `predicate` | `Predicate<T>?` | `nil` | Filter condition |
| `sortBy` | `[SortDescriptor<T>]` | `[]` | Sort order |
| `fetchLimit` | `Int?` | `nil` | Maximum results |
| `fetchOffset` | `Int?` | `nil` | Skip first N results |
| `includePendingChanges` | `Bool` | `true` | Include unsaved in-memory changes |
| `propertiesToFetch` | `[PartialKeyPath<T>]` | all | Specific properties to load |
| `relationshipKeyPathsForPrefetching` | `[PartialKeyPath<T>]` | `[]` | Related models to eagerly load |
### fetchLimit and fetchOffset (Pagination)
```swift
func fetchPage(page: Int, pageSize: Int) throws -> [Trip] {
var descriptor = FetchDescriptor<Trip>(
sortBy: [SortDescriptor(\.startDate)]
)
descriptor.fetchLimit = pageSize
descriptor.fetchOffset = page * pageSize
return try modelContext.fetch(descriptor)
}
```
### includePendingChanges
When `true` (default), the fetch includes objects inserted or modified in the
current context but not yet saved. Set to `false` for read-only queries against
the persisted store only.
```swift
var descriptor = FetchDescriptor<Trip>()
descriptor.includePendingChanges = false // Only persisted data
```
Note: `includePendingChanges: true` cannot be used with batched fetches
(`fetch(_:batchSize:)`). This will throw
`SwiftDataError.includePendingChangesWithBatchSize`.
### propertiesToFetch (Partial Loading)
Load only specific attributes to reduce memory footprint:
```swift
var descriptor = FetchDescriptor<Trip>()
descriptor.propertiesToFetch = [\.name, \.destination, \.startDate]
let trips = try modelContext.fetch(descriptor)
// Only name, destination, startDate are loaded; other properties fault on access
```
### relationshipKeyPathsForPrefetching
Eagerly load related objects to avoid N+1 query patterns:
```swift
var descriptor = FetchDescriptor<Trip>()
descriptor.relationshipKeyPathsForPrefetching = [
\.accommodation,
\.tags
]
let trips = try modelContext.fetch(descriptor)
// Accessing trip.accommodation does not trigger a separate fetch
```
### Fetch Variants on ModelContext
| Method | Returns | Use Case |
|--------|---------|----------|
| `fetch(_:)` | `[T]` | Standard fetch, all results in memory |
| `fetch(_:batchSize:)` | `FetchResultsCollection<T>` | Lazy batched loading |
| `fetchCount(_:)` | `Int` | Count only, no objects loaded |
| `fetchIdentifiers(_:)` | `[PersistentIdentifier]` | IDs only, lightweight |
| `fetchIdentifiers(_:batchSize:)` | `FetchResultsCollection<PersistentIdentifier>` | Batched ID loading |
| `enumerate(_:batchSize:...)` | `Void` | Process large sets in batches |
### FetchResultsCollection (Batched Fetch)
```swift
let results: FetchResultsCollection<Trip> = try modelContext.fetch(
FetchDescriptor<Trip>(sortBy: [SortDescriptor(\.name)]),
batchSize: 100
)
// Iterate lazily -- only 100 objects in memory at a time
for trip in results {
print(trip.name)
}
```
Requirements for batched fetch:
- `includePendingChanges` must be `false` (or will throw).
- Results are read-only snapshots.
---
## Complex Sort Descriptors
### Single Sort
```swift
SortDescriptor(\.name, order: .forward) // A-Z
SortDescriptor(\.name, order: .reverse) // Z-A
SortDescriptor(\.startDate) // Ascending (default)
```
### Multi-Level Sort
```swift
let descriptor = FetchDescriptor<Trip>(
sortBy: [
SortDescriptor(\.isFavorite, order: .reverse), // Favorites first
SortDescriptor(\.startDate, order: .forward), // Then by date
SortDescriptor(\.name, order: .forward) // Then alphabetical
]
)
```
### Optional Key Path Sort
Sort on optional properties -- nil values sort to the end:
```swift
@Query(sort: \.endDate, order: .reverse) private var trips: [Trip]
// endDate is Date? -- trips without endDate appear last
```
### Dynamic Sort Switching
```swift
struct TripListView: View {
@State private var sortOrder: SortOrder = .forward
@State private var sortKey: TripSortKey = .name
var body: some View {
SortedTripList(sortKey: sortKey, sortOrder: sortOrder)
.toolbar {
Picker("Sort", selection: $sortKey) {
Text("Name").tag(TripSortKey.name)
Text("Date").tag(TripSortKey.date)
Text("Destination").tag(TripSortKey.destination)
}
}
}
}
enum TripSortKey: String, CaseIterable {
case name, date, destination
}
struct SortedTripList: View {
@Query private var trips: [Trip]
init(sortKey: TripSortKey, sortOrder: SortOrder) {
let sortDescriptor: SortDescriptor<Trip> = switch sortKey {
case .name: SortDescriptor(\.name, order: sortOrder)
case .date: SortDescriptor(\.startDate, order: sortOrder)
case .destination: SortDescriptor(\.destination, order: sortOrder)
}
_trips = Query(sort: [sortDescriptor])
}
var body: some View {
List(trips) { trip in
TripRow(trip: trip)
}
}
}
```
---
## Sectioned Queries Pattern
Current Apple docs include `sectionBy:` `Query` initializers for sectioned
queries in iOS 27 / Xcode 27 beta. Use them only when the deployment target and
SDK support those beta APIs.
For iOS 26-compatible guidance, custom grouping, or section keys derived from
formatters/business logic, build sectioned views manually:
### Using Dictionary Grouping
```swift
struct SectionedTripListView: View {
@Query(sort: \.startDate) private var trips: [Trip]
private var sections: [(String, [Trip])] {
let formatter = DateFormatter()
formatter.dateFormat = "MMMM yyyy"
let grouped = Dictionary(grouping: trips) { trip in
formatter.string(from: trip.startDate)
}
return grouped.sorted { $0.key < $1.key }
}
var body: some View {
List {
ForEach(sections, id: \.0) { section, trips in
Section(section) {
ForEach(trips) { trip in
TripRow(trip: trip)
}
}
}
}
}
}
```
### Using Enum-Based Sections
```swift
enum TripStatus: String, CaseIterable {
case upcoming = "Upcoming"
case current = "Current"
case past = "Past"
}
struct StatusSectionedView: View {
@Query(sort: \.startDate) private var trips: [Trip]
private func trips(for status: TripStatus) -> [Trip] {
let now = Date()
return trips.filter { trip in
switch status {
case .upcoming: trip.startDate > now
case .current: trip.startDate <= now && trip.endDate >= now
case .past: trip.endDate < now
}
}
}
var body: some View {
List {
ForEach(TripStatus.allCases, id: \.self) { status in
let sectionTrips = trips(for: status)
if !sectionTrips.isEmpty {
Section(status.rawValue) {
ForEach(sectionTrips) { trip in
TripRow(trip: trip)
}
}
}
}
}
}
}
```
---
## Dynamic Query Switching
### Filter + Sort Controlled by Parent
```swift
struct TripBrowserView: View {
@State private var searchText = ""
@State private var showFavoritesOnly = false
var body: some View {
NavigationStack {
FilteredTripList(
searchText: searchText,
favoritesOnly: showFavoritesOnly
)
.searchable(text: $searchText)
.toolbar {
Toggle("Favorites", isOn: $showFavoritesOnly)
}
}
}
}
struct FilteredTripList: View {
@Query private var trips: [Trip]
init(searchText: String, favoritesOnly: Bool) {
let predicate = #Predicate<Trip> { trip in
(searchText.isEmpty || trip.name.localizedStandardContains(searchText))
&& (!favoritesOnly || trip.isFavorite == true)
}
_trips = Query(
filter: predicate,
sort: [SortDescriptor(\.startDate, order: .reverse)]
)
}
var body: some View {
List(trips) { trip in
NavigationLink(trip.name) {
TripDetailView(trip: trip)
}
}
}
}
```
### Full Dynamic Descriptor
```swift
struct AdvancedTripList: View {
@Query private var trips: [Trip]
init(
destination: String?,
minDate: Date?,
sortKey: KeyPath<Trip, some Comparable>,
ascending: Bool,
limit: Int?
) {
var descriptor = FetchDescriptor<Trip>(
sortBy: [SortDescriptor(\.startDate, order: ascending ? .forward : .reverse)]
)
if let destination {
descriptor.predicate = #Predicate<Trip> { trip in
trip.destination == destination
}
}
if let limit {
descriptor.fetchLimit = limit
}
_trips = Query(descriptor)
}
var body: some View {
List(trips) { trip in
TripRow(trip: trip)
}
}
}
```
---
## Background Fetch Patterns with `@ModelActor`
### Basic Background Fetch
```swift
@ModelActor
actor TripDataHandler {
func fetchUpcomingTrips() throws -> [PersistentIdentifier] {
let now = Date()
let descriptor = FetchDescriptor<Trip>(
predicate: #Predicate { $0.startDate > now },
sortBy: [SortDescriptor(\.startDate)]
)
return try modelContext.fetchIdentifiers(descriptor)
}
func fetchTripCount(destination: String) throws -> Int {
let descriptor = FetchDescriptor<Trip>(
predicate: #Predicate<Trip> { trip in
trip.destination == destination
}
)
return try modelContext.fetchCount(descriptor)
}
}
// Usage from SwiftUI view
struct TripDashboardView: View {
@Environment(\.modelContext) private var modelContext
@State private var upcomingCount = 0
var body: some View {
Text("Upcoming: \(upcomingCount)")
.task {
let handler = TripDataHandler(
modelContainer: modelContext.container
)
upcomingCount = (try? await handler.fetchTripCount(
destination: "Paris"
)) ?? 0
}
}
}
```
### Background Import with Progress
```swift
@ModelActor
actor ImportHandler {
func importTrips(
_ records: [TripRecord],
progress: @Sendable (Int) -> Void
) throws -> Int {
var imported = 0
for (index, record) in records.enumerated() {
let trip = Trip(
name: record.name,
destination: record.destination,
startDate: record.startDate,
endDate: record.endDate
)
modelContext.insert(trip)
imported += 1
// Save periodically to flush memory
if index % 500 == 0 {
try modelContext.save()
progress(imported)
}
}
try modelContext.save()
return imported
}
}
```
### Resolving Identifiers on MainActor
```swift
@ModelActor
actor DataHandler {
func findDuplicateIDs() throws -> [PersistentIdentifier] {
// Complex logic to find duplicates
let all = try modelContext.fetch(FetchDescriptor<Trip>())
var seen = Set<String>()
var duplicateIDs: [PersistentIdentifier] = []
for trip in all {
if seen.contains(trip.name) {
duplicateIDs.append(trip.persistentModelID)
}
seen.insert(trip.name)
}
return duplicateIDs
}
}
// On MainActor, resolve IDs to objects
struct DuplicateReviewView: View {
@Environment(\.modelContext) private var modelContext
@State private var duplicates: [Trip] = []
var body: some View {
List(duplicates) { trip in
Text(trip.name)
}
.task {
let handler = DataHandler(modelContainer: modelContext.container)
let ids = (try? await handler.findDuplicateIDs()) ?? []
duplicates = ids.compactMap { id in
modelContext.registeredModel(for: id) as Trip?
?? (try? modelContext.model(for: id) as? Trip)
}
}
}
}
```
---
## Aggregate Queries
SwiftData does not provide built-in aggregate functions (SUM, AVG, etc.).
Compute aggregates using fetch + Swift computation.
### Count
```swift
let count = try modelContext.fetchCount(
FetchDescriptor<Trip>(predicate: #Predicate { $0.isFavorite == true })
)
```
### Sum, Average, Min, Max
```swift
let trips = try modelContext.fetch(FetchDescriptor<Trip>())
let totalBudget = trips.reduce(0.0) { $0 + $1.budget }
let averageBudget = trips.isEmpty ? 0 : totalBudget / Double(trips.count)
let maxBudget = trips.map(\.budget).max() ?? 0
let minBudget = trips.map(\.budget).min() ?? 0
```
### Efficient Aggregates with Partial Fetch
Fetch only the property needed for aggregation:
```swift
var descriptor = FetchDescriptor<Trip>()
descriptor.propertiesToFetch = [\.budget]
let trips = try modelContext.fetch(descriptor)
let total = trips.reduce(0.0) { $0 + $1.budget }
```
### Background Aggregate Computation
```swift
@ModelActor
actor StatsHandler {
struct TripStats: Sendable {
let totalCount: Int
let favoriteCount: Int
let averageDuration: TimeInterval
}
func computeStats() throws -> TripStats {
let allTrips = try modelContext.fetch(FetchDescriptor<Trip>())
let favoriteCount = try modelContext.fetchCount(
FetchDescriptor<Trip>(predicate: #Predicate { $0.isFavorite == true })
)
let totalDuration = allTrips.reduce(0.0) { sum, trip in
sum + trip.endDate.timeIntervalSince(trip.startDate)
}
let avgDuration = allTrips.isEmpty ? 0 : totalDuration / Double(allTrips.count)
return TripStats(
totalCount: allTrips.count,
favoriteCount: favoriteCount,
averageDuration: avgDuration
)
}
}
```
---
## Enumerate for Large Datasets
Use `enumerate` instead of `fetch` when processing many records to keep memory
usage constant:
```swift
// Process all trips without loading all into memory
try modelContext.enumerate(
FetchDescriptor<Trip>(sortBy: [SortDescriptor(\.startDate)]),
batchSize: 1000,
allowEscapingMutations: false
) { trip in
// Process each trip
trip.isProcessed = true
}
try modelContext.save()
```
Parameters:
- `batchSize`: Objects per batch (default 5000). Lower values use less memory.
- `allowEscapingMutations`: When `false`, objects are autoreleased after the
block. Set to `true` only if mutations must persist beyond the block.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |