How much valuable time does your team lose each week sifting through Jira for that one piece of must-have information? It’s probably more than you think. In fact, the management advisors at McKinsey found that employees spend almost two hours per day searching for information. Fortunately, using advanced searches, you can use JQL to dramatically reduce the time you spend combing through Jira.
Atlassian designed Jira Query Language (JQL) as an easy tool for both programming aficionados and less technical users alike. If you’re just starting out with advanced searches, JQL may feel intimidating. But with a bit of guidance, you’ll cut down on the hours per day you spend searching for information in no time.
Getting started with Jira query language (JQL)
You can think of JQL as dialing a phone number.
It was probably pretty mind-boggling the first time your young eyes saw the jumble of dashes, plus signs, numbers, and maybe even parentheses. But, when you finally understood the phone number format of your country, you were able to quickly dial any number you wanted to.
While Jira advanced searches might feel just as puzzling at first blush, you can quickly learn formatting hacks to become a master of this vital tool. Using this guide, you’ll be able to mix and match variables to uncover any information tucked away in your Jira instance.
JQL filters data using the following variables:
- Fields
- Operators
- Values
- Keywords or Conditions
- Functions
Once you understand what each one means, you can start building JQL searches. Plus, the JQL editor is like your fairy godmother—constantly looking over your shoulder to provide auto-complete suggestions if you’re ever in a jam.
Let’s dive into the key ingredients of an iron-clad JQL search query.
Fields
A field indicates what area you’re looking to search in. It’s how you narrow down your entire Jira instance into a smaller search perimeter. For instance, you can look for specific information in a:
- Issue type
- Project
- Assignee
- Reporter
- Status
- Epic
- Priority
- Release or Version
- Sprint
- Due Date
Let’s build on an example:
We’ll start by looking for the information involved in a specific Jira project. Here’s the very first term in your very first advanced JQL search:
Project
Operators
Operators are where the magic happens. This is where we tell Jira what range of information we are looking for. JQL uses common mathematical symbols like equals (=):
- Equals =
- Doesn’t equal !=
- Greater than >
- Less than <
- Get creative and combine two signs into less than or equal to <=
Back to our example:
Using the operator “=,” we are going to look for issues related to a particular project.
Project =
Operators can also use language like “in,” “was,” or “was not.”
Values
Here’s where you will add the particular value you are searching for. Using fields, you’ve pared down your instance to a specific area of search. Your operator indicates the range of information you’re interested in. Now, you’ll use values to tell Jira what exactly you’d like to find there.
Let’s revisit our example:
By inputting a value, we will search for issues in the project named “Gameplay.”
Project = “Gameplay”
Other ways to use simple operators and values:
- Find issues that are not currently in progress: Status != In Progress
- Find issues related to a specific release or version: FixVersion = “7.2”
- Find issues assigned to a particular user named Jeremiah:
assignee = Jeremiah
- Want to find issues previously assigned to Jeremiah, but are now assigned to other team members?
assignee WAS Jeremiah
- Find issues that are tagged low priority: Priority = Low
- Find issues without an assignee: assignee is EMPTY
- List issues due before October 12, 2021: due < “2021/10/12”
What if you’re looking for more than one piece of information within a single search? Next, we’ll see how to combine two or more values into one query.
Keywords or Conditions
Here’s where you can really get into the nitty-gritty and narrow down your search. Using AND or OR, you can combine various conditions into one search query to further curate your list of results.
Check out our example, now using a keyword:
By inputting a value, we will search for issues in the project named “Gameplay.” We’re going to combine two values into a single search to find issues within the “Gameplay” project that are currently assigned to Jeremiah.
Project = “Gameplay” AND assignee = Jeremiah
You can use the below chart to visualize how each piece fits into the overall puzzle.
Build your query with as many keywords as needed. Here, we’ll look for all “Gameplay” issues assigned to Jeremiah. But we will narrow down the search to only include open issues created since the start of the month.
Project = “Gameplay” assignee = Jeremiah AND created >= startOfYear() AND status = Open
What’s with the ()?
Well spotted. In the above example, we used startOfYear() to help narrow our list down to issues created during that time frame.
Words followed by parentheses are known as functions in JQL. When we use a function, we’re telling Jira that it needs to look up a real-time piece of information to complete the search.
In the startOfYear()example, we’re asking Jira to find out what year it is in order to complete the search. Here are a few common functions you might use in your JQL search:
- Search only within the current login. Here, Jira will need to quickly establish the time frame of your current session: currentLogin()
- Search for information pertaining to the logged-in user. First, Jira needs to identify who the current user is, and then it can run the search: reporter = currentUser()
- Look for issues due by the end of this week. No need to grab a calendar to look up the dates; this function asks Jira to do the math for you: due < endOfWeek
JQL functions are a very handy way to ask Jira to look up real-time information on your behalf.
Ready to write your own advanced Jira search?
Using JQL in Jira, you can make sure you’re not one of the thousands of companies wasting 25% of the day searching for information. Smart organizations are further cutting down on search time by using powerful tools like Power Scripts for Jira. This add-on pre-compiles data, so when you run popular JQL routines, search returns are available even more quickly.
Have questions or need further assistance with Jira issues? Connect with our service desk to get your questions answered!
Last updated: 2023-07-31
Appfire
Appfire is an enterprise collaboration software company that enables teams to plan and deliver their best work. Since launching in 2005 as one of the original Atlassian ecosystem partners, Appfire has built a portfolio of top-selling apps for more than 30,000 customers — including 55% of Fortune 500 companies. As a product-led company, Appfire identifies gaps in industries serving developers and client support teams and then builds solutions that drive productivity and efficiency.
See all content by Appfire
