Learning iOS Core Data

A deep, hands-on guide to Core Data in Swift on iOS. We’ll work through the entire framework — the stack, the data model, CRUD, the unforgiving concurrency model, performance optimization, migrations, CloudKit sync — and then show how Core Data integrates with SwiftUI in two ways: the modern property-wrapper path (@FetchRequest, @Environment(\.managedObjectContext)) that’s expedient and good for many apps, and the manual path (custom repositories, NSFetchedResultsController, hand-rolled ObservableObjects) that gives you full control for testable, layered architectures. iOS-specific examples throughout, with attention to the gotchas that bite real apps.

Table of Contents

1. What Core Data Is (and Isn’t)
2. The Core Data Stack: Container, Coordinator, Contexts, Store
3. The Data Model: Entities, Attributes, Relationships
4. NSManagedObject and Code Generation
5. CRUD: Creating, Reading, Updating, Deleting
6. Saving Contexts and the Save Lifecycle
7. NSFetchRequest in Detail
8. NSPredicate Mastery
9. Sort Descriptors and Result Limits
10. Relationships: To-One, To-Many, Many-to-Many
11. Inverse Relationships and Why They Matter
12. Delete Rules
13. Context Concurrency Types
14. Background Contexts and perform/performAndWait
15. Parent-Child Contexts
16. Concurrency Pitfalls and Object IDs
17. Faulting and Object Lifecycles
18. Batch Operations: Insert, Update, Delete
19. Fetch Optimization
20. NSFetchedResultsController
21. SwiftUI: @FetchRequest and @SectionedFetchRequest
22. SwiftUI: @Environment(.managedObjectContext)
23. SwiftUI: Observing NSManagedObject Changes
24. SwiftUI Without Property Wrappers: The Repository Approach
25. SwiftUI Without Property Wrappers: NSFetchedResultsController Bridges
26. SwiftUI Without Property Wrappers: Combine and AsyncSequence
27. SwiftUI Without Property Wrappers: Hand-Rolled ObservableObject
28. Migrations: Lightweight and Manual
29. CloudKit Integration with NSPersistentCloudKitContainer
30. Performance Profiling and Debugging
31. Common Gotchas and Anti-Patterns
32. Where to Go Deeper

1. What Core Data Is (and Isn’t)

Core Data has a reputation. Some teams swear by it, build entire architectures around it, and would never use anything else. Others got burned by it years ago and won’t touch it. Both reactions usually trace back to the same root cause: misunderstanding what Core Data actually is.

Core Data is an object graph manager

The single most important sentence in this guide: Core Data is an object graph manager that happens to support persistence. It is not an ORM. It is not a database. It is not “SQLite with a Swift wrapper.” Internalizing this changes how you reason about it.

What it means in practice: Core Data manages a graph of objects in memory. Those objects (NSManagedObject instances) know about their relationships to each other. The graph supports change tracking (which objects have been inserted, updated, deleted), undo and redo, validation, faulting (lazy materialization of objects from disk), and KVO-based observation. Persistence — saving the graph to a backing store — is one capability among several.

You can use Core Data with no persistent store at all (an in-memory store, useful for tests). The graph behaves the same way. The only difference is that save() doesn’t write anything to disk.

What Core Data is NOT

A list of common misconceptions, with the corrections:

• Not an ORM in the relational sense. In a typical ORM, you map classes to tables, write queries in SQL or a SQL-like DSL, and the framework translates. Core Data has its own query language (NSPredicate and NSFetchRequest), its own model file format (.xcdatamodeld), and abstracts over the storage entirely. You don’t write SQL; you describe what you want, and Core Data figures it out.

• Not “SQLite with a wrapper.” While the default persistent store on iOS is SQLite, the SQL is hidden, the schema is generated by Core Data from your model, and you don’t directly control table layout. If you want SQL access, use GRDB or SQLite.swift.

• Not just for displaying data. Core Data scales to large graphs, supports complex relationship semantics, validation rules, derived properties, and conflict resolution between concurrent edits. It’s appropriate for serious data layers, not just “display some rows.”

• Not slow by default. Core Data has performance pitfalls (we’ll cover them), but a properly used Core Data stack is fast — comparable to direct SQLite for typical workloads. Most “Core Data is slow” stories are stories about misuse: faulting in a tight loop, no indexes, no batch fetching, blocking the main thread.

• Not single-threaded. Core Data has a clear concurrency model (every context is bound to a queue). It’s strict and easy to violate, but it’s not “use one context everywhere.”

When Core Data fits

Use Core Data when you have:

• An object graph with relationships that matter — a User has many Posts, a Post belongs to one User and has many Comments. The relationships aren’t incidental; they’re how your app naturally thinks.
• Need for change tracking — knowing what’s been modified since the last save, undoing, observing.
• Need for fetched results that update the UI as data changes (the NSFetchedResultsController use case — table views, collection views, and SwiftUI lists).
• Multiple parts of your app needing consistent views of the same data (the “single source of truth” property comes mostly for free).
• A model you’ll evolve over time. Core Data has migration support — lightweight for compatible changes, custom for complex ones.
• Apple-platform-only sync via CloudKit. NSPersistentCloudKitContainer is the easiest way to add sync between a user’s devices.

When something else fits better

• You need raw SQL access. Use GRDB. You’ll write SQL, and you’ll be happy.
• You need cross-platform sync (iOS + Android). Look at Realm, Couchbase Lite, or design around your own backend with REST/GraphQL.
• Your data is small and key-value. UserDefaults or a small JSON file might suffice. Don’t bring Core Data for ten preferences.
• You need real-time multi-user collaborative editing. Look at CRDT libraries or Firebase / Realtime Database. Core Data’s conflict resolution isn’t designed for live coediting.
• You’re targeting iOS 17+ and want a Swift-native API. Consider SwiftData. It’s built on Core Data internally but with @Model, @Query, value-type-feeling, and macros instead of .xcdatamodeld files.

Core Data and SwiftData

A note since SwiftData is now in the picture: SwiftData is, in a real sense, Core Data with a different API surface. Same store format under the hood (it can even share an existing Core Data SQLite file if you map carefully). Same concurrency model. Same engine. Wrapped in macros and Swift-native types instead of NSManagedObject subclasses and the model editor.

If you’re starting fresh on iOS 17+ with no existing Core Data, SwiftData is often the right choice — it’s Swift-native, type-safe, and a more modern API. But Core Data remains relevant because:

• A vast number of apps already use Core Data and aren’t going to migrate.
• Some advanced scenarios still require Core Data (custom migration policies, certain CloudKit configurations, fine control over the stack).
• SwiftData is younger and has rough edges, especially around complex predicates, sectioning, and migrations.
• Understanding Core Data makes you a much better SwiftData developer because the underlying mental model is the same.

This guide covers Core Data directly. The mental model and most patterns transfer to SwiftData with minimal adjustment.

Architecture-level placement

In a layered architecture, Core Data sits at the persistence layer. Above it: repositories, services, view models, views. Below it: the file system / SQLite, or CloudKit.

Where you draw the line between “Core Data” and the rest of your app matters a lot. Two extreme positions:

• NSManagedObject everywhere. Pass NSManagedObject instances directly to view models and views. Easiest, fastest to build, tightest coupling.
• NSManagedObject only inside the persistence layer. Map to plain Swift value types (DTOs / domain models) at the boundary. Every read produces value types; every write takes them.

Most production apps land somewhere in between. SwiftUI’s @FetchRequest strongly encourages “NSManagedObject everywhere” for the view layer — it gives you NSManagedObjects directly. We’ll cover both styles thoroughly.

What you’ll learn from this guide

By the end you should be comfortable with:

• The Core Data stack and how its components fit together.
• Designing a data model with the right entities, attributes, relationships, and indexes.
• Writing efficient fetches with NSPredicate and sort descriptors.
• The concurrency model and using background contexts safely.
• Observing changes and keeping the UI in sync — with SwiftUI’s property wrappers and without.
• Performance optimization for large datasets (faulting, prefetching, batches).
• Migrating data models without losing user data.
• Integrating with CloudKit.
• Profiling slow fetches and diagnosing concurrency bugs.

What to internalize

Core Data is an object graph manager that persists. It’s not SQL, not an ORM, not a database. Use it when your app’s natural shape is an object graph with relationships, change tracking, and observation needs. Use something else when you need raw SQL, cross-platform sync without Apple’s stack, or a smaller data set than a graph requires. SwiftData is Core Data with a different face — the patterns transfer.

2. The Core Data Stack: Container, Coordinator, Contexts, Store

The “Core Data stack” is the set of objects that, together, make Core Data work. Knowing each component and how they connect is essential — because when something goes wrong, you need to know which layer to look at.

The components

From the bottom up:

• NSPersistentStore — the actual storage. By default an SQLite file on disk; can also be in-memory, XML (macOS), or binary. You usually have one persistent store, though you can have multiple (e.g., a CloudKit-synced store plus a local-only store).
• NSPersistentStoreCoordinator — coordinates between contexts and persistent stores. Mediates fetches and saves. Most apps have exactly one.
• NSManagedObjectModel — the schema. Loaded from your .xcdatamodeld file at runtime. Describes entities, attributes, relationships.
• NSManagedObjectContext — the working area. Holds the in-memory object graph, tracks changes, validates on save. Apps typically have multiple contexts (one for the main thread / UI, several for background work).
• NSPersistentContainer — the modern convenience type that wires up all of the above with sensible defaults.

When you create an NSPersistentContainer, it builds the model, the coordinator, the store, and a main-queue context for you. You almost always want this convenience type unless you’re writing a custom stack for advanced scenarios.

Setting up a basic stack

The minimal modern setup:

import CoreData

final class PersistenceController {
    static let shared = PersistenceController()

    let container: NSPersistentContainer

    init(inMemory: Bool = false) {
        container = NSPersistentContainer(name: "Model")
        // "Model" matches the name of your .xcdatamodeld file (without extension).

        if inMemory {
            container.persistentStoreDescriptions.first?.url = URL(fileURLWithPath: "/dev/null")
        }

        container.loadPersistentStores { description, error in
            if let error = error as NSError? {
                fatalError("Unresolved Core Data error: \(error), \(error.userInfo)")
            }
        }

        container.viewContext.automaticallyMergesChangesFromParent = true
    }
}

A few things worth unpacking:

• name: "Model" matches the filename of your .xcdatamodeld (without extension). The container loads Model.xcdatamodeld and finds the SQLite file in your app’s Application Support directory by default.

• loadPersistentStores is asynchronous in principle — it can take time on first launch (creating the SQLite file, running migrations). The completion handler runs synchronously after the load in this code, but the call returns to the caller before storage is fully set up if you don’t wait. In practice you wait synchronously here at app launch.

• inMemory: true configures the store to use /dev/null as the file URL, which the SQLite store interprets as “in-memory only.” Useful for tests and SwiftUI previews.

• automaticallyMergesChangesFromParent is critical. When background contexts save, their changes need to propagate to viewContext so your UI updates. Setting this means Core Data does the merging for you. Without it, you’d need to listen for NSManagedObjectContextDidSave notifications and merge manually.

Where the SQLite file lives

By default, the SQLite store goes in Library/Application Support/<your-app-bundle-id>/. You can find the path:

print(container.persistentStoreDescriptions.first?.url?.path ?? "no store URL")

In the simulator, it’ll look something like:

~/Library/Developer/CoreSimulator/Devices/<device-uuid>/data/Containers/Data/Application/<app-uuid>/Library/Application Support/MyApp/Model.sqlite

There are actually three files: Model.sqlite, Model.sqlite-shm (shared memory), and Model.sqlite-wal (write-ahead log). All three are part of the database. The -wal file in particular can be substantial — it accumulates transactions until checkpointed. If you’re inspecting database size, look at all three.

You can open the SQLite file in any SQLite browser to peek at the schema. You’ll see tables like ZUSER, ZPOST, with columns prefixed Z (Core Data’s convention). Don’t modify anything by hand — Core Data has invariants you’d violate.

The view context

container.viewContext is the context tied to the main queue. It’s where you do UI-related Core Data work: fetching for display, observing changes, lightweight edits. It’s automatically NSMainQueueConcurrencyType.

You access it everywhere in your UI code:

let users: [User] = try context.fetch(User.fetchRequest())

Where context is container.viewContext (passed into your view models or accessed via SwiftUI environment).

Background contexts

For heavy work — large imports, batch processing, anything that would block the UI — use a background context:

let backgroundContext = container.newBackgroundContext()
backgroundContext.perform {
    // Work here runs on the context's private queue.
    for json in incomingData {
        let user = User(context: backgroundContext)
        user.name = json["name"] as? String ?? ""
    }
    try? backgroundContext.save()
}

newBackgroundContext() creates a new context with NSPrivateQueueConcurrencyType, parented to the persistent store coordinator (not to viewContext). Each call returns a fresh context. Don’t reuse one across unrelated operations; create one per task or per background subsystem.

Stack diagram (textually)

                    ┌──────────────────────────┐
                    │  NSPersistentContainer    │
                    │  (the convenience wrap)   │
                    └────────────┬─────────────┘
                                 │
        ┌────────────────────────┼────────────────────────┐
        │                        │                        │
┌───────▼──────────┐  ┌──────────▼────────────┐  ┌────────▼─────────────┐
│  viewContext     │  │  background context A  │  │  background context B │
│  (main queue)    │  │  (private queue)       │  │  (private queue)      │
└──────────┬───────┘  └──────────┬─────────────┘  └──────────┬────────────┘
           │                     │                            │
           └─────────┬───────────┴────────────────────────────┘
                     │
       ┌─────────────▼──────────────┐
       │  NSPersistentStoreCoordinator │
       └─────────────┬──────────────┘
                     │
       ┌─────────────▼──────────────┐
       │  NSPersistentStore         │
       │  (SQLite at Model.sqlite)  │
       └────────────────────────────┘

Each context has its own copy of the object graph (its own NSManagedObject instances), but they share the underlying store via the coordinator. A save in one context goes through the coordinator to the store; if another context has automaticallyMergesChangesFromParent = true, it picks up the changes.

Configuration options on the container

A few options worth knowing:

let description = container.persistentStoreDescriptions.first!

// Enable persistent history tracking — required for many features (CloudKit, batch operations).
description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)

// Enable remote change notifications — get notified when another context (including outside your process) changes data.
description.setOption(true as NSNumber, forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)

NSPersistentHistoryTrackingKey enables a write-ahead log that records every change. This is required if you want to use batch operations and have those changes reflected in contexts (we’ll cover this in section 18). It’s also required for NSPersistentCloudKitContainer. Best practice: enable it from the start unless you have a specific reason not to.

NSPersistentStoreRemoteChangeNotificationPostOptionKey makes Core Data post NSPersistentStoreRemoteChange notifications when something changes in the store, useful when multiple processes (your app + a Share extension, for instance) share the same store via an app group.

Integrating with SwiftUI

For SwiftUI, the persistence controller exposes its viewContext via the environment:

@main
struct MyApp: App {
    let persistenceController = PersistenceController.shared

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(\.managedObjectContext, persistenceController.container.viewContext)
        }
    }
}

Then any view can access it:

struct ContentView: View {
    @Environment(\.managedObjectContext) private var context
    var body: some View { /* ... */ }
}

Or use @FetchRequest for declarative fetches. We’ll cover both extensively.

Common stack mistakes

Three mistakes I see frequently:

1. Treating the container as a heavyweight singleton you initialize lazily. You really want it created and loaded at app launch, before any UI tries to use it. Lazy initialization on first use leads to weird timing bugs.

2. Making the persistence controller’s init async or throwing. It’s fine for init to call loadPersistentStores synchronously and fatalError on failure. A failed Core Data load means the user can’t use your app; there’s nothing you can do at runtime to recover.

3. Forgetting automaticallyMergesChangesFromParent. Without it, your background imports save successfully but the UI doesn’t update. You’ll spend an afternoon debugging “why don’t I see the new data” before realizing the merge is not automatic.

What to internalize

The Core Data stack is NSPersistentContainer (modern convenience) wrapping a model, a coordinator, persistent stores, and one or more contexts. viewContext is on the main queue for UI. newBackgroundContext() gives you a private-queue context for heavy work. Set automaticallyMergesChangesFromParent = true on viewContext. Enable persistent history tracking. Initialize the container synchronously at launch.

3. The Data Model: Entities, Attributes, Relationships

The data model is the schema for your object graph. It lives in a .xcdatamodeld file in your project. The model editor is a visual tool, but everything it does ultimately produces an NSManagedObjectModel at runtime.

Creating the model file

In Xcode: File → New → File → Data Model. Name it whatever your NSPersistentContainer(name:) expects — typically the same as your project name or just “Model”.

The file is actually a directory (.xcdatamodeld) containing one or more .xcdatamodel versions. Each version is a snapshot; when you change the schema in a way that requires migration, you create a new version.

Entities

An entity is roughly equivalent to a class — it’s a named, structured shape with attributes and relationships. In SQL terms, an entity becomes a table.

To create one: in the model editor, click “Add Entity”. Give it a name. Conventionally, entity names are PascalCase singular: User, Post, Comment, not users or Posts.

Each entity has:

• A name (used in fetches: NSFetchRequest<NSManagedObject>(entityName: "User")).
• Optionally a parent entity (Core Data supports entity inheritance — rarely needed; we’ll cover briefly).
• A class name (defaults to NSManagedObject but you’ll usually subclass).
• A set of attributes.
• A set of relationships.
• A set of fetch indexes (for query performance).
• Optionally a constraint (uniqueness rules).

Attributes

An attribute is a typed field on an entity. Types available:

• Integer 16, 32, 64 — different bit widths. Use Integer 64 for general-purpose integers.
• Decimal — base-10 decimal. For currency and precise values where floating-point error is unacceptable.
• Double / Float — floating-point.
• Boolean — true/false. Stored as 0/1 internally.
• Date — Date value.
• String — variable-length text.
• Binary Data — raw Data. The model editor has a “Allows External Storage” option that stores large blobs outside the SQLite file (in Application Support).
• UUID — stored efficiently; great for entity identifiers.
• URI — stored as a URL.
• Transformable — anything Codable or supporting NSSecureCoding. We’ll discuss in detail.

For each attribute you can configure:

• Optional. Whether nil is allowed. Warning: in the model editor, “Optional” defaults to checked — if you uncheck it, you must always provide a value before save, or save fails with a validation error.
• Default value. The value used when an instance is first created.
• Indexed in Spotlight, Stored in External Record File — features for system search integration. Mostly not used in modern apps.
• Use Scalar Type — for numeric and Boolean attributes, generates Int64, Bool, etc. instead of NSNumber. Almost always what you want for Swift.
• Validation — minimum/maximum, regex patterns. Validation runs at save time.

For Date attributes, “Use Scalar Type” gives you Date instead of NSDate. You almost always want this on iOS.

A first model

Let’s design a simple model for a notes app. We’ll have Folder, Note, and Tag:

Folder
├── id: UUID
├── name: String
├── createdAt: Date
└── notes -> Note (to-many)

Note
├── id: UUID
├── title: String
├── body: String
├── createdAt: Date
├── updatedAt: Date
├── folder -> Folder (to-one, inverse of Folder.notes)
└── tags -> Tag (to-many)

Tag
├── id: UUID
├── name: String
└── notes -> Note (to-many, inverse of Note.tags)

In the model editor:

1. Add three entities: Folder, Note, Tag.
2. For each, add the attributes listed.
3. Set “Use Scalar Type” on all the scalar attributes.
4. Set defaults: id = UUID() (you can’t actually set this in the editor; we’ll set it in code), createdAt = Date() (similar), or leave the defaults blank and set them programmatically on insert.
5. Add the relationships (we’ll cover the details in section 10).

Optional vs required: the trap

The “Optional” checkbox on attributes is one of Core Data’s most common gotchas.

If Optional is unchecked (i.e., the attribute is required), Core Data validates at save time that the attribute has a value. If you’ve configured Use Scalar Type for, say, an Int64, the runtime type is Int64 (non-optional) — but Core Data still treats “0” as a missing value in some contexts. Stick with consistent decisions:

• Make the attribute required + provide a default value in the model. The default ensures save validation passes.
• Or make the attribute optional + handle nil in your code.

Avoid: required + no default + relying on yourself to always set it. You’ll save without setting it once and crash.

For UUIDs and dates that should always have a value, my recommendation:

• Make them required.
• Don’t set a default in the model (the editor doesn’t let you specify UUID() or Date()).
• Use the “awakeFromInsert” hook in your NSManagedObject subclass (we’ll see this in section 4) to set them programmatically.

public override func awakeFromInsert() {
    super.awakeFromInsert()
    self.id = UUID()
    self.createdAt = Date()
}

This runs once when the object is first inserted, before save. Required attributes get values; validation passes.

Transformable attributes

A Transformable attribute stores any object that supports NSSecureCoding. This includes things like [String], [String: String], custom Codable objects (with extra setup), UIColor, etc.

Setup:

1. Set the attribute’s type to Transformable.
2. Optionally specify a custom Value Transformer Name if you have a non-default transformer.
3. Optionally specify the Custom Class for compile-time type safety.

The default transformer is NSSecureUnarchiveFromDataTransformer, which uses NSSecureCoding. For Swift Codable types, you’ll usually write a custom transformer or a manual codable bridge.

@objc(StringArrayValueTransformer)
final class StringArrayValueTransformer: NSSecureUnarchiveFromDataTransformer {
    static let name = NSValueTransformerName(rawValue: "StringArrayValueTransformer")
    override class var allowedTopLevelClasses: [AnyClass] {
        [NSArray.self, NSString.self]
    }

    static func register() {
        let transformer = StringArrayValueTransformer()
        ValueTransformer.setValueTransformer(transformer, forName: name)
    }
}

Register at app launch:

StringArrayValueTransformer.register()

In the model editor, set the attribute’s Value Transformer Name to StringArrayValueTransformer.

For larger blobs, prefer Binary Data with “Allows External Storage” — Core Data offloads large blobs to separate files automatically.

Indexes

For attributes you query against frequently, add a fetch index. In the model editor, select an entity and look at the “Indexes” section.

A fetch index is a database index — it makes WHERE clauses on that attribute fast. Without an index, queries on a column do a full scan; with one, they hit the index directly.

Add indexes on:

• Foreign-key-like attributes you filter by (your id, userID, etc.).
• Date attributes you sort by (createdAt, updatedAt).
• Attributes used in predicates of fetches that run often.

Don’t add indexes on attributes you rarely query — they slow down writes.

A composite index covers multiple columns: (folder, createdAt) for “notes in folder X sorted by date”. Composite indexes only help when the query uses the leftmost columns first.

Constraints

You can add uniqueness constraints to an entity. In the model editor, select the entity, look at “Constraints”, and add a constraint listing the attributes that must together be unique.

Common: a unique constraint on id so you can’t have two User rows with the same UUID.

User constraint: id

When you save with a violation, Core Data either fails the save or — with the right merge policy — automatically resolves by replacing/merging. You configure the merge policy on the context:

context.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy

Available policies:

• NSErrorMergePolicy (default) — fail the save with an error.
• NSMergeByPropertyStoreTrumpMergePolicy — store wins; in-memory changes lost.
• NSMergeByPropertyObjectTrumpMergePolicy — in-memory wins; store overwritten.
• NSOverwriteMergePolicy — overwrite the store.
• NSRollbackMergePolicy — discard in-memory changes.

For an “upsert” pattern (insert if missing, update if present), use NSMergeByPropertyObjectTrumpMergePolicy plus a unique constraint on the identifier.

Configurations

Configurations let you assign entities to specific persistent stores. Most apps don’t use this, but it’s useful when you have:

• Some entities synced via CloudKit, others local-only.
• Some entities in a read-only seed store, others in a writable store.

In the editor’s “Configurations” section, you create named configurations and assign entities to them. Then in code, you assign each configuration to a specific store.

Versioning

When you change the model in a way that requires migration, you don’t edit the existing version — you create a new version. Editor menu: Editor → Add Model Version.

The current version is selected via the model file’s “Versioned Model” inspector. When the new version differs from the deployed version on user devices, Core Data attempts migration on next launch (lightweight if possible, heavy otherwise). Section 28 covers this in detail.

What to internalize

Your model file contains entities (think: tables) with attributes (columns) and relationships (foreign keys). Optional vs required is significant; use awakeFromInsert to set required values like UUIDs and dates. Use scalar types in Swift. Add indexes to attributes you query. Use constraints + merge policies for upsert semantics. Use Transformable carefully; prefer Binary Data with external storage for large blobs.

4. NSManagedObject and Code Generation

Every entity in your model has a corresponding runtime class — by default, NSManagedObject directly. For real apps you almost always create a subclass per entity. The subclass gives you typed properties, custom methods, and a place to attach behavior.

Xcode can generate these subclasses for you, manually or automatically. Understanding the options matters: pick the wrong one and you’ll have duplicate-symbol errors, missing properties, or constant manual regeneration.

Three codegen options

In the model editor, select an entity, open the inspector (right side), and look at “Codegen”. Three choices:

• Manual/None — Core Data generates nothing. You write the entire NSManagedObject subclass by hand.
• Class Definition (default) — Core Data generates the subclass invisibly at build time, in DerivedData. You don’t see the file in your project, but the class exists and can be referenced.
• Category/Extension — Core Data generates an extension to a class you provide. You write the class skeleton; Core Data generates @NSManaged properties for the attributes/relationships.

For non-trivial apps, Manual/None is usually the right choice. You get full control, no generated code in DerivedData behaving like magic, and the subclass is visible in your project.

Writing an NSManagedObject subclass manually

For our Note entity:

import Foundation
import CoreData

@objc(Note)
public final class Note: NSManagedObject {
    @NSManaged public var id: UUID
    @NSManaged public var title: String
    @NSManaged public var body: String
    @NSManaged public var createdAt: Date
    @NSManaged public var updatedAt: Date
    @NSManaged public var folder: Folder?
    @NSManaged public var tags: Set<Tag>

    public override func awakeFromInsert() {
        super.awakeFromInsert()
        let now = Date()
        self.id = UUID()
        self.createdAt = now
        self.updatedAt = now
    }
}

extension Note {
    @nonobjc public class func fetchRequest() -> NSFetchRequest<Note> {
        NSFetchRequest<Note>(entityName: "Note")
    }
}

Things to notice:

• @objc(Note) exposes the Swift class name to the Objective-C runtime as Note. Core Data uses this name to map between the model and the runtime class. The string in @objc(...) must match what you put in the model editor’s “Class” field for that entity.

• @NSManaged tells the compiler “this property’s storage is provided dynamically by NSManagedObject.” Core Data implements the getters and setters at runtime. You can’t initialize these in init or have side effects in their accessors via Swift property observers — they’re not real Swift stored properties.

• The Set<Tag> for the to-many relationship reflects how Core Data exposes to-many relationships in modern Swift. For an unordered relationship, Set<T> is the right type. For an ordered relationship, you use NSOrderedSet.

• awakeFromInsert is called once when the object is first inserted into a context. This is the right place to set required defaults like UUIDs and creation dates.

• The fetchRequest() factory is a static method that returns a typed NSFetchRequest<Note>. With Class Definition codegen this is generated for you; with manual you write it.

@NSManaged and KVO

@NSManaged properties go through the Objective-C runtime’s KVO machinery. This is how Core Data implements:

• Lazy loading (faulting): on access, Core Data fires the fault and loads the value from the store.
• Change tracking: setting a property records the change in the context’s pending changes.
• Validation: setting a property can run validation.
• Observation: external observers (KVO, SwiftUI’s ObservableObject-via-NSManagedObject) get notified.

A consequence: you can’t override @NSManaged accessors directly. To customize behavior, use willChangeValue(forKey:) / didChangeValue(forKey:) patterns or override willSave() for save-time transformations.

Computed properties and helpers

You can absolutely add computed properties and helper methods on your subclass — they don’t need @NSManaged:

extension Note {
    var displayTitle: String {
        title.isEmpty ? "Untitled" : title
    }

    var preview: String {
        String(body.prefix(100))
    }

    func touch() {
        updatedAt = Date()
    }

    static func fetchAll(in context: NSManagedObjectContext,
                        sortedBy keyPath: String = "updatedAt",
                        ascending: Bool = false) throws -> [Note] {
        let request = Note.fetchRequest()
        request.sortDescriptors = [NSSortDescriptor(key: keyPath, ascending: ascending)]
        return try context.fetch(request)
    }
}

Pure-Swift computed properties and methods are fine. They don’t go through the runtime’s dynamic dispatch.

Validation hooks

NSManagedObject provides several override points for validation:

public override func validateForInsert() throws {
    try super.validateForInsert()
    // Custom validation when inserting
    try validateBody()
}

public override func validateForUpdate() throws {
    try super.validateForUpdate()
    try validateBody()
}

private func validateBody() throws {
    if title.isEmpty && body.isEmpty {
        throw NSError(domain: "Note", code: 1,
                      userInfo: [NSLocalizedDescriptionKey: "Note must have a title or body"])
    }
}

These run automatically when the context is saved. If they throw, the save fails. Use them for invariants the database itself doesn’t enforce.

There’s also per-attribute validation via methods named validate<AttributeName>:error:. They get called during save, with the value about to be saved as a parameter (you can change it).

Lifecycle hooks

Beyond awakeFromInsert:

• awakeFromFetch — called after the object is fetched from the store. Use sparingly; modifying state here is risky because it doesn’t mark the object as “changed.”
• willSave — called just before save. The right place for updatedAt = Date() so every save updates the timestamp.
• didSave — called after save. Useful for cleaning up post-save state.
• willTurnIntoFault — called when the object is about to become a fault (we’ll cover faults in section 17).
• prepareForDeletion — called when the object is about to be deleted. Useful for cleanup of resources tied to the object.

public override func willSave() {
    super.willSave()
    if isUpdated && !isDeleted {
        if updatedAt == nil || updatedAt < Date(timeIntervalSinceNow: -0.01) {
            // updatedAt itself counts as a change; the time-window check prevents infinite recursion.
            self.updatedAt = Date()
        }
    }
}

Be very careful with willSave: setting a property re-fires willSave if the new value triggers another change. Use guards like the time-window check above to prevent infinite loops.

Generating subclasses with Editor → Create NSManagedObject Subclass

Xcode has a menu item that generates subclass files for you (Editor → Create NSManagedObject Subclass… when a model is selected). It’s useful for the initial scaffolding. You then switch the entity’s Codegen to “Manual/None” and edit the generated files freely.

What it generates: two files per entity. Note+CoreDataClass.swift for the class itself, Note+CoreDataProperties.swift for the @NSManaged properties. You can collapse them into one if you prefer.

I personally consolidate into one file per entity (Note.swift) — easier to find things.

Faults and accessors

When you access a @NSManaged property on a faulted object, Core Data fires the fault: it goes to the store, fetches the row’s data, and populates the object’s properties. The next access is just a memory read.

This is mostly invisible. The reason it matters: in tight loops, you’re firing faults you didn’t intend. Pre-fetching (covered in section 19) avoids it.

You can check fault state:

if note.isFault {
    // The object exists but its data hasn't been loaded yet.
}

For a relationship, you can check whether it’s a fault:

if note.faultingState == 0 {
    // Object's data is loaded.
}

Working with relationships

For a to-many relationship typed as Set<Tag>, you read it like any Set:

let tagNames = note.tags.map(\.name)

To modify, mutate the property:

note.tags.insert(tag)
note.tags.remove(tag)
note.tags = []  // remove all tags from this note (preserves Tag objects)

For relationships exposed as NSSet (in older codegen), Core Data provides KVC accessors:

note.mutableSetValue(forKey: "tags").add(tag)  // works but verbose

Modern Swift prefers Set<Tag> directly. The NSSet versions still work if you have inherited code.

Subclass inheritance

You can have entity inheritance in Core Data — making an entity a subclass of another. In SQL terms, this can be implemented with single-table inheritance (one table for parent and all children). The model editor lets you set “Parent Entity”.

Inheritance is rarely the right choice. It bakes assumptions into your schema that are hard to migrate, and mostly the same effects can be achieved with composition and optional relationships. Use inheritance sparingly, if at all.

What to internalize

Your NSManagedObject subclass has @NSManaged properties for entity attributes/relationships. Use Manual codegen for control. awakeFromInsert sets required defaults. Lifecycle hooks (willSave, prepareForDeletion) let you attach behavior. Add computed properties and helpers freely. Don’t override @NSManaged accessors directly. Avoid entity inheritance unless you have a strong reason.

5. CRUD: Creating, Reading, Updating, Deleting

The four operations every persistence layer supports. Core Data has a specific way to do each, and a couple of subtleties worth knowing.

Creating

To insert a new object, you initialize it on a context:

let note = Note(context: viewContext)
note.title = "First note"
note.body = "Hello, world."

try? viewContext.save()

That’s it. The object is now in the context, marked as inserted. On the next save, it’s written to the store.

Behind the scenes, Note(context:) calls NSEntityDescription.insertNewObject(forEntityName: "Note", into: context) and casts the result. The awakeFromInsert hook runs. Required defaults get set.

Alternative initialization patterns

Two other patterns you’ll see:

// Using NSEntityDescription directly:
let entity = NSEntityDescription.entity(forEntityName: "Note", in: viewContext)!
let note = Note(entity: entity, insertInto: viewContext)

// Older / KVC-style (don't do this, but you'll see it in legacy code):
let note = NSEntityDescription.insertNewObject(forEntityName: "Note", into: viewContext) as! Note

The Note(context:) form is the cleanest in modern Swift. The other forms are equivalent but more verbose.

Reading

Reading is via NSFetchRequest. The simplest fetch:

let request = Note.fetchRequest()
do {
    let notes = try viewContext.fetch(request)
    print("Loaded \(notes.count) notes")
} catch {
    print("Fetch failed: \(error)")
}

fetch(_:) returns an array of results. The fetch runs synchronously on the context’s queue. We’ll explore NSFetchRequest in depth in section 7.

For a single object by ID:

func note(withID id: UUID, in context: NSManagedObjectContext) -> Note? {
    let request = Note.fetchRequest()
    request.predicate = NSPredicate(format: "id == %@", id as CVarArg)
    request.fetchLimit = 1
    return try? context.fetch(request).first
}

We set fetchLimit = 1 because we only need one row; the SQLite query stops as soon as it finds a match instead of scanning further.

Reading all of an entity

let request = Note.fetchRequest()
let allNotes = try viewContext.fetch(request)

Beware: fetch returns all matching rows. For thousands of notes this might be a lot. Use fetchLimit, predicates, or NSFetchedResultsController for paging.

Updating

Updating is just setting properties:

note.title = "Updated title"
try? viewContext.save()

The context tracks the change. On save, the row is updated.

If you want to know whether a specific object has been modified since the last save:

if note.hasChanges {
    print("Note has unsaved changes")
}

Or check the context overall:

if viewContext.hasChanges {
    try? viewContext.save()
}

Bulk updates

For updating many objects, you have two options:

1. Fetch all, mutate, save (the slow path).
2. Use NSBatchUpdateRequest (the fast path; covered in section 18).

For a few dozen objects, option 1 is fine. For thousands, use batch updates.

Deleting

Mark for deletion:

viewContext.delete(note)
try? viewContext.save()

The object is marked as deleted; it’s removed from the store on save. After delete(_:), the object is still in memory but its isDeleted is true. After save, the object is invalid — accessing properties may crash.

For batch deletes, use NSBatchDeleteRequest (section 18).

Soft delete

Sometimes you want “deleted” to be a flag, not actual removal. Add a deletedAt: Date? attribute, set it to Date() instead of calling context.delete(_:). Filter your fetches to exclude soft-deleted objects:

request.predicate = NSPredicate(format: "deletedAt == nil")

Soft delete is useful for:

• “Recently deleted” recovery.
• Sync with a backend that needs to know about deletions.
• Audit trails.

The trade-off: every fetch needs to exclude deleted objects, and you accumulate dead rows over time. Decide based on your use case.

Counting without fetching

Sometimes you want a count, not the objects:

let count = try? viewContext.count(for: Note.fetchRequest())

This runs a SELECT COUNT(*) in SQLite and returns the count without materializing objects. Faster than fetching and counting.

For a count with predicate:

let request = Note.fetchRequest()
request.predicate = NSPredicate(format: "folder == %@", folder)
let count = try? viewContext.count(for: request)

existingObject(with:)

Given an object’s NSManagedObjectID, you can get the object in any context:

let id = note.objectID  // permanent ID after save; temporary before
let existing = try? otherContext.existingObject(with: id) as? Note

This is crucial for cross-context work (section 16). The object ID is the only safe way to refer to a Core Data object across contexts.

Discarding changes

If you’ve made edits in a context but don’t want to save them:

viewContext.rollback()  // discard all unsaved changes
viewContext.refreshAllObjects()  // reload fresh data from store
viewContext.reset()  // throw away all in-memory state; objects become invalid

Three different operations with three different effects:

• rollback() undoes inserts/updates/deletes since the last save. Existing objects revert to their last-saved values.
• refreshAllObjects() keeps your inserts but turns existing objects into faults — they’ll re-fetch their data from the store on next access.
• reset() is more aggressive — it throws away every object the context knows about. Use with care: any existing reference to an object becomes a stale reference.

For UI state recovery (e.g., user taps “Cancel” on an editor), rollback() is what you want.

Refreshing

If another part of your app modified data and you want this context to see the updates:

viewContext.refresh(note, mergeChanges: true)

mergeChanges: true keeps your local in-memory edits; the refresh just loads the latest persisted data and merges. mergeChanges: false discards your local edits.

You don’t usually need this in modern apps with automaticallyMergesChangesFromParent, but it’s the manual fallback if automatic merging isn’t enabled.

Putting it together

A typical “create or update” flow for syncing data from a server:

func upsertNote(from json: [String: Any], in context: NSManagedObjectContext) throws -> Note {
    guard let idString = json["id"] as? String,
          let id = UUID(uuidString: idString) else {
        throw NSError(domain: "Sync", code: 1)
    }

    let request = Note.fetchRequest()
    request.predicate = NSPredicate(format: "id == %@", id as CVarArg)
    request.fetchLimit = 1

    let note = try context.fetch(request).first ?? Note(context: context)

    if note.isInserted {
        note.id = id
    }
    note.title = json["title"] as? String ?? ""
    note.body = json["body"] as? String ?? ""
    if let timestamp = json["updatedAt"] as? TimeInterval {
        note.updatedAt = Date(timeIntervalSince1970: timestamp)
    }

    return note
}

Even cleaner with a unique constraint on id and NSMergeByPropertyObjectTrumpMergePolicy:

context.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy

let note = Note(context: context)
note.id = idFromJSON
note.title = ...
// On save, if a note with the same id exists, the constraint causes a conflict;
// the merge policy resolves by overwriting the existing object's properties.
try context.save()

This is genuinely upsert behavior at the database level — no fetch needed first.

What to internalize

Insert via Note(context:). Update by setting properties. Delete via context.delete(_:). Save with context.save(). Use NSBatchUpdateRequest and NSBatchDeleteRequest for many-row operations. Use objectID and existingObject(with:) for cross-context references. Use unique constraints + merge policies for upsert semantics. Soft-delete is a pattern, not a built-in feature.

6. Saving Contexts and the Save Lifecycle

Saving a context isn’t atomic in the simple sense of “write some bytes to disk.” It’s a sequence of validation, conflict resolution, persistence, notifications, and merging. Knowing the lifecycle helps you debug save failures and design save strategies that scale.

What save() actually does

Calling context.save() triggers, roughly, this sequence:

1. Validation. Each inserted and updated object’s validateForInsert() or validateForUpdate() runs, plus per-attribute validation methods.
2. willSave is called on each pending object.
3. Coordinator interaction. The context asks the persistent store coordinator to persist the changes.
4. Conflict resolution. If another context has saved conflicting changes since this context fetched, the merge policy decides what to do.
5. Store write. The coordinator passes the changes to the persistent store (SQLite), which writes them.
6. didSave is called on each saved object.
7. NSManagedObjectContextDidSave notification fires, with userInfo containing inserted/updated/deleted objects.
8. Other contexts merge. If automaticallyMergesChangesFromParent is true, sibling contexts pick up the changes and update their in-memory state.

If validation fails or conflicts can’t be resolved, save() throws and step 5 onward doesn’t happen. The context’s pending changes are still pending.

Error handling

save() is throws. Always handle errors:

do {
    try context.save()
} catch let error as NSError {
    print("Save failed: \(error.localizedDescription)")
    print("Details: \(error.userInfo)")
}

The NSError’s userInfo is rich:

• NSValidationKeyErrorKey — the property that failed validation.
• NSValidationObjectErrorKey — the object that failed.
• NSValidationValueErrorKey — the value that was invalid.
• NSDetailedErrors — for multiple validation failures, an array of individual errors.

For multi-object validation failures:

if let detailedErrors = error.userInfo[NSDetailedErrorsKey] as? [NSError] {
    for detailedError in detailedErrors {
        print(" - \(detailedError.localizedDescription)")
    }
}

When to save

A common mistake: save after every change. Don’t. Saves are expensive — they go through validation, conflict resolution, and a SQLite write.

Reasonable strategies:

• Save explicitly when the user does something save-worthy. They tap “Done”, they switch screens, the app goes to background.
• Save in batches. A bulk import does many inserts, then one save at the end.
• Save on app backgrounding. A scene-phase observer catches the moment to flush:

.onChange(of: scenePhase) { _, newPhase in
    if newPhase == .background {
        try? PersistenceController.shared.container.viewContext.save()
    }
}

Don’t save in tight loops. Don’t save inside an enumeration of fetched objects. One save at the end is typically right.

The save lifecycle hooks

We saw these in section 4. They’re the right places for derived value updates and cleanup:

• willSave() — last chance to compute derived values like updatedAt.
• didSave() — post-save notifications.
• prepareForDeletion() — cleanup before delete propagates.

public override func willSave() {
    super.willSave()
    // Update updatedAt only if it didn't change in this save cycle (avoid loops).
    let changes = changedValuesForCurrentEvent()
    if !changes.keys.contains("updatedAt") && (isInserted || isUpdated) {
        self.updatedAt = Date()
    }
}

changedValuesForCurrentEvent() returns just the changes about to be written in this specific save, not all unsaved changes. This is the key to avoiding willSave loops.

Conflict resolution

When two contexts modify the same object and both save, you have a conflict.

Concretely: context A fetches a note, context B fetches the same note. A modifies title to “X” and saves. B modifies title to “Y” and saves. What ends up in the store?

The resolution depends on the merge policy of the saving context. For NSMergeByPropertyStoreTrumpMergePolicy, B’s save loses to whatever’s in the store (which now has A’s “X”). For NSMergeByPropertyObjectTrumpMergePolicy, B’s “Y” wins.

To detect conflicts at save time:

do {
    try context.save()
} catch let error as NSError {
    if error.domain == NSCocoaErrorDomain {
        if let conflicts = error.userInfo[NSPersistentStoreSaveConflictsErrorKey] as? [NSMergeConflict] {
            for conflict in conflicts {
                print("Conflict on \(conflict.sourceObject)")
            }
        }
    }
}

For most apps, set the merge policy at context creation:

context.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy

And don’t worry about conflicts thereafter. The policy handles them automatically.

Notifications during save

Several notifications fire around save:

• NSManagedObjectContextWillSave — just before save begins.
• NSManagedObjectContextDidSave — after save completes successfully. This is the primary hook for cross-context merging.
• NSManagedObjectContextObjectsDidChange — fires whenever objects change, including unsaved changes. Useful for live UI updates.

Listen for them:

NotificationCenter.default.addObserver(
    forName: .NSManagedObjectContextDidSave,
    object: nil,
    queue: nil
) { notification in
    guard let savedContext = notification.object as? NSManagedObjectContext,
          savedContext !== self.viewContext else { return }
    self.viewContext.perform {
        self.viewContext.mergeChanges(fromContextDidSave: notification)
    }
}

If you set automaticallyMergesChangesFromParent = true, you don’t write this code — Core Data does it for you. But if you need custom merge behavior (e.g., logging changes before merging), you write a manual handler.

The userInfo of save notifications

NSManagedObjectContextDidSave’s userInfo has:

• NSInsertedObjectsKey → Set<NSManagedObject> of inserted objects.
• NSUpdatedObjectsKey → Set<NSManagedObject> of updated objects.
• NSDeletedObjectsKey → Set<NSManagedObject> of deleted objects.

You can inspect them:

if let inserted = notification.userInfo?[NSInsertedObjectsKey] as? Set<NSManagedObject> {
    for obj in inserted {
        print("Inserted: \(obj)")
    }
}

Critical caveat: these objects are tied to the saving context’s queue. If you receive the notification on a different context, you can’t safely access those objects — only their objectIDs. Use existingObject(with:) on the receiving context to get a usable instance.

Asynchronous saves

Modern code can save asynchronously:

try await context.perform {
    try context.save()
}

Or:

context.perform {
    do {
        try context.save()
    } catch {
        print("Save failed: \(error)")
    }
}

perform schedules a closure on the context’s queue and returns immediately (or, in the async version, suspends until the closure completes). For background contexts especially, always use perform to ensure you’re on the right queue.

Persistent history tracking and save

When persistent history tracking is enabled, every save writes an entry to a history table in the SQLite store. You can query this history later to discover changes that happened in other processes (a Share extension, for example) or to drive sync. Most apps don’t need to query history directly, but enabling tracking is required for batch operations and CloudKit sync.

What to internalize

save() validates, persists, and notifies. Always handle errors — they’re informative. Set a merge policy to handle conflicts gracefully. Don’t save after every change; save at coherent moments (user action, app backgrounding). The NSManagedObjectContextDidSave notification is the basis for cross-context merging, but automaticallyMergesChangesFromParent automates it. Use willSave() carefully for derived values, with guards against loops.

7. NSFetchRequest in Detail

NSFetchRequest is the workhorse for reading data. It’s deceptively simple — entity name, predicate, sort, fetch — but has a dozen knobs that affect performance dramatically. Knowing them is the difference between fast fetches and a scrollable list that hitches.

The basics

let request = NSFetchRequest<Note>(entityName: "Note")
request.predicate = NSPredicate(format: "folder == %@", folder)
request.sortDescriptors = [NSSortDescriptor(key: "createdAt", ascending: false)]
let notes = try context.fetch(request)

The generic parameter <Note> types the result, so notes is [Note]. You can use <NSManagedObject> if you don’t have a specific subclass.

When you have an NSManagedObject subclass with fetchRequest() static method, the typed form is cleaner:

let request: NSFetchRequest<Note> = Note.fetchRequest()

predicate — filtering

The predicate decides which rows match. We’ll go deep on predicates in section 8. A taste:

request.predicate = NSPredicate(format: "title CONTAINS[cd] %@", searchText)

[cd] flags mean case-insensitive and diacritic-insensitive. The %@ is a placeholder filled by the searchText value.

sortDescriptors — ordering

Always set sort descriptors, even if you “don’t care” about order. Without them, the order is undefined and may change between fetches. For consistent results:

request.sortDescriptors = [
    NSSortDescriptor(key: "createdAt", ascending: false),
    NSSortDescriptor(key: "id", ascending: true)
]

The second sort descriptor breaks ties; without it, two notes with the same createdAt could appear in inconsistent order.

For string sorting, you usually want localized comparison:

NSSortDescriptor(key: "name", ascending: true, selector: #selector(NSString.localizedCaseInsensitiveCompare))

This sorts strings respecting the user’s locale (Æ properly placed, accents handled, etc.).

fetchLimit and fetchOffset

Limit how many results to return; useful for paging:

request.fetchLimit = 50         // first 50
request.fetchOffset = 0         // starting at the beginning

For the next page:

request.fetchLimit = 50
request.fetchOffset = 50         // skip the first 50

fetchOffset with large offsets is slow on SQLite (it scans through the skipped rows). For large data sets, prefer “keyset pagination”: fetch all rows where createdAt < lastCreatedAt, with a limit.

request.predicate = NSPredicate(format: "createdAt < %@", lastDate as NSDate)
request.sortDescriptors = [NSSortDescriptor(key: "createdAt", ascending: false)]
request.fetchLimit = 50

fetchBatchSize — the magic knob

For results you’ll iterate over but might not consume entirely, set fetchBatchSize:

request.fetchBatchSize = 20

This tells Core Data to return a proxy array that, when accessed, fetches only 20 objects at a time. As you iterate past the first 20, Core Data fetches the next 20, etc.

Before fetchBatchSize, fetching 10,000 rows materialized 10,000 objects up front. With it, you get a thin array and only the rows you actually look at hit memory.

This is essential for NSFetchedResultsController-backed lists, where you’ve fetched “all notes” but might scroll through only a fraction. Most apps should set fetchBatchSize to something like 20–50 for list-backing fetches.

propertiesToFetch — partial fetches

If you only need a subset of attributes, ask for them:

request.resultType = .dictionaryResultType
request.propertiesToFetch = ["id", "title"]
let dicts = try context.fetch(request) as? [[String: Any]] ?? []

This skips loading body, dates, etc. Returns dictionaries instead of NSManagedObject instances. Use cases: extracting a list of titles for autocomplete, summary tables, anything where the full object is overkill.

propertiesToGroupBy — aggregation

For SQL-style GROUP BY:

request.resultType = .dictionaryResultType
request.propertiesToGroupBy = ["folder"]

let countDescription = NSExpressionDescription()
countDescription.name = "count"
countDescription.expression = NSExpression(forFunction: "count:", arguments: [NSExpression(forKeyPath: "id")])
countDescription.expressionResultType = .integer64AttributeType

request.propertiesToFetch = ["folder", countDescription]
let counts = try context.fetch(request) as? [[String: Any]] ?? []
// counts is like: [{folder: <Folder>, count: 42}, ...]

This is dense; for occasional aggregation it’s worth the syntax, for routine work consider doing it in Swift after a regular fetch.

relationshipKeyPathsForPrefetching — avoiding N+1

The most common Core Data performance bug: iterating fetched objects, accessing a relationship on each one, firing N faults.

let notes = try context.fetch(Note.fetchRequest())
for note in notes {
    print(note.folder?.name ?? "no folder")  // each access fires a fault!
}

Fix: prefetch the relationship:

let request = Note.fetchRequest()
request.relationshipKeyPathsForPrefetching = ["folder"]
let notes = try context.fetch(request)
for note in notes {
    print(note.folder?.name ?? "no folder")  // already loaded
}

This loads all the related Folders in a single query, alongside the Notes. For nested relationships:

request.relationshipKeyPathsForPrefetching = ["folder", "folder.parent", "tags"]

This is one of the most impactful performance optimizations. Always prefetch relationships you know you’ll access.

returnsObjectsAsFaults

By default, Core Data returns objects as faults — placeholders whose properties load on first access. If you know you’ll access most properties, you can request fully-materialized objects:

request.returnsObjectsAsFaults = false

Behind the scenes, this changes the SQL to load all attributes in the initial fetch. Faster overall when you know you need the data; wasteful if you’ll only access a few fields.

For dictionary results (resultType = .dictionaryResultType), this setting doesn’t apply.

includesSubentities

If your model uses entity inheritance (rare), this controls whether the fetch includes subentities. Default true.

includesPendingChanges

By default, fetches include pending unsaved changes in the context. If you want only the persisted state:

request.includesPendingChanges = false

Use this carefully — it can lead to “stale” results in your UI if you’ve made changes that haven’t been saved.

affectedStores

If you have multiple persistent stores (common with CloudKit + local), you can scope the fetch to specific stores:

request.affectedStores = [container.persistentStoreCoordinator.persistentStores.first!]

Most apps don’t need this.

shouldRefreshRefetchedObjects

When fetching, if an object is already in the context, by default the existing in-memory state takes precedence over the database state. To force a refresh from the database:

request.shouldRefreshRefetchedObjects = true

This is the “I really want the latest” flag. Costs a bit because Core Data has to reconcile in-memory edits with database reads.

Putting it all together

A well-tuned fetch for a list of notes in a folder, with prefetched tags, paged, batched:

func notes(in folder: Folder, search: String?, context: NSManagedObjectContext) throws -> [Note] {
    let request = Note.fetchRequest()

    var predicates: [NSPredicate] = [NSPredicate(format: "folder == %@", folder)]
    if let search, !search.isEmpty {
        predicates.append(NSPredicate(format: "title CONTAINS[cd] %@ OR body CONTAINS[cd] %@",
                                      search, search))
    }
    request.predicate = NSCompoundPredicate(andPredicateWithSubpredicates: predicates)

    request.sortDescriptors = [
        NSSortDescriptor(key: "updatedAt", ascending: false),
        NSSortDescriptor(key: "id", ascending: true)
    ]
    request.fetchBatchSize = 20
    request.relationshipKeyPathsForPrefetching = ["tags"]

    return try context.fetch(request)
}

This fetch:

• Filters by folder and (optionally) search text.
• Sorts by updatedAt (descending) with id as tiebreaker.
• Returns results in batches of 20 (the rest fetch lazily).
• Prefetches the tags relationship so iterating doesn’t fire N faults.

Asynchronous fetches

NSAsynchronousFetchRequest runs in the background:

let asyncRequest = NSAsynchronousFetchRequest(fetchRequest: request) { result in
    if let notes = result.finalResult {
        // notes is [Note]
    }
}
do {
    try context.execute(asyncRequest)
} catch {
    print("Async fetch failed: \(error)")
}

In modern code, you typically use perform { } on a background context for async work instead. NSAsynchronousFetchRequest predates Swift Concurrency.

What to internalize

NSFetchRequest configures a query: predicate, sort, limit, offset, batch size, prefetch. fetchBatchSize makes large fetches lazy. relationshipKeyPathsForPrefetching avoids N+1 queries. propertiesToFetch with dictionary result type skips unwanted columns. Always set sort descriptors. For paging large results, prefer keyset over offset.

8. NSPredicate Mastery

NSPredicate is the query language for Core Data. It started as a way to filter Cocoa collections and got generalized into something that can also filter Core Data fetches (and fetch into SQL). It’s powerful, terse, and full of gotchas. Mastering it makes a huge difference.

The format string syntax

The most common usage: build a predicate from a format string with placeholders.

NSPredicate(format: "title == %@", "Hello")
NSPredicate(format: "age > %d", 18)
NSPredicate(format: "isActive == %@", NSNumber(value: true))
NSPredicate(format: "createdAt >= %@", date as NSDate)

Placeholders:

• %@ — for object values (strings, dates, NSNumbers, NSManagedObjects).
• %d — for integers. Equivalent to %@ with an NSNumber.
• %K — for key paths (column names). Used for dynamic key paths.

The %K is for when the column name itself is a variable:

let key = "title"
NSPredicate(format: "%K == %@", key, value)

%K is treated as a key path; %@ is treated as a value. Don’t mix them up.

Comparison operators

NSPredicate(format: "age == 18")
NSPredicate(format: "age != 18")
NSPredicate(format: "age > 18")
NSPredicate(format: "age >= 18")
NSPredicate(format: "age < 18")
NSPredicate(format: "age <= 18")

For strings:

NSPredicate(format: "title == %@", "exact match")
NSPredicate(format: "title BEGINSWITH %@", "Hello")
NSPredicate(format: "title ENDSWITH %@", "world")
NSPredicate(format: "title CONTAINS %@", "lo, w")
NSPredicate(format: "title MATCHES %@", "^[A-Z].*")  // regex
NSPredicate(format: "title LIKE %@", "Hel*o")  // wildcards * and ?

MATCHES uses ICU regular expressions (similar to most regex flavors). LIKE uses simple wildcards (* and ?).

Modifiers: case and diacritic insensitivity

By default, string comparisons are case-sensitive and diacritic-sensitive. Add modifiers:

NSPredicate(format: "title CONTAINS[c] %@", "hello")    // case-insensitive
NSPredicate(format: "title CONTAINS[d] %@", "hello")    // diacritic-insensitive
NSPredicate(format: "title CONTAINS[cd] %@", "hello")   // both
NSPredicate(format: "title CONTAINS[n] %@", "hello")    // normalized (combines [cd])
NSPredicate(format: "title CONTAINS[l] %@", "hello")    // localized (locale-aware)

For user-facing search, almost always use [cd] or [n]. Otherwise “Hello” doesn’t match a search for “hello”, and “café” doesn’t match a search for “cafe”.

Logical operators

NSPredicate(format: "title == %@ AND createdAt > %@", title, date as NSDate)
NSPredicate(format: "title == %@ OR title == %@", a, b)
NSPredicate(format: "NOT (title == %@)", title)

You can also build compound predicates programmatically:

let p1 = NSPredicate(format: "title == %@", title)
let p2 = NSPredicate(format: "createdAt > %@", date as NSDate)
let combined = NSCompoundPredicate(andPredicateWithSubpredicates: [p1, p2])

NSCompoundPredicate has and..., or..., and not... initializers. Useful when you have a list of optional predicates to combine:

var predicates: [NSPredicate] = [NSPredicate(format: "folder == %@", folder)]
if let searchText, !searchText.isEmpty {
    predicates.append(NSPredicate(format: "title CONTAINS[cd] %@", searchText))
}
if let tag {
    predicates.append(NSPredicate(format: "ANY tags == %@", tag))
}
request.predicate = NSCompoundPredicate(andPredicateWithSubpredicates: predicates)

IN and BETWEEN

For “value is in a set”:

let allowedTitles = ["Hello", "World", "Foo"]
NSPredicate(format: "title IN %@", allowedTitles)

For range:

NSPredicate(format: "age BETWEEN {18, 65}")
NSPredicate(format: "createdAt BETWEEN %@", [startDate, endDate])

BETWEEN is inclusive on both ends.

Nil checks

Comparing to nil uses nil literal:

NSPredicate(format: "deletedAt == nil")
NSPredicate(format: "deletedAt != nil")

Or NULL:

NSPredicate(format: "deletedAt == NULL")

Both work; nil is more readable.

Relationships in predicates

For to-one:

NSPredicate(format: "folder == %@", folder)
NSPredicate(format: "folder.name == %@", "Inbox")

For to-many, use ANY, ALL, NONE:

NSPredicate(format: "ANY tags.name == %@", "important")
// "Notes that have at least one tag named 'important'"

NSPredicate(format: "ALL tags.name == %@", "draft")
// "Notes whose every tag is named 'draft'"

NSPredicate(format: "NONE tags.name == %@", "deleted")
// "Notes that have no tag named 'deleted'"

For “to-many is empty”:

NSPredicate(format: "tags.@count == 0")
NSPredicate(format: "tags.@count > 0")

@count is one of several KVC aggregation operators (others: @sum, @avg, @min, @max).

SUBQUERY: more complex relationship filters

For “notes that have at least 3 important tags”:

NSPredicate(format: "SUBQUERY(tags, $tag, $tag.name == 'important').@count >= 3")

SUBQUERY syntax: SUBQUERY(<collection>, <iterator-variable>, <predicate-using-iterator>). Returns a filtered subset; you usually take its @count or compare to another collection.

For “users whose posts all have positive scores”:

NSPredicate(format: "SUBQUERY(posts, $p, $p.score < 0).@count == 0", arguments: nil)

SUBQUERYs are powerful but verbose. Use them sparingly; they don’t always have great SQL translations.

Type-safe predicates with #Predicate (modern)

Starting iOS 17 / Swift 5.9, there’s a macro-based #Predicate syntax:

let predicate = #Predicate<Note> { note in
    note.title.contains("hello") && note.createdAt > someDate
}
let request = Note.fetchRequest()
request.predicate = NSPredicate(predicate)

This is type-checked at compile time — no %@ format string surprises. The compiler verifies that note.title exists and is a string, that someDate is a Date, etc.

For new code on iOS 17+, use #Predicate whenever possible. It’s far safer.

The catch: not every NSPredicate is expressible. Some advanced features (SUBQUERY, certain regex patterns) need to fall back to format strings. Mix as needed.

The KVC keypath quirk

You’ll sometimes see code like:

NSPredicate(format: "%K == %@", #keyPath(Note.title), "Hello")

#keyPath is a Swift compiler check that the key path is valid. With manual NSManagedObject subclasses, #keyPath(Note.title) resolves to the string "title" at compile time, and the compiler checks that Note has a title property.

This gives you a partial type safety even with classic NSPredicate. Use it for any predicate where you’d otherwise hardcode a string column name.

Dynamic predicates from search input

A real-world pattern: search across multiple fields with case-insensitive match:

func searchPredicate(for text: String) -> NSPredicate? {
    let trimmed = text.trimmingCharacters(in: .whitespaces)
    guard !trimmed.isEmpty else { return nil }

    let words = trimmed.split(separator: " ").map(String.init)
    let perWordPredicates: [NSPredicate] = words.map { word in
        NSCompoundPredicate(orPredicateWithSubpredicates: [
            NSPredicate(format: "title CONTAINS[cd] %@", word),
            NSPredicate(format: "body CONTAINS[cd] %@", word),
            NSPredicate(format: "ANY tags.name CONTAINS[cd] %@", word)
        ])
    }
    return NSCompoundPredicate(andPredicateWithSubpredicates: perWordPredicates)
}

This implements “every word the user typed must appear somewhere (title, body, or any tag name)”. You build it from search input dynamically.

Pitfalls

• Boolean attributes. Use NSNumber(value: true) or 1 / 0, not Swift true directly: NSPredicate(format: "isActive == %@", NSNumber(value: true)) or NSPredicate(format: "isActive == 1").

• Date comparisons. Cast to NSDate: NSPredicate(format: "createdAt > %@", someDate as NSDate). Otherwise the format string may misinterpret.

• UUID comparisons. Cast to CVarArg: NSPredicate(format: "id == %@", id as CVarArg).

• String contains substrings. == is exact match; CONTAINS looks for a substring. Don’t confuse them.

• Format-string injection. Don’t interpolate user input into the format string itself. Always use placeholders. NSPredicate(format: "title == \(userInput)") is unsafe; NSPredicate(format: "title == %@", userInput) is safe.

What to internalize

NSPredicate builds queries with format strings (%@ for values, %K for key paths) or, on iOS 17+, with #Predicate for compile-time safety. [cd] modifiers for case/diacritic-insensitive string compares. Use ANY/ALL/NONE for to-many relationships. Compose with NSCompoundPredicate. Always use placeholders, never interpolate user input. Cast Date to NSDate, UUID to CVarArg.

9. Sort Descriptors and Result Limits

We touched on sorting in section 7. Let’s go deeper — there are some subtleties to get right.

Why always sort

A fetch without sort descriptors returns rows in an undefined order. The order may be consistent within a single SQLite version on a single device, but it’s not part of the contract. Two consequences:

• Tests pass on your device, fail on CI.
• Two different launches show the user different ordering.
• NSFetchedResultsController requires sort descriptors and crashes without them.

Always sort. Even if you “don’t care,” pick something deterministic — usually id or createdAt.

Multiple sort descriptors

Sort descriptors apply in order:

request.sortDescriptors = [
    NSSortDescriptor(key: "priority", ascending: false),
    NSSortDescriptor(key: "createdAt", ascending: true),
    NSSortDescriptor(key: "id", ascending: true)
]

This sorts by priority descending, then for ties by createdAt ascending, then for further ties by id ascending. The id sort guarantees a fully deterministic order even when priorities and dates collide.

String sorting

The default string comparison is binary: 'a' < 'B' < 'b' because it uses character codes. For user-visible text, almost always use a localized comparator:

NSSortDescriptor(key: "name", ascending: true,
                 selector: #selector(NSString.localizedCaseInsensitiveCompare))

NSSortDescriptor(key: "name", ascending: true,
                 selector: #selector(NSString.localizedStandardCompare))

localizedStandardCompare is “Finder-like” — it handles things like sorting “iPhone 10” before “iPhone 2” with embedded numbers (when the locale supports it).

localizedCaseInsensitiveCompare is the simpler choice for general case-insensitive sort.

Sorting with key paths

You can sort by relationship attributes:

NSSortDescriptor(key: "folder.name", ascending: true)
NSSortDescriptor(key: "author.lastName", ascending: true)

This works in Core Data because the SQL becomes a JOIN. There’s a cost — joins make queries slower. For frequently-sorted relationships, consider denormalizing (e.g., copy the folder name onto the note) or limiting how often you sort by joined fields.

Modern syntax: typed sort descriptors

iOS 15+ has SortDescriptor<Element>:

let sortByDate = SortDescriptor(\Note.createdAt, order: .reverse)
let sortByTitle = SortDescriptor(\Note.title)

request.sortDescriptors = [sortByDate.toNSSortDescriptor(), sortByTitle.toNSSortDescriptor()]

But Core Data’s NSFetchRequest uses [NSSortDescriptor], not [SortDescriptor<Note>]. To bridge, use NSSortDescriptor(_:) initializer or convert via your own helper. SwiftUI’s @FetchRequest accepts both, with conversions handled by the framework.

fetchLimit vs fetchOffset

request.fetchLimit = 50
request.fetchOffset = 100

This says: “skip the first 100 results, take the next 50.” For paging, this works but has performance issues:

• SQLite must compute the first 100 rows to skip them.
• Large offsets (10,000+) become slow.
• Inserts at the start of the result set shift the offset, leading to duplicates or skipped rows on consecutive pages.

For paging large datasets, use keyset pagination:

// First page:
request.predicate = nil  // or your existing predicate
request.sortDescriptors = [NSSortDescriptor(key: "createdAt", ascending: false)]
request.fetchLimit = 50
let firstPage = try context.fetch(request)

// Next page (with the previous last item's createdAt as the cursor):
let lastItem = firstPage.last!
request.predicate = NSPredicate(format: "createdAt < %@", lastItem.createdAt as NSDate)
request.fetchLimit = 50
let secondPage = try context.fetch(request)

This uses an indexed comparison (createdAt <) instead of an offset. Always fast regardless of how deep into results you are. The trade-off: you can’t jump to “page 47” — you must walk forward.

fetchBatchSize: lazy loading

Already covered in section 7, but worth re-emphasizing:

request.fetchBatchSize = 20
let allNotes = try context.fetch(request)
// `allNotes` is an array proxy; only 20 objects are loaded immediately.
// Accessing index 35 fetches the next batch automatically.

Use this for fetches that back lists where you might not consume all results — table view data sources, anywhere with thousands of rows but paged display.

Sorting and paging together

Don’t change the sort between pages. If page 1 sorts by date, page 2 must also. Otherwise the underlying ordering shifts and your paging is wrong.

let sort = [NSSortDescriptor(key: "createdAt", ascending: false)]

func fetchPage(after cursor: Date?, in context: NSManagedObjectContext) throws -> [Note] {
    let request = Note.fetchRequest()
    if let cursor {
        request.predicate = NSPredicate(format: "createdAt < %@", cursor as NSDate)
    }
    request.sortDescriptors = sort
    request.fetchLimit = 50
    return try context.fetch(request)
}

Pass nil cursor for the first page; pass the last item’s createdAt for subsequent pages. Each page is a fresh fetch, but each is fast (cursor uses an indexed comparison).

Counting before paging

If you need to display “X of N”:

let total = try context.count(for: Note.fetchRequest())  // total notes
let page = try context.fetch(pagedRequest)               // current page

count(for:) is fast — it’s a SQL COUNT, no object materialization. Use it freely.

What to internalize

Always set sort descriptors (deterministic ordering required). Use multiple descriptors for tie-breaking. Use localizedCaseInsensitiveCompare for user-facing strings. Sort by relationship key paths only when needed (joins are costly). Paging with fetchOffset works for small offsets; for large datasets use keyset pagination (predicates + cursor). Use fetchBatchSize for lazily-loaded lists.

10. Relationships: To-One, To-Many, Many-to-Many

Relationships are what make Core Data an object graph and not just a database. They define how entities connect, and they shape your queries, your performance, and your model.

The three cardinalities

• To-One. A Note has one Folder. The note’s folder property is Folder?.
• To-Many. A Folder has many Notes. The folder’s notes property is Set<Note> (or NSOrderedSet for ordered).
• Many-to-Many. A Note can have many Tags, and a Tag can be on many Notes. Both sides have Set properties.

These cardinalities are properties of the relationship, not the entity. Core Data creates the underlying database structure to support each.

Defining a relationship

In the model editor, select an entity, click “+” in the Relationships section. For each relationship:

• Name — what the property is called (folder, notes, tags).
• Destination — what entity it points to.
• Inverse — the relationship on the other end (we’ll cover next section; you must set this).
• Type — To One or To Many.
• Optional — whether nil/empty is allowed.
• Delete Rule — what happens on delete (covered in section 12).

To-one example

Note → Folder:

Note entity:
    folder: To One → Folder, optional, inverse: Folder.notes

In Swift:

@NSManaged public var folder: Folder?

Setting the relationship:

note.folder = folder

Reading:

print(note.folder?.name ?? "no folder")

To-many example

Folder → Note:

Folder entity:
    notes: To Many → Note, optional, inverse: Note.folder

In Swift:

@NSManaged public var notes: Set<Note>

Reading:

let count = folder.notes.count
let titles = folder.notes.map(\.title)

Modifying:

folder.notes.insert(newNote)
folder.notes.remove(oldNote)

When you set note.folder = folder, Core Data automatically adds the note to folder.notes (because of the inverse). Likewise, folder.notes.insert(note) automatically sets note.folder = folder. The two sides stay consistent.

NSSet and Set in Swift

In older codegen, to-many relationships are exposed as NSSet. With manual codegen (recommended), use Swift’s Set. The bridge happens at the runtime level — Core Data internally uses NSSet, but @NSManaged var tags: Set<Tag> works.

For mutating, you can use either:

note.tags.insert(tag)  // Swift Set syntax (most natural)
note.mutableSetValue(forKey: "tags").add(tag)  // KVC syntax (older, also works)

Many-to-many example

Note ↔ Tag:

Note entity:
    tags: To Many → Tag, optional, inverse: Tag.notes

Tag entity:
    notes: To Many → Note, optional, inverse: Tag.notes

Both sides are to-many. Core Data creates a join table behind the scenes; you don’t see it, but it’s there in the SQLite database.

In Swift:

@NSManaged public var tags: Set<Tag>      // on Note
@NSManaged public var notes: Set<Note>    // on Tag

Adding:

note.tags.insert(tag)
// equivalent to:
tag.notes.insert(note)

Either side updates both. The inverse relationship makes it possible.

Ordered relationships

By default, to-many relationships are unordered (using sets). If you need order — say, items in a playlist — use an ordered to-many.

In the model editor, check “Ordered” on the relationship. The Swift type becomes NSOrderedSet:

@NSManaged public var items: NSOrderedSet

This is more cumbersome than Set because Swift doesn’t have a great native ordered-set type. You read with index:

let firstItem = playlist.items[0] as? PlaylistItem

You modify via mutable accessors:

let mutable = playlist.mutableOrderedSetValue(forKey: "items")
mutable.add(item)
mutable.insert(item, at: 0)
mutable.move(from: 1, to: 3)

Use ordered relationships when order is genuinely a property of the relationship (not derivable from a sort key). Otherwise, prefer unordered + a position attribute for cleaner SQL queries.

Querying through relationships

Already covered in the predicate section, but worth re-emphasizing:

// "Notes in folder X":
NSPredicate(format: "folder == %@", folder)

// "Notes with at least one tag named 'important'":
NSPredicate(format: "ANY tags.name == %@", "important")

// "Notes where every tag is in this list":
NSPredicate(format: "ALL tags IN %@", allowedTags)

These use the relationships as JOINs in the underlying SQL. They’re efficient if the joined attribute is indexed; slow if not.

Bidirectional consistency

Core Data maintains both sides of a relationship for you, if you’ve set up inverses. Without inverses, you must manually sync. Section 11 covers why inverses are essentially required.

Performance considerations

Each relationship traversal can fire a fault. note.folder?.name fires the folder’s fault if it hasn’t been loaded yet.

For loops accessing relationships:

for note in fetchedNotes {
    print(note.folder?.name ?? "?")  // fires N folder faults
}

Use relationshipKeyPathsForPrefetching = ["folder"] to load all folders in one query. Same idea for nested relationships:

request.relationshipKeyPathsForPrefetching = ["folder", "tags", "folder.parent"]

Each entry causes Core Data to issue an extra query (or a join) to materialize that level of relationship. Done once before the loop, not N times during it.

When the relationship is huge

Sometimes a to-many relationship has thousands of items — e.g., a user has 50,000 messages. You don’t want to load all of them just to show “5 unread.”

For these, don’t navigate the relationship; do a separate fetch:

let request = Message.fetchRequest()
request.predicate = NSPredicate(format: "user == %@ AND isRead == NO", user)
let unreadCount = try context.count(for: request)

This is a single COUNT query, very fast. Compare to:

let unreadCount = user.messages.filter { !$0.isRead }.count  // loads all 50,000!

Rule of thumb: traversing a to-many relationship loads it. For huge ones, use a fetch with the relationship as a predicate instead.

Derived attributes

iOS 13+ supports derived attributes: attributes whose value is computed from other attributes (or from a relationship’s count). They’re updated automatically by Core Data on save.

In the model editor, mark an attribute as “Derived” and provide a derivation expression. For example, messageCount on User derived from messages.@count:

messageCount: Integer 64, Derived: messages.@count

Now user.messageCount is always the count of messages, maintained automatically. You query it as a regular attribute (fast, indexable).

This pattern is excellent for “count of related items” cases. Use it instead of computing the count on every UI update.

What to internalize

Relationships have cardinality (to-one, to-many, many-to-many) and direction. To-many uses Set (or NSOrderedSet if ordered). Always set inverses; Core Data manages bidirectional consistency. Use relationshipKeyPathsForPrefetching to avoid N+1 queries. For large to-many relationships, use a fetch with the relationship as a predicate, not direct traversal. Derived attributes give you cached aggregates.

11. Inverse Relationships and Why They Matter

Inverse relationships are required by Core Data for a reason: without them, the framework can’t maintain the object graph’s consistency. Strange bugs follow. This section is about why inverses matter and how to set them up correctly.

What inverse relationships do

When you set up Note.folder and Folder.notes as inverses of each other, Core Data understands they’re two sides of the same relationship. Setting one updates the other automatically:

note.folder = folder
// Core Data automatically adds `note` to `folder.notes`

Or:

folder.notes.insert(note)
// Core Data automatically sets `note.folder = folder`

This bidirectional consistency is essential for an object graph. Without it, your in-memory graph is inconsistent; saves can produce corrupted data.

What goes wrong without inverses

Consider a model with no inverse on Note.folder:

note.folder = folder
// `folder.notes` doesn't include this note (no inverse to update).

// Now if we query:
folder.notes.contains(note)  // false! Even though note.folder == folder.

That’s just the start. Worse problems:

• Orphaned objects. When you delete a folder, Core Data uses the inverse to find related notes (to apply the delete rule). Without an inverse, related notes aren’t found. They remain pointing at a now-deleted folder.

• Faults that don’t propagate. When a folder is faulted in, Core Data updates the inverse. Without an inverse, related notes aren’t kept in sync.

• Data corruption on save. The store has the relationship; in-memory might not match. After save and refresh, things look weird.

Apple’s documentation explicitly says: every relationship should have an inverse, even if you “only ever traverse in one direction.” Don’t argue with this — it’s a hard requirement of the framework.

Setting up inverses in the model editor

When you add a relationship, the model editor has an “Inverse” dropdown. After you’ve created both sides:

1. Select Note, look at its folder relationship.
2. Set Destination: Folder.
3. Set Inverse: notes.

Then on the other side:

1. Select Folder, look at its notes relationship.
2. Set Destination: Note.
3. Set Inverse: folder.

The editor warns if a relationship has no inverse — yellow triangle in the issues navigator. Address every one.

Verifying inverses

If you have a relationship that doesn’t show an inverse, the model is incomplete. Check:

• The inverse dropdown in both directions.
• The destination entity has a corresponding relationship.

If you change a relationship’s name, the inverse may break — the model editor doesn’t always auto-update. Re-verify both sides.

One-way relationships in spirit

Sometimes you want a relationship that’s “logically one-way.” For example, a User has a lastLoginNote that points to a Note, but you don’t want every Note to know about being someone’s last-login note (because most notes aren’t).

Even here, you should set up an inverse — but one that’s lightweight. Add a lastLoginUser relationship on Note, optional and to-one. Most of the time it’s nil. The model is a little fatter but the consistency works.

If you really, really don’t want the inverse, you can set the relationship’s “Inverse” dropdown to “No Inverse Relationship” — but expect Core Data to log warnings in the console, and brace for occasional consistency bugs.

Programmatic checks

You can verify the model has no missing inverses programmatically (useful in tests):

extension NSManagedObjectModel {
    var relationshipsWithoutInverse: [(String, String)] {
        var result: [(String, String)] = []
        for entity in entities {
            for (name, rel) in entity.relationshipsByName {
                if rel.inverseRelationship == nil {
                    result.append((entity.name ?? "?", name))
                }
            }
        }
        return result
    }
}

// In a test:
func test_noMissingInverses() {
    let model = persistenceController.container.managedObjectModel
    XCTAssertTrue(model.relationshipsWithoutInverse.isEmpty,
                  "Missing inverses: \(model.relationshipsWithoutInverse)")
}

This catches accidental missing inverses before they cause runtime mysteries.

Cardinality interactions

The cardinalities of two sides of a relationship must be compatible:

• to-one ↔ to-one: a one-to-one relationship.
• to-one ↔ to-many: a one-to-many relationship (the to-many side has many of the to-one side).
• to-many ↔ to-many: a many-to-many relationship.

You can’t have, e.g., to-one ↔ to-one but with both sides being non-optional except in special cases. Generally, optionality must align so that you can construct objects piecewise.

For a one-to-one relationship like User → Profile, you typically:

• Mark both sides optional in the model.
• Enforce non-nil at app logic level (e.g., always create a Profile alongside a User).

Otherwise you can’t insert a User without first having a Profile (and vice versa), which is a chicken-and-egg problem.

What to internalize

Every relationship needs an inverse. Core Data uses inverses to maintain bidirectional consistency, propagate deletes, and update faults correctly. Without inverses, your object graph silently corrupts. Set them up in the model editor; verify with a test. Compatible cardinalities and optionality matter.

12. Delete Rules

When you delete a Core Data object, what happens to objects related to it? The answer depends on the delete rule set on each relationship. Picking the right rule for each relationship is part of getting your model right.

The four delete rules

For each relationship, you set a delete rule on its source side. The four options:

• Nullify. When the source is deleted, the related object’s relationship pointer is set to nil. The related object is preserved.
• Cascade. When the source is deleted, the related object is also deleted. Cascades chain.
• Deny. When the source is deleted, Core Data refuses if there are related objects. The save fails.
• No Action. When the source is deleted, do nothing — the related object’s pointer is not updated (it points to a deleted object). You handle consistency yourself.

These apply asymmetrically: each side of a relationship has its own rule, and they can differ.

Picking the right rule

For most cases, the rules are intuitive once you think about ownership.

Cascade when the related object can’t exist without the parent. If a Folder is deleted, all its Notes should go too (assuming notes don’t move freely between folders).

Folder.notes: Cascade

Nullify when the related object exists independently. A Note might have a Tag, but deleting the tag doesn’t delete the note — just nilify the relationship.

Tag.notes: Nullify
Note.tags: Nullify (typically; they'd usually both nullify in many-to-many)

Deny when you want to forbid deletion as long as related objects exist. A User with BillingTransactions shouldn’t be deleted — deny it.

User.transactions: Deny

No Action is rare and almost always wrong. It’s “I’ll handle consistency myself,” which means you’ll forget once and end up with dangling references.

Cascade chains

A cascade can chain. If Folder.notes is cascade and Note.attachments is cascade, deleting a folder cascades to its notes, which cascades to their attachments. All deleted in one save.

This is usually what you want, but watch for cycles. If you have A → B → A, a cascade from A to B to A could loop. Core Data is supposed to handle these gracefully, but designing your model to avoid cyclic cascades is safer.

Deny: handling rejection

If a save fails because a Deny rule blocked the delete:

do {
    try context.save()
} catch let error as NSError {
    if error.code == NSValidationRelationshipDeniedDeleteError {
        // User can't be deleted — show error to user
    }
}

For UI: detect this case before the user attempts the delete. Check the count of denying-relationship items; if greater than zero, disable the delete button or show a clear message.

Combining rules with optionality

A subtle interaction: if a relationship is non-optional (required) and the related object’s relationship is nullified, you have a problem.

Example: Note.folder is non-optional and Folder.notes is Nullify. If you delete a folder, all its notes have their folder set to nil — but that violates the non-optional constraint. Save fails.

Fix: either make Note.folder optional, or use Cascade on Folder.notes. Pick what makes sense for your model.

Cascade vs application-level deletes

Sometimes you want to delete with extra logic, not just relational propagation. For example, when a user is deleted, you want to:

1. Delete their notes.
2. Update statistics counters elsewhere.
3. Send a “user deleted” event to the analytics service.

You can use prepareForDeletion() for this:

public override func prepareForDeletion() {
    super.prepareForDeletion()
    Analytics.track("user_deleted", userID: id)
    // Other side effects
}

prepareForDeletion runs just before the object is removed. You can read its data and trigger side effects. Don’t insert or fetch new objects here — the context is in transition.

Batch deletes and rules

NSBatchDeleteRequest (covered in section 18) bypasses delete rules. It’s a SQL DELETE, no object lifecycle, no rule application. Use it for bulk deletes, but only when you’re sure no rules need to fire.

What to internalize

Each relationship has a delete rule on its source side. Cascade for owned children. Nullify for independent associates. Deny to forbid deletion when related objects exist. No Action almost never. Watch the interaction with non-optional inverses. Use prepareForDeletion() for application-level side effects.

13. Context Concurrency Types

Core Data has the strictest concurrency model of any major iOS persistence framework. Get it wrong and you crash at random — sometimes immediately, sometimes hours into a session, sometimes only on real devices and not in the simulator. Get it right and Core Data is rock solid.

The fundamental rule

Each NSManagedObjectContext is bound to a queue. Every operation on the context — every property access on its objects, every fetch, every save — must happen on that queue.

There are no exceptions. You can’t “just read this property real quick” from a different queue. The Core Data runtime enforces this; with the right environment variable set, it crashes immediately on violation.

Concurrency types

When you create a context, you specify its concurrency type:

• NSMainQueueConcurrencyType — bound to the main queue (the run loop’s queue). Use for any context that interacts with UI.
• NSPrivateQueueConcurrencyType — bound to its own private dispatch queue, automatically managed by Core Data.

NSPersistentContainer.viewContext is NSMainQueueConcurrencyType. NSPersistentContainer.newBackgroundContext() returns NSPrivateQueueConcurrencyType.

You almost never create contexts manually anymore — let the container do it. But if you do:

let context = NSManagedObjectContext(concurrencyType: .privateQueueConcurrencyType)
context.persistentStoreCoordinator = container.persistentStoreCoordinator

The perform family

To safely operate on a context from arbitrary code, wrap your work in perform or performAndWait:

context.perform {
    // Runs on the context's queue (main or private).
    // You can safely access objects, run fetches, save, etc.
}

The closure is executed on the context’s queue. If you’re already on that queue (e.g., calling viewContext.perform from main thread code), perform schedules it asynchronously — so don’t expect immediate execution.

performAndWait is the synchronous version:

context.performAndWait {
    // Runs on the context's queue, blocking until complete.
}

The current thread is blocked until the closure finishes. If you’re already on the context’s queue, performAndWait runs immediately (no scheduling). This makes it safer to use recursively.

Async/await form

Modern Swift offers async-friendly versions:

let users = try await context.perform {
    return try context.fetch(User.fetchRequest())
}

The closure runs on the context’s queue; the await suspends your code until it completes. This is the cleanest form for Swift Concurrency.

For the throwing variant, the closure can throw and the await propagates:

let result = try await context.perform {
    let user = User(context: context)
    user.name = "Alice"
    try context.save()
    return user.objectID
}

Note we return objectID (a Sendable value) rather than the User itself. We’ll see why in section 16.

Why the model is so strict

The strictness comes from the implementation:

• Each context has its own object graph (NSManagedObject instances are unique to a context).
• Each context has its own undo manager, change tracker, and lock state.
• Faulting (lazy loading) involves trips to the persistent store, which has its own queue.

If two threads tried to fault the same object simultaneously, or if two threads modified the same context’s pending changes, you’d get inconsistent state — randomly. Core Data’s solution is the queue-binding rule.

Catching violations: the concurrency debug flag

For development, set this environment variable in your scheme:

-com.apple.CoreData.ConcurrencyDebug 1

In Xcode: Edit Scheme → Run → Arguments → Arguments Passed On Launch.

With this enabled, Core Data crashes (with a clear stack trace) any time you access a managed object from the wrong queue. Always run with this in development. Never ship with it (it adds checks that slow things down).

The viewContext is on the main queue

viewContext.perform { ... } from the main thread schedules the closure asynchronously, even though you’re already on the right queue. To avoid this, you can access viewContext directly from main-thread code — but use perform defensively if you’re not sure what queue you’re on:

// Main thread, definitely:
let count = try? viewContext.count(for: User.fetchRequest())

// Maybe main thread, maybe not:
viewContext.perform {
    let count = try? self.viewContext.count(for: User.fetchRequest())
    // Use count
}

For SwiftUI views, you’re on main thread. Direct access is fine. For background work that wants to merge or query the viewContext, use perform.

MainActor and Core Data

You can mark a class @MainActor, and viewContext access from within it doesn’t need wrapping:

@MainActor
final class FolderListViewModel: ObservableObject {
    @Published var folders: [Folder] = []
    let context: NSManagedObjectContext  // viewContext

    func load() {
        let request = Folder.fetchRequest()
        folders = (try? context.fetch(request)) ?? []
    }
}

This works because @MainActor guarantees load() runs on the main thread, and viewContext is the main-queue context. No perform needed.

For background contexts, you can’t use @MainActor — they’re on private queues. Always wrap in perform.

Putting it together

A clean pattern: a “Core Data service” type that exposes async methods:

final class NoteService {
    let container: NSPersistentContainer

    init(container: NSPersistentContainer) {
        self.container = container
    }

    func createNote(title: String, body: String) async throws -> NSManagedObjectID {
        let context = container.newBackgroundContext()
        return try await context.perform {
            let note = Note(context: context)
            note.title = title
            note.body = body
            try context.save()
            return note.objectID
        }
    }

    func notes() async throws -> [NoteDTO] {
        let context = container.newBackgroundContext()
        return try await context.perform {
            let notes = try context.fetch(Note.fetchRequest())
            return notes.map(NoteDTO.init)
        }
    }
}

struct NoteDTO {
    let id: UUID
    let title: String
    let body: String

    init(_ note: Note) {
        self.id = note.id
        self.title = note.title
        self.body = note.body
    }
}

The service wraps each operation in perform on a background context. It returns plain Swift values (DTOs) and NSManagedObjectIDs — Sendable types that can cross queues safely.

What to internalize

Every context has a queue. Every access goes on that queue. viewContext is main-queue; newBackgroundContext() is private-queue. Wrap operations in context.perform { } or context.performAndWait { }. Use the async form with Swift Concurrency. Set -com.apple.CoreData.ConcurrencyDebug 1 in development. Pass objectID (not objects) across queues.

14. Background Contexts and perform/performAndWait

Now that we know contexts are queue-bound, let’s go deeper on how background contexts integrate with the rest of your app.

Creating a background context

The simplest way:

let bgContext = container.newBackgroundContext()

This returns a new context every call. Don’t cache it as a singleton; it’s lightweight. Either:

• Create one per logical operation (an import session, a sync run).
• Create one in a service class for that service’s lifetime.
• Create one per Task for short-lived background work.

Each call to newBackgroundContext() produces a context with its own queue. You can have many running concurrently.

What happens on save

When you save a background context, the changes go through the persistent store coordinator to the persistent store (SQLite). Other contexts (including viewContext) see the changes if automaticallyMergesChangesFromParent = true.

let bgContext = container.newBackgroundContext()
bgContext.perform {
    let note = Note(context: bgContext)
    note.title = "Imported"
    try? bgContext.save()
    // After save, viewContext can see the new note (eventually).
}

The merge into other contexts happens asynchronously through notifications. There’s a small lag — you can’t save in the background and immediately read in viewContext. If you need that, use viewContext.refreshAllObjects() or wait for the merge notification.

Using perform correctly

A common pattern:

bgContext.perform {
    let request = Note.fetchRequest()
    request.predicate = NSPredicate(format: "title == %@", "search")
    let results = try? bgContext.fetch(request)
    // Process results — but stay inside this closure!
    for note in results ?? [] {
        note.body = note.body.uppercased()
    }
    try? bgContext.save()
}

The closure runs on the context’s queue. Everything inside it can touch the context safely.

What you can’t do:

bgContext.perform {
    let results = try? bgContext.fetch(Note.fetchRequest())
    DispatchQueue.main.async {
        for note in results ?? [] {  // ❌ accessing background context's objects on main!
            print(note.title)
        }
    }
}

The note objects belong to bgContext. Once you’re on the main queue, accessing them is a violation. Pass objectIDs instead:

bgContext.perform {
    let results = (try? bgContext.fetch(Note.fetchRequest())) ?? []
    let ids = results.map(\.objectID)
    DispatchQueue.main.async {
        viewContext.perform {
            let mainNotes = ids.compactMap { try? viewContext.existingObject(with: $0) as? Note }
            // Now safe to use on main.
        }
    }
}

performAndWait

The synchronous version. Useful when you need a value back synchronously:

let count: Int = bgContext.performAndWait {
    return try? bgContext.count(for: Note.fetchRequest())
} ?? 0