Foobar2000:Query syntax: Difference between revisions

From Hydrogenaudio Knowledgebase
(→‎Summary of operators: comment about the NOT query)
 
(21 intermediate revisions by 6 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]].
   
== Conventions in this Document ==
Queries are written in ''italics''.


Example: ''%rating% GREATER 3''
For a list of fields and functions that can be used in query syntax, see the [[Foobar2000:Title_Formatting_Reference|title-formatting reference]].
 
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.
==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.


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 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.
* ''<field>''  A reference to a tag field. This can be either a plain field name or a title formatting expression. See [[Foobar2000:Query_syntax#Notes]] for details.
* <number> An integer value (whole number).
* ''<number>''  An integer value.
* <string> A text value, which may be enclosed in double quotation marks. See the Guidelines for details.
* ''<string>''  A text value that may be enclosed in double quotation marks. See [[Foobar2000:Query_syntax#Notes] 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.
* ''<time>''  A time value or a title formatting expression that evaluates to a time value. See [[Foobar2000:Query_syntax#Time Expressions]] 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]] below.


== Simple Search ==
==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.
The simple search mode does not use any keywords.  
* ''<any string>'' – Returns only items that have all words from the specified string within their metadata and/or file path.


*  ''<any string>''  Returns only items that have all words from specified string in their metadata or file path.
==Advanced search==
 
== 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.
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 ===
===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 ===
 
Performs integral number comparison between the value of a ''<field>'' and a ''<number>'', e.g. ”''%rating% GREATER 3''.  


* ''<field> GREATER <number>''
===Numeric expressions===
* ''<field> LESS <number>''
Performs integral number comparison between the value of a <field> and a <number>. For example: ''rating '''GREATER''' 3''
* ''<field> EQUAL <number>''
* ''<field> '''GREATER''' <number>''
 
* ''<field> '''LESS''' <number>''
=== Metadata Expressions ===
* ''<field> '''EQUAL''' <number>''
 
 
* ''<field> MISSING'' Returns only items that don't have a metadata field named ''<field>''. Example: ''genre MISSING''
===Metadata expressions===
* ''<field> PRESENT'' Returns only items that have a metadata field named ''<field>''. Example: ''genre PRESENT''
* ''<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 ===
 
 
===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.
 
 
===Combined queries using logical operators===
=== Composed Queries ===
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> 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.
* ''<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''
* ''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 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''' '''DESCENDING''' '''BY''' &lt;sort-pattern&gt;'' – 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.


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.  
====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''
*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 &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''


* ''SORT BY &lt;sort-pattern&gt;'', ''SORT ASCENDING BY &lt;sort-pattern&gt;'' Sort results in ascending order.
===Title-formatting===
* ''SORT DESCENDING BY &lt;sort-pattern&gt;'' Sort results in descending order.
*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 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'''.


== Notes ==
==Summary of operators==
 
*  ''&lt;field&gt;'' and ''&lt;string&gt;'' in HAS and IS expressions should be enclosed in double quotation marks (”) if they include spaces.  If ''&lt;field&gt;'' 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''
*  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.
*  If ''&lt;field&gt;'' in ''HAS'', ''IS'', ''GREATER'', ''LESS'', ''EQUAL'' does not include any of #$% characters, it will be treated as a metadata field.  Example: ''artist IS Radiohead''
*  You can&#039;t access technical information (such as codec specifications) or component-provided information (playback statistics and such) this way.
*  All search expressions are non-case sensitive. All keywords must be uppercase.
 
== Operator Summary ==
                                                     
{| border="1"
{| border="1"
|-
|-
Line 86: 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.