# 查询表达式帮助

## 文档约定

查询表达式以斜体表示。

例: %rating% GREATER 3

查询示例可能包含在半角尖括号中的占位符。它们需要在实际的查询中替换为有实际意义的名称。如果在示例中有多个同一类型占位符，在占位符后将会加上数字以示区别。

例: <field> GREATER <number>

本文档包含的占位符类型的说明:

- <field>
  一条对字段名(Tag Field)的引用。可以为纯字段名称或标题格式化表达式(title formatting)。参见 注意事项 获取详细信息。
- <number>
  一个整数。
- <string>
  一条含在双引号中的文本。参见 注意事项 获取详细信息。
- <time>
  一条时间数据或计算时间的标题格式化表达式。参见 时间表达式 获取详细信息。
- <expression>
  一条在组合查询中的查询表达式。规则遵循下面的 高级查询 一节。

## 简单查询

简单查询模式不使用任何关键字.

- <any string>
  返回元数据或文件路径包含指定全部字句的项目。

## 高级查询

高级查询允许建立更复杂的查询。它提供了一些关键字以对指定类型进行比较和组合多个查询表达式。

### 文本表达式

- <field> HAS <string>
  返回在指定元数据字段 <field> 中包含全部字句的项目。
  例 : title HAS blah
- <field> IS <string>
  返回指定元数据字段 <field> 中等于 <string> 的项目。
  例: artist IS blah
- * HAS <string>
  与简单查询效果相同，但可以与逻辑运算符结合 (参见后文)。

### 数字表达式

在数值 <field> 和 <number> 之间执行整数比较Performs integral number comparison between the value of a <field> and a <number>, 例: ”%rating% GREATER 3”。

- <field> GREATER <number>
  大于。
- <field> LESS <number>
  小于。
- <field> EQUAL <number>
  等于。

### 元数据表达式

- <field> MISSING
  返回不存在指定元数据字段 <field> 的项目。
  例: genre MISSING
- <field> PRESENT
  返回存在元数据字段 <field> 的项目。
  例: genre PRESENT

### 时间表达式

- <time1> BEFORE <time2>
  返回时间 <time1> 在 <time2> 之前的项目。
  例: %last_modified% BEFORE 2008
- <time1> AFTER <time2>
  返回时间 <time1> 在 <time2> 之后的项目。
  例: %last_modified% AFTER 2008
- <time1> SINCE <time2>
  返回时间 <time1> 不在 <time2> 之前的项目。
  例: %last_modified% SINCE 2007
- <time1> DURING <time2>
  返回时间 <time1> 在 <time2> 之内的项目。
  例: %last_modified% DURING 2007
- <time> DURING LAST <number> <time-unit>
  返回时间 <time> 属于最近指定时间段的项目。
  <time-unit>为 SECONDS, MINUTES, HOURS, DAYS, WEEKS 之一，分别代表秒、分、时、日、周。
  例: %last_modified% DURING LAST 2 WEEKS
  若 <number> 为 1，表达式可以简化为: <time> DURING LAST SECOND/MINUTE/HOUR/DAY/WEEK

用于这些表达式的时间的格式必须为以下格式之一: YYYY, YYYY-MM, YYYY-MM-DD, YYYY-MM-DD hh, YYYY-MM-DD hh:mm, YYYY-MM-DD hh:mm:ss，其中"Y"、"M"、"D"、"h"、"m"、"s"分别代表"年"、"月"、表"日"、"时"、"分"、"秒"，而其中的个数表示了它们所占的位数。

### 组合查询

- <expression1> AND <expression2>
  返回两个表达式返回值都为真的项目。
  例: artist IS blah AND title HAS blah
  你可以将表达式使用圆括号括起来以提升运算的优先级。
  例: ( (artist IS blah) AND (title HAS blah) ) OR (%rating% GREATER 3)
- <expression1> OR <expression2>
  返回两个表达式中返回值至少有一个为真的项目。
- NOT <expression>
  返回表达式为假的项目。
  例: NOT %last_played% AFTER %first_played%

## 查询结果排序

你可以在查询表达式结尾放入 SORT BY 运算符对查询结果使用标题格式化表达式进行排序。

- SORT BY <sort-pattern>
  对查询结果进行升序排列。
- SORT REVERSE BY <sort-pattern>
  对查询结果进行降序排列。

## 注意事项

- 若表达式使用了 HAS 或 IS 中的 <field> 和 <string> 字段中含有空格，需要用半角双引号(")括起来。
  例: title HAS "blah blah"
- 若在 HAS, IS, GREATER, LESS, EQUAL 中的 <field> 含有 #$% 中的任一字符，将会被处理为标题格式化表达式。
  例: %codec% IS MP3
- 若在含有庞大媒体库收藏中使用标题格式化表达式而不是使用简单的字段名将会大幅降低查询速度，并且在使用 IS 运算符时将会忽略字段多值 的情况。
- 若在 HAS, IS, GREATER, LESS, EQUAL 中的 <field> 不含 #$% 中的任一字符，将会视为元数据字段对待。
  例: artist IS Radiohead
- 不应访问技术信息字段（比如编码格式的规格）或插件动态提供的字段。
- 所有查询表达式忽略大小写。所有关键字必须为大写。

## 运算符摘要

运算符 | 语法 | 注释
--- | --- | ---
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> | 必须处于查询表达式结尾。