junior

Что такое JQL (Jira Query Language)?

JQL (Jira Query Language) — структурированный язык запросов для поиска задач в Jira, используемый в UI (фильтры, дашборды), REST API (эндпоинт /search), плагинах и автоматизации.

Аналогия из жизни: JQL — это как поисковая строка Google, но для задач Jira. Вместо свободного текста вы пишете структурированные условия: какой проект, какой статус, кто исполнитель — и получаете точный результат.

Базовый синтаксис

Пример

field operator value [AND|OR] field operator value ORDER BY field [ASC|DESC]

Операторы

Оператор	Описание	Пример
`=`	Равно	`project = "PROJ"`
`!=`	Не равно	`status != Done`
`>`, `<`, `>=`, `<=`	Сравнение	`created >= -7d`
`~`	Содержит (текстовый поиск)	`summary ~ "критическая ошибка"`
`!~`	Не содержит	`description !~ "test"`
`IN`	Одно из значений	`status IN (Open, "In Progress")`
`NOT IN`	Не одно из значений	`priority NOT IN (Low, Lowest)`
`IS EMPTY`	Пусто	`assignee IS EMPTY`
`IS NOT EMPTY`	Не пусто	`fixVersion IS NOT EMPTY`
`WAS`	Было (история)	`status WAS "In Progress"`
`CHANGED`	Изменилось	`assignee CHANGED`

Встроенные функции

Пример

-- Текущий пользователь
assignee = currentUser()

-- Дата: начало/конец дня, недели, месяца
created >= startOfDay()
created >= startOfWeek(-1)
duedate <= endOfMonth()

-- Члены группы
assignee IN membersOf("developers")

-- Связанные задачи
issue IN linkedIssues("PROJ-123")

-- Подзадачи
issue IN subtasksOf("PROJ-100")

-- Задачи из эпика
"Epic Link" = "PROJ-50"

-- Текстовый поиск по всем полям
text ~ "deploy*"

Custom Fields в JQL

Пример

-- По имени (с кавычками)
"Story Points" > 5

-- По ID (надёжнее)
cf[10100] > 5

Сложные запросы

Пример

project = PROJ
    AND status IN ("In Progress", "Code Review")
    AND assignee IN membersOf("backend-team")
    AND created >= startOfWeek()
    AND priority IN (Critical, Blocker)
    AND "Story Points" <= 8
ORDER BY priority DESC, created ASC

Использование JQL в Java

Пример через REST API и в плагине Jira DC

// Через REST API
public List<Issue> findCriticalBugs(String projectKey) {
    String jql = "project = %s AND type = Bug AND priority = Critical AND status != Done"
            .formatted(projectKey);

    String body = """
            {
                "jql": "%s",
                "maxResults": 50,
                "fields": ["summary", "status", "assignee", "priority"]
            }
            """.formatted(jql);

    return restClient.post()
            .uri("/search")
            .body(body)
            .retrieve()
            .body(SearchResult.class)
            .getIssues();
}

// В плагине Jira DC через SearchService
@Named
public class IssueSearchHelper {

    private final SearchService searchService;
    private final JqlQueryParser jqlQueryParser;

    @Inject
    public IssueSearchHelper(@ComponentImport SearchService searchService,
                             @ComponentImport JqlQueryParser jqlQueryParser) {
        this.searchService = searchService;
        this.jqlQueryParser = jqlQueryParser;
    }

    public SearchResults search(ApplicationUser user, String jqlString)
            throws SearchException, ParseException {
        Query query = jqlQueryParser.parseQuery(jqlString);
        return searchService.search(user, query, PagerFilter.getUnlimitedFilter());
    }
}

Производительность JQL

Индексируемые поля (status, project, priority) работают быстро
Текстовый поиск (~) использует Lucene, может быть медленным на больших инстансах
WAS и CHANGED операторы сканируют историю — дорогие операции
Сложные OR с подзапросами замедляют выполнение
Для DC: кастомные поля без индексации значительно замедляют поиск

Частые ошибки

Использование = вместо ~ для текстового поиска: summary = "error" ищет точное совпадение
Забыть кавычки для значений с пробелами: status = In Progress — ошибка, нужно "In Progress"
Неэффективные запросы с WAS/CHANGED на инстансах с большой историей
Использование ORDER BY с неиндексированными кастомными полями

Как используется в 2026

JQL остаётся основным языком запросов в Jira DC и Cloud
В Cloud добавлены новые функции: issuesWithRemoteLinksByGlobalId(), улучшенный полнотекстовый поиск
Atlassian экспериментирует с AI-ассистентом для генерации JQL из естественного языка
JQL используется в Jira Automation rules для определения scope правил

На собеседовании: знание JQL ожидается от любого Jira-разработчика. Покажите владение основными операторами, функциями (currentUser(), membersOf(), startOfWeek()) и умение составлять сложные запросы. Отметьте, что cf[id] надёжнее имени поля и что ~ поддерживает Lucene-синтаксис.

#основы #jql #jira #sql