Next Page > Hide TOC

NSFetchRequest Class Reference

Overview

The NSFetchRequest class is used to describe search criteria used to retrieve data from a persistent store.

An instance collects the criteria needed to select and—optionally—order a group of persistent objects, whether from a repository such as a file or an in-memory store such as an managed object context. A fetch request contains the following elements:

• An entity description (an instance of NSEntityDescription) that specifies which entity to search, and hence what type of object (if any) will be returned. This is the only mandatory element.

• A predicate (an instance of NSPredicate) that specifies which properties to select by and the constraints on selection, for example “last name begins with ‘J’.” If you don’t specify a predicate, then all instances of the specified entity are selected (subject to other constraints, see executeFetchRequest:error: for full details).

• An array of sort descriptors (instances of NSSortDescriptor) that specify how the returned objects should be ordered, for example by last name then by first name.

You can also specify other aspects of a fetch request—the maximum number of objects that a request should return, and which data stores the request should access. With Mac OS X v10.5 and later you can also specify, for example, whether the fetch returns managed objects or just object IDs, and whether objects are fully populated with their properties (see resultType, includesSubentities, includesPropertyValues, and returnsObjectsAsFaults).

You use NSFetchRequest objects with the method executeFetchRequest:error:, defined by NSManagedObjectContext.

You often predefine fetch requests in a managed object model—NSManagedObjectModel provides API to retrieve a stored fetch request by name. Stored fetch requests can include placeholders for variable substitution, and so serve as templates for later completion. Fetch request templates therefore allow you to pre-define queries with variables that are substituted at runtime.

Tasks

Entity

• – entity
• – setEntity:
• – includesSubentities
• – setIncludesSubentities:

Fetch Constraints

• – predicate
• – setPredicate:
• – fetchLimit
• – setFetchLimit:
• – affectedStores
• – setAffectedStores:

Sorting

• – sortDescriptors
• – setSortDescriptors:

Prefetching

• – relationshipKeyPathsForPrefetching
• – setRelationshipKeyPathsForPrefetching:

Managing How Results Are Returned

• – resultType
• – setResultType:
• – includesPropertyValues
• – setIncludesPropertyValues:
• – returnsObjectsAsFaults
• – setReturnsObjectsAsFaults:

Instance Methods

affectedStores

Returns an array containing the persistent stores specified for the receiver.

- (NSArray *)affectedStores

Return Value

An array containing the persistent stores specified for the receiver.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setAffectedStores:

Related Sample Code

• CoreRecipes

Declared In

entity

Returns the entity specified for the receiver.

- (NSEntityDescription *)entity

Return Value

The entity specified for the receiver.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setEntity:

Declared In

fetchLimit

Returns the fetch limit of the receiver.

- (NSUInteger)fetchLimit

Return Value

The fetch limit of the receiver.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setFetchLimit:

Declared In

includesPropertyValues

Returns a Boolean value that indicates whether, when the fetch is executed, property data is obtained from the persistent store.

- (BOOL)includesPropertyValues

Return Value

YES if, when the fetch is executed, property data is obtained from the persistent store, otherwise NO.

Discussion

The default value is YES.

You can set includesPropertyValues to NO to reduce memory overhead by avoiding creation of objects to represent the property values. You should typically only do so, however, if you are sure that either you will not need the actual property data or you already have the information in the row cache, otherwise you will incur multiple trips to the database.

During a normal fetch (includesPropertyValues is YES), Core Data fetches the object ID and property data for the matching records, fills the row cache with the information, and returns managed object as faults (see returnsObjectsAsFaults). These faults are managed objects, but all of their property data still resides in the row cache until the fault is fired. When the fault is fired, Core Data retrieves the data from the row cache—there is no need to go back to the database.

If includesPropertyValues is NO, then Core Data fetches only the object ID information for the matching records—it does not populate the row cache. Core Data still returns managed objects since it only needs managed object IDs to create faults. However, if you subsequently fire the fault, Core Data looks in the (empty) row cache, doesn't find any data, and then goes back to the store a second time for the data.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setIncludesPropertyValues:

Declared In

includesSubentities

Returns a Boolean value that indicates whether the receiver includes subentities in the results.

- (BOOL)includesSubentities

Return Value

YES if the request will include all subentities of the entity for the request, otherwise NO.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setIncludesSubentities:

Declared In

predicate

Returns the predicate of the receiver.

- (NSPredicate *)predicate

Return Value

The predicate of the receiver.

Discussion

The predicate is used to constrain the selection of objects the receiver is to fetch. For more about predicates, see Predicates Programming Guide.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setPredicate:

Declared In

relationshipKeyPathsForPrefetching

Returns the array of relationship keypaths to prefetch along with the entity for the request.

- (NSArray *)relationshipKeyPathsForPrefetching

Return Value

The array of relationship keypaths to prefetch along with the entity for the request.

Discussion

The default value is an empty array (no prefetching).

Prefetching allows Core Data to obtain related objects in a single fetch (per entity), rather than incurring subsequent access to the store for each individual record as their faults are tripped. For example, given an Employee entity with a relationship to a Department entity, if you fetch all the employees then for each print out their name and the name of the department to which they belong, it may be that a fault has to be fired for each individual Department object (for more details, see Core Data Performance in Core Data Programming Guide). This can represent a significant overhead. You could avoid this by prefetching the department relationship in the Employee fetch, as illustrated in the following example:

NSManagedObjectContext *context = ...;

NSEntityDescription *employeeEntity = [NSEntityDescription

    entityForName:@"Employee" inManagedObjectContext:context];

NSFetchRequest *request = [[NSFetchRequest alloc] init];

[request setEntity:employeeEntity];

[request setRelationshipKeyPathsForPrefetching:

    [NSArray arrayWithObject:@"department"]];

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setRelationshipKeyPathsForPrefetching:

Declared In

resultType

Returns the result type of the receiver.

- (NSFetchRequestResultType)resultType

Return Value

The result type of the receiver.

Discussion

The default value is NSManagedObjectResultType.

You use setResultType: to set the instance type of objects returned from executing the request—for possible values, see “Fetch request result types.” If you set the value to NSManagedObjectIDResultType, this will demote any sort orderings to “best effort” hints if you do not include the property values in the request.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setResultType:

Declared In

returnsObjectsAsFaults

Returns a Boolean value that indicates whether the objects resulting from a fetch using the receiver are faults.

- (BOOL)returnsObjectsAsFaults

Return Value

YES if the objects resulting from a fetch using the receiver are faults, otherwise NO.

Discussion

The default value is YES. This setting is not used if the result type (see resultType) is NSManagedObjectIDResultType, as object IDs do not have property values. You can set returnsObjectsAsFaults to NO to gain a performance benefit if you know you will need to access the property values from the returned objects.

By default, when you execute a fetch returnsObjectsAsFaults is YES; Core Data fetches the object data for the matching records, fills the row cache with the information, and returns managed object as faults. These faults are managed objects, but all of their property data resides in the row cache until the fault is fired. When the fault is fired, Core Data retrieves the data from the row cache. Although the overhead for this operation is small for large datasets it may become non-trivial. If you need to access the property values from the returned objects (for example, if you iterate over all the objects to calculate the average value of a particular attribute), then it is more efficient to set returnsObjectsAsFaults to NO to avoid the additional overhead.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setReturnsObjectsAsFaults:

Declared In

setAffectedStores:

Sets the array of persistent stores that will be searched by the receiver.

- (void)setAffectedStores:(NSArray *)stores

Parameters

stores

An array containing identifiers for the stores to be searched when the receiver is executed.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – affectedStores

Related Sample Code

• CoreRecipes

Declared In

setEntity:

Sets the entity of the receiver.

- (void)setEntity:(NSEntityDescription *)entity

Parameters

entity

The entity of the receiver.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – entity

Related Sample Code

• Core Data HTML Store
• CoreRecipes
• Departments and Employees
• QTMetadataEditor

Declared In

setFetchLimit:

Sets the fetch limit of the receiver.

- (void)setFetchLimit:(NSUInteger)limit

Parameters

limit

The fetch limit of the receiver. 0 specifies no fetch limit.

Discussion

The fetch limit specifies the maximum number of objects that a request should return when executed.

Special Considerations

If you set a fetch limit, the framework makes a best effort, but does not guarantee, to improve efficiency. For every object store except the SQL store, a fetch request executed with a fetch limit in effect simply performs an unlimited fetch and throws away the unasked for rows.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – fetchLimit

Declared In

setIncludesPropertyValues:

Sets if, when the fetch is executed, property data is obtained from the persistent store.

- (void)setIncludesPropertyValues:(BOOL)yesNo

Parameters

yesNo

If NO, the request will not obtain property information, but only information to identify each object (used to create managed object IDs).

Discussion

For a full discussion, see includesPropertyValues.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – includesPropertyValues

Declared In

setIncludesSubentities:

Sets whether the receiver includes subentities.

- (void)setIncludesSubentities:(BOOL)yesNo

Parameters

yesNo

If NO, the receiver will fetch objects of exactly the entity type of the request; if YES, the receiver will include all subentities of the entity for the request (if any).

Discussion

The default is YES.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – includesSubentities

Declared In

setPredicate:

Sets the predicate of the receiver.

- (void)setPredicate:(NSPredicate *)predicate

Parameters

predicate

The predicate of the receiver.

Discussion

If the predicate is empty—for example, if it is an AND predicate whose array of elements contains no predicates—the receiver has its predicate set to nil. For more about predicates, see Predicates Programming Guide.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – predicate

Related Sample Code

• CoreRecipes
• QTMetadataEditor

Declared In

setRelationshipKeyPathsForPrefetching:

Sets an array of relationship keypaths to prefetch along with the entity for the request.

- (void)setRelationshipKeyPathsForPrefetching:(NSArray *)keys

Parameters

keys

An array of relationship key-path strings in NSKeyValueCoding notation (as you would normally use with valueForKeyPath:).

Discussion

For a full discussion, see relationshipKeyPathsForPrefetching.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – relationshipKeyPathsForPrefetching

Declared In

setResultType:

Sets the result type of the receiver.

- (void)setResultType:(NSFetchRequestResultType)type

Parameters

type

The result type of the receiver.

Discussion

For further discussion, see resultType.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – resultType

Declared In

setReturnsObjectsAsFaults:

Sets whether the objects resulting from a fetch request are faults.

- (void)setReturnsObjectsAsFaults:(BOOL)yesNo

Parameters

yesNo

If NO, the objects returned from the fetch are pre-populated with their property values (making them fully-faulted objects, which will immediately return NO if sent the isFault message). If YES, the objects returned from the fetch are not pre-populated (and will receive a didFireFault message when the properties are accessed the first time).

Discussion

For a full discussion, see returnsObjectsAsFaults.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – returnsObjectsAsFaults

Declared In

setSortDescriptors:

Sets the array of sort descriptors of the receiver.

- (void)setSortDescriptors:(NSArray *)sortDescriptors

Parameters

sortDescriptors

The array of sort descriptors of the receiver. nil specifies no sort descriptors.

Discussion

The sort descriptors specify how the objects returned when the fetch request is issued should be ordered—for example by last name then by first name. The sort descriptors are applied in the order in which they appear in the sortDescriptors array (serially in lowest-array-index-first order).

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – sortDescriptors

Related Sample Code

• CoreRecipes

Declared In

sortDescriptors

Returns the sort descriptors of the receiver.

- (NSArray *)sortDescriptors

Return Value

The sort descriptors of the receiver.

Discussion

The sort descriptors are used to order the array of objects returned when the fetch is executed.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setSortDescriptors:

Declared In

Constants

Fetch request result types

These constants specify the possible result types a fetch request can return.

enum {
   NSManagedObjectResultType        = 0x00,
   NSManagedObjectIDResultType      = 0x01
};

Constants

NSManagedObjectResultType

Specifies that the request returns managed objects.

Available in Mac OS X v10.5 and later.

Declared in NSFetchRequest.h.

NSManagedObjectIDResultType

Specifies that the request returns managed object IDs.

Available in Mac OS X v10.5 and later.

Declared in NSFetchRequest.h.

Discussion

These constants are used by resultType.

NSFetchRequestResultType

Defines the type for the fetch request result type.

typedef NSUInteger NSFetchRequestResultType;

Availability

• Available in Mac OS X v10.5 and later.

Declared In

Next Page > Hide TOC