# Справочник поисковых запросов

## Соглашения в документе

Запросы выделены курсивом.
Пример: %rating% GREATER 3

Примеры запросов могут содержать подставные значения, которые заключаются в треугольные скобки. Названия таких значений нужно заменить на реальные запросы. Если несколько подставных значений одного типа встречаются в одном примере запроса, то (как в примере ниже) будут подставлены числа.
Пример: <field> GREATER <number>

Список основных типов подставных значений используемых далее в документе:

- <значение>
  Может выступать в качестве тега или выражения синтаксиса форматирования. См. Примечание для подробностей.
- <число>
  Целое число.
- <строка>
  Текстовое значение, которые может быть заключено в двойные кавычки. См. Примечание для подробностей.
- <время>
  Временное значение или синтаксическое выражение, которое определяет время. См. Временные выражения для подробностей.
- <выражение>
  Составной поисковый запрос. Использование описано в разделе Расширенный поиск.

## Простой поиск

В простом режиме не используются операторы или синтаксические выражения.

- <любая строка>
  Вернет только те элементы, которые содержат все слова из указанной строки в тегах или пути к файлу.

При использовании простого поиска, латинские символы соответствуют схожим с юникодными, например, "foo" соответствует "foo", также как "föö" и "fóo".

## Расширенный поиск

Расширенный поиск позволяет строить более сложные запросы, давая возможность сравнивать определенные типы значений и комбинировать несколько поисковых запросов.

### Текстовые выражения

- <значение> HAS <строка>
  Возвращает элемент(ы) у которых тег <значение> содержит строку <строка>.
  Пример: title HAS blah
- <значение> IS <строка>
  Возвращает элемент(ы) у которых тег <значение> является строкой <строка>.
  Пример: artist IS blah
- * HAS <строка>
  Тоже же, что и простой поиск, но может содержать логические операторы (см. далее).

### Числовые выражения

Выполнение целочисленного сравнения между <значение> и <число>, например, "%rating% GREATER 3".

- <значение> GREATER <число>
- <значение> LESS <число>
- <значение> EQUAL <число>

### ТЕГовые выражения

- <значение> MISSING
  Возвращает элемент(ы), которые НЕ содержат <значение>.
  Пример: genre MISSING
- <значение> PRESENT
  Возвращает элемент(ы), которые содержат <значение>.
  Пример: genre PRESENT

### Временные выражения

- <время1> BEFORE <время2>
  Возвращает элемент(ы) у которых значение <время1> до <время2>.
  Пример: %last_modified% BEFORE 2008
- <время1> AFTER <время2>
  Возвращает элемент(ы) у которых значение <время1> после <время2>.
  Пример: %last_modified% AFTER 2008
- <время1> SINCE <время2>
  Возвращает элемент(ы) у которых значение <время1> больше <время2>.
  Пример: %last_modified% SINCE 2007
- <время1> DURING <время2>
  Возвращает элемент(ы) у которых значение <время1> меньше <время2>.
  Пример: %last_modified% DURING 2007
- <время> DURING LAST <число> <единица времени>
  Возвращает элемент(ы) у которых значение <время> определенно в некотором временном периоде.
  <единицей времени> может выступать SECONDS, MINUTES, HOURS, DAYS или WEEKS.
  Пример: %last_modified% DURING LAST 2 WEEKS
  Если <число> = 1 запрос можно упростить до <time> DURING LAST SECOND/MINUTE/HOUR/DAY/WEEK

Временные значения используемые в запросах могут быть представлены в след. форматах: ГГГГ, ГГГГ-MM, ГГГГ-MM-ДД, ГГГГ-MM-ДД чч, ГГГГ-MM-ДД чч:мм, ГГГГ-ММ-ДД чч:мм:сс.

### Составные запросы

- <выражение1> AND <выражение2>
  Возвращает элементы для которых истинны оба выражения.
  Пример: artist IS blah AND title HAS blah
- <выражение1> OR <выражение2>
  Возвращает элементы для которых истинно хотя бы одно выражение.
- NOT <выражение>
  Возвращает элементы для которых выражение ложно.
  Пример: NOT %last_played% AFTER %first_played%

## Сортировка результатов

Чтобы отсортировать результаты поискового запросы по определенному значению, можно добавить в конец выражения оператор SORT BY.

- SORT BY <шаблон сортировки>, SORT ASCENDING BY <шаблон сортировки>
  Сортировать результаты в порядке возрастания.
- SORT DESCENDING BY <шаблон сортировки>
  Сортировать результаты в порядке убывания.

## Примечание

- <значение> и <строка> в HAS и IS-запросах должны быть заключены в кавычки ("), если содержат пробелы.
- Если <значение> в HAS, IS, GREATER, LESS, EQUAL содержит хотя бы один из этих трех символов: # $ %, то оно будет расценено как синтаксическое выражение.
  Пример: %codec% IS MP3
- Если <значение> в HAS, IS, GREATER, LESS, EQUAL НЕ содержит символов # $ %, то оно будет расценено как тег.
  Пример: artist IS Radiohead
  Учтите, что при этом не доступна тех. информация, такая как %codec% или значения плагинов (например, Playback Statistics).
- Использование синтаксических выражений вместо названий тегов уменьшает скорость поиска в больших медиа-библиотеках и рвет обработку многострочных значения с оператором IS – например, трек с двумя значениями "artist": "имя1" и "имя2" будет найдет с запросом artist IS name1, но не найдет с %artist% IS name1.
- Для контроля над последовательностью выполнения комбинированных запросов заключайте отдельные выражения в круглые скобки.
  Пример: ( (artist IS blah) AND (title HAS blah) ) OR (%rating% GREATER 3)
- Все поисковые выражения не чувствительны к регистру. Все операторы должны быть в верхнем регистре.

## Операторы (суммарно)

Оператор | Синтаксис | Комментарий
--- | --- | ---
AFTER | <время1> AFTER <время2> |
AND | <выражение1> AND <выражение2> |
BEFORE | <время1> BEFORE <время2> |
DURING | <время1> DURING <время2> |
DURING LAST | <время> DURING LAST <число> SECONDS/MINUTES/HOURS/DAYS/WEEKS <время> DURING LAST SECOND/MINUTE/HOUR/DAY/WEEK |
EQUAL | <значение> EQUAL <число> |
GREATER | <значение> GREATER <число> |
HAS | <значение> HAS <строка> * HAS <string> |
IS | <значение> IS <строка> |
LESS | <значение> LESS <число> |
MISSING | <значение> MISSING |
NOT | NOT <выражение> |
OR | <выражение1> OR <выражение2> |
PRESENT | <значение> PRESENT |
SINCE | <время1> SINCE <время2> |
SORT BY | SORT BY <шаблон сортировки> SORT DESCENDING BY <шаблон сортировки> | Должен находиться в конце выражения.