Query Quantity Samples

Query and retrieve quantity samples from HealthKit

queryQuantitySamples

Query quantity samples for a specific quantity type identifier.

queryQuantitySamples(
  identifier: QuantityTypeIdentifier,
  options: QueryOptionsWithSortOrderAndUnit
): Promise<readonly QuantitySample[]>

identifier · QuantityTypeIdentifier · required

The quantity type identifier to query (e.g., 'HKQuantityTypeIdentifierStepCount', 'HKQuantityTypeIdentifierHeartRate')

options · QueryOptionsWithSortOrderAndUnit · required

Query options for filtering and controlling the results

Show properties

limit · number · default: 20

Maximum number of samples to return. Use -1, 0, or any non-positive number for no limit

ascending · boolean · default: false

Whether to sort results in ascending order by date

unit · string

The unit to use for the returned quantity values. If not specified, uses the user’s preferred unit

filter · FilterForSamples

Filter criteria for the query

Show properties

uuid · string

Filter by a specific sample UUID

uuids · string[]

Filter by multiple sample UUIDs

date · DateFilter

Filter by date range

Show properties

startDate · Date

Start date for the query range

endDate · Date

End date for the query range

strictStartDate · boolean

Whether to strictly enforce the start date boundary

strictEndDate · boolean

Whether to strictly enforce the end date boundary

metadata · PredicateWithMetadataKey

Filter by metadata key and value

sources · SourceProxy[]

Filter by specific data sources

workout · WorkoutProxy

Filter by samples associated with a specific workout

OR · FilterForSamplesBase[]

Combine multiple filters with OR logic

AND · FilterForSamplesBase[]

Combine multiple filters with AND logic

NOT · FilterForSamplesBase[]

Negate filters

Returns

samples · QuantitySample[]

An array of quantity samples matching the query criteria

Show QuantitySample properties

uuid · string

Unique identifier for the sample

quantityType · QuantityTypeIdentifier

The type of quantity data

quantity · number

The quantity value

unit · string

The unit of measurement

startDate · Date

When the sample started

endDate · Date

When the sample ended

metadata · AnyMap

Additional metadata associated with the sample

Example

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

// Query last 7 days of step count
const stepSamples = await queryQuantitySamples(
  'HKQuantityTypeIdentifierStepCount',
  {
    limit: 100,
    ascending: false,
    filter: {
      date: {
        startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
        endDate: new Date()
      }
    }
  }
)

console.log(`Found ${stepSamples.length} step samples`)
stepSamples.forEach(sample => {
  console.log(`${sample.quantity} ${sample.unit} on ${sample.startDate}`)
})

---

queryQuantitySamplesWithAnchor

Query quantity samples using HealthKit anchors for efficient syncing. This method is ideal for keeping your app’s data in sync with HealthKit, as it returns only the samples that have changed since the last query.

queryQuantitySamplesWithAnchor(
  identifier: QuantityTypeIdentifier,
  options: QueryOptionsWithAnchorAndUnit
): Promise<QuantitySamplesWithAnchorResponse>

identifier · QuantityTypeIdentifier · required

The quantity type identifier to query

options · QueryOptionsWithAnchorAndUnit · required

Query options including anchor information

Show properties

limit · number · default: 20

Maximum number of samples to return per query. Use 0 for no limit

anchor · string

Base64-encoded anchor string from a previous query. Omit for the first query

unit · string

The unit to use for returned quantity values

filter · FilterForSamples

Additional filter criteria (see queryQuantitySamples for details)

Returns

response · QuantitySamplesWithAnchorResponse

An object containing samples, deleted samples, and the new anchor

Show properties

samples · QuantitySample[]

New or updated samples since the last anchor

deletedSamples · DeletedSample[]

Samples that were deleted since the last anchor

Show DeletedSample properties

uuid · string

UUID of the deleted sample

metadata · AnyMap

Metadata from the deleted sample

newAnchor · string

Base64-encoded anchor to use for the next query. Store this value to continue syncing

Example

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

// First sync - no anchor
const { newAnchor, samples, deletedSamples } = await queryQuantitySamplesWithAnchor(
  'HKQuantityTypeIdentifierStepCount',
  {
    limit: 100
  }
)

console.log(`Initial sync: ${samples.length} samples`)

// Store the anchor for next time
const storedAnchor = newAnchor

// Later, sync only changes
const nextResult = await queryQuantitySamplesWithAnchor(
  'HKQuantityTypeIdentifierStepCount',
  {
    limit: 100,
    anchor: storedAnchor
  }
)

console.log(`New samples: ${nextResult.samples.length}`)
console.log(`Deleted samples: ${nextResult.deletedSamples.length}`)

Always store the newAnchor value after each successful sync. Use this anchor in subsequent queries to retrieve only the changes since the last sync.

Setting limit: 0 will return all available samples, but for large datasets, it’s recommended to use a reasonable limit and paginate through results using the anchor.