AvdLee/Core-Data-Agent-Skill / core-data-expert
core-data-expert
VerifiedExpert Core Data guidance (iOS/macOS): stack setup, fetch requests & NSFetchedResultsController, saving/merge conflicts, threading & Swift Concurrency, batch operations & persistent history, migrations, performance, and NSPersistentCloudKitContainer/CloudKit sync.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.8 KB |
| references/_index.md | markdown | 4.0 KB |
| references/batch-operations.md | markdown | 14.4 KB |
| references/cloudkit-integration.md | markdown | 6.2 KB |
| references/concurrency.md | markdown | 12.5 KB |
| references/fetch-requests.md | markdown | 17.1 KB |
| references/glossary.md | markdown | 5.6 KB |
| references/migration.md | markdown | 10.6 KB |
| references/model-configuration.md | markdown | 14.2 KB |
| references/performance.md | markdown | 6.2 KB |
| references/persistent-history.md | markdown | 17.1 KB |
| references/project-audit.md | markdown | 2.1 KB |
| references/saving.md | markdown | 13.7 KB |
| references/stack-setup.md | markdown | 17.5 KB |
| references/testing.md | markdown | 7.8 KB |
| references/threading.md | markdown | 14.1 KB |
references/batch-operations.md
View on GitHub# 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |