---

Introduction to Spotlight Query Programming Guide

Contents:

Who Should Read This Document
Organization of This Document
See Also

Spotlight provides several application programming interfaces that allow your application to search for files based on metadata. The level of interaction your application requires with the search results will often dictate the API that you chose.

The simplest way to provide Spotlight support in your application 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 Spotlight 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. NSMetadataQuery supports Cocoa bindings, allowing you to display the results without writing any significant amount of glue code. As well, NSMetadataQuery 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.

Who Should Read This Document

Spotlight is a fundamental feature of Mac 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:

• “Querying Metadata With Spotlight” provides a conceptual overview of searching for files using Spotlight.

• “Displaying the Spotlight Search Window” describes how to present the standard Spotlight search window.

• “Query Expression Syntax” provides a description of Spotlight’s query language.

See Also

There are other technologies, not fully covered in this document, that are fundamental to integrating metadata into your applications. Refer to these documents for more details:

• Spotlight Overview covers the conceptual details surrounding Spotlight’s metadata usage.

• Spotlight Importer Programming Guide describes the plug-ins that extract metadata from document files.

• Spotlight Metadata Attributes Reference describe the metadata attributes provided by Apple.

---