File Metadata Query Expression Syntax
File metadata queries are constructed using a query language that is a subset of the predicate string format. The metadata search expression syntax allows an application to construct searches ‘on the fly’, allow advanced users to construct their own queries, or your application to store often used queries for easy use. The syntax is relatively straightforward, including comparisons, language agnostic options, and time and date variables.
The file metadata query expression syntax is a simplified form of filename globbing familiar to shell users. Queries have the following format:
attribute == value
attribute is a standard metadata attribute (see “File Metadata Attributes Reference”) or a custom metadata attribute defined by an importer.
For example, to query Spotlight for all the files authored by “Steve” the query would look like the following:
kMDItemAuthors ==[c] "Steve"
The available comparison operators are listed in Table 3-1.
Characters such as
‘ in the value string should be escaped using the
The search value in the example has the modifier “
c”. These are modifiers specify how the comparison is made. Table 3-2 describes the available comparison modifiers.
Search modifiers should immediately follow the comparison operator and be surrounded by square brackets
The comparison is case insensitive.
The comparison is insensitive to diacritical marks.
Table 3-3 shows several examples that use the comparison modifiers.
Using the wildcard characters (
? ) you can match substrings at the beginning of a string, end of a string, or anywhere within the string. Table 3-4 shows several common usages.
* character matches multiple characters whereas the
? wildcard character matches a single character.
Queries can be combined using a C-like syntax for
||). For example, to restrict a query to audio files authored by “Steve” the query would be:
kMDItemAuthors ==[c] "Steve" && kMDItemContentType == "public.audio"
Parenthesis can be used to further group query matching. For example, to search for audio files authored by “Steve” or “Daniel” the query would be:
(kMDItemAuthors ==[c] "Daniel" || kMDItemAuthors[c] == "Steve") &&
kMDItemContentType == "public.audio"
You can expand this search to include video files using the following query:
(kMDItemAuthors ==[c] "Daniel" || kMDItemAuthors ==[c] "Steve" ) &&
(kMDItemContentType == "public.audio" || kMDItemContentType == "public.video")
Time and Date Variables
You can also create queries that use the date and time as the search value. The date and time value is formatted as a floating-point value that is compatible with CFDate, seconds relative to January 1, 2001.
$time variable is provided that can be used to specify values relative to the current time, as shown in Table 3-5.
The current date and time.
The current date.
Dates in the previous week.
Dates in the current week.
Dates in the current month.
Dates in the current year.
The date and time by adding a positive or negative value, in seconds, to the current time.
The date by adding a positive or negative value, in days, to the current day
Dates by adding a positive or negative value, in weeks, to the current week.
Dates by adding a positive or negative value, in months, to the current month.
Dates by adding a positive or negative value, in years, to the current year.
The date by parsing the specified ISO-8601-STR compliant string.
$time variable you can restrict a search to find only files that have been changed in the last week using the following query:
((kMDItemAuthors ==[c] "Daniel" || kMDItemAuthors[c] == "Steve") &&
(kMDItemContentType == "public.audio" || kMDItemContentType == "public.video")) &&
(kMDItemFSContentChangeDate == $time.this_week(-1))