---
title: "records(matching:inZoneWith:desiredKeys:resultsLimit:)"
framework: cloudkit
role: symbol
role_heading: Instance Method
path: "cloudkit/ckdatabase/records(matching:inzonewith:desiredkeys:resultslimit:)"
---

# records(matching:inZoneWith:desiredKeys:resultsLimit:)

Searches for records that match a predicate and returns them to an awaiting caller.

## Declaration

```swift
func records(matching query: CKQuery, inZoneWith zoneID: CKRecordZone.ID? = nil, desiredKeys: [CKRecord.FieldKey]? = nil, resultsLimit: Int = CKQueryOperation.maximumResults) async throws -> (matchResults: [(CKRecord.ID, Result<CKRecord, any Error>)], queryCursor: CKQueryOperation.Cursor?)
```

## Parameters

- `query`: The query that contains the search parameters. For more information, see doc://com.apple.cloudkit/documentation/CloudKit/CKQuery.
- `zoneID`: The identifier of the record zone to search. If you’re searching a shared database, provide a record zone identifier; otherwise, you can specify nil to search all record zones in the database.
- `desiredKeys`: The fields to include on each fetched record. To include all fields, specify nil; to fetch only system fields, specify an empty array.
- `resultsLimit`: The maximum number of records to return in a single set of results.

## Return Value

Return Value A tuple with the following named elements:

## Discussion

Discussion If you specify resultsLimit and the number of matched records exceeds that value, this method returns only that number of records and a cursor — an object that marks a specific location in the full search results. To retrieve the next subset of search results, pass that cursor to the records(continuingMatchFrom:desiredKeys:resultsLimit:) method. This method throws an error if the request fails, such as when the network is unavailable or the device doesn’t have an active iCloud account; otherwise, the returned tuple includes any individual record errors. For information on a more configurable way to search a database, see CKQueryOperation.

## See Also

### Querying Records

- [records(continuingMatchFrom:desiredKeys:resultsLimit:)](cloudkit/ckdatabase/records(continuingmatchfrom:desiredkeys:resultslimit:).md)
- [fetch(withQuery:inZoneWith:desiredKeys:resultsLimit:completionHandler:)](cloudkit/ckdatabase/fetch(withquery:inzonewith:desiredkeys:resultslimit:completionhandler:).md)
- [fetch(withCursor:desiredKeys:resultsLimit:completionHandler:)](cloudkit/ckdatabase/fetch(withcursor:desiredkeys:resultslimit:completionhandler:).md)
- [perform(_:inZoneWith:completionHandler:)](cloudkit/ckdatabase/perform(_:inzonewith:completionhandler:).md)
- [records(matching:inZoneWith:)](cloudkit/ckdatabase/records(matching:inzonewith:).md)