Class

HKDocumentQuery

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

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 class’s documentType(forIdentifier:) method.

  2. (optionally) Create an NSPredicate object to filter the search results.

  3. (optionally) Create an array of 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:) 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 false, the query is still active and will call the results handler with additional results. If the done parameter is set to true, the query is complete.

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

Like many HealthKit classes, the HKDocumentQuery class should not be subclassed.

Topics

Creating Document Queries

init(documentType: HKDocumentType, predicate: NSPredicate?, limit: Int, sortDescriptors: [NSSortDescriptor]?, includeDocumentData: Bool, resultsHandler: (HKDocumentQuery, [HKDocumentSample]?, Bool, Error?) -> Void)

Instantiates and returns a document query.

let HKObjectQueryNoLimit: Int

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

Accessing the Document Query’s Properties

var includeDocumentData: Bool

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

var limit: Int

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

var sortDescriptors: [NSSortDescriptor]?

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

Relationships

Inherits From

HKQuery

Conforms To

See Also

Common Query Types

class HKSampleQuery

A general-purpose query that returns a snapshot of all the matching samples currently saved in the HealthKit store.

class HKQuantitySeriesSampleQuery

A query that accesses the series data associated with a quantity sample.

Beta
class HKAnchoredObjectQuery

A query that returns only recent changes to the HealthKit store, including a snapshot of new changes and continuous monitoring as a long-running query.

class HKObserverQuery

A long-running query that monitors the HealthKit store and updates your app whenever a matching sample is saved to or deleted from the HealthKit store.

class HKCorrelationQuery

A query that performs complex searches based on the correlation’s contents, and returns a snapshot of all matching samples.

class HKQuery

An abstract class for all the query classes in HealthKit.