Cloudkit

CloudKit

Sync data across devices using CloudKit, iCloud key-value storage, and iCloud Drive. Covers container setup, record CRUD, queries, subscriptions, CKSyncEngine, SwiftData integration, conflict resolution, and error handling. Targets iOS 26+ with Swift 6.3; older availability noted where relevant.

Contents

• Container and Database Setup
• CKRecord CRUD
• CKQuery
• CKSubscription
• CKSyncEngine (iOS 17+)
• SwiftData + CloudKit
• NSUbiquitousKeyValueStore
• iCloud Drive File Sync
• Account Status and Error Handling
• Conflict Resolution
• Common Mistakes
• Review Checklist
• References

Container and Database Setup

Enable iCloud + CloudKit in Signing & Capabilities. A container provides three databases:

import CloudKit

let container = CKContainer.default()
// Or named: CKContainer(identifier: "iCloud.com.example.app")

let publicDB  = container.publicCloudDatabase
let privateDB = container.privateCloudDatabase
let sharedDB  = container.sharedCloudDatabase

CKRecord CRUD

Records are key-value pairs. Max 1 MB per record (excluding CKAsset data).

// CREATE
let record = CKRecord(recordType: "Note")
record["title"] = "Meeting Notes" as CKRecordValue
record["body"] = "Discussed Q3 roadmap" as CKRecordValue
record["createdAt"] = Date() as CKRecordValue
record["tags"] = ["work", "planning"] as CKRecordValue
let saved = try await privateDB.save(record)

// FETCH by ID
let recordID = CKRecord.ID(recordName: "unique-id-123")
let fetched = try await privateDB.record(for: recordID)

// UPDATE -- fetch first, modify, then save
fetched["title"] = "Updated Title" as CKRecordValue
let updated = try await privateDB.save(fetched)

// DELETE
try await privateDB.deleteRecord(withID: recordID)

Custom Record Zones

Apps create custom zones in the private database. Shared databases expose zones that other users share with the current user. Custom zones support atomic commits, change tracking, and sharing; public databases do not support custom zones.

let zoneID = CKRecordZone.ID(zoneName: "NotesZone")
let zone = CKRecordZone(zoneID: zoneID)
try await privateDB.save(zone)

let recordID = CKRecord.ID(recordName: UUID().uuidString, zoneID: zoneID)
let record = CKRecord(recordType: "Note", recordID: recordID)

CKQuery

Query records with NSPredicate. Supported: ==, !=, <, >, <=, >=, BEGINSWITH, CONTAINS, IN, AND, NOT, BETWEEN, distanceToLocation:fromLocation:.

CONTAINS tests list membership except for tokenized full-text search with self CONTAINS. BEGINSWITH is the string-prefix operator; unsupported operators, key paths, or field types fail when the query executes. For every encryption review, explicitly call out field eligibility: encrypted values cannot be queried or sorted; CKAsset is encrypted by default; and CKRecord.Reference cannot be encrypted because CloudKit needs it server-side.

let predicate = NSPredicate(format: "title BEGINSWITH %@", "Meeting")
let query = CKQuery(recordType: "Note", predicate: predicate)
query.sortDescriptors = [NSSortDescriptor(key: "createdAt", ascending: false)]

let (results, _) = try await privateDB.records(matching: query)
for (_, result) in results {
    let record = try result.get()
    print(record["title"] as? String ?? "")
}

// Fetch all records of a type
let allQuery = CKQuery(recordType: "Note", predicate: NSPredicate(value: true))

// Full-text search across string fields
let searchQuery = CKQuery(
    recordType: "Note",
    predicate: NSPredicate(format: "self CONTAINS %@", "roadmap")
)

// Compound predicate
let compound = NSCompoundPredicate(andPredicateWithSubpredicates: [
    NSPredicate(format: "createdAt > %@", cutoffDate as NSDate),
    NSPredicate(format: "tags CONTAINS %@", "work")
])

CKSubscription

Subscriptions trigger push notifications when records change server-side. CloudKit/Xcode handles the APNs entitlement when CloudKit is enabled; no separate explicit App ID push setup is needed. Silent/background processing still needs Background Modes > Remote notifications.

// Query subscription -- fires when matching records change
let subscription = CKQuerySubscription(
    recordType: "Note",
    predicate: NSPredicate(format: "tags CONTAINS %@", "urgent"),
    subscriptionID: "urgent-notes",
    options: [.firesOnRecordCreation, .firesOnRecordUpdate]
)
let notifInfo = CKSubscription.NotificationInfo()
notifInfo.shouldSendContentAvailable = true  // silent push
subscription.notificationInfo = notifInfo
try await privateDB.save(subscription)

// Database subscription -- fires on any database change
let dbSub = CKDatabaseSubscription(subscriptionID: "private-db-changes")
dbSub.notificationInfo = notifInfo
try await privateDB.save(dbSub)

// Record zone subscription -- fires on changes within a zone
let zoneSub = CKRecordZoneSubscription(
    zoneID: CKRecordZone.ID(zoneName: "NotesZone"),
    subscriptionID: "notes-zone-changes"
)
zoneSub.notificationInfo = notifInfo
try await privateDB.save(zoneSub)

Handle in AppDelegate:

func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any]
) async -> UIBackgroundFetchResult {
    let notification = CKNotification(fromRemoteNotificationDictionary: userInfo)
    guard notification?.subscriptionID == "private-db-changes" else { return .noData }
    // Fetch changes using CKSyncEngine or CKFetchRecordZoneChangesOperation
    return .newData
}

CKSyncEngine (iOS 17+)

CKSyncEngine is the recommended sync approach for custom model data. It handles scheduling, transient retries, change tokens, and database subscriptions, but not app-specific save failures: CKError.serverRecordChanged from sentRecordZoneChanges.failedRecordSaves still requires custom conflict resolution and rescheduling. Automatic sync timing is indeterminate. Requires CloudKit capability + Remote notifications; private/shared databases only.

import CloudKit

final class SyncManager: CKSyncEngineDelegate {
    let syncEngine: CKSyncEngine

    init(container: CKContainer = .default()) {
        let config = CKSyncEngine.Configuration(
            database: container.privateCloudDatabase,
            stateSerialization: Self.loadState(),
            delegate: self
        )
        self.syncEngine = CKSyncEngine(config)
    }

    func handleEvent(_ event: CKSyncEngine.Event, syncEngine: CKSyncEngine) async {
        switch event {
        case .stateUpdate(let update):
            Self.saveState(update.stateSerialization)
        case .accountChange(let change):
            handleAccountChange(change)
        case .fetchedRecordZoneChanges(let changes):
            for mod in changes.modifications { processRemoteRecord(mod.record) }
            for del in changes.deletions { processRemoteDeletion(del.recordID) }
        case .sentRecordZoneChanges(let sent):
            for saved in sent.savedRecords { markSynced(saved) }
            for fail in sent.failedRecordSaves { handleSaveFailure(fail) }
        default: break
        }
    }

    func nextRecordZoneChangeBatch(
        _ context: CKSyncEngine.SendChangesContext,
        syncEngine: CKSyncEngine
    ) async -> CKSyncEngine.RecordZoneChangeBatch? {
        let pending = syncEngine.state.pendingRecordZoneChanges
            .filter { context.options.zoneIDs.contains($0) }
        return await CKSyncEngine.RecordZoneChangeBatch(
            pendingChanges: pending
        ) { recordID in self.recordToSend(for: recordID) }
    }
}

// Schedule changes
let zoneID = CKRecordZone.ID(zoneName: "NotesZone")
let recordID = CKRecord.ID(recordName: noteID, zoneID: zoneID)
syncEngine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])

// Trigger immediate sync (pull-to-refresh)
try await syncEngine.fetchChanges()
try await syncEngine.sendChanges()

Key point: persist stateSerialization across launches; the engine needs it to resume from the correct change token.

SwiftData + CloudKit

ModelConfiguration supports CloudKit sync. In every SwiftData CloudKit implementation or review, always report two verdicts:

• Model compatibility: no #Unique or unique constraints, optional

relationships, no .deny, and external storage for large Data.

• Schema rollout: initialize the development schema in nonproduction builds,

verify it in CloudKit Dashboard, promote it before release, and after production promotion only add schema; don't delete model types or change existing attributes.

import SwiftData

@Model
class Note {
    var title: String
    var body: String?
    var createdAt: Date?
    @Attribute(.externalStorage) var imageData: Data?

    init(title: String, body: String? = nil) {
        self.title = title
        self.body = body
        self.createdAt = Date()
    }
}

let config = ModelConfiguration(
    "Notes",
    cloudKitDatabase: .private("iCloud.com.example.app")
)
let container = try ModelContainer(for: Note.self, configurations: config)

NSUbiquitousKeyValueStore

Simple key-value sync. Max 1024 keys, 1 MB total, 1 MB per value. Stores locally when iCloud is unavailable.

let kvStore = NSUbiquitousKeyValueStore.default

// Write
kvStore.set("dark", forKey: "theme")
kvStore.set(14.0, forKey: "fontSize")
kvStore.set(true, forKey: "notificationsEnabled")
kvStore.synchronize()

// Read
let theme = kvStore.string(forKey: "theme") ?? "system"

// Observe external changes
NotificationCenter.default.addObserver(
    forName: NSUbiquitousKeyValueStore.didChangeExternallyNotification,
    object: kvStore, queue: .main
) { notification in
    guard let userInfo = notification.userInfo,
          let reason = userInfo[NSUbiquitousKeyValueStoreChangeReasonKey] as? Int,
          let keys = userInfo[NSUbiquitousKeyValueStoreChangedKeysKey] as? [String]
    else { return }

    switch reason {
    case NSUbiquitousKeyValueStoreServerChange:
        for key in keys { applyRemoteChange(key: key) }
    case NSUbiquitousKeyValueStoreInitialSyncChange:
        reloadAllSettings()
    case NSUbiquitousKeyValueStoreQuotaViolationChange:
        handleQuotaExceeded()
    default: break
    }
}

iCloud Drive File Sync

Use FileManager ubiquity APIs for document-level sync. Call url(forUbiquityContainerIdentifier:) and setUbiquitous off the main thread; setUbiquitous performs coordinated file work and can block. If the app is presenting the file, configure an active file presenter before moving it.

Task.detached {
    guard let ubiquityURL = FileManager.default.url(
        forUbiquityContainerIdentifier: "iCloud.com.example.app"
    ) else { return }  // iCloud not available

    let docsURL = ubiquityURL.appendingPathComponent("Documents")
    try FileManager.default.createDirectory(at: docsURL, withIntermediateDirectories: true)
    let cloudURL = docsURL.appendingPathComponent("report.pdf")
    try FileManager.default.setUbiquitous(true, itemAt: localURL, destinationURL: cloudURL)
}

Monitor files with NSMetadataQuery scoped to NSMetadataQueryUbiquitousDocumentsScope or NSMetadataQueryUbiquitousDataScope.

Account Status and Error Handling

Always check account status before sync. Listen for .CKAccountChanged.

func checkiCloudStatus() async throws -> CKAccountStatus {
    let status = try await CKContainer.default().accountStatus()
    switch status {
    case .available: return status
    case .noAccount: throw SyncError.noiCloudAccount
    case .restricted: throw SyncError.restricted
    case .temporarilyUnavailable: throw SyncError.temporarilyUnavailable
    case .couldNotDetermine: throw SyncError.unknown
    @unknown default: throw SyncError.unknown
    }
}

CKError Handling

func handleCloudKitError(_ error: Error) {
    guard let ckError = error as? CKError else { return }
    switch ckError.code {
    case .networkFailure, .networkUnavailable:
        scheduleRetryWhenOnline()
    case .serverRecordChanged:
        resolveConflict(ckError)
    case .requestRateLimited, .zoneBusy, .serviceUnavailable:
        let delay = ckError.retryAfterSeconds ?? 3.0
        scheduleRetry(after: delay)
    case .quotaExceeded:
        notifyUserStorageFull()
    case .partialFailure:
        if let partial = ckError.partialErrorsByItemID {
            for (_, itemError) in partial { handleCloudKitError(itemError) }
        }
    case .changeTokenExpired:
        resetChangeToken()
    case .userDeletedZone:
        recreateZoneAndResync()
    default: logError(ckError)
    }
}

Conflict Resolution

When saving a record that changed server-side, CloudKit returns .serverRecordChanged with three record versions. Always merge into serverRecord -- it has the correct change tag.

func resolveConflict(_ error: CKError) {
    guard error.code == .serverRecordChanged,
          let ancestor = error.ancestorRecord,
          let client = error.clientRecord,
          let server = error.serverRecord
    else { return }

    // Merge client changes into server record
    for key in client.changedKeys() {
        if server[key] == ancestor[key] {
            server[key] = client[key]           // Server unchanged, use client
        } else if client[key] == ancestor[key] {
            // Client unchanged, keep server (already there)
        } else {
            server[key] = mergeValues(          // Both changed, custom merge
                ancestor: ancestor[key], client: client[key], server: server[key])
        }
    }

    Task { try await CKContainer.default().privateCloudDatabase.save(server) }
}

Common Mistakes

DON'T: Perform sync operations without checking account status. DO: Check CKContainer.accountStatus() first; handle .noAccount.

// WRONG
try await privateDB.save(record)
// CORRECT
guard try await CKContainer.default().accountStatus() == .available
else { throw SyncError.noiCloudAccount }
try await privateDB.save(record)

DON'T: Ignore .serverRecordChanged errors. DO: Implement three-way merge using ancestor, client, and server records.

DON'T: Store user-specific data in the public database. DO: Use private database for personal data; public only for app-wide content.

DON'T: Poll for changes on a timer. DO: Use CKDatabaseSubscription or CKSyncEngine for push-based sync.

// WRONG
Timer.scheduledTimer(withTimeInterval: 30, repeats: true) { _ in fetchAll() }
// CORRECT
let sub = CKDatabaseSubscription(subscriptionID: "db-changes")
sub.notificationInfo = CKSubscription.NotificationInfo()
sub.notificationInfo?.shouldSendContentAvailable = true
try await privateDB.save(sub)

DON'T: Retry immediately on rate limiting. DO: Use CKError.retryAfterSeconds to wait the required duration.

DON'T: Assume CKSyncEngine handles .serverRecordChanged conflicts for you. DO: Resolve failedRecordSaves with a three-way merge, then reschedule the save.

DON'T: Pass nil change token on every fetch. DO: Persist change tokens to disk and supply them on subsequent fetches.

Review Checklist

• [ ] iCloud + CloudKit capability enabled in Signing & Capabilities
• [ ] Account status checked before sync; .noAccount handled gracefully
• [ ] Private database used for user data; public only for shared content
• [ ] Custom record zones created in private DB; shared DB zones discovered from shares
• [ ] CKError.serverRecordChanged handled with three-way merge into serverRecord
• [ ] Network failures queued for retry; retryAfterSeconds respected
• [ ] CKDatabaseSubscription or CKSyncEngine used for push-based sync; Remote notifications enabled for background delivery
• [ ] Change tokens persisted to disk; changeTokenExpired resets and refetches
• [ ] .partialFailure errors inspected per-item via partialErrorsByItemID
• [ ] .userDeletedZone handled by recreating zone and resyncing
• [ ] SwiftData CloudKit review reports model compatibility and schema rollout: initialized/verified development schema, promoted before release, and additive-only production changes
• [ ] NSUbiquitousKeyValueStore.didChangeExternallyNotification observed
• [ ] Encryption review says CKRecord.Reference cannot use encryptedValues because CloudKit needs it server-side; no query/sort on encrypted fields; CKAsset is encrypted by default
• [ ] CKSyncEngine state serialization persisted across launches (iOS 17+)

References

• See references/cloudkit-patterns.md for incremental sync, CKShare, zones, CKAsset storage, batch operations, and Dashboard usage.
• CloudKit Framework
• CKContainer
• CKRecord
• CKQuery
• CKSubscription
• CKSyncEngine
• CKShare
• CKError
• NSUbiquitousKeyValueStore
• SwiftData CloudKit sync

CloudKit Patterns

Advanced CloudKit patterns including incremental sync with CKFetchRecordZoneChangesOperation, sharing with CKShare, record zone management, CKAsset file storage, batch operations, and CloudKit Dashboard.

Contents

• CKFetchRecordZoneChangesOperation (Incremental Sync)
• Server Change Token Management
• CKShare and Collaboration
• UICloudSharingController
• Record Zone Management
• CKAsset File Storage
• Batch Operations
• Operation Queues and QoS
• Encrypted Fields
• CloudKit Dashboard
• CKFetchDatabaseChangesOperation

CKFetchRecordZoneChangesOperation (Incremental Sync)

Fetches only records that changed since the last sync. Works with private and shared databases only. Provide a server change token per zone; use nil for the initial fetch.

import CloudKit

final class IncrementalSyncManager {
    private let database: CKDatabase
    private var changeTokens: [CKRecordZone.ID: CKServerChangeToken] = [:]
    private let tokenCacheURL: URL

    init(database: CKDatabase, cacheDirectory: URL) {
        self.database = database
        self.tokenCacheURL = cacheDirectory.appendingPathComponent("changeTokens.data")
        loadTokens()
    }

    func fetchChanges(in zoneIDs: [CKRecordZone.ID]) async throws {
        var configs: [CKRecordZone.ID: CKFetchRecordZoneChangesOperation.ZoneConfiguration] = [:]
        for zoneID in zoneIDs {
            let config = CKFetchRecordZoneChangesOperation.ZoneConfiguration()
            config.previousServerChangeToken = changeTokens[zoneID]
            configs[zoneID] = config
        }

        let operation = CKFetchRecordZoneChangesOperation(
            recordZoneIDs: zoneIDs,
            configurationsByRecordZoneID: configs
        )
        operation.fetchAllChanges = true

        // Process changed records
        operation.recordWasChangedBlock = { recordID, result in
            switch result {
            case .success(let record):
                self.processChangedRecord(record)
            case .failure(let error):
                self.handleRecordError(recordID, error: error)
            }
        }

        // Process deleted records
        operation.recordWithIDWasDeletedBlock = { recordID, recordType in
            self.processDeletedRecord(recordID, type: recordType)
        }

        // Update change token as zones complete
        operation.recordZoneFetchResultBlock = { zoneID, result in
            switch result {
            case .success(let (serverChangeToken, _, _)):
                self.changeTokens[zoneID] = serverChangeToken
                self.saveTokens()
            case .failure(let error):
                if let ckError = error as? CKError,
                   ckError.code == .changeTokenExpired {
                    // Clear token and refetch from scratch
                    self.changeTokens[zoneID] = nil
                    self.saveTokens()
                }
            }
        }

        operation.fetchRecordZoneChangesResultBlock = { result in
            if case .failure(let error) = result {
                print("Fetch zone changes failed: \(error)")
            }
        }

        operation.qualityOfService = .utility
        database.add(operation)
    }

    // MARK: - Token Persistence

    private func loadTokens() {
        guard let data = try? Data(contentsOf: tokenCacheURL),
              let tokens = try? NSKeyedUnarchiver.unarchivedObject(
                  ofClasses: [NSDictionary.self, CKRecordZone.ID.self,
                              CKServerChangeToken.self],
                  from: data) as? [CKRecordZone.ID: CKServerChangeToken]
        else { return }
        changeTokens = tokens
    }

    private func saveTokens() {
        guard let data = try? NSKeyedArchiver.archivedData(
            withRootObject: changeTokens, requiringSecureCoding: true)
        else { return }
        try? data.write(to: tokenCacheURL)
    }
}

Server Change Token Management

Change tokens are opaque pointers to a point in a zone's change history. Rules:

• Tokens conform to NSSecureCoding -- safe to persist to disk.
• Zone change tokens are NOT interchangeable with database change tokens.
• A .changeTokenExpired error means the token is too old; reset to nil and

refetch all changes.

• On recordZoneFetchResultBlock, cache the returned token immediately.

// Persist token alongside zone ID
func cacheToken(_ token: CKServerChangeToken?, for zoneID: CKRecordZone.ID) {
    guard let token else {
        UserDefaults.standard.removeObject(forKey: "token-\(zoneID.zoneName)")
        return
    }
    let data = try? NSKeyedArchiver.archivedData(
        withRootObject: token, requiringSecureCoding: true)
    UserDefaults.standard.set(data, forKey: "token-\(zoneID.zoneName)")
}

func cachedToken(for zoneID: CKRecordZone.ID) -> CKServerChangeToken? {
    guard let data = UserDefaults.standard.data(forKey: "token-\(zoneID.zoneName)")
    else { return nil }
    return try? NSKeyedUnarchiver.unarchivedObject(
        ofClass: CKServerChangeToken.self, from: data)
}

CKShare and Collaboration

CKShare manages shared access to records or entire record zones. Limit: 100 participants per share. Available iOS 10+.

Hierarchy-Based Sharing

Share a root record and its children (linked via parent references).

import CloudKit

// Create a share for a root record
let rootRecord = CKRecord(recordType: "Album", recordID: albumRecordID)
let share = CKShare(rootRecord: rootRecord)
share.publicPermission = .readOnly

// Customize share appearance
share[CKShare.SystemFieldKey.title] = "Vacation Photos" as CKRecordValue
share[CKShare.SystemFieldKey.shareType] = "com.example.album" as CKRecordValue

// Save share and root record together
let operation = CKModifyRecordsOperation(
    recordsToSave: [rootRecord, share],
    recordIDsToDelete: nil
)
operation.modifyRecordsResultBlock = { result in
    switch result {
    case .success:
        print("Share URL: \(share.url?.absoluteString ?? "nil")")
    case .failure(let error):
        print("Sharing failed: \(error)")
    }
}
privateDB.add(operation)

Zone-Wide Sharing

Share all records in a custom zone.

let zoneID = CKRecordZone.ID(zoneName: "SharedAlbums")
let share = CKShare(recordZoneID: zoneID)
share.publicPermission = .readWrite

Adding Participants

// Look up participants by email
let lookupInfo = CKUserIdentity.LookupInfo(emailAddress: "friend@example.com")
let participants = try await container.shareParticipants(
    forEmailAddresses: ["friend@example.com"])

for participant in participants {
    participant.permission = .readWrite
    share.addParticipant(participant)
}

// Save the updated share
try await privateDB.save(share)

Accepting a Share

// In AppDelegate or SceneDelegate
func userDidAcceptCloudKitShare(with metadata: CKShare.Metadata) {
    let container = CKContainer(identifier: metadata.containerIdentifier)
    Task {
        do {
            try await container.accept([metadata])
            // Fetch shared records from container.sharedCloudDatabase
        } catch {
            print("Accept failed: \(error)")
        }
    }
}

Required: add CKSharingSupported = YES to Info.plist so the system can launch your app from share URLs.

UICloudSharingController

Present the system sharing UI (iOS only).

import UIKit
import CloudKit

func presentSharingUI(for share: CKShare, container: CKContainer,
                      from viewController: UIViewController) {
    let sharingController = UICloudSharingController(share: share, container: container)
    sharingController.delegate = self
    sharingController.availablePermissions = [.allowReadOnly, .allowReadWrite, .allowPrivate]
    viewController.present(sharingController, animated: true)
}

// UICloudSharingControllerDelegate
extension MyClass: UICloudSharingControllerDelegate {
    func cloudSharingController(
        _ csc: UICloudSharingController,
        failedToSaveShareWithError error: Error
    ) {
        print("Save share error: \(error)")
    }

    func itemTitle(for csc: UICloudSharingController) -> String? {
        return "My Shared Album"
    }
}

Record Zone Management

Custom record zones in the private database enable atomic commits, change tracking with tokens, and record sharing.

// Create
let zoneID = CKRecordZone.ID(zoneName: "NotesZone", ownerName: CKCurrentUserDefaultName)
let zone = CKRecordZone(zoneID: zoneID)
try await privateDB.save(zone)

// Fetch all zones
let zones = try await privateDB.allRecordZones()

// Delete
try await privateDB.deleteRecordZone(withID: zoneID)

Note: the default zone does not support custom change tokens or atomic operations. Always use custom zones for sync.

CKAsset File Storage

Use CKAsset for files, images, and binary data larger than a few KB. Assets do not count toward the 1 MB record limit.

// Save an image as a CKAsset
let tempURL = FileManager.default.temporaryDirectory.appendingPathComponent("photo.jpg")
try imageData.write(to: tempURL)

let record = CKRecord(recordType: "Photo")
record["image"] = CKAsset(fileURL: tempURL)
record["caption"] = "Sunset at the beach" as CKRecordValue
try await privateDB.save(record)

// Fetch and read the asset
let fetched = try await privateDB.record(for: record.recordID)
if let asset = fetched["image"] as? CKAsset,
   let fileURL = asset.fileURL {
    let data = try Data(contentsOf: fileURL)
    // Move to app container immediately -- staging area is temporary
    let permanentURL = documentsDir.appendingPathComponent("photo.jpg")
    try FileManager.default.moveItem(at: fileURL, to: permanentURL)
}

// Remove an asset (orphan it)
record["image"] = nil
try await privateDB.save(record)
// CloudKit periodically deletes orphaned assets from the server

Exclude assets from fetch when not needed using desiredKeys on operations to save bandwidth.

Batch Operations

Use CKModifyRecordsOperation for atomic saves and deletes.

let recordsToSave: [CKRecord] = [record1, record2, record3]
let idsToDelete: [CKRecord.ID] = [oldRecordID]

let operation = CKModifyRecordsOperation(
    recordsToSave: recordsToSave,
    recordIDsToDelete: idsToDelete
)
operation.savePolicy = .changedKeys       // Only upload modified fields
operation.isAtomic = true                 // All or nothing (custom zones only)

operation.perRecordSaveBlock = { recordID, result in
    switch result {
    case .success(let record): print("Saved: \(recordID)")
    case .failure(let error): print("Failed: \(recordID) \(error)")
    }
}

operation.perRecordDeleteBlock = { recordID, result in
    switch result {
    case .success: print("Deleted: \(recordID)")
    case .failure(let error): print("Delete failed: \(recordID) \(error)")
    }
}

operation.modifyRecordsResultBlock = { result in
    if case .failure(let error) = result {
        print("Batch failed: \(error)")
    }
}

// CloudKit limits: 400 records per operation
operation.qualityOfService = .userInitiated
privateDB.add(operation)

Max 400 records per operation. For larger batches, split into chunks.

Operation Queues and QoS

Set appropriate quality of service:

// Use operation groups for related operations
let group = CKOperationGroup()
group.expectedSendSize = .kilobytes
group.expectedReceiveSize = .megabytes

let config = CKOperation.Configuration()
config.qualityOfService = .utility
config.group = group

let operation = CKQueryOperation(query: query)
operation.configuration = config
database.add(operation)

Encrypted Fields

Use encryptedValues (iOS 15+) for sensitive private or shared data that does not need query or sort indexes. CloudKit can encrypt only new schema fields; you cannot convert an existing field to encrypted storage, and encrypted values are unavailable for public database records. CKAsset data is encrypted by default, while CKRecord.Reference is not encrypted because CloudKit needs it for server-side relationship handling.

let record = CKRecord(recordType: "HealthEntry")
record.encryptedValues["heartRate"] = 72 as CKRecordValue
record.encryptedValues["notes"] = "Resting" as CKRecordValue
// Non-sensitive fields remain in plain text
record["date"] = Date() as CKRecordValue

try await privateDB.save(record)

// Read encrypted values
let fetched = try await privateDB.record(for: record.recordID)
let heartRate = fetched.encryptedValues["heartRate"] as? Int

CloudKit Dashboard

Access at iCloud Dashboard. Key capabilities:

• Schema: view/edit record types, fields, indexes. Add indexes only for

queried fields in production.

• Records: browse, create, edit, delete records in any database.
• Subscriptions: view active subscriptions.
• Logs: monitor API calls, errors, and latency.
• Telemetry: track request counts, error rates, latency percentiles.
• Environment toggle: switch between Development and Production. Simulator

only works with Development.

• Deploy to Production: migrate schema changes from dev to prod. Production

does not allow adding new record types or fields programmatically.

CKFetchDatabaseChangesOperation

Discover which zones changed in a database. Use with shared database where you do not know zone IDs in advance.

var dbChangeToken: CKServerChangeToken? = loadDatabaseChangeToken()

let operation = CKFetchDatabaseChangesOperation(
    previousServerChangeToken: dbChangeToken
)
operation.fetchAllChanges = true

var changedZoneIDs: [CKRecordZone.ID] = []
var deletedZoneIDs: [CKRecordZone.ID] = []

operation.recordZoneWithIDChangedBlock = { zoneID in
    changedZoneIDs.append(zoneID)
}

operation.recordZoneWithIDWasDeletedBlock = { zoneID in
    deletedZoneIDs.append(zoneID)
}

operation.fetchDatabaseChangesResultBlock = { result in
    switch result {
    case .success(let (token, _)):
        dbChangeToken = token
        saveDatabaseChangeToken(token)
        // Now fetch zone changes for changedZoneIDs
    case .failure(let error):
        if let ckError = error as? CKError,
           ckError.code == .changeTokenExpired {
            dbChangeToken = nil
            // Refetch from scratch
        }
    }
}

operation.qualityOfService = .utility
sharedDB.add(operation)