- 1 Query syntax help
Query syntax help
Conventions in this document
Queries are written in italics.
Example: rating GREATER 3
Query examples may contain placeholders which are enclosed in angle brackets. Their name indicates what should they need to be replaced with in 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 (e.g. artist) or a title formatting expression (e.g. "%artist%"). 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.
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 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).
Performs 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 – You can also enclose expressions in parentheses to control the evaluation order. Example: ( (artist IS blah) AND (title HAS blah) ) OR (rating GREATER 3)
- <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.
- All keywords (for example IS, HAS) must be written in upper-case.
- All search expressions, on the other hand, are non–case-sensitive. For example, artist HAS NAME will find tracks whose artist field is NAME, name, Name, and all other combinations of capital and small letters.
- Any expression that includes one or more of the reserved characters such as (, ), %, etc. should be wrapped in double quotation marks in order to have these used literally rather than as shortcuts to commands.
- <field> and <string> in HAS and IS expressions should be enclosed in double quotation marks (") if they include spaces. Example: "my favourite field or string" HAS my
- Accessing metadata fields can be simplified: If <field> in HAS, IS, GREATER, LESS, EQUAL does not include any of the characters #, $, or %, it will be treated as a metadata field. Example: artist IS Radiohead. However, this simplified method of formatting cannot be used to access/query technical information (such as codec specifications); or component-provided information: for that, the user must use title-formatting, as detailed below.
- In the rare event of complex syntax in which a search expression contains keywords in a way that could introduce ambiguity, enclose the search expression (and hence its embedded 'keywords') within double quotation marks. For example: artist IS "CONTRIVED EXAMPLE AND NOT" AND NOT releasetype IS Demo
- If <field> in HAS, IS, GREATER, LESS, or EQUAL includes at least one of the characters #, $, or %, it will be treated as a title formatting expression. That is: the title-formatting expression will be parsed, and its end-result will take its place, before the actual query is carried out.
- If spaces are likely to occur in the result, the title-formatting expression should be enclosed within double quotation marks ("), in line with the third point listed above in General.
- Double quotation marks should also be included around title-formatting expressions containing reserved characters, as noted in General above.
- Using title formatting expressions (e.g. "$meta(title)") instead of simple field names (e.g. title) will decrease search speed on large libraries and break multiple field value handling in the IS operator.
|AFTER||<time1> AFTER <time2>|
|AND||<expression1> AND <expression2>|
|BEFORE||<time1> BEFORE <time2>|
|DURING||<time1> DURING <time2>|
|DURING LAST||<time> DURING LAST <number> SECONDS/MINUTES/HOURS/DAYS/WEEKS <time> DURING LAST SECOND/MINUTE/HOUR/DAY/WEEK|
|EQUAL||<field> EQUAL <number>|
|GREATER||<field> GREATER <number>|
|HAS||<field> HAS <string> *HAS <string>|
|IS||<field> IS <string>|
|LESS||<field> LESS <number>|
|OR||<expression1> OR <expression2>|
|SINCE||<time1> SINCE <time2>|
|SORT BY||SORT BY <sort-pattern> SORT DESCENDING BY <sort-pattern>||Must be at the end of the query.|