Difference between revisions of "Foobar2000:Query syntax"

From Hydrogenaudio Knowledgebase
Jump to: navigation, search
m (Guidelines: :S)
(Summary of operators: comment about the NOT query)
 
(11 intermediate revisions by 5 users not shown)
Line 1: Line 1:
=Query syntax help=
+
This page details the syntax that can be used to query for files within the Media Library in [[Foobar2000:Foobar2000|foobar2000]].
  
This page details the syntax that can be used to query for matching files in [[Foobar2000:Foobar2000|foobar2000]]. For a list of the actual fields that can be queried with this, see the [[Foobar2000:Title_Formatting_Reference|title-formatting reference]] page.
+
For a list of fields and functions that can be used in query syntax, see the [[Foobar2000:Title_Formatting_Reference|title-formatting reference]].
  
 
==Conventions in this document==
 
==Conventions in this document==
  
Queries are written in ''italics''.
+
===Formatting===
 +
Query syntax includes various keywords, also called operators, which invoke specific behaviours. These must be typed in caps, for example DURING.
  
Example: ''rating GREATER 3''  
+
To aid readability, in the following descriptions and examples, example queries (or fragments thereof) that the user could type into foobar2000 are written in ''italics''. In addition, operators are written in '''bold'''. Such formatting is for readability only and need not/cannot be typed in foobar2000 itself.
+
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>''  
+
===Placeholders===
 +
Query examples may contain placeholders which are enclosed in angle brackets. Their names indicate what they should 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:  
+
The following common placeholders are used throughout 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 [[Foobar2000:Query_syntax#Notes|Notes]] for details.
+
* <field> – A reference to a field within the tags of files in the Media Library. This can be either a plain field name (e.g. artist) or a title formatting expression (e.g. "%artist%"). See the [[Foobar2000:Query_syntax#Guidelines|Guidelines]] below for details on these two methods of accessing fields.
* ''<number>'' – An integer value.
+
* <number> – An integer value (whole number).
* ''<string>'' – A text value that may be enclosed in double quotation marks. See [[Foobar2000:Query_syntax#Notes|Notes]] for details.
+
* <string> – A text value, which may be enclosed in double quotation marks. See the Guidelines for details.
* ''<time>'' – A time value or a title formatting expression that evaluates to a time value. See [[Foobar2000:Query_syntax#Time Expressions| Time Expressions]] for details.
+
* <time> – A time value or a title-formatting expression that evaluates to a time value. See [[Foobar2000:Query_syntax#Time Expressions| Time Expressions]] below for details.
* ''<expression>'' – A query expression in a composed query. This has to follow the rules described under [[Foobar2000:Query_syntax#Advanced Search|Advanced Search]] below.
+
* <expression> – A query expression in a composed query. This has to follow the rules described under [[Foobar2000:Query_syntax#Advanced Search|Advanced Search]] below.
  
 
==Simple search==
 
==Simple search==
The simple search mode does not use any keywords.  
+
The simple search mode does not use any keywords or functions: it is only used to search for a literal string within the Library.
* ''<any string>'' – Returns only items that have all words from specified string in their metadata or file path.
+
* ''<any string>'' – Returns only items that have all words from the specified string within their metadata and/or file path.
  
 
==Advanced search==
 
==Advanced search==
Line 28: Line 29:
  
 
===Text expressions===
 
===Text expressions===
* ''<field> HAS <string>'' – Returns only items that have all words from ''<string>'' in metadata field named ''<field>''. Example: ''title HAS blah''
+
* ''<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''
+
* ''<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).
+
* '''''*HAS''' <string> – Same as simple search, but can be combined using logical operators (see below).
 +
* '''''ALL''''' - No operators can be used. This single keyword simply returns all items within the Media Library.
  
 
===Numeric expressions===
 
===Numeric expressions===
Performs integral number comparison between the value of a ''<field>'' and a ''<number>'', e.g. "''rating GREATER 3''".
+
Performs integral number comparison between the value of a <field> and a <number>. For example: ''rating '''GREATER''' 3''
* ''<field> GREATER <number>''
+
* ''<field> '''GREATER''' <number>''
* ''<field> LESS <number>''
+
* ''<field> '''LESS''' <number>''
* ''<field> EQUAL <number>''
+
* ''<field> '''EQUAL''' <number>''
  
 
===Metadata expressions===
 
===Metadata expressions===
* ''<field> MISSING'' – Returns only items that don't have a metadata field named ''<field>''. Example: ''genre MISSING''
+
* ''<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''
+
* ''<field> '''PRESENT''''' – Returns only items that have a metadata field named <field>. Example: ''genre '''PRESENT'''''
  
 
===Time expressions===
 
===Time expressions===
* ''<time1> BEFORE <time2>'' – Returns only items where ''<time1>'' value is before ''<time2>''. Example: ''last_modified BEFORE 2008''
+
* ''<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> '''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> '''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''
+
* ''<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> '''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''''' (choose one).
 
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.
 
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.
  
===Composed queries===
+
===Combined queries using logical operators===
* ''<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)''
+
Several logical operators are available so that the user can search for items that match (or do not match) various criteria in combination. To create more complex logical queries, parentheses () can be used to enclose parts of the query to ensure that they are evaluated in the correct order (much like parentheses in mathematics).
* ''<expression1> OR <expression2>'' – Returns only items where at least one expression is true.
+
* ''<expression1> '''AND''' <expression2> – Returns only items where both expressions are true. Example: ''artist '''IS''' blah '''AND''' title '''HAS''' blah''
* ''NOT <expression>'' – Returns only items where the expression is false. Example: ''NOT last_played AFTER first_played''
+
* ''<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 enclose expressions in parentheses to control the order in which logical expressions are evaluated. Example: ''( (artist '''IS''' blah) '''AND''' (title '''HAS''' blah) ) '''OR''' (rating '''GREATER''' 3)''
 +
* To obtain an exclusive-or (XOR/EOR), which is positive if only one expression is true but not both, you can use this: ''(<expression1> '''OR''' <expression2>) '''AND''' '''NOT''' (<expression1> '''AND''' <expression2>)''
  
 
==Sorting results==
 
==Sorting results==
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.  
+
You can put a '''SORT''' '''BY''' operator at the end of your search expression to have the results from the preceding quiery sorted by the specified title-formatting pattern.  
* ''SORT BY &lt;sort-pattern&gt;'', ''SORT ASCENDING BY &lt;sort-pattern&gt;'' – Sort results in ascending order.
+
* '''''SORT''' '''BY''' &lt;sort-pattern&gt; / '''''SORT''' '''ASCENDING''' '''BY''' &lt;sort-pattern&gt; – Sort results in ascending order.
* ''SORT DESCENDING BY &lt;sort-pattern&gt;'' – Sort results in descending order.
+
* '''''SORT''' '''DESCENDING''' '''BY''' &lt;sort-pattern&gt;'' – Sort results in descending order.
  
 
==Guidelines==
 
==Guidelines==
 
===General===
 
===General===
 
====Case-sensitivity====
 
====Case-sensitivity====
*All keywords (for example ''IS'', ''HAS'') must be written in upper-case.
+
*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.
+
*All search expressions, on the other hand, are non–case-sensitive. For example, ''artist '''HAS''' name'' will find tracks whose ''artist'' field equals "NAME", "name", "Name", and all other combinations of capital and small letters.
 +
*To achieve a case-sensitive comparison between two parameters, use ''"$strcmp(%field%,string)" '''EQUAL''' 1'' and so on. For more information about how to use title-formatting within query syntax, see the relevant section below.
 +
 
 
====Double quotation marks====
 
====Double quotation marks====
*''&lt;field&gt;'' and ''&lt;string&gt;'' in HAS and IS expressions should be enclosed in double quotation marks (") if they include spaces. Example: ''"my favourite field or string" HAS my''
+
*&lt;field&gt; and &lt;string&gt; in HAS and IS expressions should be enclosed in double quotation marks (") if they include spaces. Example: ''"my favourite field or string" HAS my''
*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''
+
*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''' "MY BAND IS CALLED AND NOT" '''AND''' '''NOT''' releasetype '''IS''' Demo''
 
====Simplified access to metadata fields====
 
====Simplified access to metadata fields====
*Accessing metadata fields can be simplified: If ''&lt;field&gt;'' 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.
+
Accessing metadata fields can be simplified: If &lt;field&gt; 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.
 +
====Comparing two metadata fields====
 +
As noted above, operators such as '''IS''' compare a field (on the left) to a string (on the right). If the user wishes, instead, to compare one field to another field, this can be done using title-formatting. Example: ''"$strcmp(%field1%,%field2%)" '''EQUAL''' 1''
  
 
===Title-formatting===
 
===Title-formatting===
*If ''&lt;field&gt;'' in ''HAS'', ''IS'', ''GREATER'', ''LESS'', or ''EQUAL'' includes at least one of the characters #, $, or %, it will be treated as a [[Foobar2000:Title Formatting Reference|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 &lt;field&gt; in a (sub-)query using '''HAS''', '''IS''', '''GREATER''', '''LESS''', or '''EQUAL''' includes at least one of the characters #, $, or %, it will be treated as a [[Foobar2000:Title Formatting Reference|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.
+
*If spaces are likely to occur in the result, the title-formatting expression should be enclosed within double quotation marks ("), in line with the guidance given above in General.
*Double quotation marks should also be included around title-formatting expressions that use parentheses, such as ''$info(codec)''
+
*Double quotation marks should also be included around title-formatting expressions that use parentheses. This necessarily includes all functions, for example $meta(field) or $info(codec). Doing this removes ambiguity that might result because parenthesis are used natively by query syntax to specify the order of evaluation of logical expressions, as described under the relevant section 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.
+
*Using title formatting expressions to access metadata fields (e.g. "$meta(title)") instead of simple field names (e.g. title) will decrease the speed of queries performed upon large libraries and will break handling of multi-value fields by the operator '''IS'''.
  
==Operator summary==
+
==Summary of operators==
 
{| border="1"
 
{| border="1"
 
|-
 
|-
Line 84: Line 93:
 
! Comment  
 
! Comment  
 
|-
 
|-
| ''AFTER''  
+
| '''AFTER'''
| ''&lt;time1&gt; AFTER &lt;time2&gt;''  
+
| ''&lt;time1&gt; '''AFTER''' &lt;time2&gt;''
 
|  
 
|  
 
|-
 
|-
| ''AND''  
+
| '''AND'''  
| ''&lt;expression1&gt; AND &lt;expression2&gt;''  
+
| ''&lt;expression1&gt; '''AND''' &lt;expression2&gt;''
 
|  
 
|  
 
|-
 
|-
| ''BEFORE''  
+
| '''BEFORE'''
| ''&lt;time1&gt; BEFORE &lt;time2&gt;''  
+
| ''&lt;time1&gt; '''BEFORE''' &lt;time2&gt;''
 
|  
 
|  
 
|-
 
|-
| ''DURING''  
+
| '''DURING'''
| ''&lt;time1&gt; DURING &lt;time2&gt;''  
+
| ''&lt;time1&gt; '''DURING''' &lt;time2&gt;''
 
|  
 
|  
 
|-
 
|-
| ''DURING LAST''  
+
| '''DURING''' '''LAST'''
| ''&lt;time&gt; DURING LAST &lt;number&gt; SECONDS/MINUTES/HOURS/DAYS/WEEKS'' ''&lt;time&gt; DURING LAST SECOND/MINUTE/HOUR/DAY/WEEK''  
+
| ''&lt;time&gt; '''DURING''' '''LAST''' &lt;number&gt; '''SECONDS'''/'''MINUTES'''/'''HOURS'''/'''DAYS'''/'''WEEKS''' ''
 +
''&lt;time&gt; '''DURING''' '''LAST''' '''SECOND'''/'''MINUTE'''/'''HOUR'''/'''DAY'''/'''WEEK''' ''
 
|  
 
|  
 
|-
 
|-
| ''EQUAL''  
+
| '''EQUAL'''
| ''&lt;field&gt; EQUAL &lt;number&gt;''  
+
| ''&lt;field&gt; '''EQUAL''' &lt;number&gt;''
 
|  
 
|  
 
|-
 
|-
| ''GREATER''  
+
| '''GREATER'''
| ''&lt;field&gt; GREATER &lt;number&gt;''  
+
| ''&lt;field&gt; '''GREATER''' &lt;number&gt;''
 
|  
 
|  
 
|-
 
|-
| ''HAS''  
+
| '''HAS'''
| ''&lt;field&gt; HAS &lt;string&gt;'' ''*HAS &lt;string&gt;''  
+
| ''&lt;field&gt; '''HAS''' &lt;string&gt;''
|  
+
'' '''* HAS''' &lt;string&gt;''
 +
| See the main description above for information on the difference between using a field and the * wildcard.
 
|-
 
|-
| ''IS''  
+
| '''IS'''
| ''&lt;field&gt; IS &lt;string&gt;''  
+
| ''&lt;field&gt; '''IS''' &lt;string&gt;''
 
|  
 
|  
 
|-
 
|-
| ''LESS''  
+
| '''LESS'''
| ''&lt;field&gt; LESS &lt;number&gt;''  
+
| ''&lt;field&gt; '''LESS''' &lt;number&gt;''
 
|  
 
|  
 
|-
 
|-
| ''MISSING''  
+
| '''MISSING'''
| ''&lt;field&gt; MISSING''  
+
| ''&lt;field&gt; '''MISSING'''''
 
|  
 
|  
 
|-
 
|-
| ''NOT''  
+
| '''NOT'''
| ''NOT &lt;expression&gt;''  
+
| '''''NOT''' &lt;expression&gt; ''
|  
+
| In order to use it with a field you must write ''NOT &lt;field&gt; HAS &lt;string&gt;''.
 
|-
 
|-
| ''OR''  
+
| '''OR'''
| ''&lt;expression1&gt; OR &lt;expression2&gt;''  
+
| ''&lt;expression1&gt; '''OR''' &lt;expression2&gt;''
 
|  
 
|  
 
|-
 
|-
| ''PRESENT''  
+
| '''PRESENT'''
| ''&lt;field&gt; PRESENT''  
+
| ''&lt;field&gt; '''PRESENT'''''
 
|  
 
|  
 
|-
 
|-
| ''SINCE''  
+
| '''SINCE'''
| ''&lt;time1&gt; SINCE &lt;time2&gt;''  
+
| ''&lt;time1&gt; '''SINCE''' &lt;time2&gt;''
 
|  
 
|  
 
|-
 
|-
| ''SORT BY''  
+
| '''SORT''' '''BY'''  
| ''SORT BY &lt;sort-pattern&gt;'' ''SORT DESCENDING BY &lt;sort-pattern&gt;''  
+
| '''''SORT''' '''BY''' &lt;sort-pattern&gt;
| Must be at the end of the query.  
+
'''''SORT''' '''DESCENDING''' '''BY''' &lt;sort-pattern&gt;''
 +
| '''SORT'''ing expressions must be located at the end of the query.  
 
|}
 
|}

Latest revision as of 21:05, 2 September 2018

This page details the syntax that can be used to query for files within the Media Library in foobar2000.

For a list of fields and functions that can be used in query syntax, see the title-formatting reference.

Conventions in this document

Formatting

Query syntax includes various keywords, also called operators, which invoke specific behaviours. These must be typed in caps, for example DURING.

To aid readability, in the following descriptions and examples, example queries (or fragments thereof) that the user could type into foobar2000 are written in italics. In addition, operators are written in bold. Such formatting is for readability only and need not/cannot be typed in foobar2000 itself.

Placeholders

Query examples may contain placeholders which are enclosed in angle brackets. Their names indicate what they should 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 placeholders are used throughout this document:

  • <field> – A reference to a field within the tags of files in the Media Library. This can be either a plain field name (e.g. artist) or a title formatting expression (e.g. "%artist%"). See the Guidelines below for details on these two methods of accessing fields.
  • <number> – An integer value (whole number).
  • <string> – A text value, which may be enclosed in double quotation marks. See the Guidelines for details.
  • <time> – A time value or a title-formatting expression that evaluates to a time value. See Time Expressions below for details.
  • <expression> – A query expression in a composed query. This has to follow the rules described under Advanced Search below.

Simple search

The simple search mode does not use any keywords or functions: it is only used to search for a literal string within the Library.

  • <any string> – Returns only items that have all words from the specified string within their metadata and/or file path.

Advanced search

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.

Text 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).
  • ALL - No operators can be used. This single keyword simply returns all items within the Media Library.

Numeric expressions

Performs integral number comparison between the value of a <field> and a <number>. For example: rating GREATER 3

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

Metadata expressions

  • <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

Time expressions

  • <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 (choose one).

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.

Combined queries using logical operators

Several logical operators are available so that the user can search for items that match (or do not match) various criteria in combination. To create more complex logical queries, parentheses () can be used to enclose parts of the query to ensure that they are evaluated in the correct order (much like parentheses in mathematics).

  • <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 enclose expressions in parentheses to control the order in which logical expressions are evaluated. Example: ( (artist IS blah) AND (title HAS blah) ) OR (rating GREATER 3)
  • To obtain an exclusive-or (XOR/EOR), which is positive if only one expression is true but not both, you can use this: (<expression1> OR <expression2>) AND NOT (<expression1> AND <expression2>)

Sorting results

You can put a SORT BY operator at the end of your search expression to have the results from the preceding quiery 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.

Guidelines

General

Case-sensitivity

  • 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 equals "NAME", "name", "Name", and all other combinations of capital and small letters.
  • To achieve a case-sensitive comparison between two parameters, use "$strcmp(%field%,string)" EQUAL 1 and so on. For more information about how to use title-formatting within query syntax, see the relevant section below.

Double quotation marks

  • <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
  • 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 "MY BAND IS CALLED AND NOT" AND NOT releasetype IS Demo

Simplified access to metadata fields

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.

Comparing two metadata fields

As noted above, operators such as IS compare a field (on the left) to a string (on the right). If the user wishes, instead, to compare one field to another field, this can be done using title-formatting. Example: "$strcmp(%field1%,%field2%)" EQUAL 1

Title-formatting

  • If <field> in a (sub-)query using 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 guidance given above in General.
  • Double quotation marks should also be included around title-formatting expressions that use parentheses. This necessarily includes all functions, for example $meta(field) or $info(codec). Doing this removes ambiguity that might result because parenthesis are used natively by query syntax to specify the order of evaluation of logical expressions, as described under the relevant section above.
  • Using title formatting expressions to access metadata fields (e.g. "$meta(title)") instead of simple field names (e.g. title) will decrease the speed of queries performed upon large libraries and will break handling of multi-value fields by the operator IS.

Summary of operators

Operator Syntax Comment
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>

See the main description above for information on the difference between using a field and the * wildcard.
IS <field> IS <string>
LESS <field> LESS <number>
MISSING <field> MISSING
NOT NOT <expression> In order to use it with a field you must write NOT <field> HAS <string>.
OR <expression1> OR <expression2>
PRESENT <field> PRESENT
SINCE <time1> SINCE <time2>
SORT BY SORT BY <sort-pattern>

SORT DESCENDING BY <sort-pattern>

SORTing expressions must be located at the end of the query.