Contents

fetch(withQuery:inZoneWith:desiredKeys:resultsLimit:completionHandler:)

Searches for records that match a predicate and delivers them to a completion handler.

Declaration

@preconcurrency func fetch(withQuery query: CKQuery, inZoneWith zoneID: CKRecordZone.ID? = nil, desiredKeys: [CKRecord.FieldKey]? = nil, resultsLimit: Int = CKQueryOperation.maximumResults, completionHandler: @escaping  @Sendable (Result<(matchResults: [(CKRecord.ID, Result<CKRecord, any Error>)], queryCursor: CKQueryOperation.Cursor?), any Error>) -> Void)

Parameters

  • query:

    The query that contains the search parameters. For more information, see 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.

  • completionHandler:

    The closure to execute with the search results.

Discussion

The completion handler takes a single Result parameter that contains either a tuple, or an error if the request fails. For example, when the network is unavailable or the device doesn’t have an active iCloud account.

When present, the tuple contains the following named elements:

matchResults

An array of tuples. Each tuple includes a record identifier and a Result that contains either the corresponding matched record, or an error that describes why CloudKit can’t provide that record. For example, if CloudKit fails to materialize an asset field, it returns an error instead of a partial record. CloudKit sorts the array according to the query’s sort descriptors.

queryCursor

A cursor if the number of results exceeds resultsLimit; otherwise, nil.

If you specify resultsLimit and the number of matched records exceeds that value, CloudKit provides 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 fetch(withCursor:desiredKeys:resultsLimit:completionHandler:) method.

For information on a more configurable way to search a database, see CKQueryOperation.

See Also

Querying Records