Article

Reading Data from HealthKit

Use queries to request sample data from HealthKit.

Overview

There are three main ways to access data from the HealthKit Store:

  • Direct method calls. The HealthKit store provides methods to directly access characteristic data. These methods can be used only to access characteristic data. For more information, see HKHealthStore.

  • Queries. Queries return the current snapshot of the requested data from the HealthKit store.

  • Long-running queries. These queries continue to run in the background and update your app whenever changes are made to the HealthKit store.

Queries

Queries return the current snapshot of the data in the HealthKit store. All queries run on an anonymous background queue. When the query is complete, it executes the results handler on the background queue. HealthKit provides different types of queries, each designed to return different types of data from the HealthKit store.

  • Sample query. This is a general-purpose query. Use sample queries to access any type of sample data. Sample queries are particularly useful when you want to sort the results or limit the total number of samples returned. For more information, see HKSampleQuery.

  • Anchored object query. Use this query to search for items that have been added to or deleted from the store. The first time an anchor query is run, it returns all the matching samples currently in the store. On subsequent runs, it returns only those items that have been added or deleted since the last run. For more information, see HKAnchoredObjectQuery.

  • Statistics query. Use this query to perform statistical calculations over the set of matching samples. You can use statistics queries to calculate the sum, minimum, maximum, or average value in the set. For more information, see HKStatisticsQuery.

  • Statistics collection query. Use this query to perform multiple statistics queries over a series of fixed-length time intervals. You will often use these queries when creating graphs. They provide a simple method for calculating things such as the total number of calories consumed each day or the number of steps taken during each five-minute interval. For more information, see HKStatisticsCollectionQuery.

  • Correlation query. Use this query to perform complex searches of the data contained in a correlation. These queries can contain individual predicates for each of the sample types stored in the correlation. If you just want to match the correlation type, use a sample query instead. For more information, see HKCorrelationQuery.

  • Source query. Use this query to search for sources (apps and devices) that have saved matching samples to the HealthKit store. A source query lists all the sources that are saving a particular sample type. For more information, see HKSourceQuery.

  • Activity summary query. Use this query to search for activity summary information for the user. Each activity summary object contains a summary of the user’s activity for a given day. You can query for either a single day or a range of days. For more information, see HKActivitySummaryQuery.

  • Document query. Use this query to search for health documents. For more information, see HKDocumentQuery.

Long-Running Queries

Long-running queries continue to run an anonymous background queue, and update your app whenever changes are made to the HealthKit store. In addition, observer queries can register for background delivery. This lets HealthKit wake your app in the background whenever an update occurs.

Healthkit provides the following long-running queries:

  • Observer query. This long-running query monitors the HealthKit store and alerts you to any changes to matching samples. Use an observer query when you want to be notified about changes to the store. You can register observer queries for background delivery. For more information, see HKObserverQuery.

  • Anchored object query. In addition to returning the current snapshot of modified data, an anchored object query can act as a long-running query. If enabled, it continues to run in the background, providing updates as matching samples are added to or removed from the store. Unlike the observer query, these updates include a list of items that have been added or removed; however, anchored object queries cannot be registered for background delivery. For more information, see HKAnchoredObjectQuery.

  • Statistics collection query. In addition to calculating the current snapshot of statistical collections, this query can act as a long-running query. If matching samples are added to or removed from the store, this query recalculates the statistics collections and updates your app. Statistics collection queries cannot be registered for background delivery. For more information, see HKStatisticsCollectionQuery.

  • Activity summary query. In addition to calculating the current snapshot of the user’s activity summary, this query can act as a long-running query. If the user’s activity summary data changes, this query recalculates the activity summary and updates your app. Activity summary queries cannot be registered for background delivery. For more information, see HKActivitySummaryQuery.

See Also

Health Data

Saving Data to HealthKit

Create and share HealthKit samples.

Data Types

Specify the kind of data used in HealthKit.

Samples

Create and save health and fitness samples.

Queries

Query health and fitness data.