---
metadata:
  - name: generator
    content: Diplodoc Platform v5.57.3
  - property: og:type
    content: article
  - property: article:section
    content: Справочник API
  - property: og:title
    content: Язык запросов 2.0 в API
  - property: article:tag
    content: Техническая инструкция
alternate:
  - https://yandex.ru/support/tracker/en/api/issues/query2.md
  - https://yandex.ru/support/tracker/ru/api/issues/query2.md
  - href: ru/api/issues/query2.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/support/tracker/ru/llms.txt



# Язык запросов 2.0 в API

Используйте язык запросов 2.0, чтобы задать условия поиска задач в параметре `query2`. MLJ (Mongo-like JSON) — формат JSON для описания фильтра QL2.

В отличие от параметра `query`, в `query2` передается не строка из интерфейса Трекера, а JSON-объект.

Параметр `query2` поддерживается в методе [Найти задачи](https://yandex.ru/support/tracker/ru/api/issues/search-issues.md) в версиях API `v2` и `v3`. Рекомендуем использовать `v3`.

## Формат запроса {#structure}

Общий вид запроса с параметром `query2`:

```http
POST /v3/issues/_search
Host: api.tracker.yandex.net
Content-Type: application/json
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
  "query2": {
    "<ключ_поля>": {
      "<оператор_отношения>": "<значение_или_функция>"
    }
  }
}
```

Значение `query2` — выражение MLJ. Оно строится из трех видов конструкций:

- **условие по полю** — сравнивает поле задачи с заданным или вычисляемым значением;
- **логическая группа** — объединяет несколько условий с помощью логического оператора;
- **макрос** — задает условие по связанному объекту или включает условия сохраненного фильтра.

В синтаксисе MLJ все служебные слова начинаются с `$`: логические операторы, операторы отношения, макросы и функции. Ключи полей и значения, заданные напрямую, не начинаются с `$`.

## Условие по полю {#field-condition}

В условии укажите идентификатор поля задачи, оператор отношения и значение. Для системного или глобального поля используйте ключ. Например, `assignee` — ключ поля «Исполнитель». Отображаемое название поля вместо ключа использовать нельзя. Доступные ключи перечислены на странице [Поля задач](https://tracker.yandex.ru/admin/fields).

Для локального поля очереди укажите идентификатор поля для API (`apiId`). [Как узнать идентификатор локального поля](https://yandex.ru/support/tracker/ru/api/issues/fields.md#local)

Значение зависит от поля и оператора. Это может быть строка, число, дата или массив значений. Вместо непосредственного значения можно указать функцию. Она вычисляет значение во время выполнения запроса.

Например, этот запрос найдет задачи, назначенные текущему пользователю:

```json translate=no
{
  "query2": {
    "assignee": {
      "$eq": {
        "$me": []
      }
    }
  }
}
```

### Операторы отношения {#relation-operators}

Оператор отношения сравнивает значение поля с заданным или вычисляемым значением.

| Оператор | Описание |
| --- | --- |
| `$eq` | Равно значению. |
| `$ne` | Не равно значению. |
| `$in` | Равно одному из значений массива. |
| `$nin` | Не равно ни одному из значений массива. |
| `$gt` | Больше значения. Применяется к числам и датам. |
| `$gte` | Больше или равно значению. Применяется к числам и датам. |
| `$lt` | Меньше значения. Применяется к числам и датам. |
| `$lte` | Меньше или равно значению. Применяется к числам и датам. |
| `$empty` | Проверяет, заполнено ли поле: `true` — поле пустое, `false` — поле заполнено. |
| `$substr` | Ищет подстроку. |
| `$matchAnd` | Ищет все слова из строки. |
| `$matchOr` | Ищет хотя бы одно слово из строки. |

### Функции {#functions}

Функция начинается с символа `$` и передается как объект. Аргументы функции указываются в массиве. Функции без аргументов принимают пустой массив `[]`. Значение `$period` передается строкой.

| Функция | Формат | Описание |
| --- | --- | --- |
| `$me` | `{"$me": []}` | Текущий пользователь. Применяется к полям типа «Пользователь». |
| `$now` | `{"$now": []}` | Текущие дата и время. |
| `$today` | `{"$today": []}` | Диапазон текущего дня. |
| `$week` | `{"$week": []}` | Диапазон текущей недели. |
| `$month` | `{"$month": []}` | Диапазон текущего месяца. |
| `$quarter` | `{"$quarter": []}` | Диапазон текущего квартала. |
| `$year` | `{"$year": []}` | Диапазон текущего года. |
| `$sum_date` | `{"$sum_date": [<дата>, <период>]}` | Прибавляет к дате период. |
| `$sub_date` | `{"$sub_date": [<дата>, <период>]}` | Вычитает из даты период. |
| `$period` | `{"$period": "p2d"}` | Задает период. Применяется внутри `$sum_date` и `$sub_date`. |
| `$sum_num` | `{"$sum_num": [<число>, <число>]}` | Складывает два числа. |
| `$sub_num` | `{"$sub_num": [<число>, <число>]}` | Вычитает второе число из первого. |

## Логическая группа и операторы {#logical-group}

Логический оператор объединяет несколько условий. На верхнем уровне его можно не указывать: в этом случае используется `$and`.

Например, запрос найдет задачи, назначенные текущему пользователю, или задачи с приоритетом `blocker` либо `critical`:

```json translate=no
{
  "query2": {
    "$or": [
      {
        "assignee": {
          "$eq": {
            "$me": []
          }
        }
      },
      {
        "priority": {
          "$in": ["blocker", "critical"]
        }
      }
    ]
  }
}
```

Логические операторы связывают условия и группы. Их можно вкладывать друг в друга. Поддерживаются следующие операторы:

| Оператор | Формат | Описание |
| --- | --- | --- |
| `$and` | Массив условий или групп | Условие с оператором `$and` выполняется, если выполняются все вложенные условия и группы. |
| `$or` | Массив условий или групп | Условие с оператором `$or` выполняется, если выполняется хотя бы одно вложенное условие или одна группа. |
| `$not` | Одно условие или группа | Условие с оператором `$not` выполняется, если вложенное условие или группа не выполняется. В отличие от остальных логических операторов, `$not` принимает объект, а не массив. |
| `$nor` | Массив условий или групп | Условие с оператором `$nor` выполняется, если не выполняется ни одно вложенное условие и ни одна группа. |

## Макросы {#join-macro}

Макросы объединения задают условия по связанным с задачей объектам определенного типа, например по комментариям или связям. Они меняют контекст вложенного фильтра. Внутри макроса укажите поля связанного объекта. Значения этих полей можно задавать [функциями](#functions). Задача попадает в результаты поиска, если хотя бы один объект соответствует вложенному фильтру.

Например, этот запрос найдет задачи с комментарием текущего пользователя:

```json translate=no
{
  "query2": {
    "$comments": {
      "comment.author": {
        "$eq": {
          "$me": []
        }
      }
    }
  }
}
```

В запросах можно использовать следующие макросы:

| Макрос | Связанный объект | Пример поля вложенного фильтра |
| --- | --- | --- |
| `$comments` | Комментарии задачи | `comment.author`, `comment.text` |
| `$links` | Связи задачи | `link.to.key`, `link.relationship` |
| `$events` | События в истории задачи | `events.by`, `events.date` |
| `$components` | Компоненты | `component.lead` |
| `$queue` | Очередь | `queue.lead` |
| `$projects` | Проекты | `project.lead` |
| `$include` | Сохраненный фильтр | `include.id` |
| `$sla` | SLA | `sla.enabled` |
| `$checklistItems` | Пункты чеклиста | `checklistItem.checked` |
| `$sprints` | Спринты | `sprint.boardId` |

Макрос `$include` отличается от остальных: он не меняет контекст на связанный объект, а включает в запрос условия сохраненного фильтра. Укажите идентификатор фильтра в поле `include.id`.

Например, этот запрос ищет задачи, которые соответствуют сохраненному фильтру с идентификатором `123`:

```json translate=no
{
  "query2": {
    "$include": {
      "include.id": {
        "$eq": 123
      }
    }
  }
}
```