About File Metadata Queries

File metadata provides several application programming interfaces that allow it application to search for files based on data that is part of the file or file system. The level of interaction your application requires with the search results will often dictate the API that you chose.

The simplest way to provide metadata support in your Mac app is to use the Spotlight search window. Using this API an application can display the standard Spotlight search window, optionally providing a search string. The search results are presented directly to the user and are not available to the application. This is a good choice if your application isn't search oriented, but you want to allow users to search for contextual terms using Spotlight.

For applications that need to create queries and interact with the results there are two APIs available. The Metadata framework provides a low-level query API, MDQuery, that allows an application to search for files based on metadata values. MDQuery is completely configurable, allowing you to run synchronous and asynchronous queries and provides fine-grain control of the frequency of results batching.

The Cocoa frameworks's NSMetadataQuery class provides a high-level Objective-C interface to the MDQuery API. This class allows you to construct queries using a subset of the NSPredicate classes, and execute the queries asynchronously. The NSMetadataQuery class allows an application to specify the grouping of the results into multiple subcategories. NSMetadataQuery does not support synchronous queries and provides minimal update notifications as data is collected. On OS X NSMetadataQuery supports Cocoa bindings, allowing you to display the results without writing any significant amount of glue code.

Who Should Read This Document

Spotlight is a fundamental feature of OS X, and all developers should be familiar with its capabilities. Many applications, at a minimum, should offer users the ability to search for selected text using the Spotlight search window.

Organization of This Document

The following articles cover key concepts in understanding how Spotlight can be used to query metadata:

• Searching File Metadata with NSMetadataQuery provides a conceptual overview of searching for files using file metadata.

• Displaying the Finder’s Spotlight Search Window describes how to present the standard Spotlight search window.

• File Metadata Query Expression Syntax describes the metadata query language.