JQL stands for Jira Query Language and is the most powerful and flexible way to search for your issues in Jira. JQL is for everyone: developers, testers, agile project managers, and business users. This blog is intended to be a tutorial for those who have no experience with database queries to those who want faster access to information in Jira. So basically if you work in Jira this blog is for you.
Searching in Jira: how do I start?
The search box
The most simple search feature in Jira is the search box at the top right of your screen.
You can use this search box to:
- search a particular issue
JiraKEY-15
- search on text (searches in issue summary, description and comments)
atlassian
- Finally, the field supports Smart Querying
my open bugsThis will give you a list with all Bugs that are in the status Open and assigned to you
Search for Issues
You can also search issues from the “Issues” section in the dropdown menu.
In the screen that just opened you’ll be able to easily filter issues based on the value(s) of certain fields. A quick example search:
You can filter on any field available in Jira (depending on the selected project(s)).
Basic and Advanced Searches
There are two types of searches in Jira: basic and advanced. Basic searches, like the ones above, present you with a set of forms that you can fill in, such as Project name, Issue Type, Status, and Assignee. Basic search can be useful for getting a high-level view of your issues and status.
Now Advanced Searching is where you will get into JQL, using it to form queries. Queries are a series of simple elements strung together to form a more complex question. A query has three basic parts: fields, operators, and values.
- Field – Fields are different types of information in the system. Jira fields include priority, fixVersion, issue type, etc.
- Operator – Operators are the heart of the query. They relate the field to the value. Common operators include equals (=), not equals (!=), less than (<), etc.
- Value – Values are the actual data in the query. They are usually the item for which we are looking.
- Keyword – Keywords are specific words in the language that have special meaning. In this post we will be focused on AND and OR.
Important keywords to know
Atlassian has created a JQL reference where you can find all keywords, operators, etc that can be used in JQL. This is your go-to-guide when you want to discover new search capabilities. Here are some of the most common keywords and operators you will use:
AND
This will only return issues that match both clauses (are part of the Collaboration project and have their status set to "In Progress")
project = Collaboration AND status = "In Progress"
OR
Returns all issues from either the Collaboration project or that have their status set to "In Progress".
project = Collaboration OR status = "In Progress"
IS
This will return all issues that have no description.
description IS EMPTY
Operators
!=
status != "To Do"
Returns all issues except for those that have their status set to “To Do”
>=
"Story Points" >= 5
Find all issues that have Story Points which are greater than or equal a given value
Similar
- > | greater than
- < | smaller than
- <= | smaller than or equal
IN
status IN ("To Do", "In Progress", "Closed")
is the same as
status = "To Do" OR status = "In Progress" OR status = "Closed"
Find all issues which are either have the status “To Do”, “In Progress” or “Closed”
Reverse
- NOT IN
Putting this into practice
Let’s start with a simple example. Say you want to see what bugs your teammate filed within a certain project. You query would be:
reporter = jsmith AND project = Pipeline
Here we used the keyword “AND” to query Jira for tickets reported by John Smith in the project “Pipeline”
Other times you may want to have the query reference a set of items. For instance:
What issues are blocking or critical in Projects A, B, and C?
priority in (Blocker, Critical) AND project in (ProjA, ProjB, ProjC)
The “in” keyword will include any item that matches any item in the list. In the above example it will return all of the blocker and critical bugs in projects A, B, and C.
This is extremely helpful for organizations that have service level agreements (SLA) with their customer base. A JQL query can easily find the issues that are not meeting that SLA.
What issues are unassigned and have not been updated in the last day?assignee is EMPTY and created < -1d
In this query the “is empty” statement only includes issues where the value of the assignee field is blank. This query also shows how Jira supports relative dates. The value -1d evaluates to 1 day behind the current date when the query is run. As a result, the above query will return all issues that do not have an assignee that are at least one day old.
Don’t be intimidated by Jira’s Advanced Searching! Jira’s JQL editor makes it easy to learn JQL. The editor uses code that hints as you type. For example, if we want to type the following JQL: project = Pipeline, Jira gives suggestions at each step of the way for each of the three components of our query. Click on “Syntax help” anytime if you get stuck.
Visit the Jira product guide to learn more about JQL, advanced search with use cases, and more.
We also have a downloadable cheat sheet to keep close on hand as you perform searches with JQL. Copy and paste fields, operators and functions into the Jira search bar, as well as learn more advanced queries.
