Spotlight Semantic Indexing: Integrating App Entities with Apple Intelligence

With the expansion of Apple Intelligence, the system search index (Spotlight) does more than match keyword substrings. It performs semantic indexing across local app data. If your app models data (like documents, messages, or transaction records) as App Entities, configuring them for Spotlight indexing allows Siri, Spotlight, and smart suggestions to surface your app’s content contextually.

To expose these entities to the system’s semantic index, you bridge your AppEntity types to the CoreSpotlight database. This ensures they are indexed locally on the device.

---

Implementing the CSSearchableItem Attribute Map

To index an App Entity, you map its attributes to a CSSearchableItem representation using the CSSearchableItemAttributeSet class. This defines metadata like titles, descriptions, content tags, and local file URLs.

import AppIntents
import CoreSpotlight
import MobileCoreServices

struct RecipeEntity: AppEntity {
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Recipe"
    
    let id: UUID
    let title: String
    let prepTimeMinutes: Int
    let keywords: [String]
    
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(title)")
    }
    
    // Developer Thoughts: CoreSpotlight indexing runs asynchronously.
    // We construct the search attribute metadata using standard content types.
    func makeSearchableItem() -> CSSearchableItem {
        let attributeSet = CSSearchableItemAttributeSet(contentType: .recipe)
        attributeSet.title = title
        attributeSet.duration = NSDecimalNumber(value: prepTimeMinutes)
        attributeSet.keywords = keywords
        
        return CSSearchableItem(
            uniqueIdentifier: id.uuidString,
            domainIdentifier: "com.example.recipes.recipe",
            attributeSet: attributeSet
        )
    }
}

---

Managing the Search Index Lifecycle

Once your search items are defined, you commit them to the indexing system using CSSearchableIndex.default().

class RecipeIndexManager {
    private let index = CSSearchableIndex.default()
    
    func indexRecipes(_ recipes: [RecipeEntity]) async throws {
        let items = recipes.map { $0.makeSearchableItem() }
        
        // Developer Thoughts: Indexing operations are batch-committed.
        // If a recipe is deleted locally, you must call deleteSearchableItems 
        // to prevent stale search results from appearing in Spotlight.
        try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
            index.indexSearchableItems(items) { error in
                if let error = error {
                    continuation.resume(throwing: error)
                } else {
                    continuation.resume()
                }
            }
        }
    }
}

---

Summary

Integrating your AppEntity types with the Spotlight index makes your app’s content discoverable through system search interfaces. This setup helps users find your content quickly and increases engagement. Keep in mind that search metadata is processed locally on the device; index updates should be batched to minimize power consumption.