Query Category Samples

Query and retrieve category samples from HealthKit

queryCategorySamples

Query category samples from HealthKit with flexible filtering and sorting options.

queryCategorySamples<T extends CategoryTypeIdentifier>(
  identifier: T,
  options: QueryOptionsWithSortOrder
): Promise<readonly CategorySampleTyped<T>[]>

Parameters

identifier · CategoryTypeIdentifier · required

The category type identifier to query. See Category Type Identifiers for all available types.

options · QueryOptionsWithSortOrder · required

Query options for filtering and sorting the results.

Show properties

limit · number · required

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

ascending · boolean

Sort order for the results. true for ascending (oldest first), false for descending (newest first). Defaults to false.

filter · FilterForSamples

Advanced filtering options.

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 (exclusive vs inclusive).

strictEndDate · boolean

Whether to strictly enforce the end date (exclusive vs inclusive).

metadata · PredicateWithMetadataKey

Filter by metadata key-value pairs.

sources · SourceProxy[]

Filter by specific data sources.

OR · FilterForSamplesBase[]

Combine multiple filters with OR logic.

AND · FilterForSamplesBase[]

Combine multiple filters with AND logic.

NOT · FilterForSamplesBase[]

Negate filters.

Returns

samples · readonly CategorySampleTyped<T>[]

An array of category samples matching the query criteria.

Show CategorySampleTyped properties

uuid · string

Unique identifier for the sample.

categoryType · CategoryTypeIdentifier

The category type identifier.

value · CategoryValueForIdentifier<T>

The category value, typed according to the identifier.

startDate · Date

Start date of the category sample.

endDate · Date

End date of the category sample.

metadata · MetadataForCategoryIdentifier<T>

Metadata associated with the sample.

sourceRevision · SourceRevision

Information about the source that created this sample.

Example

import HealthKit, { CategoryValueSleepAnalysis } from 'react-native-healthkit';

// Query sleep analysis samples for the last 7 days
const samples = await HealthKit.queryCategorySamples(
  'HKCategoryTypeIdentifierSleepAnalysis',
  {
    limit: 100,
    ascending: false,
    filter: {
      date: {
        startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
        endDate: new Date(),
      },
    },
  }
);

samples.forEach((sample) => {
  console.log(`Sleep stage: ${sample.value}`);
  console.log(`Duration: ${sample.endDate.getTime() - sample.startDate.getTime()}ms`);
});

---

queryCategorySamplesWithAnchor

Query category samples with anchor-based pagination for efficient data synchronization.

queryCategorySamplesWithAnchor<T extends CategoryTypeIdentifier>(
  identifier: T,
  options: QueryOptionsWithAnchor
): Promise<CategorySamplesWithAnchorResponseTyped<T>>

Parameters

identifier · CategoryTypeIdentifier · required

The category type identifier to query. See Category Type Identifiers for all available types.

options · QueryOptionsWithAnchor · required

Query options including anchor for pagination.

Show properties

limit · number · required

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

anchor · string

The anchor from a previous query. Use this to fetch only new or updated samples since the last query. Omit this parameter on the first query.

filter · FilterForSamples

Advanced filtering options (same as queryCategorySamples).

Returns

response · CategorySamplesWithAnchorResponseTyped<T>

Response object containing samples, deleted samples, and a new anchor.

Show properties

samples · readonly CategorySampleTyped<T>[]

New or updated category samples since the last anchor.

deletedSamples · readonly DeletedSample[]

Samples that were deleted since the last anchor.

Show DeletedSample properties

uuid · string

UUID of the deleted sample.

newAnchor · string

New anchor to use for the next query. Store this value to track incremental changes.

Example

import HealthKit from 'react-native-healthkit';
import AsyncStorage from '@react-native-async-storage/async-storage';

// First query - no anchor
let response = await HealthKit.queryCategorySamplesWithAnchor(
  'HKCategoryTypeIdentifierMindfulSession',
  {
    limit: -1, // Get all samples
  }
);

console.log(`Fetched ${response.samples.length} mindful sessions`);

// Save the anchor for next time
await AsyncStorage.setItem('mindfulSessionAnchor', response.newAnchor);

// Later query - use stored anchor to get only new data
const savedAnchor = await AsyncStorage.getItem('mindfulSessionAnchor');

if (savedAnchor) {
  response = await HealthKit.queryCategorySamplesWithAnchor(
    'HKCategoryTypeIdentifierMindfulSession',
    {
      limit: -1,
      anchor: savedAnchor,
    }
  );
  
  console.log(`New samples: ${response.samples.length}`);
  console.log(`Deleted samples: ${response.deletedSamples.length}`);
  
  // Update the anchor
  await AsyncStorage.setItem('mindfulSessionAnchor', response.newAnchor);
}

The anchor-based query is particularly useful for:

• Syncing data efficiently with your backend
• Implementing real-time updates in your app
• Reducing data transfer by fetching only changes

Always store the newAnchor value and use it in subsequent queries to avoid fetching duplicate data.