Class

NSFetchRequest

A description of search criteria used to retrieve data from a persistent store.

Declaration

@interface NSFetchRequest<__covariant ResultType> : NSPersistentStoreRequest

Overview

An instance of NSFetchRequest collects the criteria needed to select and optionally to sort a group of managed objects held in a persistent store. (See NSPersistentStore and NSManagedObject.) A fetch request must contain an entity description (an instance of NSEntityDescription) or an entity name that specifies which entity to search. It frequently also contains:

  • A predicate (an instance of NSPredicate) that specifies which properties to filter by and the constraints on selection, for example, “last name begins with a ‘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:

You can also fetch distinct property values, and attribute values that satisfy a given function, as illustrated in Core Data Snippets.

You use NSFetchRequest objects with the methods executeFetchRequest:error: and countForFetchRequest:error:, defined by NSManagedObjectContext.

You often predefine fetch requests in a managed object model—NSManagedObjectModel provides an 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 predefine queries with variables that are substituted at runtime.

Topics

Managing the Fetch Request’s Entity

+ fetchRequestWithEntityName:

Returns a fetch request configured with a given entity name.

- init

Creates a new fetch request.

- initWithEntityName:

Initializes a fetch request configured with a given entity name.

entityName

The name of the entity the request is configured to fetch.

entity

The entity specified for the fetch request.

includesSubentities

A Boolean value that indicates whether the fetch request includes subentities in the results.

NSFetchRequestResultType

Constants that specify the possible result types a fetch request can return.

Specifying Fetch Constraints

predicate

The predicate of the fetch request.

fetchLimit

The fetch limit of the fetch request.

fetchOffset

The fetch offset of the fetch request.

fetchBatchSize

The batch size of the objects specified in the fetch request.

affectedStores

An array of persistent stores specified for the fetch request.

NSFetchRequestExpression

An expression that evaluates the result of a fetch request on a managed object context.

NSExpressionDescription

A special property description type intended for use with a fetch request.

NSFetchedPropertyDescription

A description object used to define which properties are fetched from Core Data.

Sorting the Results

sortDescriptors

The sort descriptors of the fetch request.

Prefetching Related Objects

relationshipKeyPathsForPrefetching

The relationship key paths to prefetch along with the entity for the request.

Managing How Results Are Returned

resultType

The result type of the fetch request.

includesPendingChanges

A Boolean value that indicates whether, when the fetch is executed, it matches against currently unsaved changes in the managed object context.

propertiesToFetch

A collection of either property descriptions or string property names that specify which properties should be returned by the fetch.

returnsDistinctResults

A Boolean value that indicates whether the fetch request returns only distinct values for the fields specified by propertiesToFetch.

includesPropertyValues

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

shouldRefreshRefetchedObjects

A Boolean value that indicates whether the property values of fetched objects will be updated with the current values in the persistent store.

returnsObjectsAsFaults

A Boolean value that indicates whether the objects resulting from a fetch request are faults.

NSFetchRequestResultType

Constants that specify the possible result types a fetch request can return.

NSFetchRequestResult

An abstract protocol used with parameterized fetch requests.

Grouping and Filtering Dictionary Results

propertiesToGroupBy

An array of objects that indicates how data should be grouped before a select statement is run in a SQL database.

havingPredicate

The predicate used to filter rows being returned by a query containing a GROUP BY directive.

Executing a Fetch Request Directly

- execute:

Executes the fetch request against the managed object context that is associated with the current queue.

Relationships

Conforms To

See Also

Fetch Requests

NSAsynchronousFetchRequest

A fetch request that retrieves results asynchronously and supports progress notification.

NSAsynchronousFetchResult

A fetch result object that encompasses the response from an executed asynchronous fetch request.

NSFetchedResultsController

A controller that you use to manage the results of a Core Data fetch request and to display data to the user.