Instance Method

executeFetchRequest:error:

Returns an array of objects that meet the criteria specified by a given fetch request.

Declaration

- (NSArray *)executeFetchRequest:(NSFetchRequest *)request error:(NSError * _Nullable *)error;

Parameters

request

A fetch request that specifies the search criteria for the fetch.

error

If there is a problem executing the fetch, upon return contains an instance of NSError that describes the problem.

Return Value

An array of objects that meet the criteria specified by request fetched from the receiver and from the persistent stores associated with the receiver’s persistent store coordinator. If an error occurs, returns nil. If no objects match the criteria specified by request, returns an empty array.

Discussion

Returned objects are registered with the receiver.

The following points are important to consider:

  • If the fetch request has no predicate, then all instances of the specified entity are retrieved, modulo other criteria below.

  • An object that meets the criteria specified by request (it is an instance of the entity specified by the request, and it matches the request’s predicate if there is one) and that has been inserted into a context but which is not yet saved to a persistent store, is retrieved if the fetch request is executed on that context.

  • If an object in a context has been modified, a predicate is evaluated against its modified state, not against the current state in the persistent store. Therefore, if an object in a context has been modified such that it meets the fetch request’s criteria, the request retrieves it even if changes have not been saved to the store and the values in the store are such that it does not meet the criteria. Conversely, if an object in a context has been modified such that it does not match the fetch request, the fetch request will not retrieve it even if the version in the store does match.

  • If an object has been deleted from the context, the fetch request does not retrieve it even if that deletion has not been saved to a store.

Objects that have been realized (populated, faults fired, “read from”, and so on) as well as pending updated, inserted, or deleted, are never changed by a fetch operation without developer intervention. If you fetch some objects, work with them, and then execute a new fetch that includes a superset of those objects, you do not get new instances or update data for the existing objects—you get the existing objects with their current in-memory state.

See Also

Registering and Fetching Objects

- countForFetchRequest:error:

Returns the number of objects a given fetch request would have returned if it had been passed to executeFetchRequest:error:.

- objectRegisteredForID:

Returns the object for a specified ID, if the object is registered with the context.

- objectWithID:

Returns an object for a specified ID even if the object needs to be fetched.

- existingObjectWithID:error:

Returns the object for the specified ID or nil if the object does not exist.

registeredObjects

The set of objects registered with the context.

- executeRequest:error:

Passes a request to the persistent store without affecting the contents of the managed object context and returns a persistent store result.

- refreshAllObjects

Refreshes all currently registered objects that are associated with this context.

retainsRegisteredObjects

A Boolean value that indicates whether the context keeps strong references to all registered managed objects.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software