Class

CKRecord

A dictionary of key-value pairs that you use to fetch and save your app's data.

Overview

Records are the fundamental objects you use to manage data in CloudKit. You may define any number of record types for your app, with each record type corresponding to a different type of information you need. Within a given record type, you then define one or more fields, each of which has a name and a data value. Records can contain simple data types such as strings and numbers or more complex types such as geographic locations or pointers to other records.

An important step in using CloudKit is defining the record types your app supports. Each new record object contains no keys or values initially. During development, you can add new keys and values at any time. The first time you set a value for a key and save the record, the server associates that type with the key for all records of the same type. (The CKRecord class does not enforce these type constraints or do any local validation of a record’s contents; those constraints are enforced by the server when you save records.)

Although records act like dictionaries, there are still limitations to the types of values you can assign to keys. The following are the object types that the CKRecord class supports. Attempting to specify objects of any other type is a programmer error and will fail. Fields of all types are searchable unless otherwise noted.

Supported Data Types

The following data types are supported in CKRecord fields.

NSString

Store relatively small amounts of text. Although strings themselves can be any length, use a CKAsset to store large amounts of text.

NSNumber

Store any numerical information, including integers and floating-point numbers.

NSData

Store arbitrary bytes of data. A typical use for data objects is to map the bytes that they contain to a struct. Do not use data objects for storing large binary data files; use a CKAsset instead. Data fields are not searchable.

NSDate

Store day and time information in an accessible form.

NSArray

Store one or more objects of any other type in this table. You can store arrays of strings, arrays of numbers, arrays of references, and so on.

CLLocation

Store geographic coordinate data. You use locations in conjunction with the Core Location framework and/or with any other services that handle location information.

CKAsset

Associate a disk-based file with the record. Assets are intimately tied to records but are managed separately. For more information about using assets, see CKAsset.

CKReference

Create a link to a related record. A reference stores the ID of the target record. The advantage of using a reference instead of storing the ID as a string is that references can initiate cascade deletions of dependent records. The disadvantage is that references can only link between records in the same record zone. For more information, see CKReference.

Interacting with Records

You interact with records as follows:

The process for defining your record types depends entirely on your app and the data you are trying to represent. It is best to design records that encapsulate data for one unit of information. For example, you might use one record type to store an employee’s name, job title, and date of hire, and use a separate record type to store address information. Using different record types lets you manage, manipulate, and validate the two types of information separately. Use fields containing CKReference objects to establish relationships between different types of records. After you define your record types, use the iCloud Dashboard to set up your record types. During development, you can also create new record types programmatically.

Indexing the Fields of a Record

Indexes make it possible to search the contents of your records efficiently. During development, the server indexes all fields whose data types can be used in the predicate of a query. This automatic indexing makes it easier to experiment with queries during development, but these indexes take up space in a database and take time to generate and maintain. So when migrating to a production environment, remove the indexes for any fields that you do not actually use in queries.

To manage the indexing behavior of your records in the production environment, use CloudKit Dashboard. When migrating your schema from the development environment to the production environment, enable indexing only for the fields that your app uses in queries and disable it for all other fields.

Customizing Records

The CKRecord class does not support any special customizations and should not be subclassed. Use this class as-is to manage data coming from or going to the server.

Storing Records Locally

If you store records in a local database, use the encodeSystemFields(with:) method to encode and store the record’s metadata. The metadata contains the record ID and change tag which is needed later to sync records in a local database with those stored by CloudKit.

Topics

Initializing a Record

init(recordType: String)

Initializes and returns a new record of the specified type.

init(recordType: String, zoneID: CKRecordZoneID)

Initializes and returns a record in the specified zone.

init(recordType: String, recordID: CKRecordID)

Initializes and returns a record using an ID that you provide.

Accessing the Record’s Fields

func object(forKey: String)

Returns the value for the given key stored in the record.

func setObject(CKRecordValue?, forKey: String)

Sets the value for the specified key.

subscript(String)

Returns the value for the given key stored in the record.

func allKeys()

Returns an array of strings corresponding to all keys currently in the record.

func changedKeys()

Returns an array of strings representing the keys that have changed recently.

Accessing the Record’s Metadata

var recordID: CKRecordID

The unique ID of the record.

var recordType: String

The app-defined string that identifies the type of the record.

var creationDate: Date?

The time when the record was first saved to the server.

var creatorUserRecordID: CKRecordID?

The ID of the user who created the record.

var modificationDate: Date?

The time when the record was last saved to the server.

var lastModifiedUserRecordID: CKRecordID?

The ID of the user who last modified the record.

var recordChangeTag: String?

A string containing the server change token for the record.

class CKRecordID

An object that uniquely identifies a record in a database.

Getting Data for Full-Text Searches

func allTokens()

Returns an array of strings that you can use for full-text searches of the field’s string-based values.

Encoding the Record’s Metadata

func encodeSystemFields(with: NSCoder)

Encodes the record’s system fields using the specified archiver.

Sharing Records

var parent: CKReference?

A reference to the parent record to this record.

var share: CKReference?

A reference to the share associated with the sharing of this record.

func setParent(CKRecord?)

Creates and sets a reference object for a parent from its record.

func setParent(CKRecordID?)

Creates and sets a reference object for a parent from the parent’s record ID.

Constants

let CKRecordParentKey: String

The key constant to the parent record.

let CKRecordShareKey: String

The key constant to a record's share reference.

let CKRecordTypeShare: String

The key constant used to retrieve the type value of the record.

let CKRecordTypeUserRecord: String

The record type for user records.

enum CKRecordSavePolicy

Constants indicating the policy to apply when saving records.

Relationships

Inherits From

See Also

Records

class CKRecordZone

The definition of a custom area for organizing related records in a database.

class CKReference

A reference used to create a many-to-one relationship between records in a database.

protocol CKRecordValue

The protocol that provides strong type checking for objects that the CloudKit framework stores on the server.

Record Operations

Asynchronously fetch or modify records.