---

NSMetadataQuery Class Reference

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:

• As individual attribute values for requested attributes.

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

• 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 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

• – init

Configuring Queries

• – searchScopes
• – setSearchScopes:
• – predicate
• – setPredicate:
• – sortDescriptors
• – setSortDescriptors:
• – valueListAttributes
• – setValueListAttributes:
• – groupingAttributes
• – setGroupingAttributes:
• – notificationBatchingInterval
• – setNotificationBatchingInterval:
• – delegate
• – setDelegate:

Running Queries

• – isStarted
• – startQuery
• – isGathering
• – isStopped
• – stopQuery

Getting Query Results

• – resultCount
• – resultAtIndex:
• – results
• – groupedResults
• – indexOfResult:
• – valueLists
• – metadataQuery:replacementObjectForResultObject:  delegate method
• – valueOfAttribute:forResultAtIndex:
• – metadataQuery:replacementValueForAttribute:value:  delegate method
• – enableUpdates
• – disableUpdates

Instance Methods

delegate

Returns the receiver’s delegate.

- (id)delegate

Return Value

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setDelegate:

Declared In

NSMetadata.h

disableUpdates

Disables updates to the query results.

- (void)disableUpdates

Discussion

You should invoke this method before iterating over query results that could change due to live updates.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – enableUpdates

Declared In

NSMetadata.h

enableUpdates

Enables updates to the query results.

- (void)enableUpdates

Discussion

You should invoke this method after you’re done iterating over the query results.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – disableUpdates

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 Mac OS X v10.4 and later.

See Also

• – groupingAttributes
• – setGroupingAttributes:

Declared In

NSMetadata.h

groupingAttributes

Returns the receiver’s grouping attributes.

- (NSArray *)groupingAttributes

Return Value

Array containing grouping attributes.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setGroupingAttributes:

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 Mac OS X v10.4 and later.

See Also

• – resultAtIndex:

Declared In

NSMetadata.h

init

Initializes an allocated NSMetadataQuery object.

- (id)init

Return Value

An initialized NSMetadataQuery object.

Availability

• Available in Mac OS X v10.4 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 Mac OS X v10.4 and later.

See Also

• – isStarted
• – isStopped
• – startQuery

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 Mac OS X v10.4 and later.

See Also

• – isGathering
• – isStopped
• – startQuery

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 Mac OS X v10.4 and later.

See Also

• – isGathering
• – isStarted
• – stopQuery

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 Mac OS X v10.4 and later.

See Also

• – setNotificationBatchingInterval:

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 Mac OS X v10.4 and later.

See Also

• – setPredicate:

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 they array returned by results.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – indexOfResult:

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 Mac OS X v10.4 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.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – groupedResults

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 Mac OS X v10.4 and later.

See Also

• – setSearchScopes:

Declared In

NSMetadata.h

setDelegate:

Sets the receiver’s delegate

- (void)setDelegate:(id)delegate

Parameters

delegate

An object to serve as the receiver’s delegate. Pass nil to remove the current delegate.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – delegate

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 Mac OS X v10.4 and later.

See Also

• – groupingAttributes

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 Mac OS X v10.4 and later.

See Also

• – notificationBatchingInterval

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 Mac OS X v10.4 and later.

See Also

• – predicate

Declared In

NSMetadata.h

setSearchScopes:

Resctrict 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 Mac OS X v10.4 and later.

See Also

• – searchScopes

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 Mac OS X v10.4 and later.

See Also

• – sortDescriptors

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 attributess 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 Mac OS X v10.4 and later.

See Also

• – valueListAttributes

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 Mac OS X v10.4 and later.

See Also

• – setSortDescriptors:

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.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – stopQuery
• – isStarted

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 Mac OS X v10.4 and later.

See Also

• – startQuery
• – isStopped

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 Mac OS X v10.4 and later.

See Also

• – setValueListAttributes:

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 Mac OS X v10.4 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 Mac OS X v10.4 and later.

Declared In

NSMetadata.h

Delegate Methods

metadataQuery:replacementObjectForResultObject:

Implemented by the delegate to return a different object for a specific query result object.

- (id)metadataQuery:(NSMetadataQuery *)query replacementObjectForResultObject:(NSMetadataItem *)result

Parameters

query

The query that produced the result object to replace.

result

The query result object to replace.

Return Value

Object that replaces the query result object.

Discussion

By default query result objects are instances of the NSMetadataItem class. By implementing this method, you can return an object of a different class type for the specified result object.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSMetadata.h

metadataQuery:replacementValueForAttribute:value:

Implemented by the delegate to return a different value for a specific attribute.

- (id)metadataQuery:(NSMetadataQuery *)query replacementValueForAttribute:(NSString *)attribute value:(id)attributeValue

Parameters

query

The query that produced the result object with attribute.

attribute

The attribute in question.

attributeValue

The attribute value to replace.

Return Value

Object that replaces the value of attribute in the result object

Discussion

The delegate implementation of this method could convert specific query attribute values to other attribute values, for example, converting date object values to formatted strings for display.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSMetadata.h

Constants

Metadata Query Search Scopes

Constants for the predefined search scopes used by setSearchScopes:.

NSString * const NSMetadataQueryUserHomeScope;
NSString * const NSMetadataQueryLocalComputerScope;
NSString * const NSMetadataQueryNetworkScope;

Constants

NSMetadataQueryUserHomeScope

Search the user’s home directory.

Available in Mac OS X v10.4 and later.

Declared in NSMetadata.h.

NSMetadataQueryLocalComputerScope

Search all local mounted volumes, including the user home directory. The user’s home directory is searched even if it is a remote volume.

Available in Mac OS X v10.4 and later.

Declared in NSMetadata.h.

NSMetadataQueryNetworkScope

Search all user-mounted remote volumes.

Available in Mac OS X v10.4 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 Mac OS X v10.4 and later.

Declared in NSMetadata.h.

Notifications

NSMetadataQueryDidFinishGatheringNotification

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

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSMetadata.h

NSMetadataQueryDidStartGatheringNotification

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

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSMetadata.h

NSMetadataQueryDidUpdateNotification

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

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSMetadata.h

NSMetadataQueryGatheringProgressNotification

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

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSMetadata.h

---