A coordinator that associates persistent stores with a model (or a configuration of a model) and that mediates between the persistent stores and the managed object contexts.


Instances of NSManagedObjectContext use a coordinator to save object graphs to persistent storage and to retrieve model information. A context without a coordinator is not fully functional as it cannot access a model except through a coordinator. The coordinator is designed to present a façade to the managed object contexts such that a group of persistent stores appears as an aggregate store. A managed object context can then create an object graph based on the union of all the data stores the coordinator covers.

Coordinators do the opposite of providing for concurrency—€”they serialize operations. If you want to use multiple threads for different write operations you use multiple coordinators. Note that if multiple threads work directly with a coordinator, they need to lock and unlock it explicitly.

Each coordinator (and thus container) may use different copies, and hence different versions, of a managed object model. This allows you to cleanly deal with file versioning.

The coordinator gives access to its underlying object stores. You can retrieve an object store when you first add one (using addPersistentStore(ofType:configurationName:at:options:)), or by using persistentStore(for:) or persistentStores. This allows you to to determine, for example, whether a store has already been added, or whether two objects come from the same store.

For more details about these tasks, see Using Persistent Stores in Core Data Programming Guide.


Initializing a Coordinator

init(managedObjectModel: NSManagedObjectModel)

Initializes the coordinator with a managed object model.

var managedObjectModel: NSManagedObjectModel

The coordinator’s managed object model.

Specifying Registered Store Types

class var registeredStoreTypes: [String : NSValue]

Returns a dictionary of the registered store types.

class func registerStoreClass(AnyClass, forStoreType: String)

Registers a given NSPersistentStore subclass for a given store type string.

Creating Persistent Stores

class NSPersistentStore

The abstract base class for all Core Data persistent stores.

class NSPersistentStoreDescription

A description object used to create and load a persistent store.

class NSAtomicStore

An abstract superclass that you subclass to create a Core Data atomic store.

class NSAtomicStoreCacheNode

A concrete class that you use to represent basic nodes in a Core Data atomic store.

class NSIncrementalStore

An abstract superclass defining the API through which Core Data communicates with a store.

class NSPersistentStoreRequest

Criteria used to retrieve data from or save data to a persistent store.

class NSPersistentStoreResult

The abstract base class for results returned from a persistent store coordinator.

class NSPersistentStoreAsynchronousResult

A concrete class used to represent the results of an asynchronous request.

class NSIncrementalStoreNode

A concrete class used to represent basic nodes in a Core Data incremental store.

class NSSaveChangesRequest

An encapsulation of a collection of changes to be made by an object store in response to a save operation on a managed object context.

Configuring Persistent Stores

func addPersistentStore(ofType: String, configurationName: String?, at: URL?, options: [AnyHashable : Any]? = nil)

Adds a new persistent store of a specified type at a given location, and returns the new store.

func setURL(URL, for: NSPersistentStore)

Sets the URL for a given persistent store.

func remove(NSPersistentStore)

Removes a given persistent store.

func destroyPersistentStore(at: URL, ofType: String, options: [AnyHashable : Any]? = nil)

Deletes (or truncates) the target persistent store in accordance with the store class' requirements.

func migratePersistentStore(NSPersistentStore, to: URL, options: [AnyHashable : Any]? = nil, withType: String)

Moves a persistent store to a new location, changing the storage type if necessary.

var persistentStores: [NSPersistentStore]

The persistent stores associated with the coordinator.

func persistentStore(for: URL)

Returns the persistent store for the specified URL.

func url(for: NSPersistentStore)

Returns the URL for a given persistent store.

var name: String?

Name of the coordinator.

Persistent Store Types

Persist data through the available store types.

Store Options

Use options dictionary keys to specify store behavior and characteristics.

Adding, Removing, and Deleting Stores

enum NSPersistentStoreRequestType

These constants specify the types of fetch request.

static let NSPersistentStoreCoordinatorStoresDidChange: NSNotification.Name

Posted whenever persistent stores are added to or removed from a persistent store coordinator, or when store UUIDs change.

static let NSPersistentStoreCoordinatorStoresWillChange: NSNotification.Name

Posted before the list of open persistent stores changes.

static let NSPersistentStoreCoordinatorWillRemoveStore: NSNotification.Name

Posted whenever a persistent store is removed from a persistent store coordinator.

Executing Fetch Requests

func execute(NSPersistentStoreRequest, with: NSManagedObjectContext)

Sends a request to all the persistent stores associated with the coordinator.

func perform(() -> Void)

Asynchronously performs the block on the coordinator's queue.

func performAndWait(() -> Void)

Synchronously performs the block on the coordinator's queue.

Migrating and Versioning Stores

Migration Options

Specify migration options in the dictionary of options when you add a persistent store using addPersistentStore(ofType:configurationName:at:options:).

Versioning Support

Metadata keys you access when comparing store versions.

Working with Metadata

func metadata(for: NSPersistentStore)

Returns a dictionary that contains the metadata currently stored and that will be stored in a given persistent store.

func setMetadata([String : Any]?, for: NSPersistentStore)

Sets the metadata stored in the persistent store during the next save operation executed on it to metadata.

Store Metadata

Use™ metadata dictionary keys to identify the store type and UUID.

Working with Spotlight

class func elementsDerived(fromExternalRecordAt: URL)

Returns a dictionary containing the parsed elements derived from the Spotlight external record file that is specified by the given URL.

Spotlight External Record Elements

Specify values for the parsed elements derived from the Spotlight external record file.

Discovering Object IDs

func managedObjectID(forURIRepresentation: URL)

Returns an object ID for the specified URI representation of an object ID if a matching store is available, or nil if a matching store cannot be found.


static let NSPersistentStoreDidImportUbiquitousContentChanges: NSNotification.Name

Posted after records are imported from the ubiquitous content store.

enum NSPersistentStoreUbiquitousTransitionType

These constants are used as the value corresponding to the NSPersistentStoreUbiquitousTransitionTypeKey in the user info dictionary of NSPersistentStoreCoordinatorStoresWillChange and NSPersistentStoreCoordinatorStoresDidChange notifications to identify the type of event leading to a change.

class func removeUbiquitousContentAndPersistentStore(at: URL, options: [AnyHashable : Any]? = nil)

Deletes all ubiquitous content for all peers for the persistent store at a given URL and also delete the local store file.

class func metadataForPersistentStore(ofType: String?, at: URL)

Returns a dictionary containing the metadata stored in the persistent store at a given URL.

func unlock()

Relinquishes a previously acquired lock.

func lock()

Attempts to acquire a lock.

func tryLock()

Attempts to acquire a lock.



Inherits From

See Also

Core Data Stack

class NSPersistentContainer

A container that encapsulates the Core Data stack in your application.

class NSManagedObjectContext

An object representing a single object space or scratch pad that you use to fetch, create, and save managed objects.

class NSManagedObjectModel

An object that describes a schema—a collection of entities (data models) that you use in your application.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software