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. For example, if you want to find all issues assigned to yourself, just enter “my” in the search bar or type “r:me” to find all issues that you’ve reported. And this is just the start!
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?
JQL is one of if not 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:
- Fields
- Operators
- Values
- Keywords
- Functions
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 need 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. In cloud this is called “Advanced issue search” and can be found under the Filters dropdown:
In server/data center:
In Cloud :
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:
- Project
- Type
- Status
- Assignee
- 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 perform 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, values, and keywords.
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
- Project
- Priority
- Fix Version
- Epic Name
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 your fields.
For example, possible values for the Priority field could be:
- Urgent
- High
- Medium
- Low
Operators in Jira Query Language
Operators are symbols like equals (=), not equal (!=), greater than (>), less than or equal to (<=), etc. They describe how your field relates to the value.
For example:
In the above search, you’re searching for issues with an Epic Name (field) that is equal to (operator) “Audio Development” (value).
“IN” is also useful and allows you to simplify queries. Rather than running multiple status queries, for example, you can use the following:
status IN (“To Do”, “In Progress”, “Closed”)
Equally, you could use:
issue IN linkedIssues(“ID-101”)
To identify all the issues linked to a specific issue. You can also use “NOT IN” to identify everything that falls outside that query.
Another powerful operator is “~”, which allows you to query the Summary, Description, Environment, Comments, and custom fields that use the “Free Text Searcher”.
“WAS”, meanwhile, allows you to call up everything that was previously connected to a given value before it was changed, e.g.:
assignee WAS Francis
You can also use “WAS NOT”, “WAS IN” and “WAS NOT IN” as you see fit.
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.
Using the same search as above and substituting “AND” for “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 of 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 handy about 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 for 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 select or type one of the suggested operators to continue building your 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:
Priority: Field
= : 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.
Precedence in JQL
What happens if you use both “AND” and “OR” keywords, though? In short, “AND” takes precedence. That means if two clauses are connected by an “AND” then they’ll be grouped together and treated as one unit. Clauses linked by an “OR”, on the other hand, will be treated as a separate unit. See the following examples:
Example. 1: status=resolved OR project=”Planning” AND assignee=Francis
Example. 2: status=resolved AND project=”Planning” OR assignee=Francis
In example 1 the query will return all resolved items in addition to all items assigned to Francis in the Planning project. In example 2 the query will return all resolved items from the Planning project and all items assigned to Francis. But if you run:
status=resolved AND (project=”Planning” OR assignee=Francis)
Then you will get all resolved items from the Planning project as well as all resolved items assigned to Francis.
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 command that users can add 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()
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 query. If we were to show this information in a spreadsheet, it would look like this:
| Due Date | Assignee | Project | Priority |
| 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 JQL is pretty good at searching through 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 order you need it.
Scoping
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.
Sorting
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 than1 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 JQL. However, there are many more features that will save you even more time and hassle. Let’s get 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
Scheduled Subscriptions
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 log in to Jira regularly 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 regularly
- 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 consistent naming. For example, you don’t want your filter names to look like this:
- OrderedByDueDate_ClosedSprint_BlogWritingEpic
- AudioDevEpic_OrderedByAssignee_CurrentSprint
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 randomly.
Use specific nomenclatures 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:
Sprint_Epic_OrderedBy
This would give us the following names:
- ClosedSprint_BlogWritingEpic_OrderedByDueDate
- CurrentSprint_AudioDevEpic_OrderedByAssignee
You’ll thank yourself later when you’re looking for specific filters!
Project tracking
Several JQL fields are particularly useful for project tracking.
- “workRatio” – query issues by how much of the original work ratio has been spent, for example, “workRatio > 25” (where more than 25% of the work is complete)
- “worklogDate” – find issues that have comments in work log entries within specific date ranges, for example, “worklogDate > “2020/12/12″”
- “worklogAuthor” – search for issues by the users who have logged work against them, for example, “worklogAuthor = “Francis””
- “watchers” – track issues by the number of people watching them, for example, “watchers > 10”
- “watcher” – allows you to see which issues specific individuals are tracking; while “voter” and “votes” have equivalent functions
JQL Add-Ons
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 the 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.
Conclusion
This concludes the basics of JQL! Hopefully, you’ve now got a grasp of how to scope and sort your way through Jira now that we’ve covered:
- 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
Mastering JQL will allow you to navigate Jira at speed and get far more value out of the product. Making the most of Jira’s massive feature set will also mean that you’re able to manage your projects and finetune your workflows much more effectively – making your team better, faster, and more efficient all around!
Recommended Reads:
- Jira to Jira Sync: How to Synchronize Multiple Jira Instances in 8 Steps
- A Complete Guide to Advanced Roadmaps for Jira
- Jira Automation: Get the Basics Right
- Jira for Project Management: Level up your Business Activities
- GDPR: The Complete 2022 Guide to Compliance Regulations in Jira
- Jira Integrations: Integrate Jira and Other Systems Bidirectionally
