A description of search criteria used to retrieve data from a persistent store.
SDKs
- iOS 3.0+
- macOS 10.4+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
Framework
- Core Data
Declaration
@interface NSFetchRequest<__covariant ResultType> : NSPersistentOverview
An instance of NSFetch collects the criteria needed to select and optionally to sort a group of managed objects held in a persistent store. (See NSPersistent and NSManagedObject.) A fetch request must contain an entity description (an instance of NSEntity) 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; seeexecutefor full details).Fetch Request: error: An array of sort descriptors (instances of
NSSort) that specify how the returned objects should be ordered, for example, by last name then by first name.Descriptor
You can also specify other aspects of a fetch request:
The maximum number of objects that a request should return; see
fetch.Limit Which data stores the request should access; see
affected.Stores Whether the fetch returns managed objects or just object IDs; see
result.Type Whether objects are fully populated with their properties; see
includes,Subentities includes, andProperty Values returns.Objects As Faults Which properties to fetch; see
properties.To Fetch result.Type The offset for the fetch to start; see
fetch.Offset Whether unsaved changes should be included; see
includes.Pending Changes
You can also fetch distinct property values, and attribute values that satisfy a given function, as illustrated in Core Data Snippets.
You use NSFetch objects with the methods execute and count, defined by NSManaged.
You often predefine fetch requests in a managed object model—NSManaged 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.