Class

NSManagedObjectModel

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

Overview

The model contains one or more NSEntityDescription objects representing the entities in the schema. Each NSEntityDescription object has property description objects (instances of subclasses of NSPropertyDescription) that represent the properties (or fields) of the entity in the schema. The Core Data framework uses this description in several ways:

  • Constraining UI creation in Interface Builder

  • Validating attribute and relationship values at runtime

  • Mapping between your managed objects and a database or file-based schema for object persistence.

A managed object model maintains a mapping between each of its entity objects and a corresponding managed object class for use with the persistent storage mechanisms in the Core Data Framework. You can determine the entity for a particular managed object with the entity method.

You typically create managed object models using the data modeling tool in Xcode, but it is possible to build a model programmatically if needed.

Loading a Model File

Managed object model files are typically stored in a project or a framework. To load a model, you provide an URL to the constructor. Note that loading a model doesn’t have the effect of loading all of its entities.

Stored Fetch Requests

It is often the case that in your application you want to get hold of a collection of objects that share features in common. Sometimes you can define those features (property values) in advance; sometimes you need to be able to supply values at runtime. For example, you might want to be able to retrieve all movies owned by Pixar; alternatively you might want to be able to retrieve all movies that earned more than an amount specified by the user at runtime.

Fetch requests are often predefined in a managed object model as templates. They allow you to pre-define named queries and their parameters in the model. Typically they contain variables that need to be substituted at runtime. NSManagedObjectModel provides API to retrieve a stored fetch request by name, and to perform variable substitution—see fetchRequestTemplate(forName:) and fetchRequestFromTemplate(withName:substitutionVariables:). You can create fetch request templates programmatically, and associate them with a model using setFetchRequestTemplate(_:forName:); typically, however, you define them using the Xcode design tool.

Configurations

Sometimes a model—particularly one in a framework—may be used in different situations, and you may want to specify different sets of entities to be used in different situations. There might, for example, be certain entities that should only be available if a user has administrative privileges. To support this requirement, a model may have more than one configuration. Each configuration is named, and has an associated set of entities. The sets may overlap. You establish configurations programmatically using setEntities(_:forConfigurationName:) or using the Xcode design tool, and retrieve the entities for a given configuration name using entities(forConfigurationName:).

Changing Models

Since a model describes the structure of the data in a persistent store, changing any parts of a model that alters the schema renders it incompatible with (and so unable to open) the stores it previously created. If you change your schema, you therefore need to migrate the data in existing stores to new version (see Core Data Model Versioning and Data Migration Programming Guide). For example, if you add a new entity or a new attribute to an existing entity, you will not be able to open old stores; if you add a validation constraint or set a new default value for an attribute, you will be able to open old stores.

Editing Models Programmatically

Managed object models are editable until they are used by an object graph manager (a managed object context or a persistent store coordinator). This allows you to create or modify them dynamically. However, once a model is being used, it must not be changed. This is enforced at runtime—when the object manager first fetches data using a model, the whole of that model becomes uneditable. Any attempt to mutate a model or any of its sub-objects after that point causes an exception to be thrown. If you need to modify a model that is in use, create a copy, modify the copy, and then discard the objects with the old model.

Fast Enumeration

In macOS 10.5 and later and on iOS, NSManagedObjectModel supports the NSFastEnumeration protocol. You can use this to enumerate over a model’s entities, as illustrated in the following example:

NSManagedObjectModel *aModel = ...;
for (NSEntityDescription *entity in aModel) {
    // entity is each instance of NSEntityDescription in aModel in turn
}

Topics

Initializing a Model

init?(contentsOf: URL)

Initializes the managed object model using the model file at the specified URL.

init()

Initializes an empty managed object model.

class func mergedModel(from: [Bundle]?)

Returns a model created by merging all the models found in given bundles.

class func mergedModel(from: [Bundle]?, forStoreMetadata: [String : Any])

Returns a merged model from a specified array for the version information in provided metadata.

init?(byMerging: [NSManagedObjectModel]?)

Creates a single model from an array of existing models.

init?(byMerging: [NSManagedObjectModel], forStoreMetadata: [String : Any])

Returns, for the version information in given metadata, a model merged from a given array of models.

Inspecting Entities and Configurations

var entities: [NSEntityDescription]

The entities in the model.

var entitiesByName: [String : NSEntityDescription]

The entities of the model, keyed by name.

var configurations: [String]

All the available configuration names of the model.

func entities(forConfigurationName: String?)

Returns the entities of the model for a specified configuration.

func setEntities([NSEntityDescription], forConfigurationName: String)

Associates the specified entities with the model using the given configuration name.

class NSEntityDescription

A description of an entity in Core Data.

class NSAttributeDescription

A description of the attributes of an entity described by an instance of NSEntityDescription.

class NSManagedObjectID

A compact, universal identifier for a managed object.

class NSPropertyDescription

A description of the properties of an entity in a Core Data managed object model.

class NSRelationshipDescription

A description of the relationships of an entity in an NSEntityDescription object.

Getting Fetch Request Templates

var fetchRequestTemplatesByName: [String : NSFetchRequest<NSFetchRequestResult>]

A dictionary of the receiver’s fetch request templates, keyed by name.

func fetchRequestTemplate(forName: String)

Returns the fetch request with a specified name.

func fetchRequestFromTemplate(withName: String, substitutionVariables: [String : Any])

Returns a copy of the fetch request template with the variables substituted by values from the substitutions dictionary.

func setFetchRequestTemplate(NSFetchRequest<NSFetchRequestResult>?, forName: String)

Associates the specified fetch request with the receiver using the given name.

Managing Localization

var localizationDictionary: [String : String]?

The localization dictionary of the model.

Handing Versions and Migration

func isConfiguration(withName: String?, compatibleWithStoreMetadata: [String : Any])

Returns a Boolean value that indicates whether a given configuration in the model is compatible with given metadata from a persistent store.

var entityVersionHashesByName: [String : Data]

A dictionary of the version hashes for the entities in the model, keyed by entity name.

var versionIdentifiers: Set<AnyHashable>

The set of developer-defined version identifiers for the model.

Working with Indexes

enum NSFetchIndexElementType

Defines the possible types of index elements.

Beta
class NSFetchIndexDescription

The description of the index.

Beta
class NSFetchIndexElementDescription

Description of an Index Element

Beta

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 NSPersistentStoreCoordinator

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.

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