Query Expression Syntax

Spotlight’s query expresion syntax is a simplified form of filename globbing familiar to shell users. Queries have the following format:

attribute == value

where attribute is a Spotlight metadata attribute (see “Spotlight 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 == "Steve"wc

The available comparison operators are listed in Table 1.

**Table 1** Comparison operators
Operator	Description
`==`	equal
`!=`	not equal
`<`	less than (available for numeric values and dates only)
`>`	greater than (available for numeric values and dates only)
`<=`	less than or equal (available for numeric values and dates only)
`>=`	greater than or equal (available for numeric values and dates only)
inRange(attributeName,minValue,maxValue)	numeric values within the range of minValue through maxValue in the specified attributeName

Characters such as " and ‘ in the value string should be escaped using the \ character.

The search value in the example has the suffix “wc”. These are modifiers that specify how the Comparison is made. Table 2 describes the available Comparison modifiers.

**Table 2** Value Comparison modifiers
Modifier	Description
`c`	The Comparison is case insensitive.
`d`	The Comparison is insensitive to diacritical marks.
`w`	The Comparison is word based, and also detects transitions from lower-case to upper-case.

Table 3 shows several examples that use the Comparison modifiers.

**Table 3** Value Comparison modifier examples
Search value	Results
"Paris"	Matches “Paris” but not “paris” nor “I love Paris”.
"Paris"c	Matches “Paris”, “paris”, but not “I love Paris”.
"Paris"wc	Matches “Paris”, “paris”, “I love Paris”, “paris-france.jpg”, but not “Comparison”.
"Window"w	Matches “MyWindowClass” and “Broken Window”, but not “NSWindow”.
"Frédéric"	Matches “Frédéric” but not “Frederic”.
"Frédéric"cd	Matches “Frédéric” and “Frederic” regardless of the word case.

Using the wildcard character (*) you can match substrings at the beginning of a string, end of a string, or anywhere within the string. Table 4 shows several common usages.

**Table 4** Using wildcards
Value	Result
"paris*"	Matches attribute values that begin with “paris”. For example, matches “paris” and “parisol”, but not “comparison”.
"*paris"	Matches attribute values that end with “paris”.
"paris"	Matches attributes that contain "paris" anywhere within the value. For example, matches “paris”, “parisol” and “Comparison”.
"paris"	Matches attribute values that are exactly equal to “paris”.

Note: Typically, queries should use the “w” modifier to do smart word matching rather than relying on the wildcard character.

Queries can be combined using a C-like syntax for AND (&&) and OR (||). For example, to restrict a Spotlight query to audio files authored by “Steve” the query would be:

kMDItemAuthors == "Steve"wc && kMDItemContentType == "audio"wc

Parenthesis can be used to further group query matching. For example, to search for audio files authored by “Steve” or “Kevin” the query would be:

(kMDItemAuthors == "Kevin"wc || kMDItemAuthors == "Steve"wc) &&

 kMDItemContentType == "audio"wc

You can expand this search to include video files using the following query:

(kMDItemAuthors == "Kevin"wc || kMDItemAuthors == "Steve"wc ) &&

 (kMDItemContentType == "audio"wc || kMDItemContentType == "video"wc )

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.

Additionally, the $time variable is provided that can be used to specify values relative to the current time, as shown in Table 5.

**Table 5** $time variable expressions
Time variable	Description
`$time.now`	The current date and time.
`$time.today`	The current date.
`$time.yesterday`	Yesterday’s date.
`$time.last_week`	Dates in before this week.
`$time.this_week`	Dates in the current week.
`$time.this_month`	Dates in the current month.
`$time.this_year`	Dates in the current year.
`$time.now(NUMBER)`	The date and time by adding a positive or negative value, in seconds, to the current time.
`$time.today(NUMBER)`	The date by adding a positive or negative value, in days, to the current day
`$time.this_week(NUMBER)`	Dates by adding a positive or negative value, in weeks, to the current week.
`$time.this_month(NUMBER)`	Dates by adding a positive or negative value, in months, to the current month.
`$time.this_year(NUMBER)`	Dates by adding a positive or negative value, in years, to the current year.
`$time.iso(ISO-8601-STR)`	The date by parsing the specified ISO-8601-STR compliant string.

Using the $time variable you can restrict a search to find only files that have been changed in the last week using the following query:

((kMDItemAuthors == "Kevin"wc || kMDItemAuthors = "Steve"wc) &&

 (kMDItemContentType == "audio"wc || kMDItemContentType = "video"wc)) &&

 (kMDItemFSContentChangeDate > $time.last_week)

Note: The value of the $time variable is set when the query is first executed. It does not update to the current time as the query continues to run.

< Previous PageNext Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.