If your Jira instance is filled to the brim with projects, issue types, or assignees, finding specific information quickly can be challenging. Fortunately, Atlassian’s tool comes with various search capabilities. The one that stands out is called Jira Query Language (JQL). It’s a highly competent tool that makes finding a needle in a data haystack much easier. If you know what you’re doing, that is.
No worries, though. This article will walk you through the key aspects of JQL. Additionally, you will see some examples of queries. With some practice, you will be able to create your own structured queries in no time.
However, before we delve into the specifics of JQL, it’s worth looking at the wider context of Jira search options. They are divided into three categories: quick, basic, and advanced. And the difference between them is substantial, to say the least.
Search types in Jira
The road to finding anything in Jira starts with the search box. No matter where you are in the Atlassian tool, you can see the box in the top bar.
Quick search
If you simply want to go to a specific issue or project in Jira, the quick search option can come in handy. How to perform a quick search in Jira?
- Click the search bar or press the “/” key.
- Type in the name or the key of the issue or project you’re looking for.
- Click the item from the list of search results.
And once you click on the result, you will be redirected to the issue page where you can see all of its details. But what if you don’t know the name or the issue key? That’s when you need to go a step higher.
Basic search
When the quick search displays too many results, you can click the “View all issues” button, which will open the Basic search mode. It’s a list of all the issues or projects in your Jira instance.
To filter the list, use checkmarks from various Jira fields, such as project, type, status, or assignee. That will quickly narrow down the range of search results. Furthermore, you can add text or even expand the list with custom fields to filter with more precision.
Advanced search
Jira’s most comprehensive search type builds on the options of basic searches with a significant change. Instead of drop-down lists of categories and checkmarks, advanced searches require text queries. This method provides much more customizability in defining the search parameters.
As for the queries, there is a specific method of creating them. That’s where JQL makes an appearance.
What is JQL?
The abbreviation stands for Jira Query Language. It’s a method of extracting specific data from a database by means of text queries. Just like English or French, JQL has its own syntax and vocabulary.
Jira’s database query language contains several key elements. Each one plays a different role in building Jira queries. Here is a breakdown of the main components of JQL.
Elements of a JQL query
In order to create Jira queries, you need to know what’s inside them. Fortunately, there are only five elements to keep in mind.
Fields
In Jira issues, fields are the building blocks of data. Each field provides a different piece of information to its users. The most popular examples of fields include status, assignee, and priority.
Typing a field in an advanced search in a given project will focus the results on a specific category of data. For instance, the command “status = done” will generate a list of all the issues in the project marked “done”.
You can find the list of JQL-compatible fields here. And if you’ve ever created custom fields, you can also use them in advanced searches.
Values
Digital Toucan describes values as “the user-defined terms that point to the specific results you need. They’re usually the main object of your search.“
In other words, a value is a distinct piece of information in a given field. For example, for a “status” field, a value could be “to do” or “done”. In a “priority” field, an example of a value is “high” or “medium”.
Operators
In a JQL query, an operator modifies the value of the field depending on the search purposes. For instance, if you’re looking for a specific assignee (field), you would use a “=” operator.
Alternatively, let’s say you want to find all tasks with a priority higher than “normal”. In that case, you would type the following text in JQL: “Priority > normal”.
In the above example, “priority” is a field, the “>” sign is the operator, and “normal” is a value.
The list of JQL operators is not as extensive as the fields, and their number is finite. As such, there won’t be any surprises similar to custom fields.
Keywords
According to Atlassian’s definition, a JQL keyword “is a word or phrase that does (or is) any of the following:
- joins two or more clauses together to form a complex JQL query
- alters the logic of one or more clauses
- alters the logic of operators
- has an explicit definition in a JQL query
- performs a specific function that alters the results of a JQL query”
To simplify this definition, think of keywords as words or phrases that provide additional conditions to your search. This element of JQL allows you to expand or narrow down the search at will.
For instance, using the “and” keyword means you can limit the list of results to those that only contain both elements of the query. The “or” keyword expands the list of results so that it contains either of the parameters. Here is the complete index of JQL keywords:
- And,
- Or,
- Not,
- Empty,
- Null,
- Order by.
Functions
A JQL function allows you to calculate various Jira data. It’s useful in situations where the values change over time. Thus, instead of searching for a value that may have changed already, it’s better to use a function. Additionally, some JQL functions help search for information that isn’t contained in fields or values.
Adding variables in parentheses will limit the scope of a function. That gives you more control over the search. If you want to know more about JQL functions, take a look at the video below.
The catalog of Jira functions can be expanded with third-party tools. For example, BigPicture contains an extension called Enhanced JQL. It adds a number of app-specific functions to the search engine, which means users can sift through data in projects, programs, and portfolios even more effectively.
Examples of a JQL query
Becoming a proficient JQL user takes some practice. However, before you get started, take a look at some JQL examples. Here is the most rudimentary blueprint for creating queries in JQL:
Field + Operator + Value
Say you want to see all the tasks assigned to Erik Copeland, one of your team members. In that case, the JQL query will look like this:
“assignee = erik.copeland’
That’s a pretty simple query, isn’t it? Let’s expand it a little. What if you wanted to see all of Erik’s completed tasks from an epic the team is working on? Just type in the following sequence:
“assignee = erik.copeland and status = done and epic link = OA-11”
The only thing that might be confusing is that last part. If you enter the name of the epic link in the search bar, it will be automatically converted into the link’s key.
As you can see in the screenshot above, the search has been successful. Only the elements that fulfill the conditions of the query are listed. Any time you open a text box and start typing, the editor will show a list of suggestions, which makes creating an advanced search query easier.
Another way of verifying if the syntax of your query is correct is to look at the symbol right next to it. If it’s a green checkmark, you’re good to go. If you add enough elements, you can create an incredibly detailed and complex query. There is no better way to make complex searches in Jira.
JQL filters
You might use certain searches regularly, so it would be great if Jira remembered the parameters of your JQL search. With filters, that’s exactly what happens.
What is a JQL filter? In simple terms, it’s a saved search query you can reuse instead of writing it from scratch every time you need it. To make finding specific information easier, Jira allows its users to view the filters in a dashboard.
The filters in your dashboard get updated automatically every 15 minutes. That way, you can easily check the changes within your search parameters without the need to write a query each time.
BigPicture extends JQL capabilities beyond search
Jira’s query language is a powerful tool. So much so that other Jira-based software use it for other purposes. Our PPM software, BigPicture, unleashes the power of JQL in reporting, configuration, and visualization.
Customized task reports
A task report is the most popular reporting type in BigPicture. The addition of JQL queries opens up another dimension of customization possibilities for project managers. Using queries in reports allows you to present detailed information and focus on specific areas of the project.
Just like in Jira’s advanced searching, BigPicture’s task reports can be narrowed down in countless ways. Here is a template for a story point progress report in open Sprints:
For time tracking, adding a short query will generate a report showing the time logged by all the users in a given month.
Naturally, the level of complexity of the query is up to you. In the image below, the search focuses on open bugs that have been marked as high-priority. And to put a cherry on top, it is narrowed down even further to report data from one team.
Filter information displayed on charts, boards, and more
The majority of BigPicture modules support Jira’s advanced search capabilities. Whether it’s a Gantt chart, an Agile board, a risk matrix, a resources panel, or a calendar – you have the option to display a specific set of data instead of the whole range.
Going back from a filtered list to a complete set of information is a one-click process. And if you have a set of queries you use regularly, BigPicture allows you to use them as pre-made filters. That way, finding exactly what you’re looking for takes even less time.
In this case, the app only displays the elements with a “to do” status. The general structure of the project is still visible, which provides a point of reference to the project as a whole. But all the other elements I don’t need to see at the moment are hidden.
This is just one example of JQL in our modules. Want to see how it works in other parts of our app? Check out our Demo instance and experience it in practice.
Custom box configuration
There are two ways BigPicture supports JQL in configuring Boxes – customizable data containers for your desired Jira sources. The first way uses entire projects, which are then narrowed down by your query. The corresponding results will flow into your new box. This method combines detailed personalization options with a faster creation time.
However, you don’t have to add entire projects to create a box. Instead, you have the option to use your saved Jira filters. As a result, your BigPicture box will be based solely on the conditions you have listed in the filter. And if you want to personalize the box even further, simply add a JQL query in the “narrow down” field. That way, you have a wider choice of scope customization.
Hopefully, you now know enough about Jira Query Language (JQL) to start writing your own queries. Compared to the basic search, this filtering method is in a league of its own. And when you add filters to the mix, regular verification of crucial project data will be a breeze.
