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

# NSExpression

An expression for use in a comparison predicate.

```
class NSExpression
```

## Overview

Comparison operations in an [`NSPredicate`](/documentation/Foundation/NSPredicate) derive from two expressions as instances of the [`NSExpression`](/documentation/Foundation/NSExpression) class. You create expressions for constant values, key paths, and so on.

Generally, anywhere in the [`NSExpression`](/documentation/Foundation/NSExpression) class hierarchy where there’s a composite API and subtypes that may only reasonably respond to a subset of that API, invoking a method that doesn’t make sense for that subtype throws an exception.

### Aggregate Expressions

[`NSExpression.ExpressionType.aggregate`](/documentation/Foundation/NSExpression/ExpressionType-swift.enum/aggregate) allows you to create predicates containing expressions that evaluate to collections that contain further expressions. The collection may be an [`NSArray`](/documentation/Foundation/NSArray), [`NSSet`](/documentation/Foundation/NSSet), or [`NSDictionary`](/documentation/Foundation/NSDictionary) object.

Core Data doesn’t support aggregate expressions.

### Subquery Expressions

The [`NSExpression.ExpressionType.subquery`](/documentation/Foundation/NSExpression/ExpressionType-swift.enum/subquery) creates a subexpression that returns a subset of a collection of objects. This allows you to create sophisticated queries across relationships, such as a search for multiple correlated values on the destination object of a relationship.

### Set Expressions

The set expressions ([`NSExpression.ExpressionType.unionSet`](/documentation/Foundation/NSExpression/ExpressionType-swift.enum/unionSet), [`NSExpression.ExpressionType.intersectSet`](/documentation/Foundation/NSExpression/ExpressionType-swift.enum/intersectSet), and [`NSExpression.ExpressionType.minusSet`](/documentation/Foundation/NSExpression/ExpressionType-swift.enum/minusSet)) combine results in a manner similar to the [`NSSet`](/documentation/Foundation/NSSet) methods.

Both sides of these expressions must evaluate to a collection; the left side must evaluate to an `NSSet` object, and the right side can be any other collection type.

```objc
(expression UNION expression)
(expression INTERSECT expression)
(expression MINUS expression)
```

Core Data doesn’t support set expressions.

### Function Expressions

In macOS 10.4, [`NSExpression`](/documentation/Foundation/NSExpression) only supports a predefined set of functions: `sum`, `count`, `min`, `max`, and `average`. You access these predefined functions in the predicate syntax using custom keywords (for example, `MAX(1, 5, 10)`).

In macOS 10.5 and later, function expressions also support arbitrary method invocations. To implement this extended functionality, use the syntax `FUNCTION(receiver, selectorName, arguments, ...),` as in the following example:

```objc
FUNCTION(@"/Developer/Tools/otest", @"lastPathComponent") => @"otest"
```

All methods must take one or more `id` arguments and return an `id` value, although you can use the `CAST` expression to convert datatypes with lossy string representations (for example, `CAST(####, "NSDate")`). macOS 10.5 extends the `CAST` expression to provide support for casting to classes for use in creating receivers for function expressions.

Although Core Data supports evaluation of the predefined functions, it doesn’t support the evaluation of custom predicate functions in the persistent stores (during a fetch).

## Topics

### Creating an Expression

[`init(expressionType:)`](/documentation/Foundation/NSExpression/init(expressionType:))

Creates the expression with the specified expression type.

[`expressionWithFormat:`](/documentation/Foundation/NSExpression/expressionWithFormat:)

Creates the expression with the specified expression arguments.

[`init(format:argumentArray:)`](/documentation/Foundation/NSExpression/init(format:argumentArray:))

Creates the expression with the specified expression format and array of arguments.

[`init(format:arguments:)`](/documentation/Foundation/NSExpression/init(format:arguments:))

Creates the expression with the specified expression format and arguments list.

[`init(format:_:)`](/documentation/Foundation/NSExpression/init(format:_:))

Creates the expression with the expression format and arguments list you specify.

[`init(coder:)`](/documentation/Foundation/NSExpression/init(coder:))

Creates an expression by decoding from the coder you specify.

### Creating an Expression for a Value

[`init(forConstantValue:)`](/documentation/Foundation/NSExpression/init(forConstantValue:))

Creates an expression that represents a specified constant value.

[`expressionForEvaluatedObject()`](/documentation/Foundation/NSExpression/expressionForEvaluatedObject())

Creates an expression that represents the object you’re evaluating.

[`init(forKeyPath:)`](/documentation/Foundation/NSExpression/init(forKeyPath:)-1aqf5)

Creates an expression that invokes the value function with a specified key path.

[`init(forVariable:)`](/documentation/Foundation/NSExpression/init(forVariable:))

Creates an expression that extracts a value from the variable bindings dictionary for a specified key.

[`init(forKeyPath:)`](/documentation/Foundation/NSExpression/init(forKeyPath:)-98by)

Creates an expression using a key path you specify.

[`expressionForAnyKey()`](/documentation/Foundation/NSExpression/expressionForAnyKey())

Creates an expression that represents any key for a Spotlight query.

### Creating a Collection Expression

[`init(forAggregate:)`](/documentation/Foundation/NSExpression/init(forAggregate:))

Creates an aggregate expression for a specified collection.

[`init(forUnionSet:with:)`](/documentation/Foundation/NSExpression/init(forUnionSet:with:))

Creates an expression object that represents the union of a specified set and collection.

[`init(forIntersectSet:with:)`](/documentation/Foundation/NSExpression/init(forIntersectSet:with:))

Creates an expression object that represents the intersection of a specified set and collection.

[`init(forMinusSet:with:)`](/documentation/Foundation/NSExpression/init(forMinusSet:with:))

Creates an expression object that represents the subtraction of a specified collection from a specified set.

### Creating a Subquery

[`init(forSubquery:usingIteratorVariable:predicate:)`](/documentation/Foundation/NSExpression/init(forSubquery:usingIteratorVariable:predicate:))

Creates an expression that filters a collection by storing elements in the collection in a specified variable and keeping the elements that the qualifier returns as true.

### Creating a Conditional Expression

[`init(forConditional:trueExpression:falseExpression:)`](/documentation/Foundation/NSExpression/init(forConditional:trueExpression:falseExpression:))

Creates an expression that returns a result, depending on the value of predicate.

### Creating an Expression Using Blocks

[`init(block:arguments:)`](/documentation/Foundation/NSExpression/init(block:arguments:))

Creates an expression object that uses the block for evaluating objects.

### Creating an Expression for a Function

[`init(forFunction:arguments:)`](/documentation/Foundation/NSExpression/init(forFunction:arguments:))

Creates an expression that invokes one of the predefined functions.

[`init(forFunction:selectorName:arguments:)`](/documentation/Foundation/NSExpression/init(forFunction:selectorName:arguments:))

Creates an expression that returns the result of invoking a selector with a specified name using specified arguments.

### Getting Information About an Expression

[`arguments`](/documentation/Foundation/NSExpression/arguments)

The arguments for the expression.

[`collection`](/documentation/Foundation/NSExpression/collection)

The collection of expressions in an aggregate expression, or the collection element of a subquery expression.

[`constantValue`](/documentation/Foundation/NSExpression/constantValue)

The constant value of the expression.

[`expressionType`](/documentation/Foundation/NSExpression/expressionType-swift.property)

The expression type for the expression.

[`NSExpression.ExpressionType`](/documentation/Foundation/NSExpression/ExpressionType-swift.enum)

Defines the possible types of an expression.

[`function`](/documentation/Foundation/NSExpression/function)

The function for the expression.

[`keyPath`](/documentation/Foundation/NSExpression/keyPath)

The key path for the expression.

[`operand`](/documentation/Foundation/NSExpression/operand)

The operand for the expression.

[`predicate`](/documentation/Foundation/NSExpression/predicate)

The predicate of a subquery expression.

[`left`](/documentation/Foundation/NSExpression/left)

The left expression of an aggregate expression.

[`right`](/documentation/Foundation/NSExpression/right)

The right expression of an aggregate expression.

[`variable`](/documentation/Foundation/NSExpression/variable)

The variable for the expression.

### Evaluating an Expression

[`expressionValue(with:context:)`](/documentation/Foundation/NSExpression/expressionValue(with:context:))

Evaluates an expression using a specified object and context.

[`allowEvaluation()`](/documentation/Foundation/NSExpression/allowEvaluation())

Forces a securely decoded expression to allow evaluation.

[`false`](/documentation/Foundation/NSExpression/false)

An expression to evalutate if a conditional expression’s predicate evaluates to false.

[`true`](/documentation/Foundation/NSExpression/true)

An expression to evalutate if a conditional expression’s predicate evaluates to true.

### Accessing the Expression Block

[`expressionBlock`](/documentation/Foundation/NSExpression/expressionBlock)

The block that executes to evaluate the expression.


---

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)