Class

HKQuery

An abstract class for all the query classes in HealthKit.

Overview

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 it directly. Instead, you always work with one of its concrete subclasses.

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.

Topics

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.

Deprecated
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 objects based on the provided metadata key, value, and 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.

struct HKQueryOptions

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

Creating Quantity Sample Predicates

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

Returns a predicate 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: NSComparisonPredicate.Operator, totalFlightsClimbed: HKQuantity)

Returns a predicate that matches workout samples based on the number of flights climbed.

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

Returns a predicate that matches workout samples based on the number of strokes while swimming.

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.

Creating Predicate Format Strings

Use these keys when creating a predicate format string.

Relationships

Inherits From

Conforms To

See Also

Common Query Types

class HKSampleQuery

A general-purpose query that returns a snapshot of all the matching samples currently saved in the HealthKit store.

class HKAnchoredObjectQuery

A query that returns only recent changes to the HealthKit store; this query both returns a snapshot of new changes, and can continue to monitor the store as a long-running query.

class HKObserverQuery

A long-running query that monitors the HealthKit store and updates your app whenever a matching sample is saved to or deleted from the HealthKit store.

class HKCorrelationQuery

A query that performs complex searches based on the correlation’s contents, and returns a snapshot of all matching samples.

class HKDocumentQuery

A query that returns a snapshot of all matching documents currently saved in the HealthKit store.