Справочник по S-JQL

Запрос структуры — это иерархическое условие для элементов, добавленных в структуру. Структурный запрос выражается на языке Structured JQL (S-JQL), описанном в этой статье.

В некоторых частях этой статьи предполагается, что вы знакомы с возможностями расширенного поиска JIRA.

Список тем структурированного JQL:

Несколько экземпляров предметов

Если в структуре есть несколько экземпляров элемента, некоторые из этих экземпляров могут соответствовать запросу, а некоторые — нет.

Рассмотрим следующую структуру:

КОД
TS-239
TS-42
TS-123
TS-239

Здесь выпуск TS-239 присутствует два раза — один в корневой позиции, а другой под другой задачей. Корень запроса будет соответствовать первому экземпляру, но не второму.

Эта разница видна при фильтрации в Виджете Структуры (см. Фильтр). Однако функция JQL Structure() соответствует задаче, если хотя бы один из ее экземпляров в структуре соответствует запросу S-JQL. В этом примере задача в структуре (корень) вернет TS-239, TS-123.

Ограничения

Структурный запрос состоит из ограничений. Ограничение соответствует элементам в структуре. В простейшем случае весь запрос структуры состоит из одного ограничения; пока рассмотрим только этот случай.

Существует два типа ограничений: базовые и реляционные ограничения.

Основное ограничение

Базовое ограничение сопоставляет элементы, которые удовлетворяют условию, независимо от их относительного положения по отношению к другим элементам.

Ограничение JQL

Ограничение JQL соответствует всем задачам в структуре, которые удовлетворяют запросу JQL. Чтобы указать его, укажите JQL-запрос, заключенный в квадратные скобки:

КОД
[status = Open]
leaf and root

Это базовое ограничение соответствует элементам, расположенным в определенных позициях внутри структуры.

КОД
leaf

КОД
root

Первое ограничение соответствует элементам на нижнем уровне иерархии, т. е. элементам, не имеющим дочерних элементов (подэлементов).

Второе ограничение соответствует элементам на верхнем уровне иерархии, т. е. элементам, у которых нет родителя.

Конкретная задача

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

Вы можете указать список ключей задач, разделенных запятыми:

КОД
TS-129, TS -239

Один ключ задачи:

КОД
TS-129

Идентификатор задачи (или их список):

КОД
19320

 Функциональное ограничение (папка, элемент)

Функции в S-JQL играют ту же роль, что и в JQL: это точка расширения, поэтому любой поставщик может разработать свои собственные функции для сопоставления элементов по своему усмотрению.

Структура поставляется в комплекте с несколькими функциями: папка (сопоставление всех папок или папок по имени) и элемент (соответствие всем элементам указанного типа или элементам по имени).

Синтаксис

Ограничение функции имеет имя и ноль или более аргументов, в зависимости от используемой функции:

КОД
folder(Urgent)

В приведенном выше примере имя функции — папка, а ее аргумент —«Срочно» (“Urgent”).

Вы можете вставить любое количество пробелов вокруг имени и аргументов:

КОД
folder ( Urgent )

Несколько аргументов функции должны быть разделены запятыми:

КОД
item(Status, In Progress)

Если аргумент содержит запятые или круглые скобки, вам необходимо заключить его в «двойные кавычки» или «одинарные кавычки»:

КОД
item(Status, "Done, Sealed, and Delivered")
folder("NU (non-urgent) issues")

В предыдущем примере сопоставляются элементы состояния в структуре с именами «Готово», «Запечатано» и «Доставлено» ("Done, Sealed, and Delivered"). Если бы это имя не было заключено в кавычки, запрос означал бы, что элемент функции получает четыре аргумента: «Статус», «Готово», «Запечатано» и «Доставлено»(Status, Done, Sealed and and Delivered.

Последний пример соответствует папкам с именами NU (несрочные) проблемы. Если бы кавычки не использовались, запрос был бы некорректным, так как первая закрывающая скобка воспринималась бы как конец аргументов папки.

Если ваш аргумент содержит кавычки, вам нужно использовать другой тип кавычек, чтобы заключить его. Предположим, вам нужно сопоставить версию с именем 3.0, 3.0.1 «Армагеддон»:

КОД
item(version, '3.0, 3.0.1 "Armageddon"')

Вы также можете избежать кавычек, используя обратную косую черту (\). Предположим, что версия называется 3.0 Beta 1 «Ближе Армагеддона»:

КОД
item(version, '3.0 Beta 1 "Armageddon\'s Near"')

Если вам нужно использовать символ обратной косой черты сам по себе, вы можете избежать его с помощью другой обратной косой черты (\\). Предположим, вам нужно сопоставить папку с именем \ (обратная косая черта) и соответствующими символами:

КОД
folder ('\\ (backslash) and related characters')

Обратите внимание: если вам не нужно заключать аргумент в кавычки, вам не нужно экранировать содержащиеся в нем кавычки или обратную косую черту:

КОД
folder (Joe's)
folder ( \ )

Наконец, если есть только один аргумент, и аргумент не содержит пробелов (или заключен в кавычки), вы можете опустить круглые скобки:

КОД
folder Urgent
folder "Not urgent"

folder()

Эта функция сопоставляет элементы папки в структуре, при необходимости фильтруя их по имени.

Без аргументов эта функция соответствует всем папкам:

КОД
folder()

С одним аргументом эта функция сопоставляет папки по имени (которое вы видите в столбце «Сводка»). Папка соответствует, если ее имя начинается с текста, указанного в первом аргументе. Разница между заглавными и строчными буквами игнорируется.

Например, следующие запросы соответствуют папкам с именами «Мои задачи», «Задачи для Кэрол» и «Не-задачи»( “My issues”,” Issues for Carol”, и “Non-issues”); и не соответствуют папкам с именами Issuing или Issuance:

КОД
folder issue
folder Issue

Если вы укажете несколько слов, разделенных пробелами, папка будет соответствовать только папкам, содержащим все эти слова.

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

Для тех, кто любит использовать регулярные выражения, есть расширенный вариант сопоставления.

Нажмите здесь для раскрытия...

Чтобы сообщить папке, что вы указываете регулярное выражение, заключите его в косую черту (/):

КОД
folder /i.*ue/

Если аргумент начинается с косой черты, но не заканчивается косой чертой, сопоставление с регулярным выражением не выполняется, и он сопоставляется как простой текст. Если вам нужно написать простой текстовый поиск, в котором текст начинается и заканчивается косой чертой, закройте ведущую косую черту обратной косой чертой (\):

КОД
folder \/???/

Запрос в приведенном выше примере соответствует папке /???/.

Еще одна сложная тема — как запрашивать точное слово (например, совпадать с задачей, но не с задачами).

Нажмите здесь для раскрытия...

Это называется строгим поиском. Строгий поиск включается, когда искомый текст начинается и заканчивается двойной кавычкой ("). Обратите внимание, однако, что кавычки удаляются из аргументов функции, поскольку кавычки также используются для указания пробелов или круглых скобок в искомом тексте. Таким образом, вам нужно будет заключить текст поиска в одинарные кавычки ('):

КОД
folder '"issue"'

item()

Эта функция сопоставляет элементы указанного типа в структуре, при необходимости фильтруя их по имени. Это обобщение функции folder() для других типов элементов.

Функция принимает два аргумента: тип элемента и имя (необязательно). Второй аргумент работает так же, как аргумент для функции folder().

Вы можете ссылаться либо на стандартные типы элементов (предоставляемые плагином Structure), либо на типы элементов, предоставляемые сторонними плагинами.

Если вам нужно сопоставить элементы всех типов, используйте звездочку (*). Следующий запрос находит все элементы, в сводке которых есть слово «Инфраструктура», независимо от их типа:

КОД
item(*, Infrastructure)

Структура предоставляет следующие типы элементов:

КОД
issue
project
version
version-name
project-component
issuetype
status
resolution
priority
label
user
group
date
cf-option
folder
memo
generator
loop-marker
sprint
missing
tempo-account (при наличии плагина Tempo Timesheets)
sd-request-type (при наличии подключаемого модуля Jira Service Management / Jira Service Desk)

Плагин Structure.Pages предоставляет следующие типы элементов:

КОД
page

Типы элементов, предоставляемые сторонними плагинами, указываются аналогичным образом. Вот как функция item() ищет типы элементов:

1. Он пытается интерпретировать аргумент имени типа как ссылку на тип элемента, предоставленный Structure, и ищет его в списке выше.
2. Если он не найден, он просматривает все типы элементов, предоставляемые всеми плагинами (включая саму структуру), и проверяет, заканчивается ли имя типа указанным текстом в виде слова. «Как слово» означает, что страница будет соответствовать типу элемента страницы Confluence, а возраст — нет. В частности, рассматриваемыми границами слов являются дефис (-), подчеркивание (_) и двоеточие (:).
3. Неоднозначное указание типа элемента, т. е. если есть два типа элемента, соответствующие описанию, является ошибкой. Следующие формы аргумента типа элемента позволяют более точно указать тип элемента.

• Полное имя типа элемента, например. com.almworks.jira.structure:type-issue или com.almworks.structure.pages:type-confluence-page.

В более общем виде форма выглядит так: <ключ плагина>:<имя типа>.

• Сокращенная форма полного имени типа элемента, например, структура:выпуск или страницы:страница.

В более общем виде форма выглядит так: <часть ключа плагина>:<часть имени типа>.

Когда функция item() ищет тип элемента для аргумента, а аргумент содержит двоеточие (:), функция сначала пытается интерпретировать его как полное имя. Только если ничего не найдено, пытается интерпретировать как сокращенную форму.

Пустое ограничение

Пустое ограничение, не соответствующее элементам:

КОД
empty

Это ограничение играет ту же роль, что и ключевое слово JQL EMPTY. Он предназначен для использования в качестве дополнительного ограничения в реляционных ограничениях, которые обсуждаются далее.

Отрицание

Любое ограничение, базовое или реляционное, может быть отменено с помощью ключевого слова NOT. Это создает ограничение, которое соответствует всем элементам, которых нет в исходном ограничении:

КОД
not root

соответствует всем элементам, которые не являются элементами верхнего уровня в структуре.

Вы всегда можете заключить ограничение в круглые скобки, чтобы облегчить понимание. Таким образом, все элементы в структуре, кроме вопросов TS-129 и TS-239, соответствуют этому структурному запросу:

КОД
not (TS-129, TS-239)

Реляционное ограничение

Базовое ограничение соответствует элементам, которые удовлетворяют условию. Реляционное ограничение сопоставляет элементы, связанные с элементами, которые удовлетворяют условию. Связанные соответствуют отношениям между позициями элементов в структуре, например, родитель-потомок.

Например,

КОД
TS -129

является основным ограничением, которое соответствует одной проблеме -129;

КОД
child in TS-129

представляет собой реляционное ограничение, соответствующее элементам, имеющим TS-129 в качестве дочернего элемента (подэлемента).

Реляционное ограничение имеет форму оператора отношения subConstraint. Здесь subConstraint — это ограничение на родственников сравниваемых элементов; другие части реляционного ограничения обсуждаются в следующих разделах.

Обратите внимание, что форма реляционного ограничения аналогична форме предложения JQL, значения оператора поля.

Действительно, опишем на английском языке тип JQL-запроса в (Epic, Story): ему соответствуют задачи, имеющие тип, который находится в значениях Epic, Story.

Теперь давайте опишем на английском языке родительский запрос структуры в [type = Epic]: он соответствует элементам, у которых родительский элемент находится в ограничении «type = Epic».

Как видите, форма, которую можно использовать для описания структурного запроса, аналогична форме JQL.

 Отношения

S-JQL имеет следующие отношения: 

• child: дочерний элемент: элемент является дочерним элементом (подэлементом) другого элемента в структуре.
• parent: элемент является родителем другого элемента в структуре.
• descendant: элемент является потомком (под- или под-под-...-элементом) другого элемента в структуре.
• ancestor: элемент является предком (родителем, родителем-родителя или родителем-родителя-...-родителя) другого элемента в структуре.
• sibling: элемент является братом другого элемента в структуре. Два элемента считаются родственными, если они находятся под одним и тем же родительским элементом.
• prevSibling: элемент является предыдущим (предшествующим) родственным элементом другого элемента в структуре. элемент A предшествует элементу B, если он является родственным элементу B и A выше, чем B (A предшествует B.)
• nextSibling: элемент является следующим (следующим) родственным элементом другого элемента в структуре.элемент A является следующим братом элемента B, если он является братом элемента B и A ниже, чем B (A идет после B.)
• self и issue — отношения предмета (или задачи) к самим себе. Их роль будет объяснена позже, в разделе, посвященном отношениям к себе и задаче, потому что сначала нужно изучить, как работают операторы и подограничения.

Существуют также комбинации вопроса и себя со всеми другими отношениями, перечисленными для полноты ниже:

Те, кто знаком с XPath, могли распознать эти отношения; действительно, они работают как соответствующие оси XPath.

Операторы

Это операторы, используемые в S-JQL:

IN, NOT IN, IS, IS NOT, =, !=, OF

оператор указывает, как subConstraint применяется к отношению:

1. IN, IS and = накладывают ограничения на родственников соответствующего элемента.

Например, рассмотрим

КОД
child in (TS-129, TS-239)

Здесь отношение является дочерним, поэтому относительный элемент рассматриваемого элемента является его дочерним в структуре. Таким образом, элемент соответствует, если хотя бы один из его дочерних элементов является TS-129 или TS-239.

2. NOT IN, IS NOT и != являются инвертированными версиями IN, IS и =. То есть элемент сопоставляется, если он не связан с каким-либо элементом, соответствующим subConstraint.

Например, рассмотрим

КОД
child not in (TS-129, TS-239)

Элемент соответствует, если ни один ребенок не является TS-129 или TS-239. Таким образом, это ограничение соответствует всем элементам, которые либо не имеют дочерних элементов, либо не имеют ни одного из этих двух элементов среди своих дочерних элементов.

КОД
not (child in (TS-129, TS-239))

КОД
child in (not (TS-129, TS-239))

3. OF соответствует родственникам элементов, которые удовлетворяют subConstraint.

Например, рассмотрим

КОД
child of (TS-129, TS-239)

Элемент совпадает, если он является потомком TS-129 или TS-239.

 Чтобы получить представление о том, как работают операторы IN (IS, =) и OF, и понять разницу между ними, рассмотрите приведенную ниже таблицу. Предположим, что мы берем все элементы в структуре и помещаем каждый из них один за другим в элемент столбца. Для каждого элемента мы берем все его родственники и помещаем каждого из них один за другим в относительный столбец. Таким образом, мы получаем пары предметов. Мы проверяем каждую пару, и если один из компонентов удовлетворяет subConstraint, мы добавляем другой компонент в набор результатов. Какой компонент добавляется, зависит от оператора:

КОД
child in (TS-129, TS-239)

КОД
parent of (TS-129, TS-239)

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

Подограничения

В качестве подограничения можно использовать любое ограничение, базовое, реляционное или их комбинацию.

Например,

КОД
child of root

выбирает элементы на втором уровне иерархии. Чтобы выбрать элементы на третьем уровне иерархии, вы можете снова использовать дочернее отношение и предыдущий запрос в качестве подограничения subConstraint:

КОД
child of (child of root)

Существует специальное базовое ограничение, пустое, которое не соответствует ни одному элементу. Он используется в качестве подограничения для сопоставления элементов, которые не имеют реляций в соответствии с отношением.

Например, возьмем дочернее отношение и посмотрим, что означают соответствующие реляционные ограничения с разными операторами.

Конечно, использовать leaf или root удобнее, но вы можете применить empty к любому другому отношению. Например, sibling is empty соответствует элементу, если он является единственным дочерним элементом своего родителя.

отношения self и Issues: добавление соответствий подограничения в набор результатов

Реляционное ограничение с отношением self ведет себя точно так же, как его подчиненное ограничение, возможно, инвертированное, если используется оператор NOT IN (IS NOT, !=).

Таким образом,

 КОД
self in [status = Open]

эквивалентно

КОД
[status = Open]

Сходным образом,

КОД
self not in [status = Open]

эквивалентно

КОД
not [status = Open]

В сочетании с другим отношением self позволяет добавлять элементы, соответствующие subConstraint, в результирующий набор. Например,

КОД
descendant of TS-129

возвращает всех потомков TS-129 на всех уровнях, но не возвращает сам TS-129. Чтобы добавить TS-129, используйте descendantOrSelf:

КОД
descendantOrSelf of TS-129

отношение задача

issue (задача) - это особый случай отношения self, который соответствует только задачам. Например, если на верхнем уровне структуры у вас есть папки и задачи, и вы хотите скрыть все папки, вы можете написать это:

КОД
descendantOrIssue of root

Этот запрос соответствует всем задачам верхнего уровня и всем их подэлементам.

Объединение ограничений с логическими операторами

Теперь мы можем определить структурный запрос как булеву комбинацию ограничений, то есть структурный запрос состоит из ограничений, связанных с И и ИЛИ. Когда два ограничения связаны с И, вместе они будут соответствовать задачам, которые соответствуют обоим ограничениям. Это позволяет ограничить результаты. Аналогичным образом, когда два ограничения связаны по ИЛИ, вместе они будут соответствовать задачам, которые соответствуют хотя бы одному из ограничений. Это позволяет расширить результаты.

Обратите внимание, что И имеет более высокий приоритет, чем ИЛИ. Это означает, что запрос структуры

КОД
leaf or (parent of leaf) and [status = Open]

соответствует всем задачам, которые либо являются листьями, либо являются родителями листьев в статусе Открыто. Чтобы также ограничить конечные задачи со статусом Open, вам нужно использовать круглые скобки:

КОД
(leaf or (parent of leaf)) and [status = Open]

Схемы синтаксических диаграмм

В качестве последней справки приведем синтаксис S-JQL в виде схем железных дорог.

structure-query структурныйзапрос

constraint ограничение

basic-constraint основное ограничение

• jql-query — любой действительный запрос JQL.
• ключ задачи — это любой допустимый ключ задачи JIRA.
• ID задачи — любой допустимый идентификатор задачи JIRA.
• имя-ограничения — это имя ограничения функции: либо связанное со структурой (папка, элемент или row_id), либо предоставленное расширением структуры (плагин).
• аргумент-ограничения является одним из следующих:
  • либо последовательность непробельных символов
  • или текст в кавычках (внутри «двойных кавычек» или «одинарных кавычек»), где кавычки можно экранировать с помощью обратной косой черты: \», \'; саму обратную косую черту можно экранировать: \\.

См. также Функциональное ограничение — Синтаксис.

relation отношение

operator оператор

По материалам Atlassian JIRA Structure: S-JQL Reference