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?

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:

• 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 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.

JQL is also getting better, especially ever after the Jira 8.0 release. Now running JQL searches 33% faster than Jira 7.12 and almost entirely eliminating memory issues previously faced when making complex searches.

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:

• Status
• Assignee
• Project
• 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, 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 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:

• Urgent
• High
• Medium
• Low

Operators in Jira Query Language

Operators are mathematical signs like equals (=), doesn’t equal (!=), greater than (>), less than or equal (<=), etc.

They describe how your field relates to your 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 “CONTAINS”, which allows you to query the Summary, Description, Environment, and Comments fields and custom fields that use the “Free Text Searcher”.

“WAS”, meanwhile, allows you to call up everything that was previously connected to a given state but isn’t anymore, e.g.:

assignee WAS francis

You can also use “WAS” as well as “WAS NOT”, “WAS IN” and “WAS NOT IN” as you need.

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 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 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:

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. That means:

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. That said, 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 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:

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

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 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 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 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:

• 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 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:

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

A number of 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 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

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