An organization’s Jira instance can quickly become a sea of issues. Seemingly overnight, an instance can accumulate thousands of epics, stories, and bugs. At first, it’s easy to remember and keep track of specific issues. But in a short amount of time, this feat of mental agility becomes impossible. A user can begin to feel like Captain Ahab, adrift at sea, searching for the elusive Moby Dick. That’s where the search functionality in Jira becomes essential. By the time you finish this article you’ll know how to fish for and catch, just the data you’re looking for!
NEW RESEARCH: LEARN HOW DECISION-MAKERS ARE PRIORITIZING DIGITAL INITIATIVES IN 2024.
Simple Search
Jira provides two simple searching interfaces to find your issues quickly and easily. The first is the Search field. In the latest Jira interface (Jira 7.x), this can be found within the persistent left-hand menu bar. This tool allows a user to do a quick search based on issue key, summary, description, comments, and even provides some Smart Querying, a quick search syntax similar to searching a Gmail inbox. This is a quick and dirty way of finding what you need. Think of it as Jira sonar. In your sea of issues, you can use it to find things quickly, but it lacks sufficient detail to get specific sets of issues that you may want.
The next simple search interface is the Search Issues screen. This is easily accessible from the Issues menu item. The basic version of this tool allows a user to filter based on any available fields in their instance. It is not limited to the small number of fields used by the Search box. The filtering is performed via an easy to use graphical user interface consisting of drop-downs and input fields. This interface is pre-set with some common fields, such as project, issue type, status, and assignee. Additional fields can be added by clicking More and selecting the fields you’d like to search on. The filtering options of each field will dynamically update based on the type of the field. For example, date fields, such as createdDate, will display options to choose date ranges, while the assignee field gives a multi-select and user search tool.
This interface is far more powerful than the Search box, but still has some limitations. Simply put, it is a very wide net with holes that are not specifically sized for the fish you want to catch.
Within the Search Issues screen is an entry-point to a more powerful and comprehensive search tool. You can use this to find exactly what you want. It’s the specific rod, line, and bait for the fish you want. Simply click on Advanced and you will discover a large text field. If you started with a basic search already it will be pre-populated with those results. This is your entryway into JQL!
Shallow End – A Simple JQL Example
Jira Query Language (JQL) is a text-based search language for Jira. Using a human readable syntax, JQL provides users with an opportunity to utilize more complex operators and logic than what is available in basic search mode.
I’ve always found that a new programming or query syntax is best introduced by way of an example, so here we go:
project = SCRUMDEMO AND (reporter = Charles.Tirrell OR assignee = Charles.Tirrell)
This JQL statement is relatively straightforward to read and understand. It will give a list of issues that are in the SCRUMDEMO project whose reporter or assignee is me, Charles Tirrell. This is a good example of a JQL query that cannot be constructed using the simple Search Issues screen. The limitation is due to the combination of both “and” and “or” keyword conditions. The combination of these logical keywords is much simpler to represent in a textual syntax than a graphical one, so this is where JQL excels!
JQL Syntax Structure
JQL syntax can be broken down into five primary elements: fields, operators, values, keywords, and functions.
- Fields are the various types of information associated with an issue in Jira. These fields can be system defaults (assignee, reporter, key, project) or custom fields created by a system administrator. It’s important to note that the Search Issues screen contains support for text autocomplete, which is a great way to search for your fields, while composing JQL.
- Operators are symbols that represent logical comparisons, such as equals (=), not equals (!=), greater than (>), or like (~). These operators can be used to form a logical statement, where a field is compared to a value.
- Values are user-defined pieces of data, such as a string, a date, or a number. These are inputs used to compare against a field in order to get a list of issues.
- Keywords are special words in JQL that perform actions like joining two or more clauses together, or altering the logic of a clause.
- Functions are special calculations used to access specific data within Jira that are not distinct fields or static values. Examples of functions include values for the current user, linked issues, or date calculations like the first day of this month.
The Atlassian Website has full documentation on all JQL elements. You can find this full documentation by clicking on the elements above.
By combining these elements together, you can form logical clauses to find individual or specific sets of issues. For example, a very basic clause would be to combine a field, operator, and value together, such as:
created >= 2018-01-11
In this example, we will find all issues created on or after January 11th, 2018. Created is a field, “>=” is an operator, and “2018-01-11” is a date value.
All these elements can be combined in a multitude of ways to form very complex statements. The key is to start small and build up your statement one piece at a time, joining together multiple clauses with keywords, such as AND or OR.
Deep End – A More Complex JQL Example
Now that we have a good understanding of the core building blocks of a JQL statement, let’s use them to make a slightly more complex JQL example. In this example, we’ll attempt to find all issues that have a description filled out, were created this year, and either were part of Version 1.0 or Version 2.0, or are marked as priority 1. This example will require us to use all our pieces of JQL syntax mentioned above. We’ll build it step-by-step.
First, let’s find all issues that have a description filled out. For this part, we’ll use the “description” field combined with two keywords (IS NOT, EMPTY).
description IS NOT EMPTY
Next, we’ll add a clause that will find all issues created this year. To do this, we’ll use the “created” field, a greater-than or equal-to operator (>=), and the startOfYear() function. This clause will be combined with our previous clause using the AND keyword.
description IS NOT EMPTY AND created >= startOfYear()
Our final step will be to add an OR clause that will allow us to find issues that are either part of Version 1.0 or Version 2.0, or is marked as priority 1. First, we’ll use the fixVersion field with an IN keyword and a list of Versions. Next, we’ll combine this using an OR keyword with a clause to find priority 1 issues. This final priority clause is a simple field + operator + value clause.
Parentheses are an important piece of syntax to ensure the proper order of operations within a JQL statement. In this statement, we’ll use parentheses to explicitly declare that this final OR clause will be processed before the rest of the previous AND clauses. This essentially means that the first two clauses (description and created) are mandatory, while the last clause will allow for fixVersion and priority to be follow “either-or” logic. Altogether, the entire JQL statement will look like this.
description IS NOT EMPTY AND created >= startOfYear() AND (fixVersion in ('Version 1.0','Version 2.0') OR priority = 1)
Error Checking
The Advanced Search Issues screen has a built in tool for error checking and will visually tell you if the statement you have entered is invalid JQL. To the left of the statement, you’ll find either a green checkmark if your JQL is valid, or a red X if it is not. In addition, the Advanced Search Issues screen will provide useful error messages to guide you while debugging your statement. This is very helpful when learning JQL.
Diving Deeper
This introduction is only the proverbial tip of the JQL iceberg. There is much, much more that you can do, but you should start in the shallows before going into the deep blue sea. Once you master the elements above, you can then move toward more interesting cases, such as using JQL statements within Confluence pages. In the meantime, you should now have the skills necessary to find every elusive issue in your Jira sea, just as Captain Ahab found his white whale.
