Структуру JQL-запросов без примеров сложно понять специалистам, не знакомым ранее с JIRA.
Мы уже успели рассказать про быстрый и базовый поиск. Теперь же прейдем к самому мощному из трех методов — к продвинутому поиску.
В этом режиме вы можете указывать критерии, которые нельзя задавать в остальных предыдущих двух режимах (например, сортировку ORDER BY). Но придётся освоить создание структурированных запросов с помощью JIRA Query Language (JQL).
Для использования «продвинутого» поиска перейдите в пункт меню Поиск --> Поиск запросов.
А если вы находитесь в режиме «базового» поиска, нажмите кнопку «Продвинутый»
1. Создание JQL-запросов
Простейший запрос на JQL состоит из поля, за которым следует оператор, а затем одно или несколько допустимых значений для этого поля. Например:
project = «YAT»
Такой запрос поможет найти все задачи проекта «YAT». Здесь использовано поле «project», оператор эквивалента "=" и допустимое значение «YAT».
Более сложный запрос может выглядеть так:
project = «YAT» AND assignee = currentuser()
Так мы отберём все задачи проекта «YAT», назначенные на текущего пользователя
(то есть на вас). В запросе содержатся: логический оператор «AND», поле «assignee» для отбора задач по текущему пользователю, оператор эквивалента "=" и функция «currentuser()», возвращающая имя текущего пользователя системы.
При создании запроса в режиме «продвинутого» поиска JIRA показывает список всех возможных операторов для поля запроса.
Также JIRA показывает список доступных значений для полей "AffectedVersion", "FixVersion", "Components", кастомных полей формата "Version" и выпадающих списков.
При использовании в поиске полей формата "User" JIRA позволяет найти необходимого пользователя по его фамилии.
Вы можете использовать круглые скобки в сложных JQL-запросах. Например, если хотите найти все разрешенные задачи в проекте «SysAdmin», а также все задачи (любого статуса, любого проекта), назначенные в настоящее время системному администратору (admin), то можете использовать круглые скобки, обозначая приоритет логических операторов в запросе.
(project=SysAdmin AND status=resolved) OR assignee=admin
Внимание!
В JQL есть зарезервированные символы.
| символ | + | . | , | ; | ? | | | * | / | % | ^ | $ | # | @ | [ | ] |
Если хотите использовать один из них в запросе, то необходимо:
- выделить текст, содержащий специальный символ, либо двойными кавычками ("......"), либо одинарными ('......');
- если в тексте поиска есть один из перечисленных ниже символов, то перед ним обязательно проставляется двойной backslashe ("\").
+ — & |! ( ) { } [ ] ^ ~ *? :
Пример:
summary ~ "\[example\]"
Внимание!
Также в JIRA есть зарезервированные слова.
Если в тексте поиска упомянуто одно из перечисленных ниже слов, этот текст нужно выделить либо двойными кавычками ("......"), либо одинарными ('......').
Список зарезервированных слов:
| A | «abort», «access», «add», «after», «alias», «all», «alter», «and», «any», «as», «asc», «audit», «avg» |
| B | «before», «begin», «between», «boolean», «break», «by», «byte» |
| C | «catch», «cf», «char», «character», «check», «checkpoint», «collate», «collation», «column», «commit», «connect», «continue», «count», «create», «current» |
| D | «date», «decimal», «declare», «decrement», «default», «defaults», «define», «delete», «delimiter», «desc», «difference», «distinct», «divide», «do», «double», «drop» |
| E | «else», «empty», «encoding», «end», «equals», «escape», «exclusive», «exec», «execute», «exists», «explain» |
| F | «false», «fetch», «file», «field», «first», «float», «for», «from», «function» |
| H | «having» |
| I | «identified», «if», «immediate», «in», «increment», «index», «initial», «inner», «inout», «input», «insert», «int», «integer», «intersect», «intersection», «into», «is», «isempty», «isnull» |
| J | «join» |
| L | «last», «left», «less», «like», «limit», «lock», «long» |
| M | «max», «min», «minus», «mode», «modify», «modulo», «more», «multiply» |
| N | «next», «noaudit», «not», «notin», «nowait», «null», «number» |
| O | «object», «of», «on», «option», «or», «order», «outer», «output» |
| P | «power», «previous», «prior», «privileges», «public» |
| R | «raise», «raw», «remainder», «rename», «resource», «return», «returns», «revoke», «right», «row», «rowid», «rownum», «rows» |
| S | «select», «session», «set», «share», «size», «sqrt», «start», «strict», «string», «subtract», «sum», «synonym» |
| T | «table», «then», «to», «trans», «transaction», «trigger», «true» |
| U | «uid», «union», «unique», «update», «user» |
| V | «validate», «values», «view» |
| W | «when», «whenever», «where», «while», «with» |
2. Использование шаблонов для поиска по тексту
Специальные символы могут быть использованы для определения шаблонов поиска по тексту. Рассмотрим несколько примеров:
| Знак | Область применения и описание | Пример |
|---|---|---|
| ? | "?" используется для замены одного символа в шаблоне. Например, написание слов «text» и «test» отличается одним символом. Для поиска обоих вариантов достаточно задать шаблон: te?t |
summary~«te?t» |
| * | "*" используется для замены в текстовом шаблоне нуля или нескольких символов. Например, для отбора текста «Windows», «Win95» или «WindowsNT» можно использовать шаблон: win* Для отбора текста «Win95» или «Windows95» можно использовать шаблон: wi*95 |
summary~«wi*95» |
| ~ | "~" может быть использована для задания нечетких поисковых шаблонов. В этом случае символ "~" подставляется в конце нужного слова. Например, чтобы найти термин, орфографически похожий на «roam», используйте шаблон: roam~ В результате могут быть найдены слова «foam» или «roams». |
summary~«prox~» |
3. Логические операторы JQL
| Оператор | Описание | Пример |
|---|---|---|
| AND | Логическая операция «И», соединяющая два или несколько условий. Используется для уточнения условий отбора. | project = «YAT» and status = «Оpen» — отобрать все задачи проекта «YAT» в статусе «Open» |
| OR | Логическая операция «ИЛИ», соединяющая два или несколько условий. | reporter = demo_1 or reporter = demo_2 — отобрать все задачи проекта, автором которых является пользователь demo_1 или пользователь demo_2. |
| NOT | Для реверсирования результата логического условия. | not assignee = demo_1 — отобрать все задачи, автором которых не является пользователь demo_1. |
| ORDER BY | Сортировать по.
По умолчанию будет использоваться собственный порядок, |
duedate = empty order by created — отобрать все задачи, у которых пустые поля «Due date» (Срок исполнения), отсортировать результаты выборки по полю «Created» (Создано). duedate = empty order by created, priority desc — |
4. Операторы сравнения JQL
| Оператор | Описание | Пример |
|---|---|---|
| = | Эквивалент.
Используется для задания |
reporter = demo_1 |
| != | Не равен.
Используется для задания критерия поиска, |
reporter != demo_1
либо можно использовать запись |
| > | Больше, чем.
Используется для создания выражений |
votes > 4 duedate > now() |
| >= | Больше либо равно.
Используется для создания выражений |
votes >= 4 duedate >= «2008/12/31» created >= "-5d" |
| < | Меньше, чем.
Используется для создания выражений |
votes < 4 duedate < now() |
| <= | Меньше либо равно.
Используется для создания выражений |
updated <= "-4w 2d" |
| IN | Используется для отбора задач по наличию в определенном поле одного из значений. Набор вариантов значений выделяется с двух сторон |
affectedVersion in («3.14», «4.2») reporter in (demo_1, demo_2) or assignee in (demo_1, demo_2) |
| NOT IN | Используется для отбора задач, в определенном поле которых не содержится ни одно из перечисленных значений. Набор вариантов значений выделяется с двух сторон |
FixVersion not in (A, B, C, D)
либо можно использовать запись |
| ~ | Содержит.
Используется исключительно для критериев |
summary ~ win summary ~ «issue collector» |
| !~ | Не содержит.
Используется исключительно для критериев |
summary !~ «issue collector»
либо можно использовать запись |
| IS | Этот оператор можно использовать только со значениями EMPTY или NULL. Используется для поиска задач, определенное поле |
fixVersion is empty |
| IS NOT | Этот оператор можно использовать только со значениями EMPTY или NULL. Применяется для поиска задач, определенное |
affectedVersion is not empty |
| WAS | Для отбора задач, определенное поле которых ранее имело указанное значение. Применимо исключительно к полям:
Оператор WAS также может иметь следующие необязательные предикаты:
|
status WAS «In Progress» — для отбора задач, когда-либо находившихся в статусе «In Progress». status WAS «Resolved» BY demo_1 BEFORE «2011/02/02» — |
| WAS IN | Для отбора задач, определенное поле которых ранее содержало одно из перечисленных значений. Область применения и предикаты, применяемые для |
status WAS IN («Resolved»,«In Progress») BEFORE «2011/02/02» — для отбора задач, переведенных в статус «Resolved» или «In Progress» до даты «2011/02/02». |
| WAS NOT IN | Для отбора задач, которые никогда, либо до некоторого момента, не содержали в определенном поле ни одно из перечисленных значений. Область применения и предикаты, применяемые для оператора WAS NOT IN, |
status WAS NOT IN («Resolved»,«In Progress») BEFORE «2011/02/02» — для отбора задач, ранее не находившихся в статусах «Resolved» и «In Progress» до даты «2011/02/02». |
| WAS NOT | Для отбора задач, которые никогда, либо до некоторого момента, не содержали в определенном поле заданного значения. Область применения и предикаты, применяемые для оператора WAS NOT, |
status WAS NOT «In Progress» BEFORE «2011/02/02» — для отбора задач, ранее не находившихся в статусе «In Progress» до даты «2011/02/02». |
| CHANGED | Для отбора задач, заданное поле которых было изменено.
Применимо исключительно к полям:
Оператор WAS также может иметь следующие необязательные предикаты:
|
assignee CHANGED — для отбора задач, исполнитель которых был изменен. status CHANGED FROM «In Progress» TO «Open» — для отбора задач AFTER startOfWeek() — для отбора задач, приоритет которых |
5. Функции JQL
| Функция | Описание | Синтаксис | Доступные операторы | Примеры |
|---|---|---|---|---|
| approved() | Только для JIRA Service Desk.
Для отбора задач JIRA Service Desk, требующих согласования, окончательное решение по которым одобрено. Применяется к полям типа «Approvals». |
approved() | = | approval = approved() |
| approver() | Только для JIRA Service Desk.
Для отбора задач JIRA Service Desk, требующих согласования Применяется к полям типа «Approvals». |
approver (user,user) |
= | approval = approver (demo_1, demo_2) |
| cascade Option() |
Для отбора задач по значению каскадного поля (полей зависимых списков). | cascadeOption (parentOption) cascadeOption |
IN, NOT IN | «Вид запроса» in cascadeOption («Застройщик», «Пролонгация») |
| closed Sprints() |
Применимо к полю «Sprint». Для отбора задач, добавленных в завершенные спринты. |
closedSprints() | IN, NOT IN | sprint in closedSprints() |
| components LeadByUser() |
Применимо к полю «Components» (Компоненты). Для отбора задач, в поле «Components» (Компоненты) которых выбран компонент, лидом которого являетесь вы сами или выбранный вами пользователь. |
Components LeadByUser() используется для отбора задач по текущему пользователю components LeadByUser (username) |
IN, NOT IN | component in components LeadByUser() — лидом компонентов являетесь вы сами. component |
| current Login() |
Возвращает время начала сеанса текущего пользователя.
Используется в выражениях с полями «Created» (Создано), |
currentLogin() | =, !=, >, >=, <, <= в предикатах операторов WAS, WAS IN, WAS NOT, WAS NOT IN, CHANGED |
created > currentLogin() |
| currentUser() | Возвращает логин текущего авторизованного пользователя.
Используется для создания выражений с полями «Reporter» |
currentUser() | =, != | reporter = currentUser() assignee != |
| earliest Unreleased Version() |
Для поиска на основе самой ранней не выпущенной версии (т. е. следующей версии, которая должна быть выпущена) указанного проекта.
Внимание Применяется для создания выражений с полями «AffectedVersion» (Проявляется в версиях"), «FixVersion» (Исправлено в версиях), кастомными полями формата Version. |
earliest Unreleased Version(project) |
IN, NOT IN | affectedVersion = earliestUnreleased Version (ABC) fixVersion = |
| endOfDay() | Для поиска по концу текущего дня.
Используется в выражениях с полями |
endOfDay()
endOfDay(«inc») где inc — Если спецификатор единицы Если опущен знак ±, |
=, !=, >, >=, <, <= в предикатах операторов WAS, WAS IN, WAS NOT, WAS NOT IN, CHANGED |
due < endOfDay() — срок исполнения до конца текущего дня. due < endOfDay |
| endOfMonth() | Для поиска по концу текущего месяца.
Используется в выражениях с полями «Created» (Создано), |
endOfMonth()
endOfMonth(«inc») где inc — Если спецификатор единицы Если опущен знак ±, |
=, !=, >, >=, <, <= в предикатах операторов WAS, WAS IN, WAS NOT, WAS NOT IN, CHANGED |
due < endOfMonth() — срок исполнения до конца текущего месяца. due < endOfMonth |
| endOfWeek() | Для поиска по концу текущей недели.
Используется в выражениях с полями «Created» (Создано), |
endOfWeek()
endOfWeek(«inc»), где inc — Если спецификатор единицы Если опущен знак ±, |
=, !=, >, >=, <, <= в предикатах операторов WAS, WAS IN, WAS NOT, WAS NOT IN, CHANGED |
due < endOfWeek() — срок исполнения до конца текущей недели. due < endOfWeek |
| endOfYear() | Для поиска по концу текущего года.
Используется в выражениях с полями «Created» |
endOfYear()
endOfYear(«inc») где inc — Если спецификатор единицы |
=, !=, >, >=, <, <= в предикатах операторов WAS, WAS IN, WAS NOT, WAS NOT IN, CHANGED |
due < endOfYear() — срок исполнения до конца текущего года. due < endOfYear |
| issueHistory() | Возвращает последние 50 просмотренных вами задач. | issueHistory() | IN, NOT IN | issue in issueHistory() |
| issuesWith RemoteLinks ByGlobalId() |
Для отбора задач, имеющих внешние ссылки с определенными global ids.
Внимание |
issues WithRemote LinksByGlobalId() |
IN, NOT IN | issue in issuesWithRemote LinksByGlobalId (abc, def) |
| lastLogin() | Возвращает время начала предыдущего сеанса текущего пользователя.
Используется в выражениях с полями |
lastLogin() | =, !=, >, >=, <, <= в предикатах операторов WAS, WAS IN, WAS NOT, WAS NOT IN, CHANGED |
created > lastLogin() |
| latest Released Version() |
Для поиска на основе самой последней выпущенной версии указанного проекта.
Внимание Применяется для создания выражений с полями «AffectedVersion» (Проявляется в версиях), «FixVersion» (Исправлено в версиях), кастомными полями формата Version. |
latest ReleasedVersion (project) |
=, != | affectedVersion = latestReleased Version(ABC) fixVersion = |
| linkedIssues() | Для отбора задач по признаку наличия связи с определенной задачей.
Внимание |
linkedIssues (issueKey) linkedIssues |
IN, NOT IN | issue in linkedIssues (ABC-123, «is duplicated by») |
| membersOf() | Для отбора задач по признаку принадлежности пользователя из определенного поля определенной JIRA-группе.
Используется для создания выражений с полями «Reporter» (Автор), «Assignee» (Исполнитель), «Voter», «Watcher» и кастомными полями формата «User». |
membersOf (Group) |
IN, NOT IN | assignee not in membersOf(QA) |
| myApproval() | Только для JIRA Service Desk.
Для отбора задач JIRA Service Desk, требующих согласования текущего пользователя или уже согласованных текущим пользователем. |
myApproval() | = | approval = myApproval() |
| myPending() | Только для JIRA Service Desk.
Для отбора задач JIRA Service Desk, требующих согласования текущего пользователя. |
myPending() | = | approval = myPending() |
| now() | Для поиска за текущее время.
Используется для создания выражений с полями «Reporter» (Автор), «Assignee» (Исполнитель), «Voter», «Watcher» и кастомными полями формата «User». |
now() | =, !=, >, >=, <, <= в предикатах операторов WAS, WAS IN, WAS NOT, WAS NOT IN, CHANGED |
duedate < now() and status not in (closed, resolved) |
| openSprints() | Применимо к полю «Sprint».
Для отбора задач, добавленных в незавершенные спринты |
openSprints() | IN, NOT IN | sprint in openSprints() |
| pending() | Только для JIRA Service Desk.
Для отбора задач JIRA Service Desk, требующих согласования. Применяется к полям типа «Approvals». |
pending() | = | approval = pending() |
| pendingBy() | Только для JIRA Service Desk.
Для отбора задач JIRA Service Desk, требующих согласования определенного(ых) пользователя(ей). Применяется к полям типа «Approvals». |
pendingBy (user1,user2) projectsLead |
= | approval = pending(demo_1) approval = |
| projectsLead ByUser() |
Для отбора задач из проектов, на роль Project Lead которых назначен определенный пользователь.
Применяется к полю «Project». |
projectsLeadByUser() — для отбора задач по текущему пользователю. projectsLead |
IN, NOT IN | project in projectsLead ByUser() AND status = Open project in |
| projects WhereUser Has Permission() |
Для отбора задач из проектов, в которых текущий пользователь имеет определенное разрешение.
Применяется к полю «Project». |
projects WhereUser HasPermission (permission) |
IN, NOT IN | project in projectsWhere UserHas Permission («Resolve Issues») AND status = Open |
| projects WhereUser HasRole() |
Для отбора задач из проектов, в которых текущий пользователь имеет определенную проектную роль.
Применяется к полю «Project». |
projectsWhere UserHasRole (rolename) |
IN, NOT IN | project in projectsWhere UserHasRole («Developers») AND status = Open |
| released Versions() |
Для поиска по выпущенным версиям определенного проекта или сразу всем JIRA-проектам.
Применяется для создания выражений с полями «AffectedVersion» (Проявляется в версиях), «FixVersion» (Исправлено в версиях), кастомными полями формата Version. |
ReleasedVersions() — для отбора задач по всем проектам. releasedVersions |
IN, NOT IN | fixVersion in releasedVersions (ABC) affectedVersion in |
| standard IssueTypes() |
Для отбора задач родительского типа. | standard IssueTypes() |
IN, NOT IN | issuetype in standard IssueTypes() |
| startOf Day() |
Для поиска по началу текущего дня.
Используется в выражениях с полями «Created» |
startOfDay()
startOfDay(«inc») где inc — Если спецификатор единицы Если опущен знак ±, |
=, !=, >, >=, <, <= в предикатах операторов WAS, WAS IN, WAS NOT, WAS NOT IN, CHANGED |
created > startOfDay() – задачи, созданные за текущий день. created > |
| startOf Month() |
Для поиска по началу текущего месяца.
Используется в выражениях с полями |
startOfMonth()
startOfMonth(«inc») где inc — Если спецификатор единицы Если опущен знак ±, |
=, !=, >, >=, <, <= в предикатах операторов WAS, WAS IN, WAS NOT, WAS NOT IN, CHANGED |
created > startOfMonth() — задачи, созданные за текущий месяц created > startOfMonth |
| startOf Week() |
Для поиска по началу текущей недели.
Используется в выражениях с полями |
startOfWeek()
startOfWeek(«inc»), где inc — Если спецификатор единицы Если опущен знак ±, |
=, !=, >, >=, <, <= в предикатах операторов WAS, WAS IN, WAS NOT, WAS NOT IN, CHANGED |
created > startOfWeek()- задачи, созданные за текущую неделю. created > |
| startOf Year() |
Для поиска по началу текущего года.
Используется в выражениях с полями |
startOfYear()
startOfYear(«inc») где inc — Если спецификатор единицы Если опущен знак ±, |
=, !=, >, >=, <, <= в предикатах операторов WAS, WAS IN, WAS NOT, WAS NOT IN, CHANGED |
created > startOfYear() — задачи созданные за текущий год. created > |
| subtask IssueTypes() |
Для отбора подзадач. | subtask IssueTypes() |
IN, NOT IN | issuetype in subtask IssueTypes() |
| unreleased Versions() |
Для поиска по не выпущенным версиям определенного проекта или сразу всем JIRA-проектам.
Применяется для создания выражений с полями «AffectedVersion» (Проявляется в версиях), «FixVersion» (Исправлено в версиях), кастомными полями формата Version. |
unreleasedVersions() используется для отбора задач по всем проектам. unreleased |
IN, NOT IN | fixVersion in unreleased Versions(ABC) |
| voted Issues() |
Для отбора задач, за которые вы отдали свой голос. | votedIssues() | IN, NOT IN | issue in votedIssues() |
| watched Issues() |
Для отбора задач, наблюдателем которых являетесь вы. | watchedIssues() | IN, NOT IN | issue in watchedIssues() |
Надеюсь, что разбор продвинутого режима поможет вам при поиске задач.
Пользуйтесь и не теряйтесь ;)
Автор: aayatsenko
