Query Syntax Help

Queries are written in italics.
Example: %rating% GREATER 3

Query examples may contain placeholders which are enclosed in angle brackets. Their name indicates what they need to be replaced within a real query. If multiple placeholders of the same type occur in the same query example, a number will be appended to the name.
Example: <field> GREATER <number>

The following common types of placeholders are used in the rest of this document:

• <field>
  A reference to a tag field. This can be either a plain field name or a title formatting expression. See Notes for details.
• <number>
  An integer value.
• <string>
  A text value that may be enclosed in double quotation marks. See Notes for details.
• <time>
  A time value or a title formatting expression that evaluates to a time value. See Time Expressions for details.
• <expression>
  A query expression in a composed query. This has to follow the rules described under Advanced Search below.

The simple search mode does not use any keywords.

• <any string>
  Returns only items that have all words from specified string in their metadata or file path.

When using the simple search, any latin characters are matched regardless of their accents, e.g. “foo” will match “foo” as well as “föö” or “fóo”.

The advanced search allows the construction of more complex queries. It offers several keywords to perform specific types of comparisons and to combine multiple query expressions.

• <field> HAS <string>
  Returns only items that have all words from <string> in a metadata field named <field>.
  Example: title HAS blah
• <field> IS <string>
  Returns only items where (at least one) metadata field <field> is equal to <string>.
  Example: artist IS blah
• * HAS <string>
  Same as simple search, but can be combined using logical operators (see below).

Perform integral number comparison between the value of a <field> and a <number>, e.g. ”%rating% GREATER 3”.

• <field> GREATER <number>
• <field> LESS <number>
• <field> EQUAL <number>

• <field> MISSING
  Returns only items that don't have a metadata field named <field>.
  Example: genre MISSING
• <field> PRESENT
  Returns only items that have a metadata field named <field>.
  Example: genre PRESENT

• <time1> BEFORE <time2>
  Returns only items where <time1> value is before <time2>.
  Example: %last_modified% BEFORE 2008
• <time1> AFTER <time2>
  Returns only items where <time1> value is after <time2>.
  Example: %last_modified% AFTER 2008
• <time1> SINCE <time2>
  Returns only items where <time1> value is not before <time2>.
  Example: %last_modified% SINCE 2007
• <time1> DURING <time2>
  Returns only items where <time1> value is a subset of <time2> period.
  Example: %last_modified% DURING 2007
• <time> DURING LAST <number> <time-unit>
  Returns items where <time> value is contained in the specified period.
  <time-unit> can be one of SECONDS, MINUTES, HOURS, DAYS, or WEEKS.
  Example: %last_modified% DURING LAST 2 WEEKS
  If <number> is 1, the expression can be simplified to <time> DURING LAST SECOND/MINUTE/HOUR/DAY/WEEK

Time values used in these expressions must be in one of the following formats: YYYY, YYYY-MM, YYYY-MM-DD, YYYY-MM-DD hh, YYYY-MM-DD hh:mm, YYYY-MM-DD hh:mm:ss.

• <expression1> AND <expression2>
  Returns only items where both expressions are true.
  Example: artist IS blah AND title HAS blah
  
• <expression1> OR <expression2>
  Returns only items where at least one expression is true.
• NOT <expression>
  Returns only items where the expression is false.
  Example: NOT %last_played% AFTER %first_played%

You can put a SORT BY operator at the end of your search expression to produce search results sorted by the specified title formatting pattern.

• SORT BY <sort-pattern>, SORT ASCENDING BY <sort-pattern>
  Sort results in ascending order.
• SORT DESCENDING BY <sort-pattern>
  Sort results in descending order.

• <field> and <string> in HAS and IS expressions should be enclosed in double quotation marks (”) if they include spaces or parentheses.
  
• If <field> in HAS, IS, GREATER, LESS, EQUAL includes at least one of #$% characters, it will be treated as a title formatting string.
  Example: %codec% IS MP3
• If <field> in HAS, IS, GREATER, LESS, EQUAL does not include any of #$% characters, it will be treated as a metadata field.
  Example: artist IS Radiohead
  Note that you can't access technical information (such as codec specifications) or component-provided information (playback statistics and such) this way.
• Using title formatting strings instead of simple field names will decrease search speed on large libraries and break multiple field value handling in the IS operator - for example, a track with two artist names: “name1” and “name2”, will be found by artist IS name1 query, but not by %artist% IS name1.
• To control the evaluation order of composed queries, enclose the individual expressions in parentheses.
  Example: ( (artist IS blah) AND (title HAS blah) ) OR (%rating% GREATER 3)
• All search expressions are not case-sensitive. All keywords must be uppercase.