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 method in API versions v2 and v3. We recommend using v3.

Request format

The general request format with the query2 parameter is:

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

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 page.

For a queue local field, specify the field's API identifier (apiId). How to find a local field identifier

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:

{
  "query2": {
    "assignee": {
      "$eq": {
        "$me": []
      }
    }
  }
}

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

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

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:

{
  "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 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 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:

{
  "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:

{
  "query2": {
    "$include": {
      "include.id": {
        "$eq": 123
      }
    }
  }
}

Was the article helpful?

Find issues

Find out the number of issues