@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftdata/references/swiftdata-queries.md

@@ -1,332 +1,237 @@
-# SwiftData Queries Reference
+# SwiftData queries
 
-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)
+Examples use this model:
 
 ```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]
+import SwiftData
+import SwiftUI
+
+@Model
+final class Workout {
+    var title: String
+    var startedAt: Date
+    var finishedAt: Date?
+    var minutes: Int
+    var calories: Double
+    var isFavorite: Bool = false
+
+    init(title: String, startedAt: Date, minutes: Int, calories: Double) {
+        self.title = title
+        self.startedAt = startedAt
+        self.minutes = minutes
+        self.calories = calories
+    }
+}
 ```
 
-### 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]
-```
+## Contents
 
-### Filter + KeyPath Sort
+- [@Query initializers](#query-initializers)
+- [FetchDescriptor in depth](#fetchdescriptor-in-depth)
+- [Sorting](#sorting)
+- [Grouping results into sections](#grouping-results-into-sections)
+- [Changing the query at runtime](#changing-the-query-at-runtime)
+- [Fetching on a background actor](#fetching-on-a-background-actor)
+- [Aggregates](#aggregates)
+- [enumerate for large sets](#enumerate-for-large-sets)
 
-```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]
-```
+## @Query initializers
 
-### FetchDescriptor
+`@Query` is a SwiftUI `DynamicProperty`, and every initializer is `@MainActor`.
 
 ```swift
-static var recentDescriptor: FetchDescriptor<Trip> {
-    var d = FetchDescriptor<Trip>(
-        predicate: #Predicate { $0.startDate > Date.now },
-        sortBy: [SortDescriptor(\.startDate)]
-    )
-    d.fetchLimit = 10
-    return d
-}
-
-@Query(RecentTripsView.recentDescriptor) private var recentTrips: [Trip]
+struct QueryShapes: View {
+    // Everything, default order
+    @Query private var all: [Workout]
+
+    // Animate changes
+    @Query(animation: .snappy) private var animated: [Workout]
+    @Query(transaction: Transaction(animation: .easeOut)) private var viaTransaction: [Workout]
+
+    // Filter plus an array of sort descriptors
+    @Query(filter: #Predicate<Workout> { $0.minutes >= 30 },
+           sort: [SortDescriptor(\Workout.startedAt, order: .reverse)],
+           animation: .default)
+    private var long: [Workout]
+
+    // Filter plus a single key path; optional keys are allowed
+    @Query(filter: #Predicate<Workout> { $0.isFavorite },
+           sort: \Workout.finishedAt, order: .forward)
+    private var favorites: [Workout]
+
+    // A prepared descriptor
+    @Query(QueryShapes.lastTen) private var recent: [Workout]
+    @Query(QueryShapes.lastTen, animation: .default) private var recentAnimated: [Workout]
+
+    static var lastTen: FetchDescriptor<Workout> {
+        var d = FetchDescriptor<Workout>(sortBy: [SortDescriptor(\.startedAt, order: .reverse)])
+        d.fetchLimit = 10
+        return d
+    }
 
-// With animation
-@Query(RecentTripsView.recentDescriptor, animation: .default)
-private var recentTrips: [Trip]
+    var body: some View { Text("\(all.count)") }
+}
 ```
 
-### 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:
+A query exposes its results as `wrappedValue`, the `modelContext` it reads
+from, and `fetchError: (any Error)?` for a fetch that failed. The wrapper has
+no projected value, so reach it through the underscored `_workouts`. Surface
+that error instead of showing an empty list:
 
 ```swift
-struct TripListView: View {
-    @Query private var trips: [Trip]
+struct WorkoutHistory: View {
+    @Query(sort: \Workout.startedAt, order: .reverse) private var workouts: [Workout]
 
     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)
-                }
-            }
+        if let error = _workouts.fetchError {
+            ContentUnavailableView("Could not load workouts",
+                                   systemImage: "exclamationmark.triangle",
+                                   description: Text(error.localizedDescription))
+        } else {
+            List(workouts) { Text($0.title) }
         }
     }
 }
 ```
 
----
+## FetchDescriptor in depth
 
-## FetchDescriptor Deep Dive
+| Property | Type | Default |
+|---|---|---|
+| `predicate` | `Predicate<T>?` | `nil` |
+| `sortBy` | `[SortDescriptor<T>]` | `[]` |
+| `fetchLimit` | `Int?` | `nil` |
+| `fetchOffset` | `Int?` | `nil` |
+| `includePendingChanges` | `Bool` | `true` |
+| `propertiesToFetch` | `[PartialKeyPath<T>]` | every attribute |
+| `relationshipKeyPathsForPrefetching` | `[PartialKeyPath<T>]` | `[]` |
 
-### Full Property Reference
+Paging needs a stable sort, otherwise rows move between pages:
 
 ```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)
+func page(_ index: Int, size: Int, in context: ModelContext) throws -> [Workout] {
+    var d = FetchDescriptor<Workout>(sortBy: [
+        SortDescriptor(\.startedAt, order: .reverse),
+        SortDescriptor(\.title)
+    ])
+    d.fetchLimit = size
+    d.fetchOffset = index * size
+    return try context.fetch(d)
 }
 ```
 
-### 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.
+- `includePendingChanges` is `true` by default: results include inserts and
+  edits in this context that are not saved yet. Set it to `false` to read only
+  what is on disk.
+- Batched fetches need `includePendingChanges = false`. Calling
+  `fetch(_:batchSize:)` while it is still `true` (the default) throws
+  `SwiftDataError.includePendingChangesWithBatchSize`.
+- `propertiesToFetch` loads only the listed attributes; any other attribute is
+  loaded when first touched.
+- `relationshipKeyPathsForPrefetching` loads the named relationships up front,
+  which avoids one extra fetch per row.
+
+Fetch calls on `ModelContext`:
+
+| Call | Returns |
+|---|---|
+| `fetch(_:)` | `[T]` |
+| `fetch(_:batchSize:)` | `FetchResultsCollection<T>` |
+| `fetchCount(_:)` | `Int` |
+| `fetchIdentifiers(_:)` | `[PersistentIdentifier]` |
+| `fetchIdentifiers(_:batchSize:)` | `FetchResultsCollection<PersistentIdentifier>` |
+| `enumerate(_:batchSize:allowEscapingMutations:block:)` | `Void` |
+
+A batched collection is walked lazily, keeping about one batch in memory at a
+time. Treat its elements as read-only snapshots.
 
 ```swift
-var descriptor = FetchDescriptor<Trip>()
-descriptor.includePendingChanges = false  // Only persisted data
+var d = FetchDescriptor<Workout>()
+d.includePendingChanges = false
+let batched = try context.fetch(d, batchSize: 200)
+let totalMinutes = batched.reduce(0) { $0 + $1.minutes }
 ```
 
-Note: `includePendingChanges: true` cannot be used with batched fetches
-(`fetch(_:batchSize:)`). This will throw
-`SwiftDataError.includePendingChangesWithBatchSize`.
-
-### propertiesToFetch (Partial Loading)
+## Sorting
 
-Load only specific attributes to reduce memory footprint:
+`SortDescriptor(\.key)` sorts ascending; pass `order: .reverse` for
+descending. Several descriptors sort by the first, then break ties with the
+next:
 
 ```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 ordering = [
+    SortDescriptor(\Workout.calories, order: .reverse),
+    SortDescriptor(\Workout.startedAt, order: .reverse),
+    SortDescriptor(\Workout.title)
 ]
-let trips = try modelContext.fetch(descriptor)
-// Accessing trip.accommodation does not trigger a separate fetch
 ```
 
-### Fetch Variants on ModelContext
+A `Bool` property cannot be a sort key: `SortDescriptor` needs a `Comparable`
+value and `Bool` is not one. Sorting on an optional key works, but do not rely on where `nil` rows land;
+with the SQLite store, `nil` sorts before other values in ascending order.
+Add a tie-breaking descriptor or filter out `nil` when placement matters.
 
-| 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)
+Let the user pick the sort by rebuilding the query in a child view:
 
 ```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
-    ]
-)
-```
+enum WorkoutSortKey: String, CaseIterable { case date, duration, title }
 
-### 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
+struct WorkoutBrowser: View {
+    @State private var key: WorkoutSortKey = .date
+    @State private var order: SortOrder = .reverse
 
     var body: some View {
-        SortedTripList(sortKey: sortKey, sortOrder: sortOrder)
+        SortedWorkouts(key: key, order: order)
             .toolbar {
-                Picker("Sort", selection: $sortKey) {
-                    Text("Name").tag(TripSortKey.name)
-                    Text("Date").tag(TripSortKey.date)
-                    Text("Destination").tag(TripSortKey.destination)
+                Picker("Sort", selection: $key) {
+                    ForEach(WorkoutSortKey.allCases, id: \.self) { Text($0.rawValue) }
                 }
             }
     }
 }
 
-enum TripSortKey: String, CaseIterable {
-    case name, date, destination
-}
-
-struct SortedTripList: View {
-    @Query private var trips: [Trip]
+struct SortedWorkouts: View {
+    @Query private var workouts: [Workout]
 
-    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)
+    init(key: WorkoutSortKey, order: SortOrder) {
+        let descriptor: SortDescriptor<Workout>
+        switch key {
+        case .date: descriptor = SortDescriptor(\.startedAt, order: order)
+        case .duration: descriptor = SortDescriptor(\.minutes, order: order)
+        case .title: descriptor = SortDescriptor(\.title, order: order)
         }
-        _trips = Query(sort: [sortDescriptor])
+        _workouts = Query(sort: [descriptor])
     }
 
-    var body: some View {
-        List(trips) { trip in
-            TripRow(trip: trip)
-        }
-    }
+    var body: some View { List(workouts) { Text($0.title) } }
 }
 ```
 
----
+## Grouping results into sections
 
-## Sectioned Queries Pattern
+There is no sectioned fetch comparable to `NSFetchedResultsController`
+sections. Group the query results yourself.
 
-SwiftData does not provide a built-in sectioned query like Core Data's
-`NSFetchedResultsController`. Build sectioned views manually:
-
-### Using Dictionary Grouping
+By a derived key:
 
 ```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)
+struct WorkoutsByWeek: View {
+    @Query(sort: \Workout.startedAt, order: .reverse) private var workouts: [Workout]
+
+    private var weeks: [(label: String, items: [Workout])] {
+        let grouped = Dictionary(grouping: workouts) { workout in
+            workout.startedAt.formatted(.dateTime.year().week())
         }
-        return grouped.sorted { $0.key < $1.key }
+        return grouped
+            .map { (label: $0.key, items: $0.value) }
+            .sorted { ($0.items.first?.startedAt ?? .distantPast) > ($1.items.first?.startedAt ?? .distantPast) }
     }
 
     var body: some View {
         List {
-            ForEach(sections, id: \.0) { section, trips in
-                Section(section) {
-                    ForEach(trips) { trip in
-                        TripRow(trip: trip)
-                    }
+            ForEach(weeks, id: \.label) { week in
+                Section(week.label) {
+                    ForEach(week.items) { Text($0.title) }
                 }
             }
         }
@@ -334,38 +239,32 @@ struct SectionedTripListView: View {
 }
 ```
 
-### Using Enum-Based Sections
+By a fixed set of buckets, skipping empty ones:
 
 ```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.now
-        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
-            }
+enum WorkoutPhase: CaseIterable {
+    case planned, running, done
+
+    func includes(_ w: Workout, at now: Date) -> Bool {
+        switch self {
+        case .planned: w.startedAt > now
+        case .running: w.startedAt <= now && w.finishedAt == nil
+        case .done: w.finishedAt != nil
         }
     }
+}
+
+struct WorkoutsByPhase: View {
+    @Query(sort: \Workout.startedAt) private var workouts: [Workout]
 
     var body: some View {
+        let now = Date()
         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)
-                        }
+            ForEach(WorkoutPhase.allCases, id: \.self) { phase in
+                let items = workouts.filter { phase.includes($0, at: now) }
+                if !items.isEmpty {
+                    Section(String(describing: phase)) {
+                        ForEach(items) { Text($0.title) }
                     }
                 }
             }
@@ -374,302 +273,195 @@ struct StatusSectionedView: View {
 }
 ```
 
----
+## Changing the query at runtime
 
-## Dynamic Query Switching
-
-### Filter + Sort Controlled by Parent
+The parent owns the inputs; the child turns them into a query in `init`.
 
 ```swift
-struct TripBrowserView: View {
-    @State private var searchText = ""
-    @State private var showFavoritesOnly = false
+struct WorkoutSearch: View {
+    @State private var text = ""
+    @State private var favoritesOnly = false
 
     var body: some View {
         NavigationStack {
-            FilteredTripList(
-                searchText: searchText,
-                favoritesOnly: showFavoritesOnly
-            )
-            .searchable(text: $searchText)
-            .toolbar {
-                Toggle("Favorites", isOn: $showFavoritesOnly)
-            }
+            FilteredWorkouts(text: text, favoritesOnly: favoritesOnly)
+                .searchable(text: $text)
+                .toolbar { Toggle("Favorites", isOn: $favoritesOnly) }
         }
     }
 }
 
-struct FilteredTripList: View {
-    @Query private var trips: [Trip]
+struct FilteredWorkouts: View {
+    @Query private var workouts: [Workout]
 
-    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)]
+    init(text: String, favoritesOnly: Bool) {
+        _workouts = Query(
+            filter: #Predicate<Workout> {
+                (text.isEmpty || $0.title.localizedStandardContains(text))
+                    && (!favoritesOnly || $0.isFavorite)
+            },
+            sort: \.startedAt, order: .reverse
         )
     }
 
-    var body: some View {
-        List(trips) { trip in
-            NavigationLink(trip.name) {
-                TripDetailView(trip: trip)
-            }
-        }
-    }
+    var body: some View { List(workouts) { Text($0.title) } }
 }
 ```
 
-### Full Dynamic Descriptor
+When more than the filter varies, build a whole 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)]
-        )
+struct RecentWorkouts: View {
+    @Query private var workouts: [Workout]
 
-        if let destination {
-            descriptor.predicate = #Predicate<Trip> { trip in
-                trip.destination == destination
-            }
+    init(since start: Date?, limit: Int?) {
+        var d = FetchDescriptor<Workout>(sortBy: [SortDescriptor(\.startedAt, order: .reverse)])
+        if let start {
+            d.predicate = #Predicate { $0.startedAt >= start }
         }
-
         if let limit {
-            descriptor.fetchLimit = limit
+            d.fetchLimit = limit
         }
-
-        _trips = Query(descriptor)
+        _workouts = Query(d)
     }
 
-    var body: some View {
-        List(trips) { trip in
-            TripRow(trip: trip)
-        }
-    }
+    var body: some View { List(workouts) { Text($0.title) } }
 }
 ```
 
----
+## Fetching on a background actor
 
-## Background Fetch Patterns with `@ModelActor`
-
-### Basic Background Fetch
+Actor methods return `Sendable` results, such as identifiers or counts, never
+model objects.
 
 ```swift
 @ModelActor
-actor TripDataHandler {
-    func fetchUpcomingTrips() throws -> [PersistentIdentifier] {
-        let descriptor = FetchDescriptor<Trip>(
-            predicate: #Predicate { $0.startDate > Date.now },
-            sortBy: [SortDescriptor(\.startDate)]
+actor WorkoutStore {
+    func idsOfLongWorkouts(since start: Date) throws -> [PersistentIdentifier] {
+        let d = FetchDescriptor<Workout>(
+            predicate: #Predicate { $0.startedAt >= start && $0.minutes >= 60 }
         )
-        return try modelContext.fetchIdentifiers(descriptor)
+        return try modelContext.fetchIdentifiers(d)
     }
 
-    func fetchTripCount(destination: String) throws -> Int {
-        let descriptor = FetchDescriptor<Trip>(
-            predicate: #Predicate<Trip> { trip in
-                trip.destination == destination
-            }
-        )
-        return try modelContext.fetchCount(descriptor)
+    func favoriteCount() throws -> Int {
+        try modelContext.fetchCount(FetchDescriptor<Workout>(predicate: #Predicate { $0.isFavorite }))
     }
-}
 
-// 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 {
+    func importSessions(_ rows: [SessionRow], progress: @Sendable (Int) -> Void) throws {
+        for (offset, row) in rows.enumerated() {
+            modelContext.insert(Workout(title: row.title, startedAt: row.start,
+                                        minutes: row.minutes, calories: row.calories))
+            if offset.isMultiple(of: 500) && offset > 0 {
                 try modelContext.save()
-                progress(imported)
+                progress(offset)
             }
         }
         try modelContext.save()
-        return imported
+        progress(rows.count)
     }
 }
+
+struct SessionRow: Sendable {
+    let title: String
+    let start: Date
+    let minutes: Int
+    let calories: Double
+}
 ```
 
-### Resolving Identifiers on MainActor
+Saving every 500 rows keeps memory flat during a long import. Call the actor
+from a view with the view's container:
 
 ```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] = []
+struct FavoriteBadge: View {
+    @Environment(\.modelContext) private var context
+    @State private var count = 0
 
     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)
+        Text("\(count)")
+            .task {
+                let store = WorkoutStore(modelContainer: context.container)
+                count = (try? await store.favoriteCount()) ?? 0
             }
-        }
     }
 }
 ```
 
----
-
-## Aggregate Queries
-
-SwiftData does not provide built-in aggregate functions (SUM, AVG, etc.).
-Compute aggregates using fetch + Swift computation.
-
-### Count
+Turning identifiers back into models on the main context: check the objects the
+context already holds, and fetch by identifier otherwise.
 
 ```swift
-let count = try modelContext.fetchCount(
-    FetchDescriptor<Trip>(predicate: #Predicate { $0.isFavorite == true })
-)
+@MainActor
+func resolve(_ ids: [PersistentIdentifier], in context: ModelContext) throws -> [Workout] {
+    try ids.compactMap { id in
+        if let cached: Workout = context.registeredModel(for: id) {
+            return cached
+        }
+        var d = FetchDescriptor<Workout>(predicate: #Predicate { $0.persistentModelID == id })
+        d.fetchLimit = 1
+        return try context.fetch(d).first
+    }
+}
 ```
 
-### 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
-```
+`context.model(for:)` also exists, but it returns an unchecked instance that
+fails on first access if the row was deleted; the fetch above returns `nil`
+instead.
 
-### Efficient Aggregates with Partial Fetch
+## Aggregates
 
-Fetch only the property needed for aggregation:
+SwiftData has no SUM, AVG, MIN or MAX. Fetch what you need and compute in
+Swift; use `fetchCount` for counts. Restrict `propertiesToFetch` so only the
+column being aggregated is loaded.
 
 ```swift
-var descriptor = FetchDescriptor<Trip>()
-descriptor.propertiesToFetch = [\.budget]
-let trips = try modelContext.fetch(descriptor)
-let total = trips.reduce(0.0) { $0 + $1.budget }
+func calorieStats(in context: ModelContext) throws -> (total: Double, average: Double, peak: Double?) {
+    var d = FetchDescriptor<Workout>()
+    d.propertiesToFetch = [\.calories]
+    let values = try context.fetch(d).map(\.calories)
+    let total = values.reduce(0, +)
+    let average = values.isEmpty ? 0 : total / Double(values.count)
+    return (total, average, values.max())
+}
 ```
 
-### Background Aggregate Computation
+Heavy statistics belong on a `@ModelActor` that returns a `Sendable` struct:
 
 ```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)
+struct WeeklySummary: Sendable {
+    let sessions: Int
+    let minutes: Int
+    let longest: Int
+}
 
-        return TripStats(
-            totalCount: allTrips.count,
-            favoriteCount: favoriteCount,
-            averageDuration: avgDuration
-        )
+extension WorkoutStore {
+    func summary(from start: Date) throws -> WeeklySummary {
+        let d = FetchDescriptor<Workout>(predicate: #Predicate { $0.startedAt >= start })
+        let rows = try modelContext.fetch(d)
+        return WeeklySummary(sessions: rows.count,
+                             minutes: rows.reduce(0) { $0 + $1.minutes },
+                             longest: rows.map(\.minutes).max() ?? 0)
     }
 }
 ```
 
----
+## enumerate for large sets
 
-## Enumerate for Large Datasets
-
-Use `enumerate` instead of `fetch` when processing many records to keep memory
-usage constant:
+For big sets, `enumerate` keeps memory flat where `fetch` would load
+everything. Save when the loop is done.
 
 ```swift
-// Process all trips without loading all into memory
-try modelContext.enumerate(
-    FetchDescriptor<Trip>(sortBy: [SortDescriptor(\.startDate)]),
-    batchSize: 1000,
+try context.enumerate(
+    FetchDescriptor<Workout>(),
+    batchSize: 1_000,
     allowEscapingMutations: false
-) { trip in
-    // Process each trip
-    trip.isProcessed = true
+) { workout in
+    workout.calories = (workout.calories * 10).rounded() / 10
 }
-try modelContext.save()
+try context.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.
-
+- `batchSize` defaults to 5,000; a smaller batch uses less memory.
+- With `allowEscapingMutations: false`, objects are released after each batch.
+  Set it to `true` only when changes must survive past the block.