NSMetadataQuery Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in iOS 5.0 and later.
Companion guide
Declared in
NSMetadata.h

Overview

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:

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 setSearchScopes: to customize.

By default, notification of updated results occurs at 1.0 seconds. Use setNotificationBatchingInterval: to customize.

You must set a predicate with the setPredicate: method before starting a query.

Tasks

Creating Metadata Queries

Configuring Queries

Running Queries

Getting Query Results

Instance Methods

delegate

Returns the receiver’s delegate.

- (id<NSMetadataQueryDelegate>)delegate
Return Value

The receiver’s delegate, or nil if there is none.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

disableUpdates

Disables updates to the query results.

- (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.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

enableUpdates

Enables updates to the query results.

- (void)enableUpdates
Discussion

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

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

enumerateResultsUsingBlock:

Enumerates the current set of results using the given block.

- (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 re-enables it upon completion. Use enumerateResultsWithOptions:usingBlock: if you want to use concurrent or reverse iteration.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSMetadata.h

enumerateResultsWithOptions:usingBlock:

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

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

Options for the enumeration. You can

block

The block to execute for each current result.

Discussion

This method disables the query at the start of the iteration and re-enables it upon completion.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSMetadata.h

groupedResults

Returns an array containing hierarchical groups of query results based on the receiver’s grouping attributes.

- (NSArray *)groupedResults
Return Value

Array containing hierarchical groups of query results.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

groupingAttributes

Returns the receiver’s grouping attributes.

- (NSArray *)groupingAttributes
Return Value

Array containing grouping attributes.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

indexOfResult:

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

- (NSUInteger)indexOfResult:(id)result
Parameters
result

Query result object being inquired about.

Return Value

Index of result in the query result array.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

init

Initializes an allocated NSMetadataQuery object.

- (id)init
Return Value

An initialized NSMetadataQuery object.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

isGathering

Returns a Boolean value that indicates whether the receiver is in the initial gathering phase of the query.

- (BOOL)isGathering
Return Value

YES when the query is in the initial gathering phase; NO otherwise.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

isStarted

Returns a Boolean value that indicates whether the receiver has started the query.

- (BOOL)isStarted
Return Value

YES when the receiver has executed the startQuery method; NO otherwise.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

isStopped

Returns a Boolean value that indicates whether the receiver has stopped the query.

- (BOOL)isStopped
Return Value

YES when the receiver has stopped the query, NO otherwise.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

notificationBatchingInterval

Returns the interval that the receiver provides notification of updated query results.

- (NSTimeInterval)notificationBatchingInterval
Return Value

The interval at which notification of updated results occurs.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

operationQueue

The queue on which query result notifications will be posted.

- (NSOperationQueue *)operationQueue
Return Value

The queue on which query result notifications will be posted.

Discussion

For more information, see setOperationQueue:.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSMetadata.h

predicate

Returns the predicate the receiver uses to filter query results.

- (NSPredicate *)predicate
Return Value

The predicate used to filter query results.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

resultAtIndex:

Returns the query result at a specific index.

- (id)resultAtIndex:(NSUInteger)index
Parameters
index

Index of the desired result in the query result array.

Return Value

Query result at the position specified by index.

Discussion

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

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

resultCount

Returns the number of results returned by the receiver.

- (NSUInteger)resultCount
Return Value

The number of objects the query produced.

Discussion

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

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

results

Returns an array containing the result objects for the receiver.

- (NSArray *)results
Return Value

Proxy array containing query result objects.

Discussion

The results 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 you should instead use the resultCount and resultAtIndex: methods.

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

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

searchItems

The array of items to which a search is scoped.

- (NSArray *)searchItems
Return Value

An array of NSURL and/or NSMetadataItem objects to which the search is scoped.

Discussion

For more information, see setSearchItems:.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSMetadata.h

searchScopes

Returns an array containing the receiver’s search scopes.

- (NSArray *)searchScopes
Return Value

An array containing the receiver’s search scopes.

Discussion

The array can contain NSString or NSURL objects that represent file system directories or the search scopes specified in “Constants.” An empty array indicates that there is no limitation on where the receiver searches.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

setDelegate:

Sets the receiver’s delegate

- (void)setDelegate:(id<NSMetadataQueryDelegate>)delegate
Parameters
delegate

An object to serve as the receiver’s delegate. The delegate must implement the NSMetadataQueryDelegate Protocol protocol. Pass nil to remove the current delegate.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
NSMetadata.h

setGroupingAttributes:

Sets the receiver’s grouping attributes to specific attribute names.

- (void)setGroupingAttributes:(NSArray *)attributes
Parameters
attributes

Array containing attribute names.

Discussion

Invoking this method on a receiver while it’s running a query, stops the query and discards current results, and immediately starts a new query.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

setNotificationBatchingInterval:

Sets the interval between update notifications sent by the receiver.

- (void)setNotificationBatchingInterval:(NSTimeInterval)timeInterval
Parameters
Term

The Interval at which notification of updated results is to occur.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

setOperationQueue:

Sets the queue on which query result notifications will be posted to the given queue.

- (void)setOperationQueue:(NSOperationQueue *)operationQueue
Parameters
operationQueue

The queue on which query result notifications should be posted.

Discussion

You use this method to decouple 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.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSMetadata.h

setPredicate:

Sets the predicate used by the receiver to filter the query results.

- (void)setPredicate:(NSPredicate *)predicate
Parameters
predicate

A predicate to be used to filter query results.

Discussion

Invoking this method on a receiver running a query causes the existing query to stop, all current results are discarded, and a new query is started immediately.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

setSearchItems:

Scopes the search to the given array of items.

- (void)setSearchItems:(NSArray *)items
Parameters
items

An array of NSURL and/or NSMetadataItem objects to which to scope the search.

Discussion

You use this method to scope the metadata query to a given collection existing URLs and/or metadata items.

Availability
  • Available in iOS 7.0 and later.
Declared In
NSMetadata.h

setSearchScopes:

Restrict the search scope of the receiver.

- (void)setSearchScopes:(NSArray *)scopes
Parameters
scopes

Array of NSString or NSURL objects that specify file system directories. You can also include the predefined search scopes specified in “Constants.” An empty array removes search scope limitations.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

setSortDescriptors:

Sets the sort descriptors to be used by the receiver.

- (void)setSortDescriptors:(NSArray *)descriptors
Parameters
descriptors

Array of sort descriptors.

Discussion

Invoking this method on the receiver running a query causes the existing query to stop, all current results are discarded, and a new query is started immediately.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

setValueListAttributes:

Sets the value list attributes for the receiver to the specific attribute names.

- (void)setValueListAttributes:(NSArray *)attributes
Parameters
attributes

Array of value list attributes.

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.

Invoking this method on the receiver while it’s running a query, stops the query and discards current results, and immediately starts a new query.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

sortDescriptors

Returns an array containing the receiver’s sort descriptors.

- (NSArray *)sortDescriptors
Return Value

An array containing sort descriptors.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

startQuery

Attempts to start the query.

- (BOOL)startQuery
Return Value

YES when successful; NO otherwise.

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:

__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
}
Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

stopQuery

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

- (void)stopQuery
Discussion

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

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

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

valueListAttributes

Returns an array containing the value list attributes the receiver generates.

- (NSArray *)valueListAttributes
Return Value

Array containing value list attributes.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

valueLists

Returns a dictionary containing the value lists generated by the receiver.

- (NSDictionary *)valueLists
Return Value

Dictionary of NSMetadataQueryAttributeValueTuple objects.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

valueOfAttribute:forResultAtIndex:

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

- (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 setValueListAttributes:, as a sorting key in a specified sort descriptor, or as one of the grouping attributes specified set for the query.

index

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.

Availability
  • Available in iOS 5.0 and later.
Declared In
NSMetadata.h

Constants

Metadata Query Search Scopes

Constants for the predefined search scopes used by setSearchScopes:.

NSString * const NSMetadataQueryUbiquitousDocumentsScope;
NSString * const NSMetadataQueryUbiquitousDataScope;
Constants
NSMetadataQueryUbiquitousDocumentsScope

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

Available in iOS 5.0 and later.

Declared in NSMetadata.h.

NSMetadataQueryUbiquitousDataScope

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

Available in iOS 5.0 and later.

Declared in NSMetadata.h.

Content Relevance

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

NSString * const NSMetadataQueryResultContentRelevanceAttribute;
Constants
NSMetadataQueryResultContentRelevanceAttribute

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.

Declared in NSMetadata.h.

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.

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

Key to retrieve an array of items added to the query result.

Available in iOS 7.0 and later.

Declared in NSMetadata.h.

NSMetadataQueryUpdateChangedItemsKey

Key to retrieve an array of items that have changed in the query result.

Available in iOS 7.0 and later.

Declared in NSMetadata.h.

NSMetadataQueryUpdateRemovedItemsKey

Key to retrieve an array of items removed from the query result.

Available in iOS 7.0 and later.

Declared in NSMetadata.h.

Notifications

NSMetadataQueryDidFinishGatheringNotification

Posted when the receiver has finished with the initial result-gathering phase of the query.
Availability
Declared In
NSMetadata.h

NSMetadataQueryDidStartGatheringNotification

Posted when the receiver begins with the initial result-gathering phase of the query.
Availability
Declared In
NSMetadata.h

NSMetadataQueryDidUpdateNotification

Posted when the receiver’s results have changed during the live-update phase of the query.
Availability
Declared In
NSMetadata.h

NSMetadataQueryGatheringProgressNotification

Posted as the receiver’s is collecting results during the initial result-gathering phase of the query.
Availability
Declared In
NSMetadata.h