Foobar2000:Query syntax: Difference between revisions

From Hydrogenaudio Knowledgebase
(formatting, some more examples, clarifying some points)
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.
 
===Placeholders===
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.
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>''
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 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#Guidelines|Guidelines]] below for details.
* ''<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. Returns all items in media library. Example: ''ALL''
* '''''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===
===Composed queries===
* ''<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 various criteria. 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). An example is provided as the final item on the list below.
* ''<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'' – You can also enclose expressions in parentheses to control the evaluation order. Example: ''( (artist '''IS''' blah) '''AND''' (title '''HAS''' blah) ) '''OR''' (rating '''GREATER''' 3)''
* ''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''
* 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 on how to mix title-formatting in 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, such as $info(codec)
*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 85: Line 91:
! 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'' or '''''*HAS''' &lt;string&gt;''
|  
| See the main description above for information on the difference between '''HAS''' and '''*HAS'''.
|-
|-
| ''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; ''
|  
|  
|-
|-
| ''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; or '''''SORT''' '''DESCENDING''' '''BY''' &lt;sort-pattern&gt;''
| Must be at the end of the query.  
| '''SORT'''ing expressions must be located at the end of the query.  
|}
|}

Revision as of 00:50, 2 June 2013

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 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 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 Guidelines below for details.
  • <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.

Composed queries

Several logical operators are available so that the user can search for items that match various criteria. 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). An example is provided as the final item on the list below.

  • <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
  • 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 on how to mix title-formatting in 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, such as $info(codec)
  • 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&gt or *HAS <string> See the main description above for information on the difference between HAS and *HAS.
IS <field> IS <string>
LESS <field> LESS <number>
MISSING <field> MISSING
NOT NOT <expression>
OR <expression1> OR <expression2>
PRESENT <field> PRESENT
SINCE' <time1> SINCE <time2>
SORT BY SORT BY <sort-pattern> or SORT DESCENDING BY <sort-pattern> SORTing expressions must be located at the end of the query.