JQL optimization recommendations

All JQL queries are not created equal. JQL uses a strict logic that will do exactly what you tell it to do, whether or not it’s the most efficient way. These inefficiencies can add up, causing performance issues in boards, plans, or projects.

On this page, we’ll talk about some general guidelines for writing an efficient JQL query.

Limit the scope of your query

When constructing your JQL query, tell Jira where it should search for issues by including or excluding specific projects or boards.

When a query has to search through fewer issues, results load faster.

Example

Let’s say you want to view all the work assigned to you using a JQL filter. However, you only work on two projects within your entire organization.

This query works:

assignee is currentUser()

But this one is better:

project in (The Big Cheese, Project Kanban) and assignee is currentUser()

Why?

The first query searches through all of the issues in your site to find the ones assigned to you. The second query is more focused on your projects. If your site has 10,000 issues Jira can look at the 500 issues in those projects and can ignore the remaining 9,500. Fewer issues to sort through, the quicker the query can run, even though the results are the same.

You can also use other fields to narrow the scope of your JQL query, such as dates, project type, or last viewed.

Use OR for main clauses with AND for sub-clauses

Due to the way that Jira interprets queries, a seemingly logical string might be broken down into several redundant searches that can take longer to execute. A common cause of redundant searches is using AND in main clauses. We recommend that AND mostly be used in sub-clauses, and that OR is reserved for main clauses. Or in more plain words, we recommend that your OR clauses live outside the brackets, and your AND clauses are inside.

Example

Say you use a JQL query to only show issues included in Project PMO or assigned to Assignee A as well as those from Project TIS or assigned to Assignee B.

This query works:

(project = TIS OR assignee = A) AND (project = PMO OR assignee = B)

But this one is better:

project in (TIS, PMO) OR assignee in (A, B)

Why?

This is because when JQL contains an AND clause, Jira only returns issues that match both sub-clauses not either/or, and would interpret the first query as:

• in Project TIS AND in Project PMO

• assigned to Assignee B AND in Project TIS

• assigned to Assignee A AND in Project PMO

• assigned to Assignee A AND assigned to Assignee B

Not only will the latter two searches not return any results, but Jira still runs the searches regardless. These unneeded searches can slow down the performance of your JQL query. The second query excludes the redundant searches, which can have a sizeable impact on run times in larger data sets.

Again, include a specific project or board to make sure the query doesn’t have to sift through unnecessary issues.

Avoid troublesome fields and functions

Some fields are known to be slow because of how complicated they are. For example, the label field needs to reference multiple data sets, which makes it a complicated field to use in search. However, the same results can be achieved quicker using the IssueKey field.

Certain functions can also be problematic. For example, the portfolioChildIssuesOf function requires several recursions through the database to use. As of right now, there’s no recommended work around.

Build your JQL query one clause at a time

The two fields and functions mentioned here are by no means an exhaustive list. You can identify which fields and functions are causing delays in your query by building it clause by clause instead of writing all of it at once. By gradually adding functions to your clause then running your search, you can identify which fields are the slowest, and mitigate or avoid those fields.