Jira Query Language, or JQL, is a versatile tool that lets you find exactly what you’re looking for when searching for issues in Jira.
You can literally save hours of work by effectively searching your Jira instance. The jql may already be familiar to power users who use Jira on a daily basis. However, having good query writing skills can also be very helpful to other team members.
It is common for non-technical Jira users to avoid using JQL to its full potential. Employees who aren’t as familiar with technology may find terms like operators and keywords to be a little bit frightful.When I first started using Jira, it was certainly to me!
However, the purpose of this tool’s design was to make it accessible to everyone. When shown the right way, even non-technical users can get the hang of it. For example, if you want to find all issues assigned to yourself, just enter “my” in the search bar or type “r:me” to discover all of the issues you’ve mentioned. And this is only the beginning!
We’ll walk you through all the fundamental concepts you need to know to become an expert Jira searcher and master JQL in this guide.
Which is JQL?
One of Jira’s most effective tools is the Jira Query Language, or JQL.
Issues are filtered by the system using the following data: And, in turn, expedites the process of finding what you’re looking for:
Fields, Operators, Values, Keywords, and Functions For instance, if you wanted to find all unplanned issues, you could look for issues that have status fields that are not closed and empty fields for epic links and fix versions.
Or, suppose you needed to determine whether your project has scope issues. You could narrow your search to issues that were previously assigned to a different sprint AND are not finished in the current sprint. This would inform you of the number of issues that were beyond the scope of the previous sprint and could not be resolved.
JQL is also getting better, particularly since Jira 8.0 was released. Currently running JQL searches 33% faster than Jira 7.12 and virtually eliminating memory issues when performing complex searches.
Overview of the Jira Query Language Interface The “Search for Issues” option can be found under “Issues” in the dropdown menu:
This will launch the search screen for Jira Query Language Interface. This screen opens the basic search tool by default which can be used to
Filter issues based on predefined fields like:
Status Assignee Project Contains Text The “Advanced” option can be found right next to the filters:
- You will have access to Jira JQL here.
- Basic vs Advanced Searching in Jira
- Basic searches in Jira are useful up to a certain point. They are simple to use and quick to fill out.
- However, as you are constrained by the existing forms, you will quickly reach their limitations.
- You will be creating your own JQL queries when you use Advanced Searching.
How to Break Down a JQL Query A JQL query is a set of words and operators that determine how far down your search Jira will go.
The queries for basic searches have already been constructed for you. However, you will need to start from scratch with them in JQL.
Keywords, fields, operators, and values make up every query.
Fields in Jira Query Language A field is a piece of information that describes problems. When you use basic searches, you fill these fields out.
Examples of Jira fields include:
- Issue type
- Project
- Priority
- Fix Version
- Epic tag
You can view a list of all fields in Jira’s documentation.
The data points in your queries are called values in the Jira Query Language.
They basically fulfill your requirements in relation to your fields.
The Priority field, for instance, could have one of the following values:
Operators in the Jira Query Language are mathematical signs like equals (=) and doesn’t equal (!).=), greater than (>), less than or equal (<=), etc.
They discuss the connection between your value and your field.
For instance:
Operators in JQL In the preceding search, you are looking for issues that have an Epic Name (field) that is the same as the operator “Audio Development” (value).
Additionally useful, “IN” makes it possible 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 locate all issues that are related to a particular issue. Additionally, you can use “NOT IN” to identify anything that is outside of that query.
“CONTAINS” is another powerful operator that lets you query custom fields that make use of the “Free Text Searcher” as well as the Summary, Description, Environment, and Comments fields.
In contrast, “WAS” enables you to call up anything that was previously connected to a particular state but is no longer, such as:
Keywords in the Jira Query Language The JQL language is made up of keywords. Like “AND” and “OR,” each keyword has a specific meaning that narrows the search further.
When you type “AND” into your query,
Issues that satisfy both of your search conditions will be returned.
A Guide to JQL: Putting Everything Together Now that you are familiar with the fundamentals, let’s look at a JQL example in Jira.
A search bar without pre-made filters will appear when you click “Advanced Search.”
With a green checkmark on the left, Jira will indicate whether your query is valid once you begin typing it.A red X indicates that your search is invalid:
JQL Tutorial You can always click the question mark to the right of the search box if you need assistance referencing the syntax.
The fact that Jira JQL will auto-suggest as you type is incredibly useful. Even if you don’t know the syntax by heart, you can still get it right this way.
For example, let’s say we start our query by searching the “Priority” field. You can use the search box to type “Priority. “Additionally, JQL will automatically suggest the next step:an employee
Example from the JQL Tutorial You can then proceed to building your JQL query by clicking on one of the suggested operators.
An example of using AND in the Jira Query Language In this example, let’s say we want to find all issues that are urgent but have not been resolved within a particular Epic link.
This is how your query would look:
JQL with AND: How does this query relate to what we’ve already learned? Let’s go through each section of this question one at a time:
Let’s use “OR” this time to run the same query:
Precedence in JQL However, what happens when you use both “AND” and “OR” keywords? In a nutshell, “AND” comes first.
Advanced searches with Jira JQL Functions: You can do a lot with fields, values, operators, and keywords. However, functions are necessary if you want to easily access complex logic.
A function is a pre-made command that can be added to a query to return a specific set of values.
They are always shown as a word followed by fields or values in parentheses.
The linkedIssues() function, for instance, could be used to locate all issues linked to one another:
JQL functions for more advanced searches The value enclosed in parentheses represents the issue for which links are being sought.
When used in conjunction with the other components of JQL, the functions of Jira JQL are particularly potent.
Let’s say I want to find out which urgent issues are due in two days in a particular project (like writing this article) and assigned to a particular user (me).Here, the endOfDay() function would be useful.
