codexkit 1.0.0

package/.codex/skills/core-data-expert/references/batch-operations.md

@@ -0,0 +1,543 @@
+# Batch Operations
+
+Batch operations provide significant performance improvements for large-scale data modifications. They operate directly at the SQL level, bypassing the object graph.
+
+## Overview
+
+Core Data provides three batch operation types:
+- **NSBatchInsertRequest** - Bulk inserts (iOS 14+)
+- **NSBatchDeleteRequest** - Bulk deletes
+- **NSBatchUpdateRequest** - Bulk updates
+
+**Key Characteristics:**
+- Operate at SQL level (very fast)
+- Don't load objects into memory
+- Don't trigger validation
+- Don't send change notifications (requires persistent history tracking)
+- Can't set relationships during batch insert
+
+## NSBatchInsertRequest (iOS 14+)
+
+### Basic Usage
+
+```swift
+let context = container.newBackgroundContext()
+
+context.perform {
+    let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { (object: NSManagedObject) -> Bool in
+        guard let article = object as? Article else { return true }
+        
+        article.name = "Sample Article"
+        article.content = "Content here"
+        article.creationDate = Date()
+        
+        return false // Continue inserting
+    }
+    
+    do {
+        try context.execute(batchInsert)
+    } catch {
+        print("Batch insert failed: \(error)")
+    }
+}
+```
+
+### Inserting Multiple Objects
+
+```swift
+func batchInsertArticles(_ data: [ArticleData]) {
+    let context = container.newBackgroundContext()
+    
+    context.perform {
+        var index = 0
+        let batchInsert = NSBatchInsertRequest(
+            entity: Article.entity()
+        ) { (object: NSManagedObject) -> Bool in
+            guard index < data.count else { return true } // Stop
+            guard let article = object as? Article else { return true }
+            
+            let articleData = data[index]
+            article.name = articleData.name
+            article.content = articleData.content
+            article.creationDate = Date()
+            
+            index += 1
+            return false // Continue
+        }
+        
+        do {
+            try context.execute(batchInsert)
+        } catch {
+            print("Batch insert failed: \(error)")
+        }
+    }
+}
+```
+
+### Using Dictionary Representation (Alternative)
+
+```swift
+let context = container.newBackgroundContext()
+
+context.perform {
+    let objects: [[String: Any]] = [
+        ["name": "Article 1", "content": "Content 1", "creationDate": Date()],
+        ["name": "Article 2", "content": "Content 2", "creationDate": Date()],
+        ["name": "Article 3", "content": "Content 3", "creationDate": Date()]
+    ]
+    
+    let batchInsert = NSBatchInsertRequest(
+        entity: Article.entity(),
+        objects: objects
+    )
+    
+    do {
+        try context.execute(batchInsert)
+    } catch {
+        print("Batch insert failed: \(error)")
+    }
+}
+```
+
+### Limitations
+
+**Cannot set relationships:**
+```swift
+// ❌ This won't work
+let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+    guard let article = object as? Article else { return true }
+    article.category = someCategory // Can't set relationships!
+    return false
+}
+```
+
+**Workaround:** Set relationships after batch insert:
+```swift
+// 1. Batch insert articles
+let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+    guard let article = object as? Article else { return true }
+    article.name = "Article"
+    return false
+}
+try context.execute(batchInsert)
+
+// 2. Fetch and set relationships
+let fetchRequest = Article.fetchRequest()
+let articles = try context.fetch(fetchRequest)
+for article in articles {
+    article.category = defaultCategory
+}
+try context.save()
+```
+
+## NSBatchDeleteRequest
+
+### Basic Usage
+
+```swift
+let context = container.newBackgroundContext()
+
+context.perform {
+    let fetchRequest: NSFetchRequest<NSFetchRequestResult> = Article.fetchRequest()
+    let batchDelete = NSBatchDeleteRequest(fetchRequest: fetchRequest)
+    
+    do {
+        try context.execute(batchDelete)
+    } catch {
+        print("Batch delete failed: \(error)")
+    }
+}
+```
+
+### With Predicate
+
+```swift
+let fetchRequest: NSFetchRequest<NSFetchRequestResult> = Article.fetchRequest()
+fetchRequest.predicate = NSPredicate(format: "views < %d", 10)
+
+let batchDelete = NSBatchDeleteRequest(fetchRequest: fetchRequest)
+
+context.perform {
+    do {
+        try context.execute(batchDelete)
+    } catch {
+        print("Batch delete failed: \(error)")
+    }
+}
+```
+
+### Getting Deleted Object IDs
+
+```swift
+let fetchRequest: NSFetchRequest<NSFetchRequestResult> = Article.fetchRequest()
+let batchDelete = NSBatchDeleteRequest(fetchRequest: fetchRequest)
+batchDelete.resultType = .resultTypeObjectIDs
+
+context.perform {
+    do {
+        let result = try context.execute(batchDelete) as? NSBatchDeleteResult
+        if let objectIDs = result?.result as? [NSManagedObjectID] {
+            print("Deleted \(objectIDs.count) objects")
+        }
+    } catch {
+        print("Batch delete failed: \(error)")
+    }
+}
+```
+
+## NSBatchUpdateRequest
+
+### Basic Usage
+
+```swift
+let context = container.newBackgroundContext()
+
+context.perform {
+    let batchUpdate = NSBatchUpdateRequest(entityName: "Article")
+    batchUpdate.predicate = NSPredicate(format: "isRead == NO")
+    batchUpdate.propertiesToUpdate = ["isRead": true]
+    
+    do {
+        try context.execute(batchUpdate)
+    } catch {
+        print("Batch update failed: \(error)")
+    }
+}
+```
+
+### Updating Multiple Properties
+
+```swift
+let batchUpdate = NSBatchUpdateRequest(entityName: "Article")
+batchUpdate.predicate = NSPredicate(format: "views < %d", 100)
+batchUpdate.propertiesToUpdate = [
+    "views": 100,
+    "lastModified": Date(),
+    "isPopular": true
+]
+
+context.perform {
+    try? context.execute(batchUpdate)
+}
+```
+
+### Using Expressions
+
+```swift
+// Increment views by 1
+let batchUpdate = NSBatchUpdateRequest(entityName: "Article")
+batchUpdate.propertiesToUpdate = [
+    "views": NSExpression(format: "views + 1")
+]
+
+context.perform {
+    try? context.execute(batchUpdate)
+}
+```
+
+### Getting Updated Object IDs
+
+```swift
+let batchUpdate = NSBatchUpdateRequest(entityName: "Article")
+batchUpdate.propertiesToUpdate = ["isRead": true]
+batchUpdate.resultType = .updatedObjectIDsResultType
+
+context.perform {
+    do {
+        let result = try context.execute(batchUpdate) as? NSBatchUpdateResult
+        if let objectIDs = result?.result as? [NSManagedObjectID] {
+            print("Updated \(objectIDs.count) objects")
+        }
+    } catch {
+        print("Batch update failed: \(error)")
+    }
+}
+```
+
+## Persistent History Tracking Integration
+
+**Critical:** Batch operations don't send change notifications. You **must** enable persistent history tracking for UI updates.
+
+### Enable Persistent History Tracking
+
+```swift
+guard let description = container.persistentStoreDescriptions.first else { return }
+
+description.setOption(true as NSNumber, 
+                     forKey: NSPersistentHistoryTrackingKey)
+description.setOption(true as NSNumber,
+                     forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)
+```
+
+### Observe Remote Changes
+
+```swift
+NotificationCenter.default.addObserver(
+    self,
+    selector: #selector(storeRemoteChange),
+    name: .NSPersistentStoreRemoteChange,
+    object: container.persistentStoreCoordinator
+)
+
+@objc func storeRemoteChange(_ notification: Notification) {
+    // Merge changes into view context
+    // See persistent-history.md for full implementation
+}
+```
+
+## Performance Comparison
+
+### Traditional Insert (Slow)
+
+```swift
+// Inserting 1000 objects: ~10 seconds
+for i in 0..<1000 {
+    let article = Article(context: context)
+    article.name = "Article \(i)"
+}
+try context.save()
+```
+
+### Batch Insert (Fast)
+
+```swift
+// Inserting 1000 objects: ~0.5 seconds
+var index = 0
+let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+    guard index < 1000 else { return true }
+    guard let article = object as? Article else { return true }
+    article.name = "Article \(index)"
+    index += 1
+    return false
+}
+try context.execute(batchInsert)
+```
+
+**Performance gain: ~20x faster**
+
+## When to Use Batch Operations
+
+### Use Batch Insert When:
+- Importing large datasets (>100 objects)
+- Initial data seeding
+- Syncing data from server
+- Performance is critical
+
+### Use Batch Delete When:
+- Deleting many objects at once
+- Clearing old data
+- Implementing data retention policies
+- Performance is critical
+
+### Use Batch Update When:
+- Updating many objects with same values
+- Bulk status changes
+- Incrementing counters
+- Performance is critical
+
+### Don't Use Batch Operations When:
+- Need to set relationships
+- Need validation
+- Need to trigger lifecycle events (willSave, etc.)
+- Working with small datasets (<50 objects)
+- Need immediate UI updates without persistent history tracking
+
+## Complete Example: Import with Batch Insert
+
+```swift
+class DataImporter {
+    let container: NSPersistentContainer
+    
+    init(container: NSPersistentContainer) {
+        self.container = container
+    }
+    
+    func importArticles(_ data: [ArticleData]) {
+        let context = container.newBackgroundContext()
+        
+        context.perform {
+            var index = 0
+            let batchInsert = NSBatchInsertRequest(
+                entity: Article.entity()
+            ) { (object: NSManagedObject) -> Bool in
+                guard index < data.count else { return true }
+                guard let article = object as? Article else { return true }
+                
+                let articleData = data[index]
+                article.name = articleData.name
+                article.content = articleData.content
+                article.views = 0
+                article.creationDate = Date()
+                
+                index += 1
+                return false
+            }
+            
+            do {
+                let result = try context.execute(batchInsert) as? NSBatchInsertResult
+                print("Inserted \(data.count) articles")
+                
+                // If you need the object IDs
+                if let objectIDs = result?.result as? [NSManagedObjectID] {
+                    print("Object IDs: \(objectIDs)")
+                }
+            } catch {
+                print("Batch insert failed: \(error)")
+            }
+        }
+    }
+}
+```
+
+## Complete Example: Cleanup with Batch Delete
+
+```swift
+class DataCleaner {
+    let container: NSPersistentContainer
+    
+    init(container: NSPersistentContainer) {
+        self.container = container
+    }
+    
+    func deleteOldArticles(olderThan days: Int) {
+        let context = container.newBackgroundContext()
+        
+        context.perform {
+            let cutoffDate = Calendar.current.date(
+                byAdding: .day,
+                value: -days,
+                to: Date()
+            )!
+            
+            let fetchRequest: NSFetchRequest<NSFetchRequestResult> = Article.fetchRequest()
+            fetchRequest.predicate = NSPredicate(
+                format: "creationDate < %@",
+                cutoffDate as NSDate
+            )
+            
+            let batchDelete = NSBatchDeleteRequest(fetchRequest: fetchRequest)
+            batchDelete.resultType = .resultTypeCount
+            
+            do {
+                let result = try context.execute(batchDelete) as? NSBatchDeleteResult
+                if let count = result?.result as? Int {
+                    print("Deleted \(count) old articles")
+                }
+            } catch {
+                print("Batch delete failed: \(error)")
+            }
+        }
+    }
+}
+```
+
+## Common Pitfalls
+
+### ❌ Not Enabling Persistent History Tracking
+
+```swift
+// Batch insert happens
+let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { ... }
+try context.execute(batchInsert)
+
+// UI doesn't update! No notifications sent
+```
+
+### ❌ Trying to Set Relationships
+
+```swift
+let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+    guard let article = object as? Article else { return true }
+    article.category = category // Won't work!
+    return false
+}
+```
+
+### ❌ Expecting Validation
+
+```swift
+// No validation happens!
+let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+    guard let article = object as? Article else { return true }
+    article.name = "" // Empty name - no validation error
+    return false
+}
+```
+
+### ❌ Using on View Context
+
+```swift
+// Don't use batch operations on view context
+viewContext.perform {
+    let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { ... }
+    try? viewContext.execute(batchInsert) // Blocks UI!
+}
+```
+
+### ✅ Correct Approach
+
+```swift
+// 1. Enable persistent history tracking
+description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
+
+// 2. Use background context
+let context = container.newBackgroundContext()
+
+// 3. Execute batch operation
+context.perform {
+    let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+        guard let article = object as? Article else { return true }
+        article.name = "Valid Name"
+        return false
+    }
+    try? context.execute(batchInsert)
+}
+
+// 4. UI updates via persistent history tracking
+```
+
+## Testing Batch Operations
+
+```swift
+func testBatchInsert() throws {
+    let context = container.newBackgroundContext()
+    
+    let expectation = XCTestExpectation(description: "Batch insert")
+    
+    context.perform {
+        var count = 0
+        let batchInsert = NSBatchInsertRequest(entity: Article.entity()) { object in
+            guard count < 10 else { return true }
+            guard let article = object as? Article else { return true }
+            article.name = "Article \(count)"
+            count += 1
+            return false
+        }
+        
+        do {
+            try context.execute(batchInsert)
+            expectation.fulfill()
+        } catch {
+            XCTFail("Batch insert failed: \(error)")
+        }
+    }
+    
+    wait(for: [expectation], timeout: 5.0)
+    
+    // Verify
+    let fetchRequest = Article.fetchRequest()
+    let articles = try context.fetch(fetchRequest)
+    XCTAssertEqual(articles.count, 10)
+}
+```
+
+## Summary
+
+1. **Use batch operations for large datasets** - 10-20x performance improvement
+2. **Enable persistent history tracking** - Required for UI updates
+3. **Use background contexts** - Don't block UI
+4. **Can't set relationships in batch insert** - Set them separately if needed
+5. **No validation or lifecycle events** - Batch operations bypass object graph
+6. **Get result types** - Use resultType to get object IDs or counts
+7. **Test thoroughly** - Verify data integrity after batch operations
+8. **Consider trade-offs** - Speed vs validation/relationships/lifecycle events