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/fetch-requests.md
View on GitHub# Fetch Requests and Querying
Optimizing fetch requests is crucial for app performance. This guide covers best practices for querying Core Data efficiently, from basic fetches to advanced aggregations.
## Basic Fetch Request
```swift
let fetchRequest: NSFetchRequest<Article> = Article.fetchRequest()
let articles = try context.fetch(fetchRequest)
```
## Optimization Strategies
### 1. Limit Properties Fetched
Only fetch the properties you actually need:
```swift
let fetchRequest = Article.fetchRequest()
fetchRequest.propertiesToFetch = ["name", "creationDate"]
// For list view, you might only need:
fetchRequest.propertiesToFetch = ["name", "categoryName", "views"]
```
**SQL Impact:**
```sql
-- Without propertiesToFetch
SELECT * FROM ZARTICLE
-- With propertiesToFetch
SELECT Z_PK, ZNAME, ZCREATIONDATE FROM ZARTICLE
```
**Benefits:**
- Reduces memory usage
- Faster query execution
- Less data transferred from disk
### 2. Use Batch Fetching
Fetch objects in batches to avoid loading everything at once:
```swift
let fetchRequest = Article.fetchRequest()
fetchRequest.fetchBatchSize = 20
```
**How it works:**
- Initially fetches only 20 objects
- Fetches next batch when needed (scrolling, iteration)
- Keeps memory usage predictable
**When to use:**
- List views (table/collection views)
- Large datasets
- Scrollable content
### 3. Set Fetch Limit
When you only need a specific number of results:
```swift
let fetchRequest = Article.fetchRequest()
fetchRequest.fetchLimit = 1 // Only fetch one result
```
**Common use cases:**
```swift
// Get newest article
fetchRequest.sortDescriptors = [NSSortDescriptor(key: "creationDate", ascending: false)]
fetchRequest.fetchLimit = 1
// Get top 10 most viewed
fetchRequest.sortDescriptors = [NSSortDescriptor(key: "views", ascending: false)]
fetchRequest.fetchLimit = 10
```
### 4. Fetch Only Object IDs
For counting or checking existence, fetch only IDs:
```swift
let fetchRequest = Article.fetchRequest()
fetchRequest.resultType = .managedObjectIDResultType
let objectIDs = try context.fetch(fetchRequest) as! [NSManagedObjectID]
```
**Benefits:**
- Minimal memory usage
- Very fast
- No faulting overhead
**Use for:**
- Counting objects
- Checking existence
- Batch operations
- Validation
## Sort Descriptors
Always specify sort descriptors for predictable results:
```swift
let fetchRequest = Article.fetchRequest()
fetchRequest.sortDescriptors = [
NSSortDescriptor(key: "creationDate", ascending: false)
]
```
### Multiple Sort Descriptors
```swift
fetchRequest.sortDescriptors = [
NSSortDescriptor(key: "category.name", ascending: true),
NSSortDescriptor(key: "name", ascending: true)
]
```
### Case-Insensitive Sorting
```swift
let sortDescriptor = NSSortDescriptor(
key: "name",
ascending: true,
selector: #selector(NSString.caseInsensitiveCompare(_:))
)
fetchRequest.sortDescriptors = [sortDescriptor]
```
### Localized Sorting
```swift
let sortDescriptor = NSSortDescriptor(
key: "name",
ascending: true,
selector: #selector(NSString.localizedStandardCompare(_:))
)
fetchRequest.sortDescriptors = [sortDescriptor]
```
## Predicates
Filter results using predicates:
### Basic Predicates
```swift
// Exact match
fetchRequest.predicate = NSPredicate(format: "name == %@", "SwiftLee")
// Contains
fetchRequest.predicate = NSPredicate(format: "name CONTAINS[cd] %@", "swift")
// [c] = case insensitive, [d] = diacritic insensitive
// Begins with
fetchRequest.predicate = NSPredicate(format: "name BEGINSWITH[c] %@", "Swift")
// Greater than
fetchRequest.predicate = NSPredicate(format: "views > %d", 100)
// Date range
let startDate = Calendar.current.startOfDay(for: Date())
let endDate = Calendar.current.date(byAdding: .day, value: 1, to: startDate)!
fetchRequest.predicate = NSPredicate(
format: "creationDate >= %@ AND creationDate < %@",
startDate as NSDate,
endDate as NSDate
)
```
### Compound Predicates
```swift
// AND
let predicate1 = NSPredicate(format: "views > %d", 100)
let predicate2 = NSPredicate(format: "category.name == %@", "Swift")
fetchRequest.predicate = NSCompoundPredicate(andPredicateWithSubpredicates: [predicate1, predicate2])
// OR
fetchRequest.predicate = NSCompoundPredicate(orPredicateWithSubpredicates: [predicate1, predicate2])
// NOT
fetchRequest.predicate = NSCompoundPredicate(notPredicateWithSubpredicate: predicate1)
```
### Relationship Predicates
```swift
// Articles with a specific category
fetchRequest.predicate = NSPredicate(format: "category.name == %@", "Swift")
// Articles with any attachments
fetchRequest.predicate = NSPredicate(format: "attachments.@count > 0")
// Articles with more than 5 attachments
fetchRequest.predicate = NSPredicate(format: "attachments.@count > 5")
// Using ANY
fetchRequest.predicate = NSPredicate(format: "ANY attachments.size > %d", 1000000)
// Using ALL
fetchRequest.predicate = NSPredicate(format: "ALL attachments.isDownloaded == YES")
```
### IN Predicate
```swift
let names = ["Swift", "iOS", "Core Data"]
fetchRequest.predicate = NSPredicate(format: "name IN %@", names)
```
## NSFetchedResultsController
For table and collection views, use `NSFetchedResultsController` for automatic updates:
```swift
class ArticlesViewController: UIViewController {
var fetchedResultsController: NSFetchedResultsController<Article>!
func setupFetchedResultsController() {
let fetchRequest = Article.fetchRequest()
fetchRequest.sortDescriptors = [
NSSortDescriptor(key: "creationDate", ascending: false)
]
fetchRequest.fetchBatchSize = 20
fetchedResultsController = NSFetchedResultsController(
fetchRequest: fetchRequest,
managedObjectContext: viewContext,
sectionNameKeyPath: nil,
cacheName: "ArticlesCache"
)
fetchedResultsController.delegate = self
try? fetchedResultsController.performFetch()
}
}
```
### With Sections
```swift
fetchedResultsController = NSFetchedResultsController(
fetchRequest: fetchRequest,
managedObjectContext: viewContext,
sectionNameKeyPath: "category.name", // Group by category
cacheName: "ArticlesByCategoryCache"
)
```
### Delegate Methods (UITableView)
```swift
extension ArticlesViewController: NSFetchedResultsControllerDelegate {
func controllerWillChangeContent(_ controller: NSFetchedResultsController<NSFetchRequestResult>) {
tableView.beginUpdates()
}
func controller(_ controller: NSFetchedResultsController<NSFetchRequestResult>,
didChange anObject: Any,
at indexPath: IndexPath?,
for type: NSFetchedResultsChangeType,
newIndexPath: IndexPath?) {
switch type {
case .insert:
if let indexPath = newIndexPath {
tableView.insertRows(at: [indexPath], with: .automatic)
}
case .delete:
if let indexPath = indexPath {
tableView.deleteRows(at: [indexPath], with: .automatic)
}
case .update:
if let indexPath = indexPath {
tableView.reloadRows(at: [indexPath], with: .automatic)
}
case .move:
if let indexPath = indexPath, let newIndexPath = newIndexPath {
tableView.deleteRows(at: [indexPath], with: .automatic)
tableView.insertRows(at: [newIndexPath], with: .automatic)
}
@unknown default:
break
}
}
func controllerDidChangeContent(_ controller: NSFetchedResultsController<NSFetchRequestResult>) {
tableView.endUpdates()
}
}
```
## Diffable Data Sources (iOS 13+)
Modern approach using `NSDiffableDataSourceSnapshot`:
```swift
class ArticlesViewController: UICollectionViewController {
private var dataSource: UICollectionViewDiffableDataSource<String, NSManagedObjectID>!
private var fetchedResultsController: NSFetchedResultsController<Article>!
func setupDataSource() {
dataSource = UICollectionViewDiffableDataSource<String, NSManagedObjectID>(
collectionView: collectionView
) { collectionView, indexPath, objectID in
let cell = collectionView.dequeueReusableCell(
withReuseIdentifier: "ArticleCell",
for: indexPath
) as! ArticleCell
if let article = try? self.viewContext.existingObject(with: objectID) as? Article {
cell.configure(with: article)
}
return cell
}
}
func setupFetchedResultsController() {
let fetchRequest = Article.fetchRequest()
fetchRequest.sortDescriptors = [NSSortDescriptor(key: "name", ascending: true)]
fetchedResultsController = NSFetchedResultsController(
fetchRequest: fetchRequest,
managedObjectContext: viewContext,
sectionNameKeyPath: nil,
cacheName: nil
)
fetchedResultsController.delegate = self
try? fetchedResultsController.performFetch()
}
}
extension ArticlesViewController: NSFetchedResultsControllerDelegate {
func controller(_ controller: NSFetchedResultsController<NSFetchRequestResult>,
didChangeContentWith snapshot: NSDiffableDataSourceSnapshotReference) {
let snapshot = snapshot as NSDiffableDataSourceSnapshot<String, NSManagedObjectID>
dataSource.apply(snapshot, animatingDifferences: true)
}
}
```
## Aggregate Fetching with NSExpression
For statistics and aggregations:
### Count
```swift
// Simple count
let count = try context.count(for: Article.fetchRequest())
// Count with predicate
let fetchRequest = Article.fetchRequest()
fetchRequest.predicate = NSPredicate(format: "views > %d", 100)
let count = try context.count(for: fetchRequest)
```
### Sum, Average, Min, Max
```swift
let fetchRequest = Article.fetchRequest()
fetchRequest.resultType = .dictionaryResultType
// Sum of views
let sumExpression = NSExpression(format: "@sum.views")
let sumDescription = NSExpressionDescription()
sumDescription.name = "totalViews"
sumDescription.expression = sumExpression
sumDescription.expressionResultType = .integer64AttributeType
fetchRequest.propertiesToFetch = [sumDescription]
let results = try context.fetch(fetchRequest) as! [[String: Any]]
if let totalViews = results.first?["totalViews"] as? Int {
print("Total views: \(totalViews)")
}
```
### Group By with Aggregates
```swift
let fetchRequest = Article.fetchRequest()
fetchRequest.resultType = .dictionaryResultType
// Category name
let categoryExpression = NSExpression(forKeyPath: "category.name")
let categoryDescription = NSExpressionDescription()
categoryDescription.name = "categoryName"
categoryDescription.expression = categoryExpression
categoryDescription.expressionResultType = .stringAttributeType
// Sum of views per category
let sumExpression = NSExpression(format: "@sum.views")
let sumDescription = NSExpressionDescription()
sumDescription.name = "totalViews"
sumDescription.expression = sumExpression
sumDescription.expressionResultType = .integer64AttributeType
fetchRequest.propertiesToFetch = [categoryDescription, sumDescription]
fetchRequest.propertiesToGroupBy = ["category.name"]
fetchRequest.sortDescriptors = [NSSortDescriptor(key: "categoryName", ascending: true)]
let results = try context.fetch(fetchRequest) as! [[String: Any]]
for result in results {
let category = result["categoryName"] as? String ?? "Unknown"
let views = result["totalViews"] as? Int ?? 0
print("\(category): \(views) views")
}
```
### Count Per Group
```swift
let fetchRequest = Article.fetchRequest()
fetchRequest.resultType = .dictionaryResultType
let categoryExpression = NSExpression(forKeyPath: "category.name")
let categoryDescription = NSExpressionDescription()
categoryDescription.name = "categoryName"
categoryDescription.expression = categoryExpression
categoryDescription.expressionResultType = .stringAttributeType
let countExpression = NSExpression(forFunction: "count:", arguments: [NSExpression(forKeyPath: "objectID")])
let countDescription = NSExpressionDescription()
countDescription.name = "count"
countDescription.expression = countExpression
countDescription.expressionResultType = .integer64AttributeType
fetchRequest.propertiesToFetch = [categoryDescription, countDescription]
fetchRequest.propertiesToGroupBy = ["category.name"]
let results = try context.fetch(fetchRequest) as! [[String: Any]]
```
## Typed Fetch Requests with Managed Protocol
Create a protocol for type-safe fetch requests:
```swift
protocol Managed: NSManagedObject {
static var entityName: String { get }
}
extension Managed {
static var entityName: String {
return String(describing: self)
}
static func fetchRequest<T: NSManagedObject>() -> NSFetchRequest<T> {
return NSFetchRequest<T>(entityName: entityName)
}
}
// Conform your entities
extension Article: Managed {}
// Usage
let fetchRequest: NSFetchRequest<Article> = Article.fetchRequest()
```
## Asynchronous Fetching
For large datasets, fetch asynchronously:
```swift
let fetchRequest = Article.fetchRequest()
let asyncFetchRequest = NSAsynchronousFetchRequest(fetchRequest: fetchRequest) { result in
guard let articles = result.finalResult else { return }
DispatchQueue.main.async {
// Update UI with articles
}
}
try? context.execute(asyncFetchRequest)
```
## Faulting Control
### Prefetching Relationships
```swift
let fetchRequest = Article.fetchRequest()
fetchRequest.relationshipKeyPathsForPrefetching = ["category", "attachments"]
```
**Benefits:**
- Reduces number of database trips
- Improves performance when accessing relationships
- Prevents N+1 query problem
### Returning Faults
```swift
fetchRequest.returnsObjectsAsFaults = false
```
**When to use:**
- You know you'll access all properties immediately
- Small result sets
- Avoid for large datasets (high memory usage)
## Common Patterns
### Fetch Single Object by ID
```swift
func fetchArticle(withID id: NSManagedObjectID) -> Article? {
return try? context.existingObject(with: id) as? Article
}
```
### Fetch or Create
```swift
func fetchOrCreateArticle(withName name: String) -> Article {
let fetchRequest = Article.fetchRequest()
fetchRequest.predicate = NSPredicate(format: "name == %@", name)
fetchRequest.fetchLimit = 1
if let existing = try? context.fetch(fetchRequest).first {
return existing
}
let article = Article(context: context)
article.name = name
return article
}
```
### Check Existence
```swift
func articleExists(withName name: String) -> Bool {
let fetchRequest = Article.fetchRequest()
fetchRequest.predicate = NSPredicate(format: "name == %@", name)
fetchRequest.fetchLimit = 1
fetchRequest.resultType = .countResultType
let count = (try? context.count(for: fetchRequest)) ?? 0
return count > 0
}
```
## Performance Tips
### ❌ Don't Fetch Everything
```swift
// Bad: Fetches all properties, all objects
let articles = try context.fetch(Article.fetchRequest())
let count = articles.count
```
### ✅ Use Count Request
```swift
// Good: Only counts, doesn't fetch objects
let count = try context.count(for: Article.fetchRequest())
```
### ❌ Don't Access Relationships in Loops
```swift
// Bad: Fires fault for each article
for article in articles {
print(article.category?.name) // Fault!
}
```
### ✅ Prefetch Relationships
```swift
// Good: Prefetches all categories at once
let fetchRequest = Article.fetchRequest()
fetchRequest.relationshipKeyPathsForPrefetching = ["category"]
let articles = try context.fetch(fetchRequest)
for article in articles {
print(article.category?.name) // No fault!
}
```
### ❌ Don't Fetch in Loops
```swift
// Bad: Multiple fetch requests
for name in names {
let fetchRequest = Article.fetchRequest()
fetchRequest.predicate = NSPredicate(format: "name == %@", name)
let articles = try? context.fetch(fetchRequest)
}
```
### ✅ Use IN Predicate
```swift
// Good: Single fetch request
let fetchRequest = Article.fetchRequest()
fetchRequest.predicate = NSPredicate(format: "name IN %@", names)
let articles = try context.fetch(fetchRequest)
```
## Debugging Fetch Requests
### Enable SQL Debug
Add launch argument:
```
-com.apple.CoreData.SQLDebug 1
```
**Output:**
```sql
CoreData: sql: SELECT Z_PK, ZNAME, ZVIEWS FROM ZARTICLE WHERE ZVIEWS > ? ORDER BY ZCREATIONDATE DESC LIMIT 20
```
### Measure Fetch Performance
```swift
let startTime = CFAbsoluteTimeGetCurrent()
let articles = try context.fetch(fetchRequest)
let timeElapsed = CFAbsoluteTimeGetCurrent() - startTime
print("Fetch took \(timeElapsed) seconds")
```
## Summary
1. **Use `propertiesToFetch`** to limit fetched properties
2. **Set `fetchBatchSize`** for large datasets (typically 20-50)
3. **Use `fetchLimit`** when you only need a few results
4. **Always specify sort descriptors** for predictable results
5. **Use predicates** to filter at the database level
6. **Use `NSFetchedResultsController`** for list views
7. **Prefetch relationships** to avoid N+1 queries
8. **Use count requests** instead of fetching for counts
9. **Use aggregate expressions** for statistics
10. **Enable SQL debug** to understand query performance
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 |