What's the deal with samples

← All articles

As with any health data, the classification is what helps identify use of the data. When working with data in HealthKit this takes the form of Type / TypeIdentifier and Sample. The Type and TypeIdentifier are used to describe the classification of the sample. The Sample is used to hold the data itself.

Types

HKObjectType is an abstract base class from which all other types derive. It exists as a way to represent a type of value that exists in HealthKit. The framework splits out the type or classification of the value from the value itself. These type definitions are created using class functions on HKObjectType with the specification of an identifier.

As well as being useful for storing data, the object type is used when making queries against HealthKit. The use of the correct type means that the values returned or stored are what is expected.

Samples

When working with the data from HealthKit, it is quite often that you are dealing with a value which is a sample of something that is going on at a particular point in time. The base type is HKSample and has concrete subclasses such as:

When working with samples, they all have common values stored with them being:

Thankfully though you won't need to deal directly with HKSample in most cases. When saving data you will be creating a sample of the appropriate type or writing an appropriately typed query when reading the data.

Category

A classic example of a category sample is sleep duration. The use of a category sample is to say that something happened between the start date and end date values. To determine what that category was, there's a couple of variables which provide the extra data.

The value being stored should match the possible values defined in the HKCategoryType property. Looking at the sleep category, these would map to what is defined in HKCategoryValueSleepAnalysis.

  • inBed
  • awake
  • asleepCore
  • asleepDeep
  • asleepREM
  • asleepUnspecified

Correlation

Correlations are super useful associations in HealthKit though at the moment are limited. A correlation is an association between samples.

When dealing with a correlation, the additional properties can be used.

There's also a helper function objects(for:) that extracts the samples for the specified object type.

Quantity

Quantity samples are the most common data type being worked with. These are used to say something happened with a value between a start and end date. The type of data can be quantified. When dealing with quantity samples, the additional properties are available.

Creating a quantity sample is making sure that identifiers, units and quantity match up as seen in the example:

let unit = HKUnit.watt()
let type = HKQuantityType(.cyclingPower)
let quantity = HKQuantity(
  unit: unit,
  doubleValue: value
)
let timestamp = Date.now

let sample = HKQuantitySample(
  type: type,
  quantity: quantity,
  start: timestamp,
  end: timestamp
)

Workout

Everyone loves doing workouts and being active. The HKWorkout type is a sample type that is used for providing details about a workout. When dealing with workout samples, the additional properties are available:

There's also a helper functions statistics(for:) to fetch the statistics relevant to a particular activity.

All samples can have associated metadata though it's more typical for workouts to have these values associated. The list of keys is defined in Workout Metadata Keys

Apple Documentation Links