A query that you perform against Spotlight metadata.


class NSMetadataQuery : NSObject


The NSMetadataQuery class encapsulates the functionality provided by the MDQuery opaque type for querying the Spotlight metadata.

NSMetadataQuery objects provide metadata query results in several ways:

  • As individual attribute values for requested attributes.

  • As value lists that contain the distinct values for given attributes in the query results.

  • As a result array proxy, containing all the query results. This is suitable for use with Cocoa bindings.

  • As a hierarchical collection of results, grouping together items with the same values for specified grouping attributes. This is also suitable for use with Cocoa bindings.

Queries have two phases: the initial gathering phase that collects all currently matching results and a second live-update phase.

By default, the receiver has no limitation on its search scope. Use the searchScopes property to customize.

By default, notification of updated results occurs at 1.0 seconds. Use the notificationBatchingInterval property to customize.

You must set a predicate with the predicate property before starting a query.


Configuring Queries

var searchScopes: [Any]

An array containing the search scopes.

var predicate: NSPredicate?

The predicate used to filter query results.

var sortDescriptors: [NSSortDescriptor]

An array of sort descriptor objects.

var valueListAttributes: [String]

An array of attributes whose values are gathered by the query.

var groupingAttributes: [String]?

An array of grouping attributes. (read-only)

var notificationBatchingInterval: TimeInterval

The interval at which notification of updated results occurs.

var searchItems: [Any]?

An array of objects that define the query’s scope.

Running Queries

var isStarted: Bool

A Boolean value that indicates whether the query has started. (read-only)

func start() -> Bool

Attempts to start the query.

var isGathering: Bool

A Boolean value that indicates whether the receiver is in the initial gathering phase of the query. (read-only)

var isStopped: Bool

A Boolean value that indicates whether the query has stopped.

func stop()

Stops the receiver’s current query from gathering any further results.

Getting Query Results

var results: [Any]

An array containing the query’s results.

var resultCount: Int

The number of results returned by the query. (read-only)

func result(at: Int) -> Any

Returns the query result at a specific index.

func index(ofResult: Any) -> Int

Returns the index of a query result object in the receiver’s results array.

var groupedResults: [NSMetadataQueryResultGroup]

An array containing hierarchical groups of query results. (read-only)

class NSMetadataQueryResultGroup

The NSMetadataQueryResultGroup class represents a collection of grouped attribute results returned by an NSMetadataQuery object.

func enumerateResults((Any, Int, UnsafeMutablePointer<ObjCBool>) -> Void)

Enumerates the current set of results using the given block.

var valueLists: [String : [NSMetadataQueryAttributeValueTuple]]

A dictionary containing the value lists generated by the query.

class NSMetadataQueryAttributeValueTuple

The NSMetadataQueryAttributeValueTuple class represents attribute-value tuples, which are objects that contain the attribute name and value of a metadata attribute.

func value(ofAttribute: String, forResultAt: Int) -> Any?

Returns the value for the attribute name attrName at the index in the results specified by idx.

func enableUpdates()

Enables updates to the query results.

func disableUpdates()

Disables updates to the query results.

var operationQueue: OperationQueue?

The queue on which query result notifications are posted.


Metadata Query Search Scopes

Constants for the predefined search scopes used by searchScopes.

Content Relevance

In addition to including the requested metadata attributes, a query result also includes content relevance, accessed with the following key.

Keys for Use with a Notification Info Dictionary

Constants for keys to retrieve the collection of changed items from a notification’s user info dictionary.


static let NSMetadataQueryDidFinishGathering: NSNotification.Name

Posted when the receiver has finished with the initial result-gathering phase of the query.

static let NSMetadataQueryDidStartGathering: NSNotification.Name

Posted when the receiver begins with the initial result-gathering phase of the query.

static let NSMetadataQueryDidUpdate: NSNotification.Name

Posted when the receiver’s results have changed during the live-update phase of the query.

static let NSMetadataQueryGatheringProgress: NSNotification.Name

Posted as the receiver is collecting results during the initial result-gathering phase of the query.


Inherits From

Conforms To

See Also


protocol NSMetadataQueryDelegate

An interface that enables the delegate of a metadata query to provide substitute results or attributes.