Hey JIRA users and administrators. I’m Dan. I’ve been using JIRA for about three years and have recently joined the team here at Atlassian. JQL is my favorite feature in JIRA. Using JQL will get you faster access to what you’re looking for, and even better, JQL gives you access to all kinds of great stuff you didn’t even know was available!
JQL stands for JIRA Query Language. It’s the most flexible way to search for issues in JIRA. JQL is really for everyone: developers, testers, project managers, as well as business users. This blog is intended to be a tutorial for those who have no experience with database queries.
If you are a developer who knows SQL
Atlassian’s implementation of JQL is very similar to SQL. Atlassian’s JQL is not to be confused with Java Query Language. The search box is fully equipped with code hints and inline validation which makes constructing queries easy. To try out JQL on your JIRA instance, you can:
- Log into JIRA
- Click Issues
- Click Edit (If you have a search in progress)
- Click “Advanced Searching”
You can then type your queries directly into JIRA. For a complete reference, go to Advanced Searching. I’ve bookmarked this link as I often go back here for the more obscure queries. This page has a lot of content so it’s helpful to go to here and do a “Ctrl/Cmd + F” and search to jump directly to a topic or keyword of interest.
What about the rest of us?
JQL is equally as awesome for non technical users as well. JQL is a very approachable and natural language. Let’s start with a simple example to help explain a few fundamental concepts to ground our discussion. If you stepped into an unfamiliar grocery store, you might ask someone there “Where can I find a package of 3 Acme cookies?” The clerk would then bring you to the right aisle and shelf for that product. JIRA can do the same for issues.
JIRA has both a simple and an advanced search. Simple search uses a set of forms the user fills in. Advanced Searching uses JQL which is a query language. Queries are a series of simple questions strung together to form a more complex question. A query has three basic parts: fields, operators, and values. You can optionally link them together using a few select keywords. Let’s define each term for the context of this discussion. I’ve linked to the JQL reference for each item.
- Field – Fields different types of information in the system. In JIRA fields can 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 the actual data in the query. They are usually the 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.
If you use one of the select linking keywords then another field-operator-value set would follow. If we go back to our example, we are asking three questions to the store clerk:
- What items in your store are made by the company Acme?
- AND what items in your store are cookies?
- AND what products in your store come in packages of three?
Visually we can represent this query using the following Venn diagram. The area of interest to us is the shaded area in the center that involves all three circles.
In the first part of the example we are using company as the field. Equals is the operator. Acme is the value we are querying on. If we wanted to ask the entire question to the store clerk in a structured way we could say:
In the above example, the query states the company must be Acme, the item must be a cookie, and the quantity needs to be three. Each condition is related to the others by the keyword AND. AND means that the condition to the left and right of AND have to be met. Since we want items that meet all three criterion we use the keyword AND. You can also use OR which means that only one of the conditions needs to be met. If you want to save money by looking for items on sale or having the store brand, we can use this query.
Using an AND would give only the area covered by both circles. An OR returns items in either circle. I almost exclusively use AND, but there are a few cases where OR has been useful. When looking at the results of a query using an AND will return less results and using an OR will return more results.
So can we get back to JIRA?
Absolutely! Effective management of dynamic projects requires specific metrics from the issue tracker relevant to your project. JIRA offers a number of fields for you to query. Click the fields link to see they types of data you can mine from JIRA. Let’s start with a simple example.
What bugs did John Smith file yesterday in the project Pipeline?
In this example the person filing the bug is stored in the reporter field. JIRA also has a project field that matches the issue key. For example issue PIPELINE-2 is in the PIPELINE project. We can set up two conditions joined by the AND keyword.
Often times you may want to have the query reference a set of items. Let’s go with a slightly more involved example.
What issues are blocking or critical in Projects A, B, and C?
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.
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?
In this query the is empty statement only includes issues where the value of the assignee field is blank. JIRA also supports relative dates. The value -1d evaluates to 1 day behind the current date when the query is run. In the above query it will return all issues that do not have an assignee that are at least one day old.
Entering JQL in Jira
JIRA’s JQL editor makes it easy to learn JQL. The editor uses code hints as you type. For new users, this will greatly simplify the learning curve to get started. The JQL editor is contextually aware of the query as you type and gives real time feedback. 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. When you see the value you’d like to select, you can use the arrow keys or mouse to select it.
One the query is complete, JIRA validates the JQL and lets us know the syntax is correct by the green check in the left hand side of the text entry box.
Note the syntax help link which opens a reference page to the JQL language. What’s next? This is the first of a four part series aimed at building JQL Ninjas for JIRA. In future blog posts we will be focusing on:
- JQL Functions and Searching Change History
- Places in JIRA to use JQL
- Extensions in the marketplace that extend the JQL language
Stay tuned in the next few weeks to learn more tips and tricks about JIRA. Want to learn even more? Sign up for the JIRA Insiders Email.