<!--
{
  "availability" : [
    "iOS: 15.4.0 -",
    "iPadOS: 15.4.0 -",
    "macCatalyst: 15.4.0 -",
    "macOS: 13.0.0 -",
    "visionOS: -",
    "watchOS: 8.5.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "HealthKit",
  "identifier" : "/documentation/HealthKit/HKStatisticsCollectionQueryDescriptor",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "HealthKit"
    ],
    "preciseIdentifier" : "s:9HealthKit37HKStatisticsCollectionQueryDescriptorV"
  },
  "title" : "HKStatisticsCollectionQueryDescriptor"
}
-->

# HKStatisticsCollectionQueryDescriptor

A query descriptor that gathers a collection of statistics calculated over a series of fixed-length time intervals.

```
struct HKStatisticsCollectionQueryDescriptor
```

## Overview

Use [`HKStatisticsCollectionQueryDescriptor`](/documentation/HealthKit/HKStatisticsCollectionQueryDescriptor) to run a query that calculates statistics grouped into time intervals. To get a snapshot of the current data in the store, create a descriptor and call its [`result(for:)`](/documentation/HealthKit/HKStatisticsCollectionQueryDescriptor/result(for:)) method.

```swift
// Create a predicate for this week's samples.
let calendar = Calendar(identifier: .gregorian)
let today = calendar.startOfDay(for: Date())

guard let endDate = calendar.date(byAdding: .day, value: 1, to: today) else {
    fatalError("*** Unable to calculate the end time ***")
}

guard let startDate = calendar.date(byAdding: .day, value: -7, to: endDate) else {
    fatalError("*** Unable to calculate the start time ***")
}

let thisWeek = HKQuery.predicateForSamples(withStart: startDate, end: endDate)

// Create the query descriptor.
let stepType = HKQuantityType(.stepCount)
let stepsThisWeek = HKSamplePredicate.quantitySample(type: stepType, predicate:thisWeek)
let everyDay = DateComponents(day:1)

let sumOfStepsQuery = HKStatisticsCollectionQueryDescriptor(
    predicate: stepsThisWeek,
    options: .cumulativeSum,
    anchorDate: endDate,
    intervalComponents: everyDay)

let stepCounts = try await sumOfStepsQuery.result(for: store)

// Use the statistics collection here.
```

To set up a long-running query that updates the calculations based on any new data that arrives while it’s running, call the [`results(for:)`](/documentation/HealthKit/HKStatisticsCollectionQueryDescriptor/results(for:)) method instead. The first result contains calculations based on samples currently in the HealthKit store, and additional results represent updates as they occur.

```swift
// Run a long-running query that updates its statistics as new data comes in.
let updateQueue = sumOfStepsQuery.results(for: store)

// Wait for the initial results and updates.
updateTask = Task {
    for try await results in updateQueue {
        // Use the statistics collection here.
    }
}
```

## Topics

### Creating Query Descriptors

[`init(predicate:options:anchorDate:intervalComponents:)`](/documentation/HealthKit/HKStatisticsCollectionQueryDescriptor/init(predicate:options:anchorDate:intervalComponents:))

Creates a statistics collection query descriptor.

### Running Queries

[`result(for:)`](/documentation/HealthKit/HKStatisticsCollectionQueryDescriptor/result(for:))

Runs a one-shot query and asynchronously returns statistics calculated from the current matching results.

[`results(for:)`](/documentation/HealthKit/HKStatisticsCollectionQueryDescriptor/results(for:))

Initiates a long-running query that returns statistics and updates using an asynchronous sequence.

[`HKStatisticsCollectionQueryDescriptor.Results`](/documentation/HealthKit/HKStatisticsCollectionQueryDescriptor/Results)

An asynchronous sequence that emits updates from a statistics collection query.

### Accessing Query Properties

[`predicate`](/documentation/HealthKit/HKStatisticsCollectionQueryDescriptor/predicate)

A predicate that defines the set of data that the query uses to calculate the statistics.

[`options`](/documentation/HealthKit/HKStatisticsCollectionQueryDescriptor/options)

A list of options that define the type of statistical calculations performed and the way in which HealthKit merges data from multiple sources.

[`anchorDate`](/documentation/HealthKit/HKStatisticsCollectionQueryDescriptor/anchorDate)

The date that anchors the collection’s time intervals.

[`intervalComponents`](/documentation/HealthKit/HKStatisticsCollectionQueryDescriptor/intervalComponents)

The date components that define the time interval for each statistics object in the collection.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)