JQL, or Jira Query Language, is a flexible tool that allows you to search for issues in Jira and pinpoint exactly what you are looking for.
Knowing how to search your Jira instance effectively can literally save you hours of work.
Power users who employ Jira on a daily basis may already have a grasp of the Jira query language. But effective query writing skills can also be quite helpful to other members of the team.
Many non-technical Jira users tend to shy away from using JQL to its full potential. Terms like operators and keywords can sound a bit frightening to less technical employees. It sure was to me when I first started using Jira!
However, this tool was designed so that anyone can benefit from its features. Even non-technical users can get the hang of it when guided in the right direction.
In this guide, we’ll walk you through all the fundamental concepts you need to know to master JQL and become a pro Jira searcher.
What is JQL?
Jira Query Language (or JQL) is one of the most powerful tools available in Jira.
The system uses the following data to filter issues. And, in turn, helps you find what you’re looking for much faster:
For example, if you wanted to find all unplanned issues, you could search for issues with a status field that is not closed, and with empty fields for epic links and fix versions.
Or let’s say you needed to figure out if your project has scoping problems. You could narrow your search for issues that are not closed in the current sprint AND that were previously assigned to another sprint. This would tell you how many issues were out of scope in the last sprint and couldn’t be completed.
Overview of Jira Query Language Interface
Under “Issues” in the dropdown menu, you can find the “Search for Issues” option:
This will open up the search screen. By default, this screen brings you to the basic search tool. Which you can use to filter issues using predefined fields like:
- Contains text
You’ll notice the “Advanced” option to the right of the filters:
This is where you’ll have access to Jira JQL.
Basic vs Advanced Searching in Jira
Basic searches in Jira are useful up to a certain point. They’re quick to fill in and easy to use.
However, you’ll reach their limitations pretty quickly, since you are limited by the existing forms.
With Advanced Searching you’ll be forming your own JQL queries.
Breaking Down a JQL Query
A JQL query is a set of words and operators that define how Jira will narrow your search.
In basic searches, the queries are already pre-built for you. Whereas you’ll have to write them from scratch in JQL.
All queries are made up of fields, operators, and values.
Fields in Jira Query Language
A field is a piece of information that describes issues – this is what you fill in when you use basic searches.
Some example of Jira fields are:
- Issue type
- Fix Version
- Epic tag
You can view a list of all fields in Jira’s documentation.
Values in Jira Query Language
Values are data points in your queries .
They’re essentially what you’re looking for in relation to your fields.
For example, possible values for the Priority field would be:
Operators in Jira Query Language
Operators are mathematical signs like equals (=), greater than (>), less than or equal (<=), etc.
They describe how your field relates to your value.
In the above search, you’re searching for issues with an Epic Name (field) that is equal to (operator) “Audio Development” (value).
Keywords in Jira Query Language
Keywords make up the JQL language. Each keyword has a specific meaning that further narrows the search, like “AND” and “OR”.
Typing “AND” in your query will return issues that match both conditions of your search.
For example, this search will return all issues that are currently in high priority and also have the “To Do” status:
On the other hand, “OR” will return all issues that fulfill either of your conditions.
The same search as above with an “OR” keyword would return:
- all issues that are high priority,
- all issues that have a “To Do” status
- and all issues that have a combination of both these conditions.
A JQL Tutorial: Putting it All Together
Now that you know the basics, let’s walk through a JQL example in Jira.
When you click on “Advanced Search”, you’ll get a search bar with no pre-made filters.
Once you start typing your query, Jira will tell you whether or not your query is valid with a green checkmark on the left. If you get a red X, it means your search is not valid:
If you need help referencing the syntax, you can always click on the question mark on the right of the search box.
What’s really handy about Jira JQL is that it will auto-suggest as you type. This allows you to get the syntax right when you don’t know it by heart.
For example, let’s say we start our query by searching the “Priority” field. You can type “Priority” in the search box. And JQL will automatically suggest what should come next: an operator.
You can then click on one of the suggested operators to continue building your JQL query.
A Jira Query Language example using AND
For this example, let’s say we want to find all issues that are urgent and not done within a specific Epic link.
Your query would look like this:
So how does this query fit in with what we’ve learned before? Let’s take each section of this query and break it down step by step:
= : Operator (Equal to)
Urgent : Value of “Priority” field
AND : Keyword
Status : Field
!= : Operator (not equal to)
Done : Value of “Status” field
AND : Keyword
“Epic Link” : Field
= : Operator (Equal to)
STAN-5 : Value of “Epic Name” field
A JQL example for “OR” Keyword
What if you’re looking for urgent issues that are not done for a specific Epic, but also want to see high priority issues?
Let’s run the same query again, but this time using “OR”:
The rest of the query remains the same, except for the addition of an “OR” keyword and a query for high priority issues.
Using Jira JQL Functions for advanced searches
You can do a great deal with fields, values, operators, and keywords. But if you want to tap into complex logic that is easily accessible, you’ll need functions.
A function is a pre-made calculation that users can plug into their query to return certain values.
They are always represented as a word followed by parentheses containing fields or values.
For example, if we wanted to find all issues linked within another issue, we could use the linkedIssues() function:
The value in the parentheses is the issue we are searching for links.
Not all JQL functions need to have a value within the parentheses. For example, if you want to check out which issues are assigned to a completed sprint, you would type in the following:
sprint in closedSprints();
Jira JQL functions are especially powerful when combined with the other elements of JQL.
Let’s say I’m trying to search which urgent issues are due in two days within a certain project (writing this article, for instance) and assigned to a specific user (me). The endOfDay() function would come in handy here.
The query would look like this:
due < endOfDay(“+2”) AND assignee = francis AND project = “BLOG” AND priority = Urgent
I’ve added +2 to the endOfDay() function because I needed to find out what is due in two days. Whereas the JQL function on its own would return only what is due at the end of the current day.
As you can see, we have 3 ‘AND’ keywords separating 4 different conditions for our JQL query. If we were to show this information in a graph, it would look like this:
|In 2 days||Francis||BLOG||Urgent|
Note: For a list of all available functions as well as the appropriate syntax and supported fields and operators, you can refer to Atlassian’s reference page.
JQL Scoping vs Sorting: narrowing down your data.
Although Jira JQL is pretty good at narrowing down from huge piles of issues, sometimes your query will still return a volume of issues that’s simply too large.
At this point, scoping and sorting comes into play to help you get to the information you need, in the priority you need it.
Scoping involves focusing your query in a specific way so that the search only returns the information that is relevant to you.
It can often be overwhelming to start with a long and complex query when performing your search. So you could just start with a wide search and narrow down from there.
Here’s an example.
Let’s start with a very general query: all open issues within a specific project:
Project = “BLOG” AND status = open
This is going to return a whole lot of issues, so let’s narrow down by current sprint:
Project = “BLOG” AND status = open AND fixVersion = “Current Sprint”
Let’s say we wanted to know which issues are urgent or high priority in our current sprint and got moved from the last sprint to find out if any urgent issues are being neglected. You can narrow down like this:
Project = “BLOG” AND status = open AND fixVersion = “Current Sprint” AND fixVersion WAS “Last Sprint” AND (priority = Urgent OR priority = High)
With the above search, you’ll get a very specific view of high or urgent priority issues that were carried over from the last sprint.
This will allow you to investigate how often this happens and why.
On the other hand, JQL sorting will allow you to order the list of returned issues in a specific manner using the keyword “ORDER BY”.
Here’s what I mean.
If you wanted the above query to be ordered by assignee, you could add to it like this:
Project = “BLOG” AND status = open AND fixVersion = “Current Sprint” AND fixVersion WAS “Last Sprint” AND (priority = Urgent OR priority = High) ORDER BY assignee
If you wanted to sort your issues using more than 1 field – for example, by assignee and by due date – you’d need to list your sorting fields in order of priority:
ORDER BY assignee, duedate
In the above query, Jira would return a list of issues sorted by assignee first, then sort by due date for all issues with the same assignee.
Smart JQL Tricks
That covers the basics of using Jira Query Language.
However, there are many more features that will save you even more time and hassle.
Let’s gid into some smart JQL tricks.
Saving JQL Filters
No need to retype the same filters over and over. If you find yourself needing to search the same query on a regular basis, you can save it for later use.
You can set up your filters to appear on your dashboard. That way, you’ll have access to your search results with a single glance.
To save your current filter, click on the “Save As” button near the top left – you’ll be prompted to name your filter:
Note that this feature is also available for basic searches.
Sharing Your JQL Queries
Once a filter is created, you can select it to share it with other users.
You can do this in several ways:
- Use the “Share” button at the top right corner
- Export the filter in another format using the “Export” button (next to “Share”)
- Changing permissions on your filter to add more users
A subscription will trigger Jira to run JQL queries on a scheduled basis and send you the results via email.
You’ll avoid needing to login to Jira on a regular basis just to perform a query yourself.
You can even send your subscriptions to other users as well.
When you set up a new subscription, you can choose to schedule them on a specific interval, as seen below:
This is especially useful for:
- Creating reports on a regular basis
- Keeping track of critical issues
- Getting visibility of new incoming issues
Consistent Filter Naming
Once you end up with several filters, it’s important to use a consistent naming nomenclature.
For example, you don’t want your filter names to look like this:
By looking at both of the above filter names at a glance, it’s really difficult to organize them because they seemed to be named in a random manner.
Use specific nomenclature to keep track of your filters. And make sure the rest of your team does the same.
This ensures that everyone understands what a specific filter does. And avoids other users creating duplicate filters if they’ve missed the point of an already existing filter.
For example, if we were to rename the two filters above, we could use the following nomenclature:
This would give us the following names:
You’ll thank yourself later when you’re looking for specific filters!
If you’ve got a grasp on JQL basics, the Atlassian Marketplace has several ready to install plugins to enhance your searching experience:
- JQL Tricks Plugin: This plugin offers over 50 extra functions. It also allows you to limit the plugin functionality to selected groups and/or limit individual functions to selected projects.
- JQL Search Extensions: These easy-to-use keyword add-ons extend your ability to find issues, comments, subtasks, attachments, versions, epics, and links. It’s currently the most popular search extension for Jira Cloud.
- JQL Booster Pack: With this plugin, you’ll get 15+ functions to extend your search capacities. These include user-related functions to have better team control, get an overall picture of your users’ recent activities, and functions to get rid of archived versions.
- JQL Functions Collection: The extra functions available in this plugin allow more complex functionalities using string and date formats.
- Groups and Organisations JQL: With two pairs of simple to use functions, you can match single and multi group custom field values with user’s groups or the Organizations field with the organizations a user belongs to.
- Scripted JQL Functions : This handy plugin allows you to harness JQL functions without having to learn the Atlassian SDK. It’s both a library of JQL functions that you can modify/extend, and a simple way for you to create your own JQL functions.
This concludes the basics of JQL!
Hopefully you’ve now got a grasp of how to scope and sort your way through Jira databases now that we’ve covered the following:
- The anatomy of a JQL query
- How to use keywords and operators to narrow your search for multiple fields
- How to scope and sort to get the most out of JQL
- How to save filters and subscriptions to save yourself time for your future searches
You should also note that Jira 8.0 is just around the corner and will add extra JQL functions, like issueLinkType and updatedBy – so look out for this update!