Foobar2000:Query syntax: Difference between revisions

From Hydrogenaudio Knowledgebase
(Changing a couple of curly quotes to neutral ones as that (just) might have been misleading. Ended up doing a few small formatting tweaks too.)
(Considerable clarification on simple field names vs. title-formatting, including replacement of misleading/incorrect examples and adding important info omitted from Notes.)
Line 1: Line 1:
=Query syntax help=
=Query syntax help=


This page details the syntax that can be used to query for matching files in [[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.
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.


==Conventions in this document==
==Conventions in this document==
Line 7: Line 7:
Queries are written in ''italics''.
Queries are written in ''italics''.


Example: ''%rating% GREATER 3''  
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.
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.
Line 14: Line 14:
   
   
The following common types of placeholders are used in the rest of this document:  
The following common types of placeholders are used in the rest of this document:  
* ''<field>'' – A reference to a tag field. This can be either a plain field name or a title formatting expression. See [[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#Notes|Notes]] for details.
* ''<number>'' – An integer value.
* ''<number>'' – An integer value.
* ''<string>'' – A text value that may be enclosed in double quotation marks. See [[Foobar2000:Query_syntax#Notes|Notes]] for details.
* ''<string>'' – A text value that may be enclosed in double quotation marks. See [[Foobar2000:Query_syntax#Notes|Notes]] for details.
Line 33: Line 33:


===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>'', e.g. "''rating GREATER 3''".  
* ''<field> GREATER <number>''
* ''<field> GREATER <number>''
* ''<field> LESS <number>''
* ''<field> LESS <number>''
Line 43: Line 43:


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


==Sorting results==
==Sorting results==
Line 61: Line 61:


==Notes==
==Notes==
* ''<field>'' and ''<string>'' in HAS and IS expressions should be enclosed in double quotation marks (") if they include spaces. – If ''<field>'' in ''HAS'', ''IS'', ''GREATER'', ''LESS'', ''EQUAL'' includes at least one of #$% characters, it will be treated as a title formatting string. Example: ''%codec% IS MP3''
* All search expressions are non-case sensitive. All keywords must be uppercase.
* 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.
* ''<field>'' and ''<string>'' in HAS and IS expressions should be enclosed in double quotation marks (") if they include spaces. Example: ''"my string" HAS my''
* If ''<field>'' in ''HAS'', ''IS'', ''GREATER'', ''LESS'', ''EQUAL'' does not include any of #$% characters, it will be treated as a metadata field. Example: ''artist IS Radiohead''
* If ''<field>'' in ''HAS'', ''IS'', ''GREATER'', ''LESS'', ''EQUAL'' does not include any of #$% characters, it will be treated as a metadata field. Example: ''artist IS Radiohead''
* You can't access technical information (such as codec specifications) or component-provided information (playback statistics and such) this way.
* On the other hand, if ''<field>'' in ''HAS'', ''IS'', ''GREATER'', ''LESS'', or ''EQUAL'' includes at least one of these characters—#, $, %—it will be treated as a [[Foobar2000:Title Formatting Reference|title formatting]] expression. That is: the end-result of said expression will take the place of the expression itself, before the actual query is carried out. Therefore, double quotation marks (") must be included around the expression (i.e. ''<field>'') in cases where spaces are expected in the result. In other words, the user may as well include quotations around all field-names or title-formatting expressions.
* All search expressions are non-case sensitive. All keywords must be uppercase.
* 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.
* The user cannot access technical information (such as codec specifications) or component-provided information ([[Foobar2000:Titleformat Playback Statistics|playback statistics]] and such) through title-formatting.


==Operator summary==
==Operator summary==
{| border="1"
{| border="1"
|-
|-

Revision as of 23:05, 11 January 2012

Query syntax help

This page details the syntax that can be used to query for matching files in foobar2000. For a list of the actual fields that can be queried with this, see the title-formatting reference page.

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.

Simple search

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.

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).

Numeric expressions

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>

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’’.

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

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

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.

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

Notes

  • All search expressions are non-case sensitive. All keywords must be uppercase.
  • <field> and <string> in HAS and IS expressions should be enclosed in double quotation marks (") if they include spaces. Example: "my string" HAS my
  • If <field> in HAS, IS, GREATER, LESS, EQUAL does not include any of #$% characters, it will be treated as a metadata field. Example: artist IS Radiohead
  • On the other hand, if <field> in HAS, IS, GREATER, LESS, or EQUAL includes at least one of these characters—#, $, %—it will be treated as a title formatting expression. That is: the end-result of said expression will take the place of the expression itself, before the actual query is carried out. Therefore, double quotation marks (") must be included around the expression (i.e. <field>) in cases where spaces are expected in the result. In other words, the user may as well include quotations around all field-names or title-formatting expressions.
  • 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.
  • The user cannot access technical information (such as codec specifications) or component-provided information (playback statistics and such) through title-formatting.

Operator summary

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>
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> SORT DESCENDING BY <sort-pattern> Must be at the end of the query.