<!--
{
  "availability" : [
    "iOS: 10.0.0 -",
    "iPadOS: 10.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 13.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 3.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "HealthKit",
  "identifier" : "/documentation/HealthKit/HKDocumentQuery",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "HealthKit"
    ],
    "preciseIdentifier" : "c:objc(cs)HKDocumentQuery"
  },
  "title" : "HKDocumentQuery"
}
-->

# HKDocumentQuery

A query that returns a snapshot of all matching documents currently saved in the HealthKit store.

```
class HKDocumentQuery
```

## Overview

Use an `HKDocumentQuery` object to search for documents in the HealthKit store. You can provide a predicate to filter the search results, a sort order for the returned samples, or even a limit to the number of samples returned.

Document queries are immutable: The query’s properties are set when the query is first created. They cannot change.

### Executing Queries

To create and execute a query, perform the following steps:

1. Create the document type by calling the [`HKObjectType`](/documentation/HealthKit/HKObjectType) class’s [`documentType(forIdentifier:)`](/documentation/HealthKit/HKObjectType/documentType(forIdentifier:)) method.
2. (optionally) Create an <doc://com.apple.documentation/documentation/Foundation/NSPredicate> object to filter the search results.
3. (optionally) Create an array of <doc://com.apple.documentation/documentation/Foundation/NSSortDescriptor> objects to provide the sort order for the results.
4. Instantiate a new query by calling the [`init(documentType:predicate:limit:sortDescriptors:includeDocumentData:resultsHandler:)`](/documentation/HealthKit/HKDocumentQuery/init(documentType:predicate:limit:sortDescriptors:includeDocumentData:resultsHandler:)) method.
5. In the results handler, handle any errors and process the results.

Note, the query returns the results in batches and may call the results handler more than once. If the `done` parameter is set to <doc://com.apple.documentation/documentation/Swift/false>, the query is still active and will call the results handler with additional results. If the `done` parameter is set to <doc://com.apple.documentation/documentation/Swift/true>, the query is complete.

```swift
guard let cdaType = HKObjectType.documentType(forIdentifier: .CDA) else {
    fatalError("Unable to create a CDA document type.")
}
 
var allDocuments = [HKDocumentSample]()
let cdaQuery = HKDocumentQuery(documentType: cdaType,
                               predicate: nil,
                               limit: HKObjectQueryNoLimit,
                               sortDescriptors: nil,
                               includeDocumentData: false) {
                                
                                (query, resultsOrNil, done, errorOrNil) in
                                
                                guard let results = resultsOrNil else {
                                    if let queryError = errorOrNil {
                                        // Handle the query error here...
                                    }
                                    
                                    return
                                }
                                
                                allDocuments += results
                                
                                if done {
                                    // the allDocuments array now contains all the samples returned by the query.
                                    // Handle the documents here...
                                }
}
```

### Subclassing Document Queries

As with many HealthKit classes, don’t subclass the [`HKDocumentQuery`](/documentation/HealthKit/HKDocumentQuery) class.

## Topics

### Creating Document Queries

[`init(documentType:predicate:limit:sortDescriptors:includeDocumentData:resultsHandler:)`](/documentation/HealthKit/HKDocumentQuery/init(documentType:predicate:limit:sortDescriptors:includeDocumentData:resultsHandler:))

Instantiates and returns a document query.

[`HKObjectQueryNoLimit`](/documentation/HealthKit/HKObjectQueryNoLimit)

A value indicating that the query returns all the matching samples in the HealthKit store.

### Accessing the Document Query’s Properties

[`includeDocumentData`](/documentation/HealthKit/HKDocumentQuery/includeDocumentData)

A Boolean value that indicates whether the sample includes the full document’s data.

[`limit`](/documentation/HealthKit/HKDocumentQuery/limit)

The maximum number of documents the receiver will return upon completion.

[`sortDescriptors`](/documentation/HealthKit/HKDocumentQuery/sortDescriptors)

An array of sort descriptors that specify the order of the results returned by this query.


---

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)