Query Workout Samples

Query workout samples from HealthKit with optional filtering and anchored queries

queryWorkoutSamples

Query workout samples from HealthKit with optional filtering and sorting.

Signature

function queryWorkoutSamples(
  options: WorkoutQueryOptions
): Promise<WorkoutProxy[]>

Parameters

options · WorkoutQueryOptions · required

Query options for filtering and sorting workouts

Show properties

filter · FilterForWorkouts

Optional filter criteria for workouts

Show properties

workoutActivityType · WorkoutActivityType

Filter by specific workout activity type (e.g., running, cycling)

duration · WorkoutDurationPredicate

Filter by workout duration

Show properties

predicateOperator · ComparisonPredicateOperator · required

Comparison operator (e.g., greaterThan, lessThan, equalTo)

durationInSeconds · number · required

Duration value in seconds

startDate · Date

Filter workouts starting after this date

endDate · Date

Filter workouts ending before this date

OR · FilterForWorkoutsBase[]

Array of filter conditions where at least one must match

AND · FilterForWorkoutsBase[]

Array of filter conditions where all must match

NOT · FilterForWorkoutsBase[]

Array of filter conditions to exclude

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 workouts first; if false, newest first

Returns

workouts · Promise<WorkoutProxy[]>

Array of workout samples matching the query criteria. Each workout is a WorkoutProxy object with methods to access workout data and routes.

Example

import { queryWorkoutSamples, WorkoutActivityType } from '@kingstinct/react-native-healthkit'

// Query all running workouts
const runningWorkouts = await queryWorkoutSamples({
  filter: {
    workoutActivityType: WorkoutActivityType.running,
  },
  limit: 10,
  ascending: false, // newest first
})

console.log(`Found ${runningWorkouts.length} running workouts`)

// Query workouts longer than 30 minutes
const longWorkouts = await queryWorkoutSamples({
  filter: {
    duration: {
      predicateOperator: 'greaterThan',
      durationInSeconds: 1800, // 30 minutes
    },
  },
  limit: -1, // fetch all
})

// Access workout data
for (const workout of runningWorkouts) {
  console.log('Workout:', {
    type: workout.workoutActivityType,
    duration: workout.duration,
    distance: workout.totalDistance,
    energyBurned: workout.totalEnergyBurned,
    startDate: workout.startDate,
  })
}

---

queryWorkoutSamplesWithAnchor

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

Signature

function queryWorkoutSamplesWithAnchor(
  options: WorkoutQueryOptionsWithAnchor
): Promise<QueryWorkoutSamplesWithAnchorResponse>

Parameters

options · WorkoutQueryOptionsWithAnchor · required

Query options with anchor support

Show properties

filter · FilterForWorkouts

Optional filter criteria (same as queryWorkoutSamples)

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<QueryWorkoutSamplesWithAnchorResponse>

Show properties

workouts · WorkoutProxy[]

Array of new or updated workout 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 { queryWorkoutSamplesWithAnchor, WorkoutActivityType } from '@kingstinct/react-native-healthkit'

// Initial query
let anchor: string | undefined

const initialResult = await queryWorkoutSamplesWithAnchor({
  filter: {
    workoutActivityType: WorkoutActivityType.running,
  },
  limit: 100,
  anchor: undefined, // first query
})

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

// Subsequent query - only gets changes since last query
const updateResult = await queryWorkoutSamplesWithAnchor({
  filter: {
    workoutActivityType: WorkoutActivityType.running,
  },
  limit: 100,
  anchor, // use saved anchor
})

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

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

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