healthkit-queries

Design and optimize HealthKit queries for accurate time-series data retrieval.

Updated Oct 4, 2025

Search Tags:#debugging #queries #iOS #time-series #data-aggregation #healthkit

Ready to run

npx skills add https://github.com/NickChristensen/HealthTrends --skill healthkit-queries

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: healthkit-queries
Source: https://github.com/NickChristensen/HealthTrends/tree/main/.agents/skills/healthkit-queries
Command: npx skills add https://github.com/NickChristensen/HealthTrends --skill healthkit-queries

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps developers design and optimize HealthKit queries to retrieve accurate results efficiently, reducing debugging time and data discrepancies.

Core Features & Use Cases

Guided query construction for HKSampleQuery and HKStatisticsCollectionQuery with correct predicates, anchor dates, and interval handling.
Edge-case handling and debugging for time zones, DST, midnight boundaries, and data overlap vs start-date semantics.
Performance and reliability patterns for background delivery, authorization checks, error handling, and safe fallbacks in widgets and app contexts.
Use cases include implementing new HealthKit features, diagnosing "data is off" issues, and optimizing long-running time-series queries on large datasets.

Quick Start

Design an hourly active energy query between two dates by selecting the appropriate HKQuery type, applying a strictStartDate predicate, and executing the query to fetch samples or statistics.

Frequently Asked Questions about healthkit-queries

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I optimize HealthKit queries for accurate time-series data aggregation?▼

Optimize HealthKit queries by selecting appropriate HKQuery types, applying strictStartDate predicates, and configuring correct anchor dates and hourly or daily intervals to retrieve accurate time-series data efficiently.

Why does my HealthKit data show discrepancies across different time zones and DST transitions?▼

HealthKit data discrepancies occur when queries fail to handle time zones, DST, and midnight boundaries correctly. Using proper anchor dates and strict start-date semantics prevents data overlap and ensures accurate time-series results.

How do I set up an hourly HKStatisticsCollectionQuery for active energy data?▼

Set up an hourly HKStatisticsCollectionQuery by selecting the appropriate HKQuery type, applying a strictStartDate predicate, configuring anchor dates, and executing the query to fetch statistics between your target dates.

Does HealthKit background delivery work reliably for widgets and app contexts?▼

HealthKit background delivery works reliably when you implement proper performance patterns, authorization checks, error handling, and safe fallbacks designed specifically for widgets and app contexts.

What is the best way to debug "data is off" issues in iOS HealthKit time-series queries?▼

Debug HealthKit data discrepancies by validating predicate configurations, checking start-date semantics versus data overlap, and verifying timezone and DST handling within your HKSampleQuery or HKStatisticsCollectionQuery implementations.

Can I use HealthKit queries to aggregate large datasets without performance issues?▼

HealthKit queries can aggregate large datasets efficiently when you apply performance and reliability patterns including proper interval configuration, optimized predicates, and robust error handling for long-running time-series queries.