HKAnchoredObjectQuery: new samples, deleted objects and the HKQueryAnchor

HKAnchoredObjectQuery is the class that makes incremental sync possible on iOS, and the only query class that tells you a sample was deleted. This page covers how it works according to Apple's documentation. The sync design built on top of it, including what to do with a deletion once you have it, lives in incremental sync, and a tested implementation of the save-the-cursor loop is in the incremental sync cookbook recipe.

What Apple says it is#

The abstract: "A query that returns changes to the HealthKit store, including a snapshot of new changes and continuous monitoring as a long-running query." The overview explains the mechanism: "An HKAnchoredObjectQuery returns an anchor value that corresponds to the last sample or deleted object received by that query. Subsequent queries can use this anchor to restrict their results to only newer saved or deleted objects."

Apple also describes it as two queries in one: it "grabs a snapshot of the data currently stored in the HealthKit store (like an HKSampleQuery)" and "can also perform a long-running query that responds to updates (like an HKObserverQuery)". Hence the advice that "you may want to use anchored object queries, even when you aren't using anchors to limit the results. In this case, set the anchor parameter to nil."

The query is "mostly immutable": you can assign updateHandler after creating it, and nothing else.

Availability. The current initializer, init(type:predicate:anchor:limit:resultsHandler:), is listed from iOS 9.0, iPadOS 9.0, Mac Catalyst 13.0, macOS 13.0, visionOS 1.0 and watchOS 2.0, as are HKQueryAnchor and HKDeletedObject. An older initializer that took an Int anchor and returned no deleted objects is marked deprecated, with Apple's note to use init(type:predicate:anchor:limit:resultsHandler:) instead.

The initializer#

The handler runs on a background queue; Apple says to "dispatch these results to the main queue before updating the user interface."

The anchor#

HKQueryAnchor is "An object used to identify all the samples previously returned by an anchored object query." Treat it as opaque: it is a position, not a timestamp, and the class offers nothing to read out of it. The handler's newAnchor is "An anchor object corresponding to the last object returned by this query."

Apple's documentation for the async descriptor version carries a tip that applies equally here: "Because HKQueryAnchor instances adopt the NSSecureCoding protocol, you can save the most recent anchor and use it the next time your app launches."

There is one constructor, init(fromValue:), and it exists for migration. Apple: "Prior to iOS 9.0, anchored object queries used anchor values to track the last sample returned by a previous query. Use this method to convert those anchor values into anchor objects."

Deleted objects#

HKDeletedObject is "An object that represents a sample that has been deleted from the HealthKit store." It carries two documented properties, uuid and metadata, so a deletion tells you which object went, not when it happened or what value it held.

The catch is on the same page: "Deleted objects are temporary; the system may remove them from the HealthKit store at any time to free up space." Apple's prescription for not missing any is to combine three things: "create an HKObserverQuery and register it for background delivery", then, because the observer "does not provide a list of deleted objects", "use the observer query's update handler to create an anchored object query for the newly deleted objects." That pairing is the subject of the HKObserverQuery page.

A minimal incremental read#

import HealthKit

func syncSteps(store: HKHealthStore, from savedAnchor: HKQueryAnchor?) {
    let stepType = HKQuantityType(.stepCount)

    let query = HKAnchoredObjectQuery(type: stepType,
                                      predicate: nil,
                                      anchor: savedAnchor,          // nil on the very first run
                                      limit: HKObjectQueryNoLimit) { _, added, deleted, newAnchor, error in
        guard let added, let deleted else { return }   // both nil only when error is set
        apply(added: added, deleted: deleted)            // your code
        if let newAnchor { save(newAnchor) }             // your code: persist only after applying
    }
    store.execute(query)
}

apply and save stand in for your own persistence. The order matters: if the app dies between saving the anchor and applying the changes, those changes are skipped for good. The cookbook recipe covers that failure in detail.

Keeping it running#

Set updateHandler before execute(_:) and the query becomes long-running. Apple: "If this property is set to nil, the anchor query automatically stops as soon as it finishes calculating the initial results." Otherwise "The system executes the update handler on a background queue whenever matching samples are saved to or deleted from the HealthKit store." Its signature matches the results handler, including a fresh anchor on every call, so save each one. Stop the query with the store's stop(_:).

Reading in batches#

A non-nil limit turns the query into a pager. Because each newAnchor corresponds to the last object returned, running the query again with that anchor continues where the last batch stopped. Apple's documentation for HKAnchoredObjectQueryDescriptor describes exactly this pattern for large histories: start with a nil anchor, read a batch, then "start a new one-shot query for the next batch. Continue reading batches until there's no new data." The async version is covered on the query descriptors page.

Pitfalls#

• Expecting a deletion to carry a date. HKDeletedObject documents only uuid and metadata. If you need to know which day a deletion affects, keep your own record of what each UUID was; incremental sync works through that.
• Relying on deleted objects lingering. Apple says the system may remove them at any time. An app that only runs its anchored query occasionally can miss deletions unless the observer and background delivery pairing is in place.
• Summing the added samples into a total. An anchored query reports changes, not totals. Recompute affected periods with HKStatisticsQuery instead of incrementing a counter.
• Forgetting that the predicate filters deletions too. A date-window predicate that excludes a sample also excludes its deletion. A predicate is fine for a bounded view, but a full sync usually wants nil.
• Not saving the anchor from the update handler. Each update hands you a new anchor. Keep only the first and the next launch replays everything since then.