Contents

EntityCollection

An array of entity identifiers that you use to improve the efficiency of operations involving large numbers of entities.

Declaration

struct EntityCollection<Entity> where Entity : AppEntity

Mentioned in

Overview

Use an EntityCollection type to manage large numbers of entities in an app intent or app entity. An entity collection stores the identifier for each entity initially and provides an option to fetch the entire AppEntity instances later if needed. Storing only the identifiers initially can save memory and speed up operations that don’t require the entire entity instance.

If you need to store the identifiers for multiple entities, use EntityCollection as the type of your variable. If you use an EntityCollection for a parameter in an app intent, the system doesn’t force the resolution of each identifier to the full AppEntity instance during parameter resolution. For a parameter that contains hundreds of entities, not resolving each identifier can save time and memory at a potentially critical moment.

The following example shows the use of an EntityCollection in an app intent to disable multiple alarms. Because the code to disable the alarms requires only the identifier for each entity, the type stores those values using an entity collection.

struct DisableAlarmsIntent: AppIntent {
    static var title: LocalizedStringResource = "Disable Alarms"

    @Parameter(title: "Alarms")
    var alarms: EntityCollection<AlarmEntity>

    func perform() async throws -> some IntentResult {
        // Use the identifiers in the database query without hydration.
        try await AlarmService.disable(alarms.identifiers)

        return .result()
    }
}

When you need more than just entity identifiers, you can call resolvedEntities() to generate the AppEntity instances for each identifier. The method uses your app’s query types to find or create the corresponding entity instances. After retrieving the entities, the entity collection caches those instances for future access.

Topics

Initializers

Instance Properties

Instance Methods

Type Aliases

Type Properties