# NSMetadataQuery A query that you perform against Spotlight metadata. ``` class NSMetadataQuery ``` ## Overview The [`NSMetadataQuery`](/documentation/Foundation/NSMetadataQuery) class encapsulates the functionality provided by the opaque type for querying the Spotlight metadata. [`NSMetadataQuery`](/documentation/Foundation/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`](/documentation/Foundation/NSMetadataQuery/searchScopes) property to customize. By default, notification of updated results occurs at 1.0 seconds. Use the [`notificationBatchingInterval`](/documentation/Foundation/NSMetadataQuery/notificationBatchingInterval) property to customize. You must set a predicate with the [`predicate`](/documentation/Foundation/NSMetadataQuery/predicate) property before starting a query. ## Topics ### Configuring queries [`searchScopes`](/documentation/Foundation/NSMetadataQuery/searchScopes) An array containing the search scopes. [`predicate`](/documentation/Foundation/NSMetadataQuery/predicate) The predicate used to filter query results. [`sortDescriptors`](/documentation/Foundation/NSMetadataQuery/sortDescriptors) An array of sort descriptor objects. [`valueListAttributes`](/documentation/Foundation/NSMetadataQuery/valueListAttributes) An array of attributes whose values are gathered by the query. [`groupingAttributes`](/documentation/Foundation/NSMetadataQuery/groupingAttributes) An array of grouping attributes. (read-only) [`notificationBatchingInterval`](/documentation/Foundation/NSMetadataQuery/notificationBatchingInterval) The interval at which notification of updated results occurs. [`delegate`](/documentation/Foundation/NSMetadataQuery/delegate) The query’s delegate. [`searchItems`](/documentation/Foundation/NSMetadataQuery/searchItems) An array of objects that define the query’s scope. ### Running queries [`isStarted`](/documentation/Foundation/NSMetadataQuery/isStarted) A Boolean value that indicates whether the query has started. (read-only) [`start()`](/documentation/Foundation/NSMetadataQuery/start()) Attempts to start the query. [`isGathering`](/documentation/Foundation/NSMetadataQuery/isGathering) A Boolean value that indicates whether the receiver is in the initial gathering phase of the query. (read-only) [`isStopped`](/documentation/Foundation/NSMetadataQuery/isStopped) A Boolean value that indicates whether the query has stopped. [`stop()`](/documentation/Foundation/NSMetadataQuery/stop()) Stops the receiver’s current query from gathering any further results. ### Getting query results [`results`](/documentation/Foundation/NSMetadataQuery/results) An array containing the query’s results. [`resultCount`](/documentation/Foundation/NSMetadataQuery/resultCount) The number of results returned by the query. (read-only) [`result(at:)`](/documentation/Foundation/NSMetadataQuery/result(at:)) Returns the query result at a specific index. [`index(ofResult:)`](/documentation/Foundation/NSMetadataQuery/index(ofResult:)) Returns the index of a query result object in the receiver’s results array. [`groupedResults`](/documentation/Foundation/NSMetadataQuery/groupedResults) An array containing hierarchical groups of query results. (read-only) [`NSMetadataQueryResultGroup`](/documentation/Foundation/NSMetadataQueryResultGroup) The `NSMetadataQueryResultGroup` class represents a collection of grouped attribute results returned by an [`NSMetadataQuery`](/documentation/Foundation/NSMetadataQuery) object. [`enumerateResults(_:)`](/documentation/Foundation/NSMetadataQuery/enumerateResults(_:)) Enumerates the current set of results using the given block. [`enumerateResults(options:using:)`](/documentation/Foundation/NSMetadataQuery/enumerateResults(options:using:)) Enumerates the current set of results using the given options and block. [`valueLists`](/documentation/Foundation/NSMetadataQuery/valueLists) A dictionary containing the value lists generated by the query. [`NSMetadataQueryAttributeValueTuple`](/documentation/Foundation/NSMetadataQueryAttributeValueTuple) The `NSMetadataQueryAttributeValueTuple` class represents attribute-value tuples, which are objects that contain the attribute name and value of a metadata attribute. [`value(ofAttribute:forResultAt:)`](/documentation/Foundation/NSMetadataQuery/value(ofAttribute:forResultAt:)) Returns the value for the attribute name `attrName` at the index in the results specified by `idx`. [`enableUpdates()`](/documentation/Foundation/NSMetadataQuery/enableUpdates()) Enables updates to the query results. [`disableUpdates()`](/documentation/Foundation/NSMetadataQuery/disableUpdates()) Disables updates to the query results. [`operationQueue`](/documentation/Foundation/NSMetadataQuery/operationQueue) The queue on which query result notifications are posted. ### Working with notifications [`NSMetadataQueryDidFinishGathering`](/documentation/Foundation/NSNotification/Name-swift.struct/NSMetadataQueryDidFinishGathering) Posted when the receiver has finished with the initial result-gathering phase of the query. [`NSMetadataQueryDidStartGathering`](/documentation/Foundation/NSNotification/Name-swift.struct/NSMetadataQueryDidStartGathering) Posted when the receiver begins with the initial result-gathering phase of the query. [`NSMetadataQueryDidUpdate`](/documentation/Foundation/NSNotification/Name-swift.struct/NSMetadataQueryDidUpdate) Posted when the receiver’s results have changed during the live-update phase of the query. [`NSMetadataQueryGatheringProgress`](/documentation/Foundation/NSNotification/Name-swift.struct/NSMetadataQueryGatheringProgress) Posted as the receiver is collecting results during the initial result-gathering phase of the query. ### Working with notification messages [`NSMetadataQuery.DidFinishGatheringMessage`](/documentation/Foundation/NSMetadataQuery/DidFinishGatheringMessage) A message a metadata query sends when it finishes the initial result-gathering phase of the query. [`NSMetadataQuery.DidStartGatheringMessage`](/documentation/Foundation/NSMetadataQuery/DidStartGatheringMessage) A message a metadata query sends when it starts the initial result-gathering phase of the query. ### Constants [Metadata Query Search Scopes](/documentation/Foundation/metadata-query-search-scopes) Constants for the predefined search scopes used by [`searchScopes`](/documentation/Foundation/NSMetadataQuery/searchScopes). [Content Relevance](/documentation/Foundation/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](/documentation/Foundation/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. --- Copyright © 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)