A short guide to the Jira Query Language 

Atlassian’s project management tool Jira offers organizations an unprecedented volume of options when it comes to task management, organizations, and scheduling. However, as your instance grows in the number of issues and accumulates thousands of epics, bugs, and stories, it’s time to change your approach. 

At first, remembering and keeping track of specific issues might be easy. But sooner or later, your teams will need a tool to make sense of all the complex information locked inside your instance. That’s why the search functionality is so important. 

In this article, I show what the Jira Query Language (JQL) is and how you can make the most of it at your organization. 

In general, Jira offers two simple searching interfaces to help its users find issues quickly: the Search field and JQL.

You’ll find it in the left-hand menu bar. Users can type in a keyword to carry out a quick search based on issue key, summary, comments, and description. It also allows taking advantage of Smart Querying, a simple search syntax similar to the one you use when searching your Gmail inbox. This functionality comes in handy if you want to find the issue you need quickly. However, it doesn’t allow to input details to make your searches more specific. 

Another search interface is the Search Issues screen. You can access it from the Issues menu. The basic version allows users to filter issues on the basis of any fields that are available in their instance. Note that this search function isn’t limited to the very small number of fields that are part of the Search box described above. 

Here, the filtering is carried out on a simple user interface that includes drop-down lists and input fields. To make your life easier, it’s pre-set with some common fields: project, issue type, status, and assignee. You can add other fields by clicking More and selecting the ones you’d like to search for. 

The smart thing about this functionality is that the filtering options of ever field are dynamically updated depending on the type of the field you choose. 

Even if it’s more advanced than the Search box, this screen has its limitations. That’s where JQL can help.

The Search Issues screen offers a more powerful search tool for users: JQL. Click on Advanced, and you’ll get a large text field. If you’ve already started with a basic search, the field will be pre-populated with those results. This is where the JQL magic happens.

Jira Query Language (JQL) is basically a text-based search language you can use in Jira to find the issues you’re looking for. It uses a human-readable syntax to deliver more complex logic and operators than the ones available in the basic search mode.

To show you how JQL works, here’s an example:

project = SCRUM1 AND (reporter = Radoslaw.Cichocki OR assignee = Radoslaw.Cichocki)

Thi JQL statement is pretty straightforward. You don’t need to have technical skills to read and understand it. It simply gives a list of issues that are in the SCRUM1 project whose reported, or assignee is me, Radoslaw Cichocki.  

The query is very simple, but you can’t construct anything similar to it in the Search Issues screen. Here’s why: the Search Issues limits the use of keywords. You can’t include both AND and OR in your search query. In JQL, you can do that – and the combination of these keywords is much easier to represent in textual syntax than in a graphical one. 

We can break the JQL syntax into five key elements: fields, operators, values, keywords, and functions.

By putting these elements together, you can create logical clauses to find specific sets or individual issues. 

For example, here’s a clause that combines a field, operator, and value:

created >= 2019-05-15

In this example, you can find all the issues created on or after May 15th, 2019. “created” acts as a field, “>=” is an operator, and “2019-05-15” works as a date value. Together, they form a complex statement that allows to find the issues you need easily. 

The beauty of JQL lies in its flexibility and versatility. You can combine these building blocks in multiple ways to form very complex statements.

All these elements can be combined in a multitude of ways to form very complex statements. When creating a more advanced JQL statement, start small and build it one piece at a time. Link multiple clauses with keywords such as AND or OR to form a statement that brings you the results you need.

Try to write a JQL statement that finds all issues that include a description, were created this year, and were part of Version 4.0 or Version 5.0, or are marked as a priority.

The first condition we need to include in our statement is the description – we’re only looking for issues that have the description field filled out. So we write the following:

description IS NOT EMPTY

Next, we need to add a clause that finds all issues created this year. To do that, we need to use the “created” field, the greater-than or equal-to operator we’ve used in the previous example (>=), and this function: startOfYear(). We need to combine this clause with the one we’ve just written by using the AND keyword.

So we now get this string:

description IS NOT EMPTY AND created >= startOfYear()

Finally, we need to add an OR clause allows finding issues that are either part of Version 4.0 or Version 5.0, or are marked as a priority. 

To do that, we’ll use the fixVersion field with IN and a list of Versions. And then combine it using an OR keyword with another clause: one that finds priority issues. This final priority clause is a simple field + operator + value clause.

Here’s what it looks like:

fixVersion in (‘Version 1.0′,’Version 2.0’) OR priority = 1

We now need to combine it with the bit we’ve written before to form the full search query. That’s where parentheses come in. Knowing how to use them is important because they ensure the right order of operations within a JQL statement.  

In our example, we need to make sure that the final OR clause is processed before the rest of the previous AND clauses. The first two clauses are mandatory.

The entire JQL statement will look like this:

description IS NOT EMPTY AND created >= startOfYear() AND (fixVersion in (‘Version 1.0′,’Version 2.0’) OR priority = 1)

This article is just an introduction to JQL which offers many more options to Jira users. Once you feel comfortable using the syntax I sketched above, you can move to more advanced uses of JQL. For more information on JQL and its many uses, check out this page in the Atlassian documentation. 

Are you looking for Jira experts to help your company make the most of Jira? Get in touch with us; we help organizations across different industries to achieve their goals with the help of this incredibly versatile project management tool.