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 Button

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

After clicking 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. If a sprint is not chosen, then the default is the current active 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)

Jira Software users can query on epic links. For example, find all Epics that have unresolved stories:

issueFunction in epicsOf("resolution = unresolved")

Jira Software users can also query on epic links to find all epics which do contain any issues.

project = <ProjectKeyHere> and issuetype = Epic and NOT (issueFunction in epicsOf("project = <ProjectKeyHere>")

This function will only return issues of the Epic type.

issuesInEpics(subquery)

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 / componentMatch

The following functions provide lists of projects and components that match the provided regular expression.

projectMatch(reg exp)
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(subquery)

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

parentsOf(subquery)

Returns the parents of issues specified by the subquery. For example, to find Closed parents with Open sub-tasks in the project DEMO, you could do:

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

To show parent issues that have at least one open sub-task, in the DEMO project, you might do:

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.