<!--
{
  "availability" : [
    "iOS: 3.0.0 -",
    "iPadOS: 3.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.4.0 -",
    "tvOS: -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "CoreData",
  "identifier" : "/documentation/CoreData/NSFetchRequest",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Core Data"
    ],
    "preciseIdentifier" : "c:objc(cs)NSFetchRequest"
  },
  "title" : "NSFetchRequest"
}
-->

# NSFetchRequest

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

```
class NSFetchRequest<ResultType> where ResultType : NSFetchRequestResult
```

## Overview

An instance of [`NSFetchRequest`](/documentation/CoreData/NSFetchRequest) collects the criteria needed to select and optionally to sort a group of [NSManagedObject](https://developer.apple.com/library/archive/releasenotes/Cocoa/CoreDataReleaseNotes/index.html#//apple_ref/doc/uid/TP40006503-SW6) managed objects held in an [`NSPersistentStore`](/documentation/CoreData/NSPersistentStore) persistent store. A fetch request contains an [`NSEntityDescription`](/documentation/CoreData/NSEntityDescription) or an entity name that specifies which entity to search. It frequently also contains:

- An <doc://com.apple.documentation/documentation/Foundation/NSPredicate> predicate that specifies which properties to filter by and the constraints on selection, such as, `“last name begins with a ‘J’”`. If you don’t specify a predicate, then the system fetches all instances of the entity that you specified, subject to other constraints. For more information, see [`fetch(_:)`](/documentation/CoreData/NSManagedObjectContext/fetch(_:)-38ys1).
- An array of <doc://com.apple.documentation/documentation/Foundation/NSSortDescriptor> sort descriptors that specify how to order the returned objects, such as ascending by last name and then by first name.

You can also specify other aspects of a fetch request:

- [`fetchLimit`](/documentation/CoreData/NSFetchRequest/fetchLimit): The maximum number of objects that a request returns
- [`fetchOffset`](/documentation/CoreData/NSFetchRequest/fetchOffset): The number of objects to skip
- [`affectedStores`](/documentation/CoreData/NSFetchRequest/affectedStores): Which data stores the request accesses
- [`resultType`](/documentation/CoreData/NSFetchRequest/resultType): Whether the fetch returns managed objects, object IDs, dictionaries, or a count
- [`includesPropertyValues`](/documentation/CoreData/NSFetchRequest/includesPropertyValues) and : Whether objects are fully populated with their properties
- [`returnsObjectsAsFaults`](/documentation/CoreData/NSFetchRequest/returnsObjectsAsFaults): Whether the objects are faults
- [`includesSubentities`](/documentation/CoreData/NSFetchRequest/includesSubentities): Whether the fetch includes subentities of the fetched entity
- [`propertiesToFetch`](/documentation/CoreData/NSFetchRequest/propertiesToFetch): Which properties to fetch
- [`includesPendingChanges`](/documentation/CoreData/NSFetchRequest/includesPendingChanges): Whether to include unsaved changes

Use [`execute()`](/documentation/CoreData/NSFetchRequest/execute()) to perform the fetch directly on the managed object context that’s associated with the current queue. Or use one of the [`NSManagedObjectContext`](/documentation/CoreData/NSManagedObjectContext) methods such as [`perform(_:)`](/documentation/CoreData/NSManagedObjectContext/perform(_:)) to execute the fetch.

> Note:
> When you execute an instance of ``doc://com.apple.coredata/documentation/CoreData/NSFetchRequest``, it always accesses the underlying persistent stores to retrieve the latest results.

In <doc://com.apple.documentation/documentation/SwiftUI>, you can use a <doc://com.apple.documentation/documentation/SwiftUI/FetchRequest> property wrapper to execute the fetch and assign the results to a property. First, create the request:

```swift
let request: NSFetchRequest = {
    // Create a fetch request.
    let request = ShoppingItem.fetchRequest()
    
    // Limit the maximum number of items that the request returns.
    request.fetchLimit = 100
            
    // Filter the request results, such as to only return unchecked items.
    request.predicate = NSPredicate(format: "isChecked = false")
    
    // Sort the fetched results, such as ascending by name.
    request.sortDescriptors = [NSSortDescriptor(keyPath: \ShoppingItem.name, ascending: true)]

    return request
}()
```

Then use a <doc://com.apple.documentation/documentation/SwiftUI/FetchRequest> property wrapper with the request to declare a property that receives the objects that the fetch returns:

```swift
// Use a `FetchRequest` property wrapper to fetch the managed objects
// and assign the result.
@FetchRequest(fetchRequest: request) private var items: FetchedResults<ShoppingItem>
```

> Tip:
> If you don’t need to specify multiple properties of the fetch, you can avoid creating the fetch request separately and declare it in the property wrapper instead. See <doc://com.apple.documentation/documentation/SwiftUI/FetchRequest> for more information.

You often predefine fetch requests in an [`NSManagedObjectModel`](/documentation/CoreData/NSManagedObjectModel) managed object model to provide an API to retrieve a stored fetch request by name. Stored fetch requests can include placeholders for variable substitution, and serve as templates for later completion. Fetch request templates allow you to predefine queries with variables to substitute at runtime.

## Topics

### Managing the Fetch Request’s Entity

[`init(entityName:)`](/documentation/CoreData/NSFetchRequest/init(entityName:)-5anoo)

Returns a fetch request configured with a given entity name.

[`init()`](/documentation/CoreData/NSFetchRequest/init())

Creates a new fetch request.

[`entityName`](/documentation/CoreData/NSFetchRequest/entityName)

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

[`entity`](/documentation/CoreData/NSFetchRequest/entity)

The entity specified for the fetch request.

[`includesSubentities`](/documentation/CoreData/NSFetchRequest/includesSubentities)

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

[`NSFetchRequestResultType`](/documentation/CoreData/NSFetchRequestResultType)

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

### Specifying Fetch Constraints

[`predicate`](/documentation/CoreData/NSFetchRequest/predicate)

The predicate of the fetch request.

[`fetchLimit`](/documentation/CoreData/NSFetchRequest/fetchLimit)

The fetch limit of the fetch request.

[`fetchOffset`](/documentation/CoreData/NSFetchRequest/fetchOffset)

The fetch offset of the fetch request.

[`fetchBatchSize`](/documentation/CoreData/NSFetchRequest/fetchBatchSize)

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

[`affectedStores`](/documentation/CoreData/NSFetchRequest/affectedStores)

An array of persistent stores specified for the fetch request.

[`NSFetchRequestExpression`](/documentation/CoreData/NSFetchRequestExpression)

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

[`NSExpressionDescription`](/documentation/CoreData/NSExpressionDescription)

An object that describes an expression to include with a fetch request.

[`NSFetchedPropertyDescription`](/documentation/CoreData/NSFetchedPropertyDescription)

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

### Sorting the Results

[`sortDescriptors`](/documentation/CoreData/NSFetchRequest/sortDescriptors)

The sort descriptors of the fetch request.

### Prefetching Related Objects

[`relationshipKeyPathsForPrefetching`](/documentation/CoreData/NSFetchRequest/relationshipKeyPathsForPrefetching)

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

### Managing How Results Are Returned

[`resultType`](/documentation/CoreData/NSFetchRequest/resultType)

The result type of the fetch request.

[`includesPendingChanges`](/documentation/CoreData/NSFetchRequest/includesPendingChanges)

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

[`propertiesToFetch`](/documentation/CoreData/NSFetchRequest/propertiesToFetch)

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

[`returnsDistinctResults`](/documentation/CoreData/NSFetchRequest/returnsDistinctResults)

A Boolean value that indicates whether the fetch request returns only distinct values for the fields specified by [`propertiesToFetch`](/documentation/CoreData/NSFetchRequest/propertiesToFetch).

[`includesPropertyValues`](/documentation/CoreData/NSFetchRequest/includesPropertyValues)

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

[`shouldRefreshRefetchedObjects`](/documentation/CoreData/NSFetchRequest/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`](/documentation/CoreData/NSFetchRequest/returnsObjectsAsFaults)

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

[`NSFetchRequestResultType`](/documentation/CoreData/NSFetchRequestResultType)

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

[`NSFetchRequestResult`](/documentation/CoreData/NSFetchRequestResult)

An abstract protocol used with parameterized fetch requests.

### Grouping and Filtering Dictionary Results

[`propertiesToGroupBy`](/documentation/CoreData/NSFetchRequest/propertiesToGroupBy)

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

[`havingPredicate`](/documentation/CoreData/NSFetchRequest/havingPredicate)

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

### Executing a Fetch Request Directly

[`execute()`](/documentation/CoreData/NSFetchRequest/execute())

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


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)