NSMetadataQuery Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.4 and later.
Companion guide
File Metadata Search Programming Guide
Declared in
NSMetadata.h
Related sample code

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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
Declared In
NSMetadata.h

groupingAttributes

Returns the receiver’s grouping attributes.

- (NSArray *)groupingAttributes
Return Value

Array containing grouping attributes.

Availability
  • Available in OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
Declared In
NSMetadata.h

init

Initializes an allocated NSMetadataQuery object.

- (id)init
Return Value

An initialized NSMetadataQuery object.

Availability
  • Available in 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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
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 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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
Related Sample Code
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
Related Sample Code
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 OS X v10.4 and later.
See Also
Related Sample Code
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 OS X v10.4 and later.
See Also
Related Sample Code
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
Related Sample Code
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
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 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 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;
NSString * const NSMetadataQueryUbiquitousDocumentsScope;
NSString * const NSMetadataQueryUbiquitousDataScope;
Constants
NSMetadataQueryUserHomeScope

Search the user’s home directory.

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

Declared in NSMetadata.h.

NSMetadataQueryNetworkScope

Search all user-mounted remote volumes.

Available in OS X v10.4 and later.

Declared in NSMetadata.h.

NSMetadataQueryUbiquitousDocumentsScope

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

Available in OS X v10.7 and later.

Declared in NSMetadata.h.

NSMetadataQueryUbiquitousDataScope

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

Available in OS X v10.7 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 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
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


© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-10-12)

Did this document help you? Yes It's good, but... Not helpful...