JQL functions – Advanced searching in JIRA

JQL full form is Jira Query Language is used to search your issues in Jira. A JQL query is a set of words and operators that define how JIRA will narrow your search. A function in JQL appears as a word followed by parentheses, which may contain one or more explicit values or JIRA fields.

Field – Fields are different types of information in the system. Jira fields include priority, fix Version, issue type, etc.

A keyword in JQL −

• joins two or more queries together to form a complex JQL query.
• alters the logic of one or more queries.
• alters the logic of operators.
• has an explicit definition in a JQL query.
• performs a specific function that defines the results of a JQL query.

Keywords − Keywords are specific words in the language that have special meanings. 

• AND − ex – status = open AND priority = urgent And assignee = Ashish.
• OR − ex – duedate < now() or duedate is empty.
• NOT − ex – not assignee = Ashish .
• EMPTY − ex – affectedVersion is empty / affectedVersion = empty.
• NULL − ex – assignee is null.
• ORDER BY − ex – duedate = empty order by created, priority desc.

Operators: Operators are used to comparing values of the left side with the right side, such that only true results are displayed as the search result.

List of Operators

• Equals: =
• Not Equals: !=
• Greater Than: >
• Less Than: <
• Greater Than Equals: =>
• Less than equals: =<
• IN
• NOT IN
• CONTAINS: ~
• Does Not contain: ! ~
• IS
• IS NOT
• WAS
• WAS IN
• WAS NOT IN
• WAS NOT
• CHANGED

JQL Restricted/Reserved words and characters

JQL has a list of reserved characters: space (” “) + . , ; ? | * / % ^ $ # @ [ ]

If you wish to use these characters in queries, you need to:

• surround them with quote marks (you can use either single quote-marks (‘) or double quote-marks (“)); and if you are searching a text field and the character is on the list of reserved characters for text searches,
• precede them with two backslashes. For example: version = “[example]”

Common JQL Filters

epicsOf: This function allows you to query epic links, such as finding all epics that have unresolved stories.

Syntax: issueFunction in epicsOf (Subquery)

Examples: issueFunction in epicsOf (“project=DIGITAL and resolution = unresolved”)

issueFunction in epicsOf (“project=DIGITAL and issuetype = defect and status not in (Closed,Resolved,Abandoned)”)

Explanation: The first query will return all the epics with unresolved issues in the DIGITAL project. The second query will return all the epics with defects not having Closed, Resolved, Abandoned in them for DIGITAL project.

linkedIssues(): If you want to get the list of issues linked to a specific issue, use the built-in JQL function linkedIssues().

Syntax: issue in linkedIssues(issueKey)

Example: issue in linkedIssues(“DIGITAL-1”)

linkedIssues(): If you want to get the list of issues linked to a specific issue with a specific link type, use the built-in JQL function linkedIssues(issueKey, linkType).

Syntax: issue in linkedIssues(issueKey, linkType).

Example: issue in linkedIssues(“DIGITAL-1”, implements)

hasLinks(): If you want to filter all issues that have ANY linked issues, use hasLinks(link type) function.

Syntax: issueFunction in hasLinks()

Example: issue in hasLinks(implements)

issuesinEpics: This function lets you find all stories, tasks, etc for open epics in a project, and then look specifically at the status of issues, such as in progress, open, etc.

Syntax: issueFunction in issuesInEpics (Subquery)

Example: issueFunction in issuesInEpics (“project=DIGITAL and status = ‘in progress’”)

Explanation: This query will return all the stories, tasks, etc for open epics in the project DIGITAL.

linkedIssuesOf: This function allows you to return linked issues, such as all unresolved issues that are blocked by open issues.

Syntax: issueFunction linkedIssuesOf(Subquery, [link name])

Example: issueFunction linkedIssuesOf (“project=DIGITAL and status=Open”) and resolution is empty

Explanation: This query will return the issues that are open in DIGITAL project and the team hasn’t started yet.

linkedIssues OfRecursive: This function allows you to return linked issues recursively, that is, to return all issues that are linked directly and indirectly to the results of the initial query. For example, the example query returns all issues linked to DIGITAL-1. 

Syntax: issueFunction in linkedIssuesOfRecursive (Subquery)

Example: issueFunction in linkedIssuesOfRecursive(“issue =DIGITAL-1”)

Explanation: This query will return all of the links, both direct and indirect, that trace back to that main issue. So this information gives a good idea of the scope of a particular issue.

linkedIssuesOf AllRecursive: This function allows you to include the sub-task and epic links when you don’t specify a link type. Otherwise, it functions identically to linkedissuesofRecursive

Syntax: issueFunction in linkedIssuesOf AllRecursive

Example: issueFunction in linkedIssues OfAllRecursive(“issue =DIGITAL-1”)

Explanation: This query will return all-recursive links that also include all epics and all subtasks for an issue as well.

substasksOf: This function allows you to query epic links, such as finding all epics that have unresolved stories.

Syntax: issueFunction in subtasksOf (Subquery)

Example: issuefunction in subtasksOf (“issuetype = story and status != closed”)

Explanation: This query will return a list of all sub-tasks with issue-type stories that are not marked closed.

parentsOf: This function allows you to return the parents of issues that you specify in the subquery. For example, you can find the parent issues of all issues where you are the assignee of an open sub-task using the resolution is empty and currentUser function.

Syntax: issueFunction in parentsOf (Subquery)

Example: issueFunction in parentsOf (“resolution is empty and assignee = currentUser()”)

Explanation: This query will return all of the parent issues where you are the assignee of an open sub-task.

projectMatch / componentMatch / versionMatch: These functions provide lists of projects, components, and versions respectively that match the provided regular expression.

Syntax:

• projectMatch(reg exp)
• componentMatch(reg exp)
• versionMatch(reg exp)

Example: component in componentMatch(“^Web.*”)

All issues that have a component beginning with Web.

fixVersion in versionMatch(“^2020-*”) 

All issues in the JRA project that have a fix version beginning with 2020-.

addedAfterSprintStart: Shows issues that were added to the named sprint (or all active sprints if a second argument is not provided), after the sprint started. This is useful for seeing how the scope of a sprint has changed when the sprint is in progress.

Syntax: issueFunction in addedAfterSprintStart(board name, [sprint name])

Example: issueFunction in addedAfterSprintStart(“DIGITAL Scrum Board”, “DIGITAL Sprint 1”)

Explanation: This shows issues that were added to the named sprint (or all active sprints if the second argument is not provided), after the sprint started. This is useful for seeing how the scope of a sprint has changed when the sprint is in progress.

removedAfterSprintStart: Shows issues that have been removed from the named sprint (or all active sprints if a second argument is not provided), after the sprint has started.

Syntax: removedAfterSprintStart(board name, [sprint name])

incompleteInSprint: Shows issues that have not been completed in the named sprint (or all active sprints if a second argument is not provided).

Syntax: incompleteInSprint(board name, [sprint name])

completeInSprint: Shows issues that are complete in the named sprint (or all active sprints if a second argument is not provided).

Syntax: completeInSprint(board name, [sprint name])

nextSprint: Shows issues that are members of the next, not-yet-started sprint on the specified board.

Syntax: nextSprint(board name)

previousSprint:Shows issues that are members of the last completed sprint.

Syntax: previousSprint(board name)

openSprints(): Search for issues assigned to a Sprint that has not yet been completed. Note, it is possible for an issue to belong to both a completed Sprint(s) and an incomplete Sprint(s).

Syntax: sprint in openSprints()

Example: Find all issues that are assigned to a sprint that has not yet been completed: sprint in openSprints()

closedSprints(): Search for issues assigned to a completed Sprint. Note, it is possible for an issue to belong to both a completed Sprint(s) and an incomplete Sprint(s)

Syntax: sprint in closedSprints()

Example: Find all issues that are assigned to a completed sprint: sprint in closedSprints()

releasedVersions(): Perform searches based on the released versions (i.e. versions that your JIRA administrator has released) of a specified project. You can also search on the released versions of all projects, by omitting the project parameter. 

Syntax: fixVersion in releasedVersions() or affectedVersion in releasedVersions()

Example: 

• Find issues whose FixVersion is a released version of the DIGITAL project: fixVersion in releasedVersions(DIGITAL)
• Find issues that relate to released versions of the DIGITAL project: (affectedVersion in releasedVersions(DIGITAL)) or (fixVersion in releasedVersions(DIGITAL))

unreleasedVersions(): Perform searches based on the unreleased versions (i.e. versions that your JIRA administrator has not yet released) of a specified project. You can also search on the unreleased versions of all projects, by omitting the project parameter.

Syntax: unreleasedVersions() or unreleasedVersions(project)

Example:

• Find issues whose FixVersion is an unreleased version of the DIGITAL project:
  fixVersion in unreleasedVersions(DIGITAL)
• Find issues that relate to unreleased versions of the DIGITAL project:
  affectedVersion in unreleasedVersions(DIGITAL)

latestReleasedVersion(): Perform searches based on the latest released version (i.e. the most recent version that has been released) of a specified project. Note, the “latest” is determined by the ordering assigned to the versions, not by actual Version Due Dates.

Syntax: latestReleasedVersion(project)

Example: 

• Find issues whose FixVersion is the latest released version of the DIGITAL project: fixVersion = latestReleasedVersion(DIGITAL)
• Find issues that relate to the latest released version of the DIGITAL project:
  affectedVersion = latestReleasedVersion(DIGITAL) or fixVersion = latestReleasedVersion(DIGITAL)

earliestUnreleasedVersion(): Perform searches based on the earliest unreleased version (i.e. next version due to be released) of a specified project. Note, the “earliest” is determined by the ordering assigned to the versions, not by actual Version Due Dates.

Syntax: earliestUnreleasedVersion(project)

Examples: 

• Find issues whose FixVersion is the earliest unreleased version of the DIGITAL project: fixVersion = earliestUnreleasedVersion(DIGITAL)
• Find issues that relate to the earliest unreleased version of the DIGITAL project: affectedVersion = earliestUnreleasedVersion(DIGITAL) or fixVersion = earliestUnreleasedVersion(DIGITAL)

Recommended Reading

• Scrum Board – Create & Customize for Scrum Team
• Kanban Board – Create & Customize for Kanban Team
• Scrum Board – Tips and Tricks for JIRA
• JIRA Structure – Create & Manage Epics and Stories
• Bulk Jira Issue creation using CSV Template
• JIRA Reports use in tracking Agile Projects
• Issue Analysis Reports use in Agile Projects
• Sprint ID for an Active or Closed Sprint
• Text Field search using advanced search in JIRA

JIRA Reference: Click Here