<!--
{
  "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/CKRecord",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "CloudKit"
    ],
    "preciseIdentifier" : "c:objc(cs)CKRecord"
  },
  "title" : "CKRecord"
}
-->

# CKRecord

A collection of key-value pairs that store your app’s data.

```
class CKRecord
```

## Overview

Records are the fundamental objects that manage data in CloudKit. You can define any number of record types for your app, with each record type corresponding to a different type of information. Within a record type, you then define one or more fields, each with a name and a 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. A new record object doesn’t contain any keys or values. 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 doesn’t impose these type constraints or do any local validation of a record’s contents. CloudKit enforces these constraints when you save the records.

> Note: The ability to add new keys is only possible during development. When you deploy to a production environment, the server returns an error if you try to specify an unknown record type or try to save a record that contains unknown keys.

Although records behave like dictionaries, there are 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 results in failure. Fields of all types are searchable unless otherwise noted.

### Supported Data Types

`CKRecord` fields support the following data types:

- <doc://com.apple.documentation/documentation/Foundation/NSString>: Stores relatively small amounts of text. Although strings themselves can be any length, use a [`CKAsset`](/documentation/CloudKit/CKAsset) to store large amounts of text.
- <doc://com.apple.documentation/documentation/Foundation/NSNumber>: Stores any numerical information, including integers and floating-point numbers.
- <doc://com.apple.documentation/documentation/Foundation/NSData>: Stores arbitrary bytes of data. A typical use for data objects is to map the bytes that they contain to a `struct`. Don’t use data objects for storing large binary data files; use a [`CKAsset`](/documentation/CloudKit/CKAsset) instead. Data fields aren’t searchable.
- <doc://com.apple.documentation/documentation/Foundation/NSDate>: Stores day and time information in an accessible form.
- <doc://com.apple.documentation/documentation/Foundation/NSArray>: Stores 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.
- <doc://com.apple.documentation/documentation/CoreLocation/CLLocation>: Stores geographic coordinate data. You use locations in conjunction with the Core Location framework and any other services that handle location information.
- [`CKAsset`](/documentation/CloudKit/CKAsset): Associates a disk-based file with the record. Although assets have a close association with records, you manage them separately. For more information about using assets, see [`CKAsset`](/documentation/CloudKit/CKAsset).
- [`CKRecord.Reference`](/documentation/CloudKit/CKRecord/Reference): Creates 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 [`CKRecord.Reference`](/documentation/CloudKit/CKRecord/Reference).

> Important: To ensure the speed of fetching and saving records, the data that a record stores must not exceed 1 MB. Assets don’t count toward this limit, but all other data types do.

### Defining Records

The process for defining your record types depends entirely on your app and the data you’re trying to represent. It’s 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 the employee’s address information. Using different record types lets you manage, manipulate, and validate the two types of information separately.

Use fields that contain [`CKRecord.Reference`](/documentation/CloudKit/CKRecord/Reference) objects to establish relationships between different types of records. After you define your record types, use the iCloud Dashboard to set them up. 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 with data types it can use in the predicate of a query. This automatic indexing makes it easier to experiment with queries during development, but the indexes require space in a database, and require time to generate and maintain.

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

Use this class as-is to manage data coming from or going to the server, and don’t subclass it.

### Storing Records Locally

If you store records in a local database, use the [`encodeSystemFields(with:)`](/documentation/CloudKit/CKRecord/encodeSystemFields(with:)) method to encode and store the record’s metadata. The metadata contains the record ID and the change tag, which you need later to sync records in a local database with those in CloudKit.

## Topics

### Creating a Record

[`init(recordType:recordID:)`](/documentation/CloudKit/CKRecord/init(recordType:recordID:))

Creates a record using an ID that you provide.

[`CKRecord.RecordType`](/documentation/CloudKit/CKRecord/RecordType-swift.typealias)

The data type that CloudKit requires for record types.

[`CKRecord.FieldKey`](/documentation/CloudKit/CKRecord/FieldKey)

The data type that CloudKit requires for record field names.

[`init(recordType:zoneID:)`](/documentation/CloudKit/CKRecord/init(recordType:zoneID:))

Creates a record in the specified zone.

[`initWithRecordType:`](/documentation/CloudKit/CKRecord/initWithRecordType:)

Creates a new record of the specified type.

[`initWithRecordType:zoneID:`](/documentation/CloudKit/CKRecord/initWithRecordType:zoneID:)

Creates a record in the specified zone.

[`initWithRecordType:recordID:`](/documentation/CloudKit/CKRecord/initWithRecordType:recordID:)

Creates a record using an ID that you provide.

[`CKRecordType`](/documentation/CloudKit/CKRecordType)

A data type that CloudKit requires for record types.

[`CKRecordTypeShare`](/documentation/CloudKit/CKRecordTypeShare-8b6yt)

The system type that identifies a share record.

[`CKRecordTypeUserRecord`](/documentation/CloudKit/CKRecordTypeUserRecord-49k30)

The system type that identifies a user record.

[`CKRecordFieldKey`](/documentation/CloudKit/CKRecordFieldKey)

A data type that CloudKit requires for record field names.

### Accessing the Record’s Fields

[`object(forKey:)`](/documentation/CloudKit/CKRecord/object(forKey:))

Returns the object that the record stores for the specified key.

[`objectForKey:`](/documentation/CloudKit/CKRecord/objectForKey:)

Returns the object that the record stores for the specified key.

[`subscript(_:)`](/documentation/CloudKit/CKRecord/subscript(_:)-51whk)

Returns the object that the record stores for the specified key.

[`subscript(_:)`](/documentation/CloudKit/CKRecord/subscript(_:)-4g91i)

Returns the object that the record stores for the specified key.

[`setObject(_:forKey:)`](/documentation/CloudKit/CKRecord/setObject(_:forKey:))

Stores an object in the record using the specified key.

[`allKeys()`](/documentation/CloudKit/CKRecord/allKeys())

Returns an array of the record’s keys.

[`changedKeys()`](/documentation/CloudKit/CKRecord/changedKeys())

Returns an array of keys with recent changes to their values.

[`makeIterator()`](/documentation/CloudKit/CKRecord/makeIterator())

Returns an iterator of the record’s key-value pairs.

[`CKRecordKeyValueIterator`](/documentation/CloudKit/CKRecordKeyValueIterator)

An iterator of the record’s key-value pairs.

[`CKRecordValueProtocol`](/documentation/CloudKit/CKRecordValueProtocol)

A description of a CloudKit record value.

[`setObject:forKey:`](/documentation/CloudKit/CKRecord/setObject:forKey:)

Stores an object in the record using the specified key.

[`setObject:forKeyedSubscript:`](/documentation/CloudKit/CKRecord/setObject:forKeyedSubscript:)

Stores an object in the record using the specified key.

[`allKeys`](/documentation/CloudKit/CKRecord/allKeys)

Returns an array of the record’s keys.

[`changedKeys`](/documentation/CloudKit/CKRecord/changedKeys)

Returns an array of keys with recent changes to their values.

[`CKRecordKeyValueSetting`](/documentation/CloudKit/CKRecordKeyValueSetting)

A protocol for managing the key-value pairs of a CloudKit record.

[`CKRecordValue`](/documentation/CloudKit/CKRecordValue-swift.typealias)

A data type for objects that CloudKit stores on the server.

[`CKRecordCreationDateKey`](/documentation/CloudKit/CKRecordCreationDateKey)

A key constant that a record uses for its CKRecord.creationDate.

[`CKRecordCreatorUserRecordIDKey`](/documentation/CloudKit/CKRecordCreatorUserRecordIDKey)

A key constant that a record uses for its CKRecord.creatorUserRecordID.

[`CKRecordLastModifiedUserRecordIDKey`](/documentation/CloudKit/CKRecordLastModifiedUserRecordIDKey)

A key constant that a record uses for its CKRecord.lastModifiedUserRecordID.

[`CKRecordModificationDateKey`](/documentation/CloudKit/CKRecordModificationDateKey)

A key constant that a record uses for its CKRecord.modificationDate.

[`CKRecordRecordIDKey`](/documentation/CloudKit/CKRecordRecordIDKey)

A key constant that a record uses for its CKRecord.recordID.

[`CKRecordParentKey`](/documentation/CloudKit/CKRecordParentKey-2kx8l)

The key constant that a record uses for its CKRecord.parent.

[`CKRecordShareKey`](/documentation/CloudKit/CKRecordShareKey-rrat)

The key constant that a record uses for its CKRecord.share.

### Accessing the Record’s Metadata

[`recordID`](/documentation/CloudKit/CKRecord/recordID)

The unique ID of the record.

[`recordType`](/documentation/CloudKit/CKRecord/recordType-6v7au)

The value that your app defines to identify the type of record.

[`CKRecord.SystemType`](/documentation/CloudKit/CKRecord/SystemType)

Possible values for record types of system records.

[`recordType`](/documentation/CloudKit/CKRecord/recordType-9s09b)

The value that your app defines to identify the type of record.

[`creationDate`](/documentation/CloudKit/CKRecord/creationDate)

The time when CloudKit first saves the record to the server.

[`creatorUserRecordID`](/documentation/CloudKit/CKRecord/creatorUserRecordID)

The ID of the user who creates the record.

[`modificationDate`](/documentation/CloudKit/CKRecord/modificationDate)

The most recent time that CloudKit saved the record to the server.

[`lastModifiedUserRecordID`](/documentation/CloudKit/CKRecord/lastModifiedUserRecordID)

The ID of the user who most recently modified the record.

[`recordChangeTag`](/documentation/CloudKit/CKRecord/recordChangeTag)

The server change token for the record.

[`CKRecord.ID`](/documentation/CloudKit/CKRecord/ID)

An object that uniquely identifies a record in a database.

### Encrypting the Record’s Values

[`encryptedValues`](/documentation/CloudKit/CKRecord/encryptedValues)

An object that manages the record’s encrypted key-value pairs.

### Getting Data for Full-Text Searches

[`allTokens()`](/documentation/CloudKit/CKRecord/allTokens())

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

### Encoding the Record’s Metadata

[`encodeSystemFields(with:)`](/documentation/CloudKit/CKRecord/encodeSystemFields(with:))

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

### Sharing Records

[`parent`](/documentation/CloudKit/CKRecord/parent)

A reference to the record’s parent record.

[`share`](/documentation/CloudKit/CKRecord/share)

A reference to the share object that determines the share status of the record.

[`CKRecord.Reference`](/documentation/CloudKit/CKRecord/Reference)

A relationship between two records in a record zone.

[`setParent(_:)`](/documentation/CloudKit/CKRecord/setParent(_:)-23du1)

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

[`setParent(_:)`](/documentation/CloudKit/CKRecord/setParent(_:)-7egcx)

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

[`CKRecord.SystemFieldKey`](/documentation/CloudKit/CKRecord/SystemFieldKey)

Possible values for types of system field keys on 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)