CKRecord.Reference
A relationship between two records in a record zone.
Declaration
class ReferenceMentioned in
Overview
A CKReference object creates a many-to-one relationship between records in your database. Each reference object stores information about the one record that is the target of the reference. You then save the reference object in the fields of one or more records to create a link from those records to the target. You may only create references between records within the same zone of the same database.
References create a stronger relationship between records than just saving the ID of a record as a string. Specifically, you can use references to create an ownership model between two records. When the reference object’s action is CKRecord.ReferenceAction.deleteSelf, the target of the reference—that is, the record in the reference’s recordID property—becomes the owner of the source record. Deleting the target (owner) record deletes all its source records. The deletion of any owned records can trigger further deletions if those records are the owners of other records. If a record contains two or more CKReference objects with an action of CKRecord.ReferenceAction.deleteSelf, CloudKit deletes the record when it deletes any of the objects it references.
To save multiple records that contain references between them, save the target records first or save all the records in one batch operation using CKModifyRecordsOperation.
Interacting with Reference Objects
You use reference objects to create strong links between two records and to search for related fields. When you create new records, you create reference objects and assign them to fields of your records. The only other time you create reference objects is when you build a search predicate to search for related records.
Linking to Another Record
To link records together and create a strong relationship between them, create a new CKReference object, initialize it with the owner record, and assign that reference object to a field of the owned record. When you design the relationships among your own records, make the owner the more important of two related records. The owner record rarely depends on any records that point to it. The owner record is also the one that you typically fetch first from the database.
The figure below shows an example of a relationship between a to-do list record and a set of item records that represent individual items to complete. The to-do list is the primary record, or owner, in the relationship because it represents the entire to-do list, including all items on the list. As a result, each item record has a field that contains a CKReference object that points to the owning to-do list record.
[Image]
The following code sample shows how to create the reference object for each item record and configure it to point at the list record:
An ownership type of organization is useful even if one object doesn’t explicitly own another. Ownership helps establish the relationships between records and how you search for them in the database. Ownership doesn’t require the deletion of the owned records when you delete their owner record. You can prevent such deletions by specifying the CKRecord.ReferenceAction.none action when you create a CKReference object.
Searching for Related Records
When you want to find records for a single owner object, you create a CKReference object and use it to build your search predicate. When you use reference objects in search predicates, the search code looks only at the ID value in the reference object. It matches the ID in records of the specified type with the ID you provide in the CKReference object.
The code sample below shows how to use a reference object to construct a query for the records in the figure above. The listID variable is a placeholder for the record ID of the list with the items you want to retrieve. The predicate tells the query object to search the owningList field of the target records and compare the reference object there with the one in the recordToMatch variable. Executing the query operation object returns the matching records asynchronously to the completion block you provide.