NSFetchRequest Class Reference

Discussion

The default value is 0. A batch size of 0 is treated as infinite, which disables the batch faulting behavior.

If you set a non-zero batch size, the collection of objects returned when the fetch is executed is broken into batches. When the fetch is executed, the entire request is evaluated and the identities of all matching objects recorded, but no more than batchSize objects’ data will be fetched from the persistent store at a time. The array returned from executing the request will be a proxy object that transparently faults batches on demand. (In database terms, this is an in-memory cursor.)

You can use this feature to restrict the working set of data in your application. In combination with fetchLimit, you can create a subrange of an arbitrary result set.

Discussion

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

Discussion

The default value is 0.

This setting allows you to specify an offset at which rows will begin being returned. Effectively, the request will skip over the specified number of matching entries. For example, given a fetch which would normally return a, b, c, d, specifying an offset of 1 will return b, c, d, and an offset of 4 will return an empty array. Offsets are ignored in nested requests such as subqueries.

This can be used to restrict the working set of data. In combination with -fetchLimit, you can create a subrange of an arbitrary result set.

Discussion

For a full discussion, see setHavingPredicate:. For a discussion of GROUP BY, see setPropertiesToGroupBy:.

Discussion

For a full discussion, see includesPendingChanges.

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.

Discussion

The default is YES.

Discussion

This method provides a convenient way to configure the entity for a fetch request without having to retrieve an NSEntityDescription object. When the fetch is executed, the request uses the managed object context to find the entity with the given name. The model associated with the context’s persistent store coordinator must contain an entity named entityName.

Discussion

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

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 Predicate Programming Guide.

Discussion

For a full discussion, see setPropertiesToFetch:.

Discussion

For a full description see setPropertiesToGroupBy:.

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"]];

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 “NSFetchRequestResultType.” If you set the value to NSManagedObjectIDResultType, this will demote any sort orderings to “best efforts” hints if you do not include the property values in the request.

Discussion

The default value is 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.

Discussion

For a full discussion, see fetchBatchSize.

Discussion

For a full discussion, see fetchLimit.

Discussion

For a full discussion, see fetchOffset.

Discussion

If a having predicate is supplied, it will be run after the GROUP BY. Specifying a HAVING predicate requires that a GROUP BY also be specified. For a discussion of GROUP BY, see setPropertiesToGroupBy:.

Discussion

The default value is YES.

If the value is NO, the fetch request skips checking unsaved changes and only returns objects that matched the predicate in the persistent store.

Discussion

For a full discussion, see includesPropertyValues.

Discussion

The property descriptions may represent attributes, to-one relationships, or expressions. The name of an attribute or relationship description must match the name of a description on the fetch request’s entity.

Discussion

If you use this setting, then you must set the resultType to NSDictionaryResultType, and the SELECT values must be literals, aggregates, or columns specified in the GROUP BY. Aggregates will operate on the groups specified in the GROUP BY rather than the whole table. If you set properties to group by, you can also set a having predicate—see setHavingPredicate:.

Discussion

For a full discussion, see relationshipKeyPathsForPrefetching.

Discussion

For further discussion, see resultType.

Discussion

For a full discussion, see returnsDistinctResults.

Discussion

For a full discussion, see returnsObjectsAsFaults.

Discussion

By default, when you fetch objects they maintain their current property values, even if the values in the persistent store have changed. By invoking this method with the parameter YES, when the fetch is executed the property values of fetched objects to be updated with the current values in the persistent store. This provides more convenient way to ensure managed object property values are consistent with the store than by using refreshObject:mergeChanges: (NSManagedObjetContext) for multiple objects in turn.

Discussion

For a full discussion, see setShouldRefreshRefetchedObjects:.

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).