Quantity Statistics

Query aggregated statistics for quantity samples

queryStatisticsForQuantity

Query aggregated statistics for a quantity type over a specified time period.

queryStatisticsForQuantity(
  identifier: QuantityTypeIdentifier,
  statistics: readonly StatisticsOptions[],
  options?: StatisticsQueryOptions
): Promise<QueryStatisticsResponse>

identifier · QuantityTypeIdentifier · required

The quantity type identifier to query statistics for

statistics · StatisticsOptions[] · required

Array of statistics to compute. Available options:

• 'cumulativeSum' - Total sum of all values
• 'discreteAverage' - Average of discrete values
• 'discreteMax' - Maximum value
• 'discreteMin' - Minimum value
• 'duration' - Total duration
• 'mostRecent' - Most recent sample

options · StatisticsQueryOptions

Optional query configuration

Show properties

unit · string

Unit for returned values. Defaults to user’s preferred unit

filter · FilterForSamples

Filter criteria including date range, sources, metadata, etc.

Returns

statistics · QueryStatisticsResponse

Statistics results for the query

Show properties

averageQuantity · Quantity

Average quantity (if 'discreteAverage' was requested)

maximumQuantity · Quantity

Maximum quantity (if 'discreteMax' was requested)

minimumQuantity · Quantity

Minimum quantity (if 'discreteMin' was requested)

sumQuantity · Quantity

Sum of all quantities (if 'cumulativeSum' was requested)

mostRecentQuantity · Quantity

Most recent quantity value (if 'mostRecent' was requested)

mostRecentQuantityDateInterval · QuantityDateInterval

Date range of the most recent quantity

duration · Quantity

Total duration (if 'duration' was requested)

startDate · Date

Start date of the statistics period

endDate · Date

End date of the statistics period

sources · SourceProxy[]

Data sources that contributed to these statistics

Example

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

// Get total steps for today
const today = new Date()
today.setHours(0, 0, 0, 0)

const stats = await queryStatisticsForQuantity(
  'HKQuantityTypeIdentifierStepCount',
  ['cumulativeSum', 'discreteMax'],
  {
    unit: 'count',
    filter: {
      date: {
        startDate: today,
        endDate: new Date()
      }
    }
  }
)

console.log(`Total steps today: ${stats.sumQuantity?.quantity}`)
console.log(`Max steps in one sample: ${stats.maximumQuantity?.quantity}`)

---

queryStatisticsCollectionForQuantity

Query statistics broken down into intervals (e.g., daily, hourly) over a time period.

queryStatisticsCollectionForQuantity(
  identifier: QuantityTypeIdentifier,
  statistics: readonly StatisticsOptions[],
  anchorDate: Date,
  intervalComponents: IntervalComponents,
  options?: StatisticsQueryOptions
): Promise<readonly QueryStatisticsResponse[]>

identifier · QuantityTypeIdentifier · required

The quantity type identifier to query

statistics · StatisticsOptions[] · required

Array of statistics to compute for each interval

anchorDate · Date · required

The anchor date that defines interval boundaries

intervalComponents · IntervalComponents · required

Defines the interval duration

Show properties

minute · number

Number of minutes per interval

hour · number

Number of hours per interval

day · number

Number of days per interval

month · number

Number of months per interval

year · number

Number of years per interval

options · StatisticsQueryOptions

Optional query configuration (unit and filter)

Returns

collection · QueryStatisticsResponse[]

Array of statistics, one for each interval in the time range

Example

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

// Get daily step counts for the last week
const now = new Date()
const weekAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000)

const dailyStats = await queryStatisticsCollectionForQuantity(
  'HKQuantityTypeIdentifierStepCount',
  ['cumulativeSum'],
  weekAgo,
  { day: 1 }, // 1-day intervals
  {
    unit: 'count',
    filter: {
      date: {
        startDate: weekAgo,
        endDate: now
      }
    }
  }
)

dailyStats.forEach((stats, index) => {
  console.log(`Day ${index + 1}: ${stats.sumQuantity?.quantity || 0} steps`)
})

---

queryStatisticsForQuantitySeparateBySource

Query statistics with results separated by data source.

queryStatisticsForQuantitySeparateBySource(
  identifier: QuantityTypeIdentifier,
  statistics: readonly StatisticsOptions[],
  options?: StatisticsQueryOptions
): Promise<QueryStatisticsResponseFromSingleSource[]>

identifier · QuantityTypeIdentifier · required

The quantity type identifier to query

statistics · StatisticsOptions[] · required

Array of statistics to compute

options · StatisticsQueryOptions

Optional query configuration

Returns

sourceStatistics · QueryStatisticsResponseFromSingleSource[]

Array of statistics, one per data source

Show properties

source · SourceProxy

The data source for these statistics

averageQuantity · Quantity

Average from this source

sumQuantity · Quantity

Sum from this source

...other statistics · Quantity

Other requested statistics from this source

Example

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

// Get step counts by source
const statsBySource = await queryStatisticsForQuantitySeparateBySource(
  'HKQuantityTypeIdentifierStepCount',
  ['cumulativeSum'],
  {
    filter: {
      date: {
        startDate: new Date(Date.now() - 24 * 60 * 60 * 1000),
        endDate: new Date()
      }
    }
  }
)

statsBySource.forEach(stats => {
  const sourceName = stats.source.name
  const steps = stats.sumQuantity?.quantity || 0
  console.log(`${sourceName}: ${steps} steps`)
})

---

queryStatisticsCollectionForQuantitySeparateBySource

Query interval-based statistics with results separated by data source.

queryStatisticsCollectionForQuantitySeparateBySource(
  identifier: QuantityTypeIdentifier,
  statistics: readonly StatisticsOptions[],
  anchorDate: Date,
  intervalComponents: IntervalComponents,
  options?: StatisticsQueryOptions
): Promise<readonly QueryStatisticsResponseFromSingleSource[]>

identifier · QuantityTypeIdentifier · required

The quantity type identifier to query

statistics · StatisticsOptions[] · required

Array of statistics to compute

anchorDate · Date · required

The anchor date for interval boundaries

intervalComponents · IntervalComponents · required

The interval duration (see queryStatisticsCollectionForQuantity)

options · StatisticsQueryOptions

Optional query configuration

Returns

collection · QueryStatisticsResponseFromSingleSource[]

Array of statistics per source per interval

Example

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

// Get hourly heart rate by source for today
const today = new Date()
today.setHours(0, 0, 0, 0)

const hourlyStatsBySource = await queryStatisticsCollectionForQuantitySeparateBySource(
  'HKQuantityTypeIdentifierHeartRate',
  ['discreteAverage'],
  today,
  { hour: 1 },
  {
    unit: 'count/min',
    filter: {
      date: {
        startDate: today,
        endDate: new Date()
      }
    }
  }
)

// Group by source
const bySource = new Map()
for (const stats of hourlyStatsBySource) {
  const sourceName = stats.source.name
  if (!bySource.has(sourceName)) {
    bySource.set(sourceName, [])
  }
  bySource.get(sourceName).push(stats)
}

bySource.forEach((stats, sourceName) => {
  console.log(`\n${sourceName}:`)
  stats.forEach(s => {
    console.log(`  ${s.startDate?.toLocaleTimeString()}: ${s.averageQuantity?.quantity} BPM`)
  })
})

Use the “separate by source” variants when you need to attribute data to specific apps or devices, which is useful for data provenance and conflict resolution.

Statistics queries are more efficient than fetching all samples and computing statistics manually, especially for large datasets.