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, dictate where Jira 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 that 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 and 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 Software 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 sizable impact on run times in
larger data sets.

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.