Every question the HealthKit Queries pages answer
The 9 healthkit queries pages answer 40 named questions between them. Every one is listed below, and every link lands on the paragraph that answers it rather than the top of the page.
HKSampleQuery: a one-time snapshot of matching samples
- How do I make HKSampleQuery return every matching sample instead of a capped number?Pass HKObjectQueryNoLimit as the limit. Apple documents it as a value indicating that the query returns all the matching samples in the…
- Can I sort an array of HealthKit samples with HKSampleSortIdentifierStartDate?No. Apple's note on the sortDescriptors parameter says sort descriptors built from HealthKit's sort identifiers, such as…
- Which thread does the HKSampleQuery results handler run on?A background one. Apple documents that queries run on an anonymous background queue and that the results handler executes on that…
- Can a single HKSampleQuery read more than one data type?Yes, from iOS 15.0 and watchOS 8.0. The initializer init(queryDescriptors:limit:resultsHandler:) takes an array of HKQueryDescriptor…
HealthKit query predicates: predicateForSamples, HKQueryOptions and HKSamplePredicate
- Does predicateForSamples(withStart:end:options:) match samples that start before the window?Yes, when no options are passed. Apple's documentation shows the convenience method alongside an equivalent predicate format string that…
- What is the difference between strictStartDate and strictEndDate in HKQueryOptions?They choose which end of the sample must fall inside the window. Apple documents that with strictStartDate the sample's start time must be…
- Can I filter a HealthKit query with any NSPredicate format string?No. Apple explains that HealthKit converts a query's predicate to SQL and runs it on the underlying store, which limits the predicates you…
- How do I limit a HealthKit query to data written by one app or device?Use HKQuery.predicateForObjects(from:). Apple provides versions that take a single HKSource, a set of sources, a set of HKDevice values or…
- What is HKSamplePredicate used for in HealthKit?It is the filter type for HealthKit's Swift concurrency query descriptors. Apple describes it as bundling an HKSampleType with an optional…
HKStatisticsQuery: one sum, average or extreme over a window
- Why does sumQuantity() return nil on my HKStatisticsQuery result?Most often because the query was not created with the cumulativeSum option. Apple's documentation for sumQuantity() says it returns the sum…
- Can one HKStatisticsQuery return both a sum and an average?No. Apple documents that you cannot combine a discrete option with a cumulative option in HKStatisticsOptions. You can combine several…
- What does the separateBySource option do in an HKStatisticsQuery?It makes HealthKit calculate the requested statistics separately for each source as well. Apple explains that statistics queries merge data…
- Can I use HKStatisticsQuery to total workout distance or energy?Not over HKWorkout objects directly. Apple states that statistics queries work with quantity samples only, and that to calculate statistics…
HKStatisticsCollectionQuery: daily totals, anchorDate and intervalComponents
- What should anchorDate be for daily totals in HKStatisticsCollectionQuery?Any date whose time of day is when you want each day to begin, usually a midnight. Apple explains that the anchor sets the start of one…
- Why are some days missing from statistics() on an HKStatisticsCollection?Because statistics() returns objects only for intervals that contain at least one matching sample. Apple documents that it ignores…
- Does HKStatisticsCollectionQuery keep running after it returns the initial results?Only if you set statisticsUpdateHandler. Apple documents that when that property is nil the query stops automatically once it has…
- Why does the HKStatisticsCollectionQuery initializer have no results handler?Because this class takes its handlers as properties instead. Apple's article notes that unlike most other queries, you do not set the…
HKAnchoredObjectQuery: new samples, deleted objects and the HKQueryAnchor
- What anchor should I pass to HKAnchoredObjectQuery the first time it runs?Pass nil. Apple documents that a nil anchor returns all the matching samples and recently deleted objects currently in the HealthKit store,…
- Can I save an HKQueryAnchor and reuse it the next time my app launches?Yes. Apple's documentation for the anchored object query descriptor notes that HKQueryAnchor instances adopt the NSSecureCoding protocol,…
- Does HealthKit keep HKDeletedObject records forever?No. Apple states that deleted objects are temporary and that the system may remove them from the HealthKit store at any time to free up…
- Does the predicate on an HKAnchoredObjectQuery filter deleted objects as well as samples?Yes. Apple describes the predicate parameter as one that filters both the samples and the deleted objects the query returns. A date-window…
- What is the HKQueryAnchor init(fromValue:) initializer for?Migrating from the old integer anchors. Apple explains that before iOS 9.0 anchored object queries tracked the last returned sample with an…
HKObserverQuery and enableBackgroundDelivery: how the pair works
- Does the HKObserverQuery update handler tell me which samples changed?No. Apple's article states that the observer query's update handler receives no information about the change, only that a change occurred,…
- Should I call the HKObserverQuery completion handler if background delivery is not enabled?No. Apple's documentation for the update handler says you must call the completion handler as soon as you finish processing when you have…
- Does HKUpdateFrequency.hourly mean HealthKit wakes my app every hour?No. Apple defines hourly as the system launching your app at most once an hour in response to changes, so it is a ceiling that applies only…
- How do I stop HealthKit background delivery for one data type?Call disableBackgroundDelivery(for:withCompletion:) on HKHealthStore with that type, or its async throws form. Apple documents that it…
- Can one HKObserverQuery watch more than one sample type?Yes, from iOS 15.0 and watchOS 8.0. The initializer init(queryDescriptors:updateHandler:) takes an array of HKQueryDescriptor objects, and…
HealthKit async/await queries: HKSampleQueryDescriptor and the other descriptors
- What is the difference between result(for:) and results(for:) on a HealthKit query descriptor?result(for:) runs a one-shot query and asynchronously returns a snapshot of the current matching results, as Apple describes it.…
- Which OS versions support the HealthKit query descriptors?Apple's documentation lists HKSampleQueryDescriptor, HKAnchoredObjectQueryDescriptor, HKStatisticsQueryDescriptor,…
- Does HKSampleQueryDescriptor run an HKSampleQuery underneath?Yes. Apple's documentation for HKSampleQueryDescriptor says that calling its result(for:) method creates and executes an HKSampleQuery in…
- How do I read several HealthKit data types with one query descriptor?Pass one HKSamplePredicate per type in the predicates array. Apple's documentation for the sample and anchored object descriptors says to…
HKWorkoutRouteQuery: reading a workout's GPS route in batches
- Why does my HKWorkoutRouteQuery data handler get called more than once?Because HealthKit returns a route's locations in batches. Apple documents the handler as a block called each time the system returns a…
- Why is there no route for a workout that just appeared in HealthKit?Because route data is usually saved after the workout. Apple explains that an app must save a workout before associating route data with…
- How accurate are the GPS locations in a HealthKit workout route?Apple's "Reading route data" article says locations from the HealthKit store are accurate within 50 meters but may need additional…
- Can HKWorkoutRouteQuery read only part of a workout route?Yes, from iOS 16.0 and watchOS 9.0. The initializer init(route:dateInterval:dataHandler:) limits the read to a date interval. Apple…
- Which CLLocation fields does HealthKit keep in a workout route?Apple says HKWorkoutRoute saves a subset of CLLocation properties, including timestamp, coordinate, altitude, speed, course,…
HKActivitySummaryQuery: reading Move, Exercise and Stand rings
- Which HealthKit permission lets my app read activity ring data?Read authorization for the activity summary type, which you get from HKObjectType.activitySummaryType(). Apple documents that this method…
- Does the Move ring in HKActivitySummary always measure calories?No. Since iOS 14.0 the activityMoveMode property says whether the Move ring measures active energy burned or Apple Move Time. Apple…
- Can my app save an HKActivitySummary to HealthKit?No. Apple states that you can create your own HKActivitySummary objects if needed but cannot save them to the store. The objects you read…
- Why do activity summary predicates need date components with a calendar?Because activity summaries are keyed to the user's day, not to absolute timestamps. Apple's documentation for…
Back to the HealthKit Queries hub, or see every question this site answers.