iOS Developer Library

Developer

Foundation Framework Reference NSMetadataQuery Class Reference

Options
Deployment Target:

On This Page
Language:

NSMetadataQuery

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

Inheritance


Conforms To


Import Statement


import Foundation @import Foundation;

Availability


Available in iOS 5.0 and later.
  • An array containing the search scopes.

    Declaration

    Swift

    var searchScopes: [AnyObject]

    Objective-C

    @property(copy) NSArray *searchScopes

    Discussion

    This array can contain NSURL or NSString objects that represent file-system directories or the search scopes for the query. For a list of valid search scopes, see Metadata Query Search Scopes. An empty array indicates that there is no limitation on where the query searches.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • predicate predicate Property

    The predicate used to filter query results.

    Declaration

    Swift

    @NSCopying var predicate: NSPredicate?

    Objective-C

    @property(copy) NSPredicate *predicate

    Discussion

    Setting this property while a query is running stops the query and discards the current results. The receiver immediately starts a new query.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • An array of sort descriptor objects.

    Declaration

    Swift

    var sortDescriptors: [AnyObject]

    Objective-C

    @property(copy) NSArray *sortDescriptors

    Discussion

    Setting this property while a query is running stops the query and discards the current results. The receiver immediately starts a new query.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    var valueListAttributes: [AnyObject]

    Objective-C

    @property(copy) NSArray *valueListAttributes

    Discussion

    The query collects the values of these attributes into uniqued lists that can be used to summarize the results of the query. If attributes is nil, the query generates no value lists. Note that value list collection increases CPU usage and significantly increases the memory usage of an NSMetadataQuery object.

    Setting this property while a query is running stops the query and discards the current results. The receiver immediately starts a new query.

    For a list of valid attributes, see Attribute Keys and Cloud Storage Keys in NSMetadataItem Class Reference.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

    See Also

    valueLists

  • An array of grouping attributes. (read-only)

    Declaration

    Swift

    var groupingAttributes: [AnyObject]?

    Objective-C

    @property(copy) NSArray *groupingAttributes

    Discussion

    Setting this property while a query is running stops the query and discards the current results. The receiver immediately starts a new query.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • The interval at which notification of updated results occurs.

    Declaration

    Swift

    var notificationBatchingInterval: NSTimeInterval

    Objective-C

    @property NSTimeInterval notificationBatchingInterval

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • delegate delegate Property

    The query’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSMetadataQueryDelegate?

    Objective-C

    @property(assign) id< NSMetadataQueryDelegate > delegate

    Discussion

    This property contains an object that acts as the query’s delegate, or nil. The delegate must implement the NSMetadataQueryDelegate Protocol. Pass nil to remove the current delegate.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    var searchItems: [AnyObject]?

    Objective-C

    @property(copy) NSArray *searchItems

    Discussion

    Use this method to scope the metadata query to a collection of existing URLs and/or metadata items. This array contains the NSURL and/or NSMetadataItem items to be searched.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • started started Property

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

    Declaration

    Swift

    var started: Bool { get }

    Objective-C

    @property(readonly, getter=isStarted) BOOL started

    Discussion

    This property contains YEStrue when the receiver has executed the startQuery method; otherwise, NOfalse.

    Import Statement

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • Attempts to start the query.

    Declaration

    Swift

    func startQuery() -> Bool

    Objective-C

    - (BOOL)startQuery

    Return Value

    YEStrue when successful; otherwise, NOfalse.

    Discussion

    A query can’t be started if the receiver is already running a query or no predicate has been specified.

    This method must be called on the main thread. For example:

    Swift

    • var startQuery = false
    • let query = // Set up a query
    • dispatch_sync(dispatch_get_main_queue()) {
    • startQuery = query.startQuery()
    • }
    • if !startQuery {
    • // Handle the error
    • }

    Objective-C

    • __block BOOL startedQuery = NO;
    • NSMetadataQuery * query = //Initialize and set up a query
    • dispatch_sync(dispatch_get_main_queue(), ^{
    • startedQuery = [query startQuery];
    • });
    • if (!startedQuery) {
    • // Handle the error
    • }

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • gathering gathering Property

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

    Declaration

    Swift

    var gathering: Bool { get }

    Objective-C

    @property(readonly, getter=isGathering) BOOL gathering

    Discussion

    This property contains YEStrue when the query is in the initial gathering phase; otherwise, NOfalse.

    Import Statement

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • stopped stopped Property

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

    Declaration

    Swift

    var stopped: Bool { get }

    Objective-C

    @property(readonly, getter=isStopped) BOOL stopped

    Discussion

    This property contains YEStrue when the receiver has stopped the query; otherwise, NOfalse.

    Import Statement

    import Foundation

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    func stopQuery()

    Objective-C

    - (void)stopQuery

    Discussion

    The receiver first completes gathering any unprocessed results. If a query is stopped before the gathering phase finishes, it does not post an NSMetadataQueryDidStartGatheringNotification notification.

    You call this function to stop a query that is generating too many results to be useful but you still want to access the available results. If the receiver is sent a startQuery message after performing this method, the existing results are discarded.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • results results Property

    An array containing the query’s results. (read-only)

    Declaration

    Swift

    var results: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *results

    Discussion

    The array is a proxy object that is primarily intended for use with Cocoa bindings. While it is possible to copy the proxy array and receive a “snapshot” of the complete current query results, it is generally not recommended due to performance and memory issues. To access individual result array elements, use the resultCount and resultAtIndex: methods.

    The array supports key-value observing, which can be used to be notified when items are added, removed, or updated in the array of results.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

    See Also

    groupedResults

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

    Declaration

    Swift

    var resultCount: Int { get }

    Objective-C

    @property(readonly) NSUInteger resultCount

    Discussion

    For performance reasons, you should use this method, rather than invoking count on results.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • Returns the query result at a specific index.

    Declaration

    Swift

    func resultAtIndex(_ index: Int) -> AnyObject

    Objective-C

    - (id)resultAtIndex:(NSUInteger)index

    Parameters

    index

    The index of the desired result in the query result array.

    Return Value

    The query result at the position specified by index.

    Discussion

    For performance reasons, use this method when retrieving a specific result, rather than the array returned by results.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func indexOfResult(_ result: AnyObject) -> Int

    Objective-C

    - (NSUInteger)indexOfResult:(id)result

    Parameters

    result

    The query result object being inquired about.

    Return Value

    Index of result in the query result array.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    var groupedResults: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *groupedResults

    Discussion

    These groups are based on the receiver’s grouping attributes.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • Enumerates the current set of results using the given block.

    Declaration

    Swift

    func enumerateResultsUsingBlock(_ block: (AnyObject!, Int, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

    - (void)enumerateResultsUsingBlock:(void (^)(id result, NSUInteger idx, BOOL *stop))block

    Parameters

    block

    The block to execute for each current result.

    Discussion

    This method disables the query at the start of the iteration and reenables it upon completion. Use enumerateResultsWithOptions:usingBlock: if you want to use concurrent or reverse iteration.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • Enumerates the current set of results using the given options and block.

    Declaration

    Swift

    func enumerateResultsWithOptions(_ opts: NSEnumerationOptions, usingBlock block: (AnyObject!, Int, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

    - (void)enumerateResultsWithOptions:(NSEnumerationOptions)opts usingBlock:(void (^)(id result, NSUInteger idx, BOOL *stop))block

    Parameters

    opts

    Options for the enumeration. For a complete list of options, see NSEnumerationOptions.

    block

    The block to execute for each current result.

    Discussion

    This method disables the query at the start of the iteration and reenables it upon completion.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • A dictionary containing the value lists generated by the query. (read-only)

    Declaration

    Swift

    var valueLists: [NSObject : AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSDictionary *valueLists

    Discussion

    This property contains a dictionary of NSMetadataQueryAttributeValueTuple objects.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func valueOfAttribute(_ attributeName: String, forResultAtIndex index: Int) -> AnyObject?

    Objective-C

    - (id)valueOfAttribute:(NSString *)attributeName forResultAtIndex:(NSUInteger)index

    Parameters

    attributeName

    The attribute of the result object at index being inquired about. The attribute must be specified in valueListAttributes, as a sorting key in a specified sort descriptor, or as one of the grouping attributes specified set for the query.

    index

    The index of the desired return object in the query results array.

    Return Value

    Value for attributeName in the result object at index in the query result array.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • Enables updates to the query results.

    Declaration

    Swift

    func enableUpdates()

    Objective-C

    - (void)enableUpdates

    Discussion

    Unless you use enumerateResultsUsingBlock: or enumerateResultsWithOptions:usingBlock:, you should invoke this method after you’re done iterating over the query results.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • Disables updates to the query results.

    Declaration

    Swift

    func disableUpdates()

    Objective-C

    - (void)disableUpdates

    Discussion

    Unless you use enumerateResultsUsingBlock: or enumerateResultsWithOptions:usingBlock:, you should invoke this method before iterating over query results that could change due to live updates.

    Import Statement

    import Foundation

    Availability

    Available in iOS 5.0 and later.

  • The queue on which query result notifications are posted.

    Declaration

    Swift

    var operationQueue: NSOperationQueue?

    Objective-C

    @property(retain) NSOperationQueue *operationQueue

    Discussion

    Use this property to decouple the processing of results from the thread used to execute the query. This makes it easier to synchronize query result processing with other related operations—such as updating the data model or user interface—which you might want to perform on the main queue.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.

  • Constants for the predefined search scopes used by searchScopes.

    Declaration

    Swift

    let NSMetadataQueryUbiquitousDocumentsScope: NSString! let NSMetadataQueryUbiquitousDataScope: NSString! let NSMetadataQueryAccessibleUbiquitousExternalDocumentsScope: NSString!

    Objective-C

    NSString * const NSMetadataQueryUbiquitousDocumentsScope; NSString * const NSMetadataQueryUbiquitousDataScope; NSString * const NSMetadataQueryAccessibleUbiquitousExternalDocumentsScope

    Constants

    • NSMetadataQueryUbiquitousDocumentsScope

      NSMetadataQueryUbiquitousDocumentsScope

      Search all files in the Documents directories of the app’s iCloud container directories.

      Available in iOS 5.0 and later.

    • NSMetadataQueryUbiquitousDataScope

      NSMetadataQueryUbiquitousDataScope

      Search all files not in the Documents directories of the app’s iCloud container directories.

      Available in iOS 5.0 and later.

    • NSMetadataQueryAccessibleUbiquitousExternalDocumentsScope

      NSMetadataQueryAccessibleUbiquitousExternalDocumentsScope

      Search for documents outside the app’s container. This search can locate iCloud documents that the user previously opened using a document picker view controller. This lets your app access the documents again without requiring direct user interaction. The result’s NSMetadataItemURLKey attributes return security-scoped NSURLs. For more information on working with security-scoped URLs, see Security-Scoped URLs in NSURL Class Reference.

      Available in iOS 8.0 and later.

    Import Statement

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

    Declaration

    Swift

    let NSMetadataQueryResultContentRelevanceAttribute: NSString!

    Objective-C

    NSString * const NSMetadataQueryResultContentRelevanceAttribute;

    Constants

    • NSMetadataQueryResultContentRelevanceAttribute

      NSMetadataQueryResultContentRelevanceAttribute

      The key used to retrieve an NSNumber object with a floating point value between 0.0 and 1.0 inclusive. The relevance value indicates the relevance of the content of a result object. The relevance is computed based on the value of the result itself, not on its relevance to the other results returned by the query. If the value is not computed, it is treated as an attribute on the item that does not exist.

      Available in iOS 5.0 and later.

    Import Statement

  • Constants for keys to retrieve the collection of changed items from a notification’s user info dictionary. Note that when querying the ubiquitous scope, these keys get added to the user info dictionary only in OS X v10.10 and iOS 8.0 or later. To track changes in earlier versions, use KVO on the query’s results property instead.

    Declaration

    Swift

    let NSMetadataQueryUpdateAddedItemsKey: NSString! let NSMetadataQueryUpdateChangedItemsKey: NSString! let NSMetadataQueryUpdateRemovedItemsKey: NSString!

    Objective-C

    NSString * const NSMetadataQueryUpdateAddedItemsKey; NSString * const NSMetadataQueryUpdateChangedItemsKey; NSString * const NSMetadataQueryUpdateRemovedItemsKey;

    Constants

    • NSMetadataQueryUpdateAddedItemsKey

      NSMetadataQueryUpdateAddedItemsKey

      The key for retrieving an array of items added to the query result.

      Available in iOS 8.0 and later.

    • NSMetadataQueryUpdateChangedItemsKey

      NSMetadataQueryUpdateChangedItemsKey

      The key for retrieving an array of items that have changed in the query result.

      Available in iOS 8.0 and later.

    • NSMetadataQueryUpdateRemovedItemsKey

      NSMetadataQueryUpdateRemovedItemsKey

      The key for retrieving an array of items removed from the query result.

      Available in iOS 8.0 and later.

    Import Statement