---
metadata:
  - name: generator
    content: Diplodoc Platform v5.57.3
  - property: og:type
    content: article
  - property: article:section
    content: API reference
  - property: og:title
    content: Query language 2.0 in the API
  - property: article:tag
    content: Technical instructions
alternate:
  - https://yandex.ru/support/tracker/en/api/issues/query2.md
  - https://yandex.ru/support/tracker/ru/api/issues/query2.md
  - href: en/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/en/llms.txt



# Query language 2.0 in the API

Use query language 2.0 to set issue search conditions in the `query2` parameter. MLJ (Mongo-like JSON) is a JSON format for describing a QL2 filter.

Unlike the `query` parameter, `query2` accepts a JSON object rather than a string copied from the Tracker interface.

The `query2` parameter is supported by the [Finding issues](https://yandex.ru/support/tracker/en/api/issues/search-issues.md) method in API versions `v2` and `v3`. We recommend using `v3`.

## Request format {#structure}

The general request format with the `query2` parameter is:

```http
POST /v3/issues/_search
Host: api.tracker.yandex.net
Content-Type: application/json
Authorization: OAuth <OAuth-token>
X-Org-ID or X-Cloud-Org-ID: <organization_ID>

{
  "query2": {
    "<field_key>": {
      "<relation_operator>": "<value_or_function>"
    }
  }
}
```

The `query2` value is an MLJ expression. It consists of three types of constructs:

- **Field condition**: Compares an issue field with a specified or calculated value.
- **Logical group**: Combines multiple conditions using a logical operator.
- **Macro**: Sets a condition on a related object or includes the conditions of a saved filter.

In MLJ syntax, all reserved words start with `$`: logical operators, relation operators, macros, and functions. Field keys and direct values do not start with `$`.

## Field condition {#field-condition}

In a condition, specify an issue field identifier, relation operator, and value. For a system or global field, use the field key. For example, `assignee` is the key of the Assignee field. You can't use the field's display name instead of its key. The available keys are listed on the [Issue fields](https://tracker.yandex.com/admin/fields) page.

For a queue local field, specify the field's API identifier (`apiId`). [How to find a local field identifier](https://yandex.ru/support/tracker/en/api/issues/fields.md#local)

The value depends on the field and operator. It can be a string, number, date, or array of values. Instead of a direct value, you can specify a function. It calculates the value when the request is executed.

For example, this request finds issues assigned to the current user:

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

### Relation operators {#relation-operators}

A relation operator compares the field value with a specified or calculated value.

| Operator | Description |
| --- | --- |
| `$eq` | Equals a value. |
| `$ne` | Does not equal a value. |
| `$in` | Equals one of the values in an array. |
| `$nin` | Does not equal any of the values in an array. |
| `$gt` | Is greater than a value. Applies to numbers and dates. |
| `$gte` | Is greater than or equal to a value. Applies to numbers and dates. |
| `$lt` | Is less than a value. Applies to numbers and dates. |
| `$lte` | Is less than or equal to a value. Applies to numbers and dates. |
| `$empty` | Checks whether a field is populated: `true` means the field is empty, and `false` means it is populated. |
| `$substr` | Searches for a substring. |
| `$matchAnd` | Searches for all words in a string. |
| `$matchOr` | Searches for at least one word in a string. |

### Functions {#functions}

A function starts with `$` and is passed as an object. Specify function arguments in an array. Functions without arguments accept an empty array, `[]`. Pass the `$period` value as a string.

| Function | Format | Description |
| --- | --- | --- |
| `$me` | `{"$me": []}` | Current user. Applies to user fields. |
| `$now` | `{"$now": []}` | Current date and time. |
| `$today` | `{"$today": []}` | Current-day range. |
| `$week` | `{"$week": []}` | Current-week range. |
| `$month` | `{"$month": []}` | Current-month range. |
| `$quarter` | `{"$quarter": []}` | Current-quarter range. |
| `$year` | `{"$year": []}` | Current-year range. |
| `$sum_date` | `{"$sum_date": [<date>, <period>]}` | Adds a period to a date. |
| `$sub_date` | `{"$sub_date": [<date>, <period>]}` | Subtracts a period from a date. |
| `$period` | `{"$period": "p2d"}` | Specifies a period. Use it inside `$sum_date` and `$sub_date`. |
| `$sum_num` | `{"$sum_num": [<number>, <number>]}` | Adds two numbers. |
| `$sub_num` | `{"$sub_num": [<number>, <number>]}` | Subtracts the second number from the first. |

## Logical group and operators {#logical-group}

A logical operator combines multiple conditions. You can omit it at the top level. In this case, `$and` is used.

For example, this request finds issues assigned to the current user, or issues with the `blocker` or `critical` priority:

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

Logical operators link conditions and groups. You can nest them. The following operators are supported:

| Operator | Format | Description |
| --- | --- | --- |
| `$and` | Array of conditions or groups | A condition with the `$and` operator is satisfied if all nested conditions and groups are satisfied. |
| `$or` | Array of conditions or groups | A condition with the `$or` operator is satisfied if at least one nested condition or group is satisfied. |
| `$not` | One condition or group | A condition with the `$not` operator is satisfied if the nested condition or group is not satisfied. Unlike other logical operators, `$not` accepts an object rather than an array. |
| `$nor` | Array of conditions or groups | A condition with the `$nor` operator is satisfied if none of the nested conditions or groups are satisfied. |

## Macros {#join-macro}

Join macros set conditions on related objects of a specific type, such as comments or issue links. They change the context of the nested filter. Inside the macro, specify fields of the related object. You can use [functions](#functions) to set the values of these fields. An issue appears in the search results if at least one object matches the nested filter.

For example, this request finds issues with a comment by the current user:

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

You can use the following macros in queries:

| Macro | Related object | Example nested-filter field |
| --- | --- | --- |
| `$comments` | Issue comments | `comment.author`, `comment.text` |
| `$links` | Issue links | `link.to.key`, `link.relationship` |
| `$events` | Issue history events | `events.by`, `events.date` |
| `$components` | Components | `component.lead` |
| `$queue` | Queue | `queue.lead` |
| `$projects` | Projects | `project.lead` |
| `$include` | Saved filter | `include.id` |
| `$sla` | SLA | `sla.enabled` |
| `$checklistItems` | Checklist items | `checklistItem.checked` |
| `$sprints` | Sprints | `sprint.boardId` |

The `$include` macro is different: it doesn't change the context to a related object. Instead, it includes the conditions of a saved filter in the query. Specify the filter ID in the `include.id` field.

For example, this request searches for issues that match the saved filter with ID `123`:

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