Query Correlation Samples

Query correlation samples from HealthKit like blood pressure and food

Overview

Correlations in HealthKit combine multiple related samples into a single entity. The two main correlation types are:

• Blood Pressure: Combines systolic and diastolic blood pressure readings
• Food: Combines nutritional information (calories, protein, carbs, fats, etc.)

queryCorrelationSamples

Query correlation samples from HealthKit with optional filtering and sorting.

Signature

function queryCorrelationSamples(
  typeIdentifier: CorrelationTypeIdentifier,
  options: QueryOptionsWithSortOrder
): Promise<readonly CorrelationSample[]>

Parameters

typeIdentifier · CorrelationTypeIdentifier · required

The type of correlation to query:

• 'HKCorrelationTypeIdentifierBloodPressure' - Blood pressure readings
• 'HKCorrelationTypeIdentifierFood' - Food/nutrition entries

options · QueryOptionsWithSortOrder · required

Query options for filtering and sorting

Show properties

filter · FilterForSamples

Optional filter criteria

Show properties

startDate · Date

Filter samples starting after this date

endDate · Date

Filter samples ending before this date

sourceRevision · SourceRevision

Filter by specific app or device source

limit · number · required

Maximum number of samples to return. Use -1, 0, or any non-positive number to fetch all samples

ascending · boolean · default: "false"

Sort order by start date. If true, oldest first; if false, newest first

Returns

correlations · Promise<CorrelationSample[]>

Array of correlation samples matching the query criteria

Show CorrelationSample properties

uuid · string

Unique identifier for the correlation

correlationType · CorrelationTypeIdentifier

The type of correlation

objects · (CategorySample | QuantitySample)[]

Array of related samples (e.g., systolic and diastolic for blood pressure)

startDate · Date

When the correlation was recorded

endDate · Date

End date of the correlation

metadataFoodType · string

Food type description (only for food correlations)

Example

import { queryCorrelationSamples } from '@kingstinct/react-native-healthkit'

// Query blood pressure readings
const bloodPressureReadings = await queryCorrelationSamples(
  'HKCorrelationTypeIdentifierBloodPressure',
  {
    limit: 10,
    ascending: false, // newest first
  }
)

for (const reading of bloodPressureReadings) {
  console.log('Blood Pressure:', {
    date: reading.startDate,
    uuid: reading.uuid,
  })
  
  // Extract systolic and diastolic values
  for (const obj of reading.objects) {
    if ('quantityType' in obj) {
      console.log(`${obj.quantityType}: ${obj.quantity} ${obj.unit}`)
    }
  }
}

// Query food entries from last week
const weekAgo = new Date()
weekAgo.setDate(weekAgo.getDate() - 7)

const foodEntries = await queryCorrelationSamples(
  'HKCorrelationTypeIdentifierFood',
  {
    filter: {
      startDate: weekAgo,
    },
    limit: -1, // all entries
    ascending: true,
  }
)

for (const food of foodEntries) {
  console.log('Food:', {
    date: food.startDate,
    foodType: food.metadataFoodType,
  })
  
  // Extract nutritional values
  for (const obj of food.objects) {
    if ('quantityType' in obj) {
      console.log(`${obj.quantityType}: ${obj.quantity} ${obj.unit}`)
    }
  }
}

---

queryCorrelationSamplesWithAnchor

Query correlation samples using an anchor to track changes and support pagination. This is useful for syncing data efficiently.

Signature

function queryCorrelationSamplesWithAnchor(
  typeIdentifier: CorrelationTypeIdentifier,
  options: QueryOptionsWithAnchor
): Promise<QueryCorrelationSamplesWithAnchorResponse>

Parameters

typeIdentifier · CorrelationTypeIdentifier · required

The type of correlation to query (same as queryCorrelationSamples)

options · QueryOptionsWithAnchor · required

Query options with anchor support

Show properties

filter · FilterForSamples

Optional filter criteria (same as queryCorrelationSamples)

limit · number · required

Maximum number of samples to return. Use -1, 0, or any non-positive number to fetch all samples

anchor · string

Anchor from previous query to fetch only new/changed data. Omit or pass undefined for initial query

Returns

response · Promise<QueryCorrelationSamplesWithAnchorResponse>

Show properties

correlations · CorrelationSample[]

Array of new or updated correlation samples since the anchor

deletedSamples · DeletedSample[]

Array of deleted sample UUIDs and deletion dates

newAnchor · string

New anchor value to use for the next query

Example

import { queryCorrelationSamplesWithAnchor } from '@kingstinct/react-native-healthkit'

// Initial query
let anchor: string | undefined

const initialResult = await queryCorrelationSamplesWithAnchor(
  'HKCorrelationTypeIdentifierBloodPressure',
  {
    limit: 100,
    anchor: undefined, // first query
  }
)

console.log(`Initial: ${initialResult.correlations.length} readings`)
anchor = initialResult.newAnchor

// Subsequent query - only gets changes since last query
const updateResult = await queryCorrelationSamplesWithAnchor(
  'HKCorrelationTypeIdentifierBloodPressure',
  {
    limit: 100,
    anchor, // use saved anchor
  }
)

console.log(`New readings: ${updateResult.correlations.length}`)
console.log(`Deleted readings: ${updateResult.deletedSamples.length}`)
anchor = updateResult.newAnchor // save for next time

// Handle deletions
for (const deleted of updateResult.deletedSamples) {
  console.log(`Reading ${deleted.uuid} was deleted on ${deleted.deletedDate}`)
}

Anchored queries are ideal for syncing correlation data efficiently. The anchor tracks the state of the HealthKit database, so subsequent queries only return changes since the last query.