- Spotlight Programming
- Spotlight
- Definition
- Spotlight is a fast, extensible, desktop search technology that allows users to organize and search for files based on metadata.
- Technologies
- Database ("Spotlight Store")
- meta-data store
- content index
- one per filesystem
- Query API
- Importer plugins
- Plugin API
- Concepts
- Metadata
- Attribute / Value
- Metadata attribute
- predefined
- File system
- Image related
- Video related
- Audio related
- "common" attributes
- author
- city
- email
- organization
- ...
- Special Attributes
- kMDItemPath
- "expensive" attribute,
- retrievable, but not use in query
- lMDItemTextContent
- use in query but not retrievable
- Spotlight Metadata Attributes Reference
- custom
- Properties
- name
- Naming Convention
- reverse DNS naming with _ instead of .
- (Value Object) type
- CFString
- CFNumber
- CFBoolean
- CFDate
- multivalue
- uniqued
- used when a very small number of values is possible
- nosearch
- attribute only searched when specifically declared
- ignored in wildcard searches
- Display Name
- Description
- Metadata attribute value
- Localizable
- Dictionary object instead of String
- Command Line Tools
- mdfind
- finds files matching a given query
- Example
- Find all files with any metadata attribute value matching the string "image"
- Find all files that contain "MyFavoriteAuthor" in the kMDItemAuthor metadata attribute
- mdfind "kMDItemAuthor == '*MyFavoriteAuthor*'"
- Find all images containing "apple", using the Spotlight menu syntax
- mdfind -interpret "apple kind:image"
- Does not seem to perform localization, i.e.
mdfind -interpret "apple Art:Bilder"
does not work on a german system.
- Find "live" all files with any metadata attribute value matching the string "skateboard"
- mdfind -live skateboard
- The find continues to run after gathering the initial results, providing a count of the number of files that match the query.
- developer.apple.com > Documentation > Darwin > Reference > ManPages > Man1 > Mdfind.1
- mdimport
- mdls
- mdutil
- mdcheckschema
- Query
- Defining a query
- Query Expression Syntax
- Using MDQuery
- Using NSMetadataQuery
- Use NSPredicate
- Sorting
- "value list attributes"
- Scope
- URLs
- directory pathes
- predefined locations
- user's home directory
- locally mounted volumes
- remotely mounted volumes
- Result items: NSMetadataItem
- Running a query
- 1. Initial results gathering
- 2. Live-update of results
- Using the result
- Disable updates while accessing the result
- Customize result using callbacks
- Spotlight Importer
- Plugin-bundle to extract metadata information from files
- located in
- in application's bundle at MyApp.app/Contents/Library/Spotlight
- ~/Library/Spotlight
- /Library/Spotlight
- Framework/PlugIn
- System provided importers in: /System/Library/Spotlight
- Custom document formats need their own importer
- Associated through uniform type identifiers (UTIs)
- Templates for CFPlugin project and schema file in Xcode
- Additional Guidelines
- Don't store metadata in external files
- metadata in the same file as data
- System store of metadata "volatile"
- Import without user interaction
- Import when application not running
- User should be able to know/control metadata extracted/stored/searched
- e.g. personal information
- Schema.xml
- Use Xcode's Spotlight Plug-In template to create an import plug-in.
The template will generate a unique PLUGIN_ID (UUID) for your importer.
- Performance
- Extract metadata quickly and minimal effort
- Consider this when designing the file format
- No memory leaks
- Links
- The "Spotlight menu" Query Syntax
- Syntax Elements
- “AND” “NOT” “OR”
- ( ... )
- "..."
- attributeName:....
- e.g. kind:music
- name is localized. E.g. in Germany "Art:Musik"
- name is case sensitive
- (i.e. "art:Musik" will not work, but "Art:Musik")
- For a complete list checkout
- en
- /System/Library/Frameworks/CoreServices.framework/Frameworks /Metadata.framework/Resources/English.lproj/schema.string
- de
- /System/Library/Frameworks/CoreServices.framework/Frameworks /Metadata.framework/Resources/German.lproj/schema.string
- For dates special values are defined
- this week,
this month,
this year;
today,
yesterday,
tomorrow;
next week,
next month,
next year
- "<" ">" "-"
- date:>1/1/07 will find any file modified after January 1, 2007. (The dates you enter must correspond to the short date format you have set in your International preferences.)
date:<12/31/07 will find any file modified before December 31, 2007.
date:1/1/07-12/31/07 will find files modified between those two dates.
- "mdfind -interpret ..." also uses this syntax
- Spotlight Usage Tips
- cmd-option-Space
- cmd-Space
- Open Spotlight menu
- Return
- Open selected file in Finder
- option-Return
- Show all results in Finder
- cmd-Return
- Show selected file in Finder
- cmd-F
- Open Spotlight search (from Finder). Only search Files and Folders, not other Spotlight items
- cmd-F, cmd-F
- Second search directory is Home (not current directory)
- cmd-shift-F
- Change the dictionary used for Spotlight definitions
- macosxhints.com > Article ? ...
- The first dictionary found in the Dictionary.app (Lexikon) preferences is used
- For a German-English dictionary checkout BeoLingus
- Spotlight and Timemachine
- Exclude backup volume from Spotlight
- Spotlight and "other" Backups
- Exclude backup volume from Spotlight
- Make sure, Backup does not overwrite .Spotlight-V100 directory on backup volume
- Change the default Spotlight Preview zoom level
- Run Spotlight searches based on Finder labels
- To find files by label with Spotlight, or in the Finder's find box, type label:1 (or any other number up to 7). The numbers don't seem to correspond exactly to the order in the Finder; but you can see them by doing mdls on files. Here's how each number corresponds to one of the Finder's label colors: 0 - None 1 - Gray 2 - Green 3 - Purple 4 - Blue 5 - Yellow 6 - Red 7 - Orange The actual key name is kMDItemFSLabel in the mdls output.
- macosxhints.com > Article ? ...
- Add some "other" search attributes to the menu
- System files - Include system Files, preference files, plug-ins, etc...
- Spotlight items - Includes contacts, email, calendars, bookmarks, etc...
- option-Click on (+) in Search rules row
- adds an "Any/All/None" subgroup row
- Can be nested
- build complex boolean expressions
- (+) becomes (…)
- Build-in calculator
- Start programs
- Add easy to recall words to Spotlight comment if you always forget the apps name
- Use 'mdfind -s path' to show contents of smart folder
- Only documented in "usage" text when running mdfind without parameter
- Sample Code
- Developer/Examples/AppKit/Spotlighter
- sample application demonstrating how to use the Cocoa NSMetadataQuery to access the new Spotlight feature in Mac OS 10.4 Tiger
- Developer/Examples/Metadata
- ImporterExample
- provide a complete example of how to write a metadata importer, along with declaring a UTI for your document as part of your application project.
- SampleImporter
- an example importer dealing with Application bundle meta information.
- Written in C (not Objective-C)
- http://developer.apple.com/samplecode/SpotlightAPI/
- Some small sample programs that Show how to use the Spotlight API in your programs.
- MDItemREf uses MDItemRef to get metadata for a file dragged into the window.
- MDQueryRef1 does a query using MDQuery
- developer.apple.com > Samplecode > SpotlightAPI
- http://developer.apple.com/samplecode/Spotlight
- Sample code that shows how to write Spotlight Importers.
- a simple Spotlight importer for the old IFF image file format
- a Spotlight importer that shows how to define new attributes
- a Spotlight importer that shows how to deal with a package based file format
- developer.apple.com > Samplecode > Spotlight
- http://developer.apple.com/samplecode/SpotlightFortunes
- Demonstrates how to provision a Spotlight importer plug-in for a custom UTI, and how to use a NSMetadataQuery with bindings to display live query results in a table view.
- This sample was inspired by the classic Unix fortune program. Instead of reading entries from a monolithic .fortunes file, it uses Spotlight to find all files with the com.example.fortune-file UTI and displays them in a Cocoa table view. Since the focus of this sample is Spotlight's live query support, only minimal support for creating new fortune files is provided.
- developer.apple.com > Samplecode > SpotlightFortunes
- http://developer.apple.com/samplecode/PredicateEditorSample
- demonstrates how to use the NSPredicateEditor class. The NSPredicateEditor class is a subclass of NSRuleEditor that is specialized for editing NSPredicate objects. This sample is intended to show how to use the many different features and aspects of this control and leverages Spotlight to search your Address Book.
- developer.apple.com > Samplecode > PredicateEditorSample > Index
- http://developer.apple.com/samplecode/PhotoSearch/
- http://developer.apple.com/samplecode/SBSetFinderComment
- Set/Get Finder Comments using Scripting Bridge
- http://developer.apple.com/samplecode/WhackedTV/
- http://developer.apple.com/samplecode/DepartmentAndEmployees/listing4.html
- extract useful information from the file formats for your document, and set the values into the attribute dictionary for Spotlight to include
- http://developer.apple.com/samplecode/CoreRecipes/listing29.html
- use Spotlight to find the other Core Recipes store files on the disk (to load into the "Imported" section of the view.) Here we set up a predicate to match the UTI type (the content type of the file), and then start a metadata query with it. We get notifications each time the content changes.
- http://developer.apple.com/samplecode/iSpend/
- References
- Apple
- Working with Spotlight (Tiger Developer Overview Series)
- Spotlight Overview
- Spotlight Query Programming Guide
- Spotlight Metadata Attributes Reference
- Spotlight Importer Programming Guide
- Spotlight Reference Collection
- Where does Spotlight search?
- All Home folders (local and network-based, as well as FileVault and non-FileVault). This includes:
The Documents, Movies, Music, and Pictures folders
The Trash of all users and each mounted volume.
~/Library/Metadata/
~/Library/Caches/Metadata/
~/Library/Mail/
~/Library/Caches/com.apple.AddressBook/Metadata/
~/Library/PreferencePanes/
Spotlight also searches these non-Home folder locations by default:
/Library/PreferencePanes/
/System/Library/PreferencePanes/
/Applications
- support.apple.com > Kb > TA23187
- Spotlight Plugins (Downloads)
- Search Kit Programming Guide
- Third Party
- Spotlight tips (The X Lab)
- Spotlight Strikes Back: In Leopard, It Works Great
- Spotlight’s Secret Search Syntax
- Chapter "Advanced Spotlight Menu Searches", OS X 10.5 Missing Manual, David Pogue (excerpt)
- Programming with Spotlight (MacDevCenter.com)
- Leopard - Optimizing Spotlight Search
- Copyright 2009, Udo Borkowski, Aachen