JQL Functions

Enhanced Search features several JQL functions not available as default in Jira, which are documented within this section.

There are two ways to insert functions into your Enhanced Search JQL queries. Add functions either by typing into the text field or by clicking Insert Function.

Available Fields

Functions can be customised in many ways, and search a variety of fields in Jira. Make a request to the Jira Cloud REST API to see all fields you can use inside of the function expressions. For example, customfield_10024 or priority.id.

https://your-Jira.atlassian.net/rest/api/2/issue/{issueIdOrKey}?expand=schema

Subqueries

Most of the functions require a JQL 'subquery' as the starting point for the function you’ve selected. Providing an empty string (e.g. "") causes the query to match each issue in your Jira instance, making your query very inefficient.

Insert Function

We have provided the Insert Function option to help new users generate the correct JQL for their query.

After clicking the '+' Insert Function, the Insert Functions and Users window opens. A list of available functions is shown on the left. Select a function from the list to be presented with a form you can fill in to generate valid JQL for that function.

After filling in all required fields on the form, click Add to Query to add the relevant query clause to the end of your existing search query.

When your query has been added, click the Search for Issues icon.

Text Field

More advanced users can type their JQL query directly into the JQL query text field. Alternatively, you can use the text field to make small edits to a JQL created using the Insert Function feature, such as quickly changing the project name.

Operators

Enhanced Search uses the in and not in operators for all JQL functions. You can also use some additional operators for the Date Function.

Agile Functions

The following functions search issues based on sprint information.

inSprint

Query sprint issues of a specified agile board.

inSprint(board, sprint)

issueFunction in inSprint("EX Scrum Board", "Sprint 3")

nextSprint

Query the issues of the next active sprint of a specified agile board.

nextSprint(board)

issueFunction in nextSprint(452) AND assignee = currentUser()

previousSprint

Query the issues of the previous active sprint of a specified agile board.

previousSprint(board)

issueFunction in previousSprint("Kanban Board") AND fixVersion IS EMPTY

addedAfterSprintStart

Query the issues added after the sprint began for the active sprint of an agile board. Only the board name is required. The current active sprint is the default if a sprint is not chosen. However, if there is more than one current sprint (parallel sprints) enabled for the board, it is mandatory to add the sprint parameter, as the function can only return one sprint. 

addedAfterSprintStart(board, sprint)

issueFunction in addedAfterSprintStart("EX Scrum Board", "Sprint 3")

Using IDs

You can use the board ID or name as the first argument. If a board and sprint are used, but the sprint was not created from that particular board, then the function will not show any results. The sprint needs to have been created from the board used in the function. This is a limitation on the information we receive from Jira when an issue is moved into a sprint after the sprint has started.

You can use the sprint ID as the second parameter, but you must not contain the ID within quotes. For example:

issueFunction in addedAfterSprintStart("EX Scrum Board", 30)

To find the sprint ID:

1. Go to the board's backlog.

2. Right click the elipsis icon just above the sprint.
   

3. Copy the link, or URL, that looks similar to https://your-jira-instance.atlassian.net/rest/greenhopper/1.0/xboard/plan/sprints/actions?sprintId=30.
4. Go to the end of the link where you can retrieve the ID. In this example, the ID is 30.

Date Functions

dateCompare

The dateCompare function compares two dates on the same issue, for instance to find all issues that were updated later than the created date:

dateCompare(Subquery, date comparison expression)

issueFunction in dateCompare("project = DEMO", "created < updated")

Time Windows

Use time windows on both side of the expression. For example, if you needed to find issues resolved before or up to six days after their due date:

issueFunction in dateCompare("project = DEMO", "resolutiondate +1d < duedate +1w")

Created and Updated

Use created or updated to find issues based on when they were created or updated. For example, to find issues that were resolved within two weeks of creation, use:

issueFunction in dateCompare("project = DEMO", "created +2w > resolutiondate ")

Datetime Custom Fields

Use date and datetime custom fields. For example:

issueFunction in dateCompare("project = DEMO", "resolutiondate > customfield_10500")

(where customfield_10500 is the name of a 'date' custom field).

Operators

Equal to Operator

Use the equality operator = to find issues that have been resolved on the same date that’s in a custom field:

issueFunction in dateCompare("project = DEMO", "resolutiondate = customfield_10500")

Greater than or Equal to Operator

Use the greater or equal operator >= to find issues that have been resolved on or after the same date that’s in a custom field:

issueFunction in dateCompare("project = DEMO", "resolutiondate >= customfield_10500")

Smaller or Equal to Operator

Use the smaller or equal operator ⇐ to find issues that have been resolved on or before the same date that’s in a custom field:

issueFunction in dateCompare("project = DEMO", "resolutiondate <= customfield_10500")

Not Equal to Operator

Use the not equal operator != to find issues that have been resolved on a different date than that’s in a custom field:

issueFunction in dateCompare("project = DEMO", "resolutiondate != customfield_10500")

Clear Time Operator

Use the .clearTime() method to get the date part of a date or datetime field. The date is converted to the user’s timezone, before the date is extracted:

issueFunction in dateCompare("project = DEMO", "customfield_10500.clearTime() = duedate.clearTime()")

Epic Functions

Use this JQL function to filter via epic links.

epicsOf(subquery)

The epicsOf function returns epics associated with the issues found by the subquery provided.

Finding epics with Issues

To find epics with associated issues, you would use a subquery within epicsOf that specifies the criteria for the issues of interest. For example, to find epics related to all issues with a specific label, you might use issueFunction in epicsOf("labels = 'urgent'").

This query returns all epics that contain at least one issue labelled 'urgent'.

Finding empty epics

To identify epics within a specific project with no child issues, you can use the epicsOf function in conjunction with other JQL criteria.

You may try something like the example below, which may work depending on your use case.

issueFunction not in epicsOf("project = <project name>") AND project = "<project name>" AND issueType = Epic

issuesInEpics(subquery)

This function allows you to find issues related to epics found by the subquery. For example, find all stories for open Epics in a project:

issueFunction in issuesInEpics("project = DEMO AND status = 'To Do'")

issueFunction in issuesInEpics("resolution IS NOT EMPTY") AND resolution IS EMPTY

Issue Link Functions

The following functions use issue link attributes to sort through issues.

linkedIssuesOf

linkedIssuesOf(Subquery, [link name])

This is similar to parentsOf and subtasksOf, in that it will return the linked issues.

To find all the unresolved issues that are blocked by issues in the Open state you could use:

issueFunction in linkedIssuesOf("status = Open", "blocks") AND resolution IS EMPTY

With no link name argument, this function will search for the linked issues whatever the link type:

issueFunction in linkedIssuesOf("resolution = unresolved")

linkedIssuesOfRecursive

linkedIssuesOfRecursive(Subquery, [Link name])

This is similar to linkedIssuesOf, in that it will return the linked issues, however this function traverses issue links recursively to return all issues that are linked (directly and indirectly) to the results of the initial subquery.

We have protection mechanisms built in to deal with circular dependencies in your issue links. For example, if DEMO-1 links to DEMO-2, DEMO-2 links to DEMO-3 and DEMO-3 links to DEMO-1, then we will notice that we have already seen DEMO-1 and stop processing. 

To find all direct and indirectly linked issues of a particular issue you can use:

issueFunction in linkedIssuesOfRecursive("issue = DEMO-1")

So if we have the following setup:

Then our query would return: DEMO-1, DEMO-2, DEMO-3, DEMO-4 and DEMO-5.

You can limit the type (and direction) of links that are traversed using the second parameter.

issueFunction in linkedIssuesOfRecursive("issue = DEMO-1", "blocks")

In this instance, if we use the example already mentioned, only DEMO-2, DEMO-3 and DEMO-4 will be returned.

The Link Type parameter behaves exactly the same as the Link Description parameter for linkedIssuesOf.

linkedIssuesOfRecursiveLimited

linkedIssuesOfRecursiveLimited(Subquery, Traversal depth, [Link name])

This function is exactly the same as linkedIssuesOfRecursive but it allows us to limit the depth of traversals along issue links that the function will do.

The following query will follow all links, recursively, from all issues in the DEMO project until it has traversed a maximum of 2 links deep along any link path.

issueFunction in linkedIssuesOfRecursiveLimited("project = DEMO", 2)

Using the following setup:

Our query with the depth parameter would return: DEMO-1, DEMO-2, TEST-1, TEST-2, TEST-4 and TEST-5.

We could specify the link name as well, to get different results:

issueFunction in linkedIssuesOfRecursiveLimited("issue = TEST-2", 3, "is blocked by")

which would return: TEST-3, TEST-6 and TEST-5

Match Functions

Filter issues based on specified field values.

issueFieldMatch

Query on any field by regular expression.

issueFieldMatch (subquery, fieldname, regexp)

To find all issues where the description contains a ABC0000 where 0000 is any number, you could use:

issueFunction in issueFieldMatch("project = DEMO", "description", "ABC\d{4}")

issueFieldExactMatch

Find issues by matching the text of a field exactly.

issueFieldExactMatch (subquery, fieldname, regexp)

projectMatch

The following functions provide lists of projects that match the provided regular expression for the project key.

projectMatch(reg exp)

For example, you want to look for all projects that have keys starting with ABC:

project in projectMatch("^ABC")

componentMatch

The following functions provide lists of components that match the provided regular expression for the component name.

componentMatch(reg exp)

For example, you want to look for all issues that have a component beginning with Web:

component in componentMatch("^Web.*")

versionMatch

The following function provides lists of versions that match the provided regular expression.

versionMatch(reg exp, [project keys])

For example, you want to find issues with the fixVersion field value that starts with RC across all projects:

fixVersion in versionMatch("^RC.*")

And the same search but restricted to several projects:

fixVersion in versionMatch("^RC.*", "DEMO, EXAMPLE, TEST")

Sub-task Functions

Return sub-tasks of issues, or parent of sub-tasks.

subtasksOf

Returns the sub-tasks of issues specified by the subquery. For example:

issueFunction in subtasksOf("project = DEMO")

To find unresolved sub-tasks of resolved issues you might do:

issueFunction in subtasksOf("resolution IS NOT EMPTY") AND resolution IS EMPTY

To find sub-tasks that are Open, but their parent issue has a resolution of Fixed, you could use:

issueFunction in subtasksOf("resolution = Fixed") AND status = Open

childrenOf

This function allows users to find descendant issues of a given subquery, including children and grandchildren. For instance, it can be used to find children issues of initiatives and epics.

The syntax for it is:

childrenOf(subquery)

Examples:

• To get all children issues of an initiative or any issue type:
  

  issueFunction in childrenOf("issue = EXAMPLE-1")
  
  

• To find children issues of a project that aren’t subtasks:
  

  issueFunction in childrenOf("project = DEMO") and issueType != "Subtask"

parentsOf

This function allows users to find the ancestor issues of a given subquery, including parents and grandparents. For instance, it can be used to find parent issues of subtasks, stories and epics.

To find the parent issue of subtasks:

parentsOf(subquery)

To find the parents (and grandparents) of stories, epics and beyond:

parentsOf(subquery, "all")

Examples:

• To find parent issues of subtasks in a project:

  issueFunction in parentsOf("project = DEMO")
  
  

• To find all the epics and initiatives in a project with stories, epics and initiatives:

  issueFunction in parentsOf("project = DEMO", "all")
  
  

• To find just the initiatives in a project which has initiatives, epics and stories:
  

  issueFunction in parentsOf("project = DEMO", "all") and issueType!="Epic"

• To find parent issues that have at least one open sub-task:
  

  issueFunction in parentsOf("project = DEMO AND status = Open")
  
  

• To find closed parent issues with open sub-tasks:
  

  status = Closed AND issueFunction in parentsOf("project = DEMO AND status = open")

Troubleshooting Tips

Occasionally you may see a red X show up next to your filter; this indicates an issue with the filter.

Check the filter for mistakes. In this example, a project name has not been specified. A correctly configured filter displays a green checkmark.