Overview

You can create Spotlight indexes where each record is indexed individually. This feature is only supported in non-document-based applications. For document-based applications, you should use store metadata as described in Store Metadata-Level Indexing.

In this approach, Core Data manages a directory in the Library/Caches/Metadata/Core Data/ in a user’s home directory (the structure of this directory is private—don’t depend on it). For each separate program, Core Data creates a subdirectory; within each subdirectory Core Data creates a further subdirectory for each persistent store used by the program. Within the directory for a given store, for each instance of each entity that you choose to index, Core Data creates a new external record file. The external record files are used by Spotlight to index the persistent store.

There are three processes involved in creating and maintaining the Spotlight index:

• Your program.

  Within your program, the Core Data framework maintains the persistent store and creates the external record files to trigger the spotlight indexing

• The Spotlight importer.

  The importer does the actual indexing. It is launched whenever an external record changes.

  You have to write and maintain the importer; for every external record, it needs to add suitable data to the Spotlight index. This is in many respects the most important part of developing the importer.

• Core Data External Record daemon.

  This is a secondary process used by the Core Data framework. It is used to improve performance if you modify a large number of records (more than a hundred or so) at the same time. In this situation, Core Data writes a single work file which the external daemon subsequently unpacks to create individual external records.

The main purpose of the external record file is simply to serve as a pointer to a record (an instance of an entity) in a persistent store. In the importer, you fetch a corresponding managed object from your application’s persistent store and use it to update the Spotlight index.

Provided that at least one property for an entity is specified as being indexed (see Configuring the Model), then whenever a change to an instance of that entity is committed to the persistent store, the corresponding external record file is updated (minimally the last modification date changed). The external record file may be empty (a zero-length file), however you can also, optionally, specify properties whose values Core Data should store in the file. The importer does not use any data you may have specified should be stored in the external record itself (to understand how you might use it, see Using External Records).

Creating the Project

When you create a new project with Xcode, choose a non-document-based application that uses Core Data for storage and has Spotlight Indexing (“Core Data Application with Spotlight Importer”). The Xcode template adds the Importer files and creates a build target for the importer. There are then two targets that you have to manage—the application and the importer. They both share a common managed object model.

Configuring the Model

To enable Spotlight indexing, you need to specify which properties of which entities should be indexed and which—if any—of those properties should be added to the external record.

In Configuration inspector, for each of the properties that you want to be indexed, select:

• Index in Spotlight

• (Optional) Store in external record file

Provided that at least one property for an entity has the “Index in Spotlight” flag set, then whenever a change to an instance of that entity is committed to the persistent store, the corresponding external record file is updated (minimally the last modification date changed). This means that the Spotlight importer will run and so the Spotlight index will be updated with new data.

If you only choose “Index in Spotlight,” Core Data just creates a zero-length file for the corresponding record. If you also select “Store in External Record”, the property is added to the contents of the external record. Simple types, such as strings, dates, and numbers, are exported directly; relationships are stored as UUIDs.

The importer does not itself use any data you may have specified should be stored in the external record. You may, however, want to use the external records yourself, for example for error recovery or to assist debugging—see Using External Records. Unless you do, though, to avoid the overhead of duplicating data and taking up space on disk, you should not choose to store property values in the external record.

Configuring your Program

There are several options you can set for the store to specify where the external records should be stored, the extension for the external record file names, and the format in which the external records should be written:

NSExternalRecordsDirectoryOption

This constant specifies the directory URL where the external records are stored.

You must specify a directory in the user’s Library/Caches/Metadata/CoreData or Library/CoreData directory. You must use this in conjunction with the NSExternalRecordsExtensionOption option.

NSExternalRecordExtensionOption

This constant specifies the extension used for the external record files.

You must use this in conjunction with the NSExternalRecordsDirectoryOption option.

NSExternalRecordsFileFormatOption

This constant specifies the file format to use when writing external records.

The default is to write the records as XML (NSXMLExternalRecordType)—this is a good choice if you want a human-readable format, or want to be able to share content with other applications. Otherwise you should typically use the binary format (NSBinaryExternalRecordType).

You set these options when you configure the persistent store coordinator, as shown in the following example:

NSString *externalRecordsSupportFolder = <#Path for records folder#>;

NSURL *storeURL = <#URL for the store#>;

NSMutableDictionary *storeOptions = @{

    NSExternalRecordExtensionOption:@"MyExtension",

    NSExternalRecordsDirectoryOption:externalRecordsSupportFolder,

    NSExternalRecordsFileFormatOption:NSBinaryExternalRecordType};

NSPersistentStoreCoordinator *aPSC = <#Get the coordinator#>;.

if (![aPSC addPersistentStoreWithType:NSSQLiteStoreType configuration:nil URL:storeURL

           options:storeOptions error:&error]) {

    [[NSApplication sharedApplication] presentError:error];

}

Implementing the Importer

This section describes primarily the features of an importer that are unique to Core Data. To understand the fundamentals of how to implement a Spotlight importer, you should read Spotlight Importer Programming Guide. Note also that most of the configuration and implementation details are discussed in the Importer ReadMe file and provided as comments in the templates.

Broadly speaking, there are two aspects to implementing the importer: configuring the project settings, for example, the file extension for your external record type; and customizing the method that adds data from a record to the Spotlight index. The latter aspect is probably the most important aspect of the task.

- (BOOL)importFileAtPath:(NSString *)filePath attributes:(NSMutableDictionary *)spotlightData error:(NSError **)error

NSDictionary *pathInfo = [NSPersistentStoreCoordinator elementsDerivedFromExternalRecordURL:[NSURL fileURLWithPath:filePath]];

self.modelURL = [NSURL fileURLWithPath:[pathInfo valueForKey:NSModelPathKey]];

self.storeURL = [NSURL fileURLWithPath:[pathInfo valueForKey:NSStorePathKey]];

NSURL *objectURI = [pathInfo valueForKey:NSObjectURIKey];

NSManagedObject *instance = [[self managedObjectContext] objectWithID:oid];

NSString *displayString = <#Create a display string from a managed object#>;

[spotlightData setObject:displayString forKey:(__bridge id<NSCopying>)kMDItemDisplayName];

- (BOOL)import<EntityName>:(EntityClass *)instance

                attributes:(NSMutableDictionary *)spotlightData

- (BOOL)importFileAtPath:(NSString *)filePath attributes:(NSMutableDictionary *)spotlightData error:(NSError **)error {

    NSDictionary *pathInfo =

        [NSPersistentStoreCoordinator elementsDerivedFromExternalRecordURL:

                                            [NSURL fileURLWithPath:filePath]];

    NSString *entityName = [pathInfo objectForKey:NSEntityNameInPathKey];

    self.modelURL = [NSURL fileURLWithPath:[pathInfo valueForKey:NSModelPathKey]];

    self.storeURL = [NSURL fileURLWithPath:[pathInfo valueForKey:NSStorePathKey]];

    NSURL  *objectURI = [pathInfo valueForKey:NSObjectURIKey];

    NSManagedObjectID *oid =

        [[self persistentStoreCoordinator] managedObjectIDForURIRepresentation:objectURI];

    if (!oid) {

        NSLog(@"%@:%s to find object id from path %@", [self class], _cmd, filePath);

        return NO;

    }

    /*

     Create and invoke an NSInvocation object that sends a message to self where:

         The selector follows the format import<EntityName>:attributes:

         The return value is a BOOL.

    */

    NSString *importSelectorString =

        [NSString stringWithFormat:@"import%@:attributes:", entityName];

    SEL importSelector = NSSelectorFromString(importSelectorString);

    if (![self respondsToSelector:importSelector]) {

        NSLog(@"%@:%s Couldn't import an instance of entity %@",

            [self class], _cmd, entityName);

        return NO;

    }

    NSManagedObject *instance = [[self managedObjectContext] objectWithID:oid];

    NSMethodSignature *methodSignature = [self methodSignatureForSelector:importSelector];

    NSInvocation *invocation =

        [NSInvocation invocationWithMethodSignature:methodSignature];

    [invocation setTarget:self];

    [invocation setSelector:importSelector];

    [invocation setArgument:&instance atIndex:2];

    [invocation setArgument:&spotlightData atIndex:3];

    BOOL returnValue;

    [invocation invoke];

    [invocation getReturnValue:&returnValue];

    return returnValue;

}

- (BOOL)importPerson:(Person *)person attributes:(NSMutableDictionary *)spotlightData {

    // Set the display name for Spotlight search results.

    [spotlightData setObject:[person fullName] forKey:(__bridge id<NSCopying>)kMDItemDisplayName];

    NSDate *dob = person.dateOfBirth;

    if (dob != nil) {

        [spotlightData setObject:dob forKey:(__bridge id<NSCopying>)kMDItemTimestamp];

    }

    NSMutableString *text = [NSMutableString stringWithFormat:@"%@", [person fullName]];

    for (NSManagedObject *address in person.addresses) {

        NSString *component;

        component = [address street1];

        if (component) {

            [text appendFormat:@" %@", component];

        }

        component = [address city];

        if (component) {

            [text appendFormat:@" %@", component];

        }

        component = [address state];

        if (component) {

            [text appendFormat:@" %@", component];

        }

        component = [address zip];

        if (component) {

            [text appendFormat:@" %@", component];

        }

    }

    [spotlightData setObject:text forKey:(__bridge id<NSCopying>)kMDItemTextContent];

    return YES;

}

Opening an External Record

The final aspect of supporting Spotlight integration is to display the appropriate record when the user makes a selection after a Spotlight search. You have to implement the application delegate method application:openFiles: to respond to an open file request for an external record:

- (void)application:(NSApplication *)theApplication openFiles:(NSArray *)files {

    NSString *aPath = [files lastObject]; // Just an example to get at one of the paths.

    if (aPath && [aPath hasSuffix:YOUR_EXTERNAL_RECORD_EXTENSION]) {

        // Decode URI from path.

        NSURL *objectURI = [[NSPersistentStoreCoordinator elementsDerivedFromExternalRecordURL:[NSURL fileURLWithPath:aPath]] objectForKey:NSObjectURIKey];

        if (objectURI) {

            NSManagedObjectID *moid = [[self persistentStoreCoordinator] managedObjectIDForURIRepresentation:objectURI];

            if (moid) {

                    NSManagedObject *mo = [[self managedObjectContext] objectWithID:moid];

                    // Your code to select the object in your application's UI.

            }

        }

    }

}

The template shows how to identify the managed object that the user selected. How you then ensure that this object is displayed in the user interface is dependent entirely upon your application architecture and the schema in your managed object model.

Using External Records

The importer does not use any data you may have specified should be stored in the external record itself (see Overview). In other programs, however, you can use the following NSPersistentStoreCoordinator methods to interact with external records:

• elementsDerivedFromExternalRecordURL: is a class method that takes a URL to an external record file and returns a dictionary with the derived elements such as the name of the entity and the URI for the managed object instance.

• importStoreWithIdentifier:fromExternalRecordsDirectory:toURL:options:withType:error: creates and populates a new store using external records found at a specified location.

In some circumstances, therefore, you could use the external record for example for error recovery or to recreate a store that has somehow become corrupted. You might also use the XML representation to allow data exchange with other programs. It’s up to you to decide what information might be useful and in what situations you might use this data, and so which properties of which entities you want to include in the external record.

The structure of the external records directory is not guaranteed to remain constant between releases of the operating system. You can, though, regardless of their layout, simply iterate through the external records directories (for example, using NSFileManager’s enumeratorAtPath:) to retrieve all the files whose path extension is that which you specified for your external records.

You can also use the external records as a diagnostic when you are developing your program and the importer. You can ensure that the correct information is being added to the records, and that they’re being updated when you expect them to be—although note the caveat in Why aren’t my records in sync?.

Troubleshooting

Many hints for troubleshooting are given in the Spotlight Importer Programming Guide. In particular, you can test your importer using /usr/bin/mdimport, as illustrated by this example:

/usr/bin/mdimport -d2 ~/Library/Caches/Metadata/CoreData/$ApplicationName/$StoreID/$Entity/$fileName

// Clear out all custom classes used by the model to avoid having to link them

// with the importer. Remove this code if you need to access your custom logic.

NSString *managedObjectClassName = [NSManagedObject className];

for (NSEntityDescription *entity in managedObjectModel) {

    if (![[entity name] isEqualToString:@"Person"]) {

        [entity setManagedObjectClassName:managedObjectClassName];

    }

}

FAQ