Mac Developer Library

Developer

CoreData Framework Reference NSEntityDescription Class Reference

Options
Deployment Target:

On This Page
Language:

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.

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
  • }

Inheritance


Import Statement


Swift

import CoreData

Objective-C

@import CoreData;

Availability


Available in OS X v10.4 and later.
  • name name Property

    The entity name of the receiver.

    Declaration

    Swift

    var name: String?

    Objective-C

    @property(copy) NSString *name

    Special Considerations

    Setting the name raises an exception if the receiver’s model has been used by an object graph manager.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.4 and later.

  • The managed object model with which the receiver is associated. (read-only)

    Declaration

    Swift

    unowned(unsafe) var managedObjectModel: NSManagedObjectModel { get }

    Objective-C

    @property(readonly, assign) NSManagedObjectModel *managedObjectModel

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.4 and later.

    See Also

    setEntities: (NSManagedObjectModel)
    setEntities:forConfiguration:: (NSManagedObjectModel)

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

    Declaration

    Swift

    var managedObjectClassName: String

    Objective-C

    @property(copy) NSString *managedObjectClassName

    Discussion

    The class specified by name must NSManagedObject or a subclass of NSManagedObject.

    Special Considerations

    Setting the class name raises an exception if the receiver’s model has been used by an object graph manager.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.4 and later.

  • The renaming identifier for the receiver.

    Declaration

    Swift

    var renamingIdentifier: String

    Objective-C

    @property(copy) NSString *renamingIdentifier

    Discussion

    The renaming identifier is used to resolve naming conflicts between models. When creating a mapping model between two managed object models, a source entity and a destination entity that share the same identifier indicate that an entity mapping should be configured to migrate from the source to the destination.

    If you do not set this value, the identifier will return the entity’s name.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.6 and later.

  • abstract abstract Property

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

    Declaration

    Swift

    var abstract: Bool

    Objective-C

    @property(getter=isAbstract) BOOL abstract

    Return Value

    YEStrue if the receiver represents an abstract entity, otherwise NOfalse.

    Discussion

    YEStrue if the receiver represents an abstract entity, otherwise NOfalse. An abstract entity might be Shape, with concrete sub-entities such as Rectangle, Triangle, and Circle.

    Special Considerations

    Setting whether an entity is abstract raises an exception if the receiver’s model has been used by an object graph manager.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.10 and later.

  • userInfo userInfo Property

    The user info dictionary of the receiver.

    Declaration

    Swift

    var userInfo: [NSObject : AnyObject]?

    Objective-C

    @property(nonatomic, strong) NSDictionary *userInfo

    Special Considerations

    Setting the user info dictionary raises an exception if the receiver’s model has been used by an object graph manager.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.4 and later.

  • A dictionary containing the receiver’s sub-entities. (read-only)

    Declaration

    Swift

    var subentitiesByName: [NSObject : AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSDictionary *subentitiesByName

    Return Value

    The keys in the dictionary are the sub-entity names, the corresponding values are instances of NSEntityDescription.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.4 and later.

  • An array containing the sub-entities of the receiver.

    Declaration

    Swift

    var subentities: [AnyObject]

    Objective-C

    @property(strong) NSArray *subentities

    Discussion

    The sub-entities are instances of NSEntityDescription.

    Special Considerations

    Setting the sub-entities raises an exception if the receiver’s model has been used by an object graph manager.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.4 and later.

  • The super-entity of the receiver. (read-only)

    Declaration

    Swift

    unowned(unsafe) var superentity: NSEntityDescription? { get }

    Objective-C

    @property(readonly, assign) NSEntityDescription *superentity

    Discussion

    If the receiver has no super-entity, returns nil.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func isKindOfEntity(_ entity: NSEntityDescription) -> Bool

    Objective-C

    - (BOOL)isKindOfEntity:(NSEntityDescription *)entity

    Parameters

    entity

    An entity.

    Return Value

    YEStrue if the receiver is a sub-entity of entity, otherwise NOfalse.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    class func entityForName(_ entityName: String, inManagedObjectContext context: NSManagedObjectContext) -> NSEntityDescription?

    Objective-C

    + (NSEntityDescription *)entityForName:(NSString *)entityName inManagedObjectContext:(NSManagedObjectContext *)context

    Parameters

    entityName

    The name of an entity.

    context

    The managed object context to use. Must not be nil.

    Return Value

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

    Discussion

    Raises NSInternalInconsistencyException if context is nil.

    This method is functionally equivalent to the following code example.

    • NSManagedObjectModel *managedObjectModel = [[context persistentStoreCoordinator] managedObjectModel];
    • NSEntityDescription *entity = [[managedObjectModel entitiesByName] objectForKey:entityName];
    • return entity;

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.4 and later.

    See Also

    entitiesByName

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

    Declaration

    Swift

    class func insertNewObjectForEntityForName(_ entityName: String, inManagedObjectContext context: NSManagedObjectContext) -> AnyObject

    Objective-C

    + (id)insertNewObjectForEntityForName:(NSString *)entityName inManagedObjectContext:(NSManagedObjectContext *)context

    Parameters

    entityName

    The name of an entity.

    context

    The managed object context to use.

    Return Value

    A new, autoreleased, fully configured instance of the class for the entity named entityName. The instance has its entity description set and is inserted it into context.

    Discussion

    This method makes it easy for you to create instances of a given entity without worrying about the details of managed object creation. The method is conceptually similar to the following code example.

    • NSManagedObjectModel *managedObjectModel =
    • [[context persistentStoreCoordinator] managedObjectModel];
    • NSEntityDescription *entity =
    • [[managedObjectModel entitiesByName] objectForKey:entityName];
    • NSManagedObject *newObject = [[NSManagedObject alloc]
    • initWithEntity:entity insertIntoManagedObjectContext:context];
    • return newObject;

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.4 and later.

  • The version hash for the receiver. (read-only)

    Declaration

    Swift

    @NSCopying var versionHash: NSData { get }

    Objective-C

    @property(readonly, copy) NSData *versionHash

    Discussion

    The version hash is used to uniquely identify an entity based on the collection and configuration of properties for the entity. The version hash uses only values which affect the persistence of data and the user-defined versionHashModifier value. (The values which affect persistence are: the name of the entity, the version hash of the superentity (if present), if the entity is abstract, and all of the version hashes for the properties.) This value is stored as part of the version information in the metadata for stores which use this entity, as well as a definition of an entity involved in an NSEntityMapping object.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • The version hash modifier for the receiver.

    Declaration

    Swift

    var versionHashModifier: String?

    Objective-C

    @property(copy) NSString *versionHashModifier

    Discussion

    This value is included in the version hash for the entity. You use it to mark or denote an entity as being a different “version” than another even if all of the values which affect persistence are equal. (Such a difference is important in cases where, for example, the structure of an entity is unchanged but the format or content of data has changed.)

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.5 and later.

    See Also

    – versionHash

  • Returns a copy of the receiver

    Declaration

    Objective-C

    - (id)copy

    Return Value

    A copy of the receiver.

    Special Considerations

    NSEntityDescription’€˜s implementation of copy returns an entity such that:

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

    You should not, therefore, use an entity as a key in a dictionary (see Using Entity Descriptions in Dictionaries).

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

    Declaration

    Swift

    var compoundIndexes: [AnyObject]?

    Objective-C

    @property(strong) NSArray *compoundIndexes

    Discussion

    The arrays contained in the returned array contain instances of NSAttributeDescription, NSRelationshipDescription that represent properties of the entity, or of NSString that match the name of attributes or relationships of the entity.

    Compound indexes are only used by stores that natively support compound indices—setting them is only advisory. Indexes apply to the entire inheritance hierarchy.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.7 and later.