<!--
{
  "availability" : [
    "iOS: 8.0.0 -",
    "iPadOS: 8.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.10.0 -",
    "tvOS: -",
    "visionOS: 1.0.0 -",
    "watchOS: 3.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "CloudKit",
  "identifier" : "/documentation/CloudKit/CKQueryOperation",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "CloudKit"
    ],
    "preciseIdentifier" : "c:objc(cs)CKQueryOperation"
  },
  "title" : "CKQueryOperation"
}
-->

# CKQueryOperation

An operation for executing queries in a database.

```
class CKQueryOperation
```

## Overview

A `CKQueryOperation` object is a concrete operation that you can use to execute queries. A query operation applies query parameters to the specified database and record zone, delivering any matching records asynchronously to the handlers that you provide.

To perform a new search:

1. Initialize a `CKQueryOperation` object with a [`CKQuery`](/documentation/CloudKit/CKQuery) object that contains the search criteria and sorting information for the records you want.
2. Assign a handler to the [`queryCompletionBlock`](/documentation/CloudKit/CKQueryOperation/queryCompletionBlock) property so that you can process the results and execute the operation.
   
   If the search yields many records, the operation object may deliver a portion of the total results to your blocks immediately, along with a cursor for obtaining the remaining records. Use the cursor to initialize and execute a separate `CKQueryOperation` instance when you’re ready to process the next batch of results.
3. Optionally, configure the results by specifying values for the [`resultsLimit`](/documentation/CloudKit/CKQueryOperation/resultsLimit) and [`desiredKeys`](/documentation/CloudKit/CKQueryOperation/desiredKeys-4a6vy) properties.
4. Pass the query operation object to the [`add(_:)`](/documentation/CloudKit/CKDatabase/add(_:)) method of the target database to execute the operation.

CloudKit restricts queries to the records in a single record zone. For new queries, you specify the zone when you initialize the query operation object. For cursor-based queries, the cursor contains the zone information. To search for records in multiple zones, you must create a separate `CKQueryOperation` object for each zone you want to search, although you can initialize each of them with the same [`CKQuery`](/documentation/CloudKit/CKQuery) object.

If you assign a handler to the operation’s <doc://com.apple.documentation/documentation/Foundation/Operation/completionBlock> property, the operation calls it after it executes and returns any results. Use a handler to perform housekeeping tasks for the operation, but don’t use it to process the results of the operation. The handler you provide should manage any failures, whether due to an error or an explicit cancellation.

## Topics

### Creating a Query Operation

[`init(query:)`](/documentation/CloudKit/CKQueryOperation/init(query:))

Creates an operation that searches for records in the specified record zone.

[`init(cursor:)`](/documentation/CloudKit/CKQueryOperation/init(cursor:))

Creates an operation with additional results from a previous search.

[`init()`](/documentation/CloudKit/CKQueryOperation/init())

Creates an empty query operation.

### Configuring the Query Operation

[`query`](/documentation/CloudKit/CKQueryOperation/query)

The query for the search.

[`cursor`](/documentation/CloudKit/CKQueryOperation/cursor-swift.property)

The cursor for continuing the search.

[`CKQueryOperation.Cursor`](/documentation/CloudKit/CKQueryOperation/Cursor-swift.class)

An object that marks the stopping point for a query and the starting point for retrieving the remaining results.

[`zoneID`](/documentation/CloudKit/CKQueryOperation/zoneID)

The ID of the record zone that contains the records to search.

[`resultsLimit`](/documentation/CloudKit/CKQueryOperation/resultsLimit)

The maximum number of records to return at one time.

[`maximumResults`](/documentation/CloudKit/CKQueryOperation/maximumResults)

A constant value that represents the maximum number of results CloudKit retrieves.

[`desiredKeys`](/documentation/CloudKit/CKQueryOperation/desiredKeys-7qrse)

The fields of the records to fetch.

[`desiredKeys`](/documentation/CloudKit/CKQueryOperation/desiredKeys-4a6vy)

The fields of the records to fetch.

### Processing the Query Results

[`recordFetchedBlock`](/documentation/CloudKit/CKQueryOperation/recordFetchedBlock)

The closure to execute when a record becomes available.

[`queryCompletionBlock`](/documentation/CloudKit/CKQueryOperation/queryCompletionBlock)

The closure to execute after CloudKit retrieves all of the records.


---

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)