Hydrogenaudio Knowledgebase - User contributions [en]

Foobar2000:Query syntax

2013-02-10T10:11:43Z

72.230.134.188: /* Text expressions */

=Query syntax help=

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

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 [[Foobar2000:Query_syntax#Notes|Notes]] for details.
* ''<number>'' – An integer value.
* ''<string>'' – A text value that may be enclosed in double quotation marks. See [[Foobar2000:Query_syntax#Notes|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]] 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.

==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).
* ''ALL'' - No operators. Returns all items in media library. Example: ''ALL''

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

==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 is ''NAME'', ''name'', ''Name'', and all other combinations of capital and small letters.
====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 "CONTRIVED EXAMPLE 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.

===Title-formatting===
*If ''<field>'' 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 spaces are likely to occur in the result, the title-formatting expression should be enclosed within double quotation marks ("), in line with the third point listed above in General.
*Double quotation marks should also be included around title-formatting expressions 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.

==Operator summary==
{| border="1"
|-
! 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.
|}

Foobar2000:Query syntax

2013-02-10T10:11:04Z

72.230.134.188: /* Text expressions */

=Query syntax help=

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

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 [[Foobar2000:Query_syntax#Notes|Notes]] for details.
* ''<number>'' – An integer value.
* ''<string>'' – A text value that may be enclosed in double quotation marks. See [[Foobar2000:Query_syntax#Notes|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]] 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.

==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).
* ''ALL'' - No operators. Shows all items in media library. Example: ''ALL''

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

==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 is ''NAME'', ''name'', ''Name'', and all other combinations of capital and small letters.
====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 "CONTRIVED EXAMPLE 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.

===Title-formatting===
*If ''<field>'' 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 spaces are likely to occur in the result, the title-formatting expression should be enclosed within double quotation marks ("), in line with the third point listed above in General.
*Double quotation marks should also be included around title-formatting expressions 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.

==Operator summary==
{| border="1"
|-
! 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.
|}