The HKQuery class is the basis for all the query objects that retrieve data from the HealthKit store. The HKQuery class is an abstract class. You should never instantiate an HKQuery object directly. Instead, you always work with one of its concrete subclasses: HKAnchoredObjectQuery, HKCorrelationQuery, HKObserverQuery, HKSampleQuery, HKSourceQuery, HKStatisticsQuery, or HKStatisticsCollectionQuery objects.


  • HKAnchoredObjectQuery

    This query returns an anchor for the last sample saved to the HealthKit store. On subsequent queries, you can use the anchor to request only the samples that have been added after the anchor. This lets you quickly query for new items in the store. See HKAnchoredObjectQuery.

  • HKCorrelationQuery

    This query allows more complex filtering of complex, correlation data. With it, you provide a separate predicate for each of the sample types stored in the correlation. A correlation is returned only if the correlation’s predicate and all of its contents’ predicates match. See HKCorrelation.

  • HKObserverQuery

    These long-running queries call their update handler whenever a matching object is saved to the HeathKit store. With these queries, you can observe and respond to data saved in the background by other apps or entered directly into the store from connected Bluetooth devices. You can also register observer queries for background delivery. With background delivery, HealthKit will launch your app in response to changes in the store, letting your app respond to those changes. See HKObserverQuery.

  • HKSampleQuery

    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. See HKSampleQuery.

  • HKSourceQuery

    This query returns a list of sources (apps and devices) that have saved data that matches a specified sample type and predicate. See HKSourceQuery.

  • HKStatisticsQuery

    These queries calculate aggregate values (average, minimum, maximum, or sum) for quantity samples data. See HKStatisticsQuery.

  • HKStatisticsCollectionQuery

    Like the statistics query, this query returns average, minimum, maximum or sum data for the specified quantity samples. However, instead of returning a single result, this query lets you specify a time interval and it performs the calculation repeatedly over that interval, returning an array of results.

    For example, by specifying a day long interval and a sum calculation, you can calculate the number of steps the user has taken each day over a series of days. Each entry in the resulting array represents the sum of steps for one day. See HKStatisticsCollectionQuery.

Queries and Predicates

All the concrete HKQuery subclasses take a predicate. You can use this predicate to filter the samples returned by the query. When HealthKit runs a query, it converts the predicate to SQL and executes the SQL on the underlying store. This has two important side effects.

  • Predicates improve the performance of your query, both in terms of speed and memory usage. Because the predicate is performed by the store, it restricts the number of HealthKit objects that are instantiated and returned.

  • Since the predicates are executed by the store, you are limited in the type of predicates that you can use. Specifically, HealthKit provides a number of predicate key paths (for example, HKPredicateKeyPathUUID and HKPredicateKeyPathMetadata). You can create predicates using only these key paths.

Subclassing Notes

Like many HealthKit classes, the HKQuery class should not be subclassed.


Getting and Setting Properties

var predicate: NSPredicate?

A predicate used to filter the objects returned from the HealthKit store.

var sampleType: HKSampleType?

The type of objects being queried.

var objectType: HKObjectType?

The type of objects being queried.

Creating Object Predicates

class func predicateForObject(with: UUID)

Returns a predicate that matches an object with the specified universally unique identifier (UUID).

class func predicateForObjects(with: Set<UUID>)

Returns a predicate that matches the objects with the specified universally unique identifiers (UUIDs).

class func predicateForObjects(from: HKSource)

Returns a predicate that matches all the objects that were created by the provided source.

class func predicateForObjects(from: Set<HKSource>)

Returns a predicate that matches all the objects that were created by any of the provided sources.

class func predicateForObjects(from: Set<HKDevice>)

Returns a predicate that matches all the objects that were created by any of the provided devices.

class func predicateForObjects(withDeviceProperty: String, allowedValues: Set<String>)

Returns a predicate that matches all objects created by devices with the specified properties.

class func predicateForObjects(from: Set<HKSourceRevision>)

Returns a predicate that matches all the objects that were created by any of the provided source revisions.

class func predicateForObjects(withMetadataKey: String)

Returns a predicate that matches any object whose metadata contains the provided key.

class func predicateForObjects(withMetadataKey: String, allowedValues: [Any])

Returns a predicate that matches objects based on the provided metadata key and an array of target values.

class func predicateForObjects(withMetadataKey: String, operatorType: NSComparisonPredicate.Operator, value: Any)

Returns a predicate that matches any object whose metadata contains the provided key, and the metadata’s value for the key matches the provided value using the provided operator.

class func predicateForObjectsWithNoCorrelation()

Returns a predicate that matches all objects that are not associated with a HealthKit correlation.

Creating Sample Predicates

class func predicateForSamples(withStart: Date?, end: Date?, options: HKQueryOptions = [])

Returns a predicate for samples whose start and end dates fall within the specified time interval.

Creating Quantity Sample Predicates

class func predicateForQuantitySamples(with: NSComparisonPredicate.Operator, quantity: HKQuantity)

Returns a property that matches samples based on the target quantity.

Creating Category Sample Predicates

class func predicateForCategorySamples(with: NSComparisonPredicate.Operator, value: Int)

Returns a predicate that checks a category sample’s value.

Creating Workout Predicates

class func predicateForObjects(from: HKWorkout)

Returns a predicate that matches any objects that have been associated with the provided workout.

class func predicateForWorkouts(with: NSComparisonPredicate.Operator, duration: TimeInterval)

Returns a predicate for matching workouts based on their duration.

class func predicateForWorkouts(with: NSComparisonPredicate.Operator, totalDistance: HKQuantity)

Returns a predicate for matching workouts based on the total distance traveled.

class func predicateForWorkouts(with: NSComparisonPredicate.Operator, totalEnergyBurned: HKQuantity)

Returns a predicate for matching workouts based on the total energy burned.

class func predicateForWorkouts(with: HKWorkoutActivityType)

Returns a predicate for matching workouts based on the type of activity.

Creating Activity Summary Predicates

class func predicateForActivitySummary(with: DateComponents)

Returns a predicate that matches the activity summary for the specified day.

class func predicate(forActivitySummariesBetweenStart: DateComponents, end: DateComponents)

Returns a predicate for matching all the activity summaries that fall between the days identified by the start and end date components.


struct HKQueryOptions

Constants that describe how a sample’s time period overlaps with the target time period.

Device Property Keys

Valid keys for the predicateForObjects(withDeviceProperty:allowedValues:) method. Use these keys to create predicates that match the specified device property.


Inherits From

Conforms To