A quick reference to JQL

Courtesy - DALL-E

JQL stands for "Jira Query Language," and it is a powerful search language used to query Jira data. JQL allows users to search for issues in Jira by specifying criteria such as issue type, status, project, assignee, and custom fields. It can be used to filter and sort issues, create custom reports, and automate processes within Jira.

JQL syntax is similar to SQL, but it is specific to Jira and is used within Jira's search interface. JQL can be used by both technical and non-technical users to find, analyze, and report on data within Jira.

This blog is intended to be a tutorial for those who have no experience with database queries or SQL queries to those who want faster access to information in Jira. So basically if you use Jira then this blog is for you.

Where to start searching in your Jira Console?

When using the Jira console, there are a few places you can start searching depending on what you're looking for. Here are some common options:

1 - Quick Search: At the top of the Jira console, you'll see a Quick Search bar. This is a simple text search that lets you search across all issues in Jira. Simply type in your search term and press Enter to see a list of matching issues.

2 - Filter Navigator: If you need to perform a more complex search, you can use the Filter Navigator. This is accessible via the "Filters" dropdown menu in the Jira console. The Filter Navigator lets you build more advanced queries using JQL or a graphical interface.

Depending on what you're looking for, one or more of these options may be a good place to start your search in Jira.

Basic and Advanced Searches

Jira provides two types of searches: basic and advanced.

Basic Search: Basic search is a simple text search that allows you to search for issues in Jira based on keywords. You can access the basic search bar by clicking on the search icon in the Jira header. This search bar is located in the top navigation bar, and it allows you to enter one or more keywords to search for issues. The basic search will match against the summary, description, and other fields in Jira. You can also use basic search operators such as "AND," "OR," and "NOT" to refine your search.

Advanced Search: Advanced search allows you to build complex queries using the Jira Query Language (JQL). You can access the advanced search by clicking on the "Advanced Search" link in the basic search dropdown menu. Advanced search provides a more powerful and flexible way to search for issues based on specific criteria such as issue type, status, project, assignee, and custom fields. You can use JQL to create more complex queries and combine multiple criteria. You can save your search queries and share them with other users or use them to create filters and dashboards.

We will focus more on JQL for the remainder of this blog.

JQL Structure

The basic structure of a JQL query consists of three components:

<field> <operator> <value> <keyword>

Field: Refers to the Jira field that you want to search for. Examples include:

Assignee, Affected version, Attachments, Comment, Component, Created, Creator, Description, Due, Epic link, Filter, Fix version, Issue key, Labels, Last viewed, Priority, Project, Reporter, Resolved, Sprint, Status, Summary, Text, Time spent, Voter, Watcher, custom field – Any custom field defined by the administrator and accessible to the user

Operator: Specifies the comparison operator that you want to use to compare the field to the value. Examples of operators include:

=, !=, >, <, >=, <=, ~, !~, IN, NOT IN, IS, IS NOT, WAS, WAS NOT, WAS IN, WAS NOT IN, CHANGED

Value: Refers to the value that you want to compare the field against. You could also use some pre-built functions to return dynamic values, these functions include:

Time related: startOfDay/Week/Month/Year,  endOfDay/Week/Month/Year,  lastLogin(),  now(), currentLogin()

People related: currentUser(), membersOf()

Issue related: issueHistory() openSprints() watchedIssues() myApproval() myPending()

Keyword: To perform complex searches, the following keywords help link search clauses together “AND”, “OR” and “IS”

It's important to note that JQL is case-insensitive and can use parentheses to group clauses, allowing for more complex queries. Additionally, JQL supports functions that can be used to search for issues with certain attributes or characteristics.

Here are a couple of examples

• JQL query searches for all open issues in the "Acme" project:

project = Acme AND status != Closed

In this query, "project" is the field, "=" is the operator, and "Acme" is the value. The "AND" operator is used to combine two clauses: the project is "Acme," and the status is not "Closed." together

• Search for all issues in a specific project and with a specific status:

project = "Acme Project" AND status = "In Progress"

This query will find all issues in the "Acme Project" that are currently in the "In Progress" status.

• Search for all issues created in the last 7 days:

created >= -7d

This query will find all issues created within the last 7 days.

• Search for all issues with a certain label:

labels = "security-issue"

This query will find all issues with the "security-issue" label.

• Search for all issues of a certain type and with a certain resolution:

issuetype = Bug AND resolution = "Cannot Reproduce"

This query will find all bugs that have been marked with the "Cannot Reproduce" resolution.

• Search for all issues containing a specific keyword in the summary or description:

text ~ "error message"

This query will find all issues that contain the phrase "error message" in the summary or description.

Reserved characters, term modifiers etc.. to be aware off

In JQL there are several reserved characters and words that have special meaning and are used to build queries. These include:

Reserved Characters:

Parentheses: () - Used to group clauses in a query

Quotation marks: "" - Used to enclose phrases or words that have spaces in them

Asterisk: * - Used as a wildcard to represent any number of characters in a search

Question mark: ? - Used as a wildcard to represent a single character in a search

Boolean operators: AND, OR, NOT - Used to combine multiple search criteria

Reserved Words:

a, and, are, as, at, be, but, by, for, if, in, into, is, it, no, not, of, on, or, s, such, t, that, the, their, then, there, these, they, this, to, was, will, with

Term Modifiers:

Replace single character with ? example - m?t 

Replace multiple characters with * example - win* 

Add ~ to the end of a single term e.g. marry~ 

Add ~ to the end of a single term e.g. marry~

Use Cases for JQL

There can be numerous use cases for JQL as it makes information in Jira accessible easily to all the stakeholders who use Jira, including Jira administrators, Users, Project administrators etc.. enabling each of them to easily create custom queries to suit their specific needs.

• Issue tracking: JQL can be used to track and monitor issues in Jira, allowing users to quickly find and view information about specific issues.
• Reporting: JQL can be used to generate reports based on specific search criteria, making it easy to get an overview of the progress of a project or team.
• Project management: JQL can be used to manage projects and tasks, allowing users to filter issues by status, priority, and other key criteria.
• Resource allocation: JQL can be used to identify issues that are assigned to specific team members, making it easier to allocate resources and balance workloads.
• Customer support: JQL can be used to track and manage customer support tickets, allowing support teams to quickly find and respond to customer issues.
• Bug tracking: JQL can be used to track and manage bugs and other issues in software development projects, helping developers to quickly identify and fix problems.
• Quality assurance: JQL can be used to track and manage quality assurance tasks, allowing teams to ensure that all issues are resolved before a product or feature is released.

Conclusion

JQL is a powerful query language used to search and filter issues in Jira. It allows users to create custom queries to search for specific issues based on a wide range of criteria, including issue type, status, priority, assignee, and more.

JQL provides a number of benefits, including efficient searching, customizable queries, easy automation, cross-project searching, and standardized language. Some common use cases for JQL include issue tracking, reporting, project management, resource allocation, customer support, bug tracking, and quality assurance.

Overall, JQL is a versatile tool that can help users save time, increase productivity, and make more informed decisions when managing projects and issues in Jira.