Class

NSEntityDescription

An NSEntityDescription object describes an entity in Core Data. Entities are to managed objects what Class is to id, or—to use a database analogy—what tables are to rows. An instance specifies an entity’s name, its properties (its attributes and relationships, expressed by instances of NSAttributeDescription and NSRelationshipDescription) and the class by which it is represented.

Overview

An NSEntityDescription object is associated with a specific class whose instances are used to represent entries in a persistent store in applications using the Core Data Framework. Minimally, an entity description should have:

  • A name

  • The name of a managed object class

    (If an entity has no managed object class name, it defaults to NSManagedObject.)

You usually define entities in a Managed object modelusing the data modeling tool in Xcode. NSEntityDescription objects are primarily used by the Core Data Framework for mapping entries in the persistent store to managed objects in the application. You are not likely to interact with them directly unless you are specifically working with models. Like the other major modeling classes, NSEntityDescription provides you with a user dictionary in which you can store any application-specific information related to the entity.

Editing Entity Descriptions

Entity descriptions are editable until they are used by an object graph manager. This allows you to create or modify them dynamically. However, once a description is used (when the managed object model to which it belongs is associated with a persistent store coordinator), it must not (indeed cannot) be changed. This is enforced at runtime: any attempt to mutate a model or any of its sub-objects after the model is associated with a persistent store coordinator 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.

If you want to create an entity hierarchy, you need to consider the relevant API. You can only set an entity’s sub-entities (see subentities), you cannot set an entity’s super-entity directly. To set a super-entity for a given entity, you must therefore set an array of subentities on that super entity and include the current entity in that array. So, the entity hierarchy needs to be built top-down.

Using Entity Descriptions in Dictionaries

NSEntityDescription’s copy method returns an entity such that

[[entity copy] isEqual:entity] == NO

Since NSDictionary copies its keys and requires that keys both conform to the NSCopying protocol and have the property that copy returns an object for which [[object copy] isEqual:object] is true, you should not use entities as keys in a dictionary. Instead, you should either use the entity’s name as the key, or use a map table (NSMapTable) with retain callbacks.

Fast Enumeration

NSEntityDescription supports the NSFastEnumeration protocol. You can use this to enumerate over an entity’s properties, as illustrated in the following example:

NSEntityDescription *anEntity = ...;
for (NSPropertyDescription *property in anEntity) {
    // property is each instance of NSPropertyDescription in anEntity in turn
}

Symbols

Information About an Entity Description

var name: String?

The entity name of the receiver.

var managedObjectModel: NSManagedObjectModel

The managed object model with which the receiver is associated.

var managedObjectClassName: String!

The name of the class that represents the receiver’s entity.

var renamingIdentifier: String?

The renaming identifier for the receiver.

var isAbstract: Bool

A Boolean value that indicates whether the receiver represents an abstract entity.

var userInfo: [AnyHashable : Any]?

The user info dictionary of the receiver.

Managing Inheritance

var subentitiesByName: [String : NSEntityDescription]

A dictionary containing the receiver’s sub-entities.

var subentities: [NSEntityDescription]

An array containing the sub-entities of the receiver.

var superentity: NSEntityDescription?

The super-entity of the receiver.

func isKindOf(entity: NSEntityDescription)

Returns a Boolean value that indicates whether the receiver is a sub-entity of another given entity.

Working with Properties

var propertiesByName: [String : NSPropertyDescription]

A dictionary containing the properties of the receiver.

var properties: [NSPropertyDescription]

An array containing the properties of the receiver.

var attributesByName: [String : NSAttributeDescription]

The attributes of the receiver in a dictionary.

var relationshipsByName: [String : NSRelationshipDescription]

The relationships of the receiver in a dictionary.

func relationships(forDestination: NSEntityDescription)

Returns an array containing the relationships of the receiver where the entity description of the relationship is a given entity.

Retrieving an Entity with a Given Name

class func entity(forEntityName: String, in: NSManagedObjectContext)

Returns the entity with the specified name from the managed object model associated with the specified managed object context’s persistent store coordinator.

Creating a New Managed Object

class func insertNewObject(forEntityName: String, into: NSManagedObjectContext)

Creates, configures, and returns an instance of the class for the entity with a given name.

Managing Versioning Support

var versionHash: Data

The version hash for the receiver.

var versionHashModifier: String?

The version hash modifier for the receiver.

Managing Compound Indexes

var compoundIndexes: [[Any]]

The compound indexes for the entity as an array of arrays.