An object representing a large file associated with a record.
- iOS 8.0+
- macOS 10.10+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 3.0+
Use asset objects to incorporate external files—such as image, sound, video, text, and binary data files—into your app’s records. You can also use assets in places where the data you want to assign to a field is more than a few kilobytes in size. To associate an asset with a record, assign it as the value of one of the record’s fields.
The content of an asset is stored separately from the record that references it but is tied closely to that record. When you save a record that has an asset, CloudKit saves both the record and the asset data to the server. Similarly, when you fetch the record, the server returns both the record data and any assets. If multiple records refer to the same asset, however, CloudKit saves or fetches only one copy of the asset data. CloudKit saves only the asset data; it does not save the filename or any other metadata associated with the initial file you provide.
When you download a record containing an asset, CloudKit keeps the asset data around for a little while but may delete it at any point in the future to free up disk space. After fetching a record containing an asset, you can retrieve the asset data with the URL in the
file property. If you want to ensure that the asset’s data remains local to the device, write the data to a file in your app’s local container directory and reference the data from the new file.
You cannot delete asset data directly from the server. When you no longer want the data associated with an asset, remove all asset objects that point to that data from your records. For example, for a record that contains an asset as a field, set the value of the field to
nil. When no asset objects refer to the data, the server lazily deletes the asset data at some point in the future. (Exactly when is not specified, but assume at least several days.)