Foobar2000:Query syntax - Revision history

Tipar: /* Summary of operators */ comment about the NOT query

2018-09-02T21:05:22Z

Summary of operators: comment about the NOT query

← Older revision		Revision as of 21:05, 2 September 2018
Line 141:		Line 141:
	\| '''NOT'''		\| '''NOT'''
	\| '''''NOT''' <expression> ''		\| '''''NOT''' <expression> ''
	\|		\| In order to use it with a field you must write ''NOT <field> HAS <string>''.
	\|-		\|-
	\| '''OR'''		\| '''OR'''

198.72.153.188: /* Placeholders */

2016-05-15T15:22:09Z

Placeholders

← Older revision		Revision as of 15:22, 15 May 2016
Line 11:		Line 11:

	===Placeholders===		===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 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>''		* Example: ''<field> '''GREATER''' <number>''

72.174.139.113: /* Time expressions */

2015-06-15T02:10:37Z

Time expressions

← Older revision		Revision as of 02:10, 15 June 2015
Line 49:		Line 49:
	* ''<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''''' (choose one).		* ''<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.

Foosion: /* Summary of operators */ Word order.

2014-05-31T22:39:49Z

Summary of operators: Word order.

← Older revision		Revision as of 22:39, 31 May 2014
Line 125:		Line 125:
	\| ''<field> '''HAS''' <string>''		\| ''<field> '''HAS''' <string>''
	'' '''* HAS''' <string>''		'' '''* HAS''' <string>''
	\| See the main description above for information on the difference between using a field and the wildcard *.		\| See the main description above for information on the difference between using a field and the * wildcard.
	\|-		\|-
	\| '''IS'''		\| '''IS'''

Foosion: /* Summary of operators */ Fixed inconsistent formatting

2014-05-31T22:39:21Z

Summary of operators: Fixed inconsistent formatting

← Older revision		Revision as of 22:39, 31 May 2014
Line 110:		Line 110:
	\|-		\|-
	\| '''DURING''' '''LAST'''		\| '''DURING''' '''LAST'''
	\| ''<time> '''DURING''' '''LAST''' <number> '''SECONDS'''/'''MINUTES'''/'''HOURS'''/'''DAYS'''/'''WEEKS''' <time> '''DURING''' '''LAST''' '''SECOND'''/'''MINUTE'''/'''HOUR'''/'''DAY'''/'''WEEK'''''		\| ''<time> '''DURING''' '''LAST''' <number> '''SECONDS'''/'''MINUTES'''/'''HOURS'''/'''DAYS'''/'''WEEKS''' ''
			''<time> '''DURING''' '''LAST''' '''SECOND'''/'''MINUTE'''/'''HOUR'''/'''DAY'''/'''WEEK''' ''
	\|		\|
	\|-		\|-
Line 117:		Line 118:
	\|		\|
	\|-		\|-
	\| ''GREATER''		\| '''GREATER'''
	\| ''<field> '''GREATER''' <number>''		\| ''<field> '''GREATER''' <number>''
	\|		\|
	\|-		\|-
	\| '''HAS'''		\| '''HAS'''
	\| ''<field> '''HAS''' <string&gt'' or '''''*HAS''' <string>''		\| ''<field> '''HAS''' <string>''
	\| See the main description above for information on the difference between ~~'''HAS'''~~ and ~~'''~~*~~HAS'''~~.		'' '''* HAS''' <string>''
			\| See the main description above for information on the difference between using a field and the wildcard *.
	\|-		\|-
	\| '''IS'''		\| '''IS'''
Line 130:		Line 132:
	\|-		\|-
	\| '''LESS'''		\| '''LESS'''
	\| <field> '''LESS''' <number>		\| ''<field> '''LESS''' <number>''
	\|		\|
	\|-		\|-
Line 149:		Line 151:
	\|		\|
	\|-		\|-
	\| '''SINCE''''		\| '''SINCE'''
	\| ''<time1> '''SINCE''' <time2>''		\| ''<time1> '''SINCE''' <time2>''
	\|		\|
	\|-		\|-
	\| '''SORT''' '''BY'''		\| '''SORT''' '''BY'''
	\| '''''SORT''' '''BY''' <sort-pattern> or '''''SORT''' '''DESCENDING''' '''BY''' <sort-pattern>''		\| '''''SORT''' '''BY''' <sort-pattern>
			'''''SORT''' '''DESCENDING''' '''BY''' <sort-pattern>''
	\| '''SORT'''ing expressions must be located at the end of the query.		\| '''SORT'''ing expressions must be located at the end of the query.
	\|}		\|}

Db1989 at 01:02, 2 June 2013

2013-06-02T01:02:04Z

Db1989: /* Case-sensitivity */

2013-06-02T00:53:59Z

Case-sensitivity

← Older revision		Revision as of 00:53, 2 June 2013
Line 69:		Line 69:
	*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 equals "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.		*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====
	*<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''		*<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''

Db1989: /* Placeholders */

2013-06-02T00:52:59Z

Placeholders

← Older revision		Revision as of 00:52, 2 June 2013
Line 15:		Line 15:

	The following common placeholders are used throughout 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#Guidelines\|Guidelines]] below 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 (whole number).		* <number> – An integer value (whole number).
	* <string> – A text value, which may be enclosed in double quotation marks. See the Guidelines for details.		* <string> – A text value, which may be enclosed in double quotation marks. See the Guidelines for details.

Db1989: formatting, some more examples, clarifying some points

2013-06-02T00:50:46Z

formatting, some more examples, clarifying some points

Show changes

72.230.134.188: /* Text expressions */

2013-02-10T10:11:43Z

Text expressions

← Older revision		Revision as of 10:11, 10 February 2013
Line 31:		Line 31:
	* ''<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. ~~Shows~~ all items in media library. Example: ''ALL''		* ''ALL'' - No operators. Returns all items in media library. Example: ''ALL''

	===Numeric expressions===		===Numeric expressions===

← Older revision		Revision as of 01:02, 2 June 2013
Line 52:		Line 52:
	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===
	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~~.		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~~'' – 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''
	* ''<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>)''		* 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>)''

Line 82:		Line 83:
	*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 [[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 <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 [[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.		*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 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'''.		*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'''.