Contents

CKFetchDatabaseChangesOperation

An operation that fetches database changes.

Declaration

class CKFetchDatabaseChangesOperation

Overview

Use this operation to fetch all record zone changes in a database. This includes new record zones, changed zones — including deleted or purged zones — and zones that contain record changes. When you create the operation, you provide a server change token, which is an opaque token that represents a specific point in the database’s history. CloudKit returns only the changes that occur after that point. For your app’s first fetch, or to refetch every change in the database’s history, use nil instead.

The operation yields new change tokens during its execution, and issues a final change token when it completes without error. The change tokens conform to NSSecureCoding and are safe to cache on-disk. This operation’s tokens aren’t compatible with CKFetchRecordZoneChangesOperation so you should segregate them in your cache. Don’t infer any behavior or order from the tokens’ contents.

When your app launches for the first time, use this operation to fetch all the database’s changes. Cache the results on-device and use CKDatabaseSubscription to subscribe to future changes. Fetch those changes on receipt of the push notifications the subscription generates. It’s not necessary to perform a fetch each time your app launches, or to schedule fetches at regular intervals.

The operation calls recordZoneWithIDChangedBlock for each zone that contains record changes. It also calls it for new and modified record zones. Store the IDs that CloudKit provides to this callback. Use those IDs with CKFetchRecordZoneChangesOperation to fetch the corresponding changes. There are similar callbacks for deleted and purged record zones.

To run the operation, add it to the corresponding database’s operation queue. The operation executes its callbacks on a private serial queue.

The following example shows how to create the operation, configure its callbacks, and execute it. For brevity, it omits the delete, and purge callbacks.

// Create a fetch operation using the server change
// token from the previous fetch.
CKFetchDatabaseChangesOperation *operation =
    [[CKFetchDatabaseChangesOperation alloc]
     initWithPreviousServerChangeToken:token];

// Collect the IDs of the modified record zones.
operation.recordZoneWithIDChangedBlock = ^(CKRecordZoneID *recordZoneID) {
    [recordZoneIDs addObject:recordZoneID];
};

// Process any change tokens that CloudKit provides
// as the operation runs.
operation.changeTokenUpdatedBlock = ^(CKServerChangeToken *newToken) {
    tokenHandler(newToken);
};

// Store the final change token and pass the IDs of the
// modified record zones for further processing.
operation.fetchDatabaseChangesCompletionBlock =
    ^(CKServerChangeToken *newToken, BOOL more, NSError *error) {
    if (error) {
        // Handle the error.
    } else {
        tokenHandler(newToken);
        recordZonesHandler(recordZoneIDs);
    }
};

// Set an appropriate QoS and add the operation to the shared
// database's operation queue to execute it.
operation.qualityOfService = NSQualityOfServiceUtility;
[CKContainer.defaultContainer.sharedCloudDatabase addOperation:operation];

Topics

Creating an Operation

Configuring the Operation

Processing the Operation’s Results

Instance Properties

See Also

Database Changes