JQL Cheat Sheet: Master JQL Query Language & Syntax

Jira Query Language or JQL is the most important tool for locating your issue and saving hours of work. It not only locates issues, but it also allows you to conduct precise and effective searches in Jira. 

Whether you’re a beginner or, an advanced user, or even a non-tech user, mastering JQL query language is super easy because of its straightforward syntax and logical structure. 

To get you started, here’s a guide on the JQL cheat sheet, which will introduce you to the world of JQL syntax. With our guide, you’ll be able to write structured JQL queries and explore similar issues to optimize your Jira workflow. Let’s get started.

What is JQL?

Jira Query Language is a powerful and flexible query language that allows users to search, filter, and retrieve issues in Jira accurately and with versatility. 

JQL, unlike basic search functionalities, offers you the ability to create search queries that are custom to your project needs, using fields, operators, and values to define particular conditions.

It provides even more functionalities like searching issues by status in progress, narrowing results by specific issue types, and finding dependencies through linked issues. This level of control not only makes project tracking simple but it also gives you the exact data you need to make your best decisions.

For example, you can search for status in progress, filter by issue type, or identify linked issues to streamline the project. 

JQL Syntax Overview

JQL query is a set of words and operators that defines how you want to search in Jira.  The queries are already pre-built in basic searches. However, for advanced searching, you can construct the queries from scratch. 

Fields, operators, values, and keywords make up these queries. The first step is learning how to create the right JQL syntax in Jira. It involves combining: 

Fields

A field is a type of data you’re querying in JIRA. Some examples of Jira fields are:

• Issue type
• Project
• Priority
• Fix Version
• Epic Name

For example, using the priority field allows you to retrieve all the issues that are on priority. 

Operators

It defines the relationship between fields and values (e.g., =, !=, IN). They are symbols such as equals (=), not equal (!=), greater than (>), less than or equal to (<=), and so on. They explain how your field relates to the value.

Values

These are your criteria or the data points that you’re filtering for (the target value or range you’re querying like To Do, Done).

Keywords

The keywords add logic to your queries and help combine or exclude conditions (e.g., AND, OR, NOT). For the “AND” operator, the search will return values for both conditions, whereas for the “OR” condition, the search will return one condition. 

For example, if you type 

(status = “In Progress” OR status = “To Do”) AND NOT priority = Low)

This query will return all issues that are either “In Progress” or “To Do” but excludes those with a low priority.

Functions

Functions add dynamic and powerful capabilities to your queries. They perform calculations or retrieve results based on pre-defined rules or pre-made commands. You can customize your queries in a more flexible manner. 

Let’s say you wanted to know all the unplanned issues, or you wanted to figure out if your project is having scoping problems. 

How do you use Jira to understand that? 

With function queries, you can search for all the not-closed issues that can be denoted by empty fields of epic links and fixes. 

You can also imply the other way around by filtering your search to issues that were not closed in the current sprint and were not assigned to another sprint either. 

So this will tell you how many tasks or issues were exceeding scope and were not marked as done in the last sprint. 

Example Query

status = “In Progress” AND assignee = currentUser()

This returns issues assigned to you with a status of “In Progress.”

Creating Structured Queries

JQL allows you to structure queries so you can combine a handful of conditions to filter data down exactly or work through complicated scenarios. 

Through the use of logical operators, functions, and dynamic filters, you can modify your searches to fit the unique needs of your project. 

Here’s how to build effective structured queries:

To create structured queries in Jira Query Language (JQL), you can use the JQL Query Inserter and the @WithPlugin(“com.almworks.jira.structure”) annotation: 

• JQL Query Inserter: Use this tool to manually or automate create structures.  

• @WithPlugin(“com.almworks.jira.structure”) annotation: This annotation is used for the insertion of issues into the structure. 

1. Combine Basic Queries

Use AND or OR to merge conditions: 

status = “To Do” OR priority = High

2. Filter Linked Issue

To find issues with specific links, use: 

issue in linkedIssues(“ABC-123”, “blocks”)

3. Date Ranges

Return issues created within a time frame: 

created >= startOfMonth() AND created <= endOfMonth()

JQL for Linked Issues

Linked issues are crucial for tracking dependencies. Here’s how to query them:

1. Find all linked issues

issue in linkedIssues(“KEY-456”)

2. Filter by link types

issue in linkedIssues(“KEY-456”, “relates to”)

3. Return unresolved linked issues

issue in linkedIssues(“KEY-456”) AND resolution = Unresolved

Common JQL Queries

1. Find issues by assignee

assignee = “John Doe”

2. Search for text

text ~ “keyword”

3. Return issues in a specific project

project = “ProjectName”

4. Filter by priority and status

priority = High AND status = “In Progress”

5. Locate unresolved issues in Jira

resolution = Unresolved

Best Practices of Using Jira

Becoming proficient in Jira JQL can significantly streamline the process of searching and organizing data, but some best practices should be followed to utilize it to the maximum extent. 

Whether you’re a beginner or looking to refine your skills, these tips will help you craft better queries, save time, and collaborate more effectively with your team.

Start With A Clear Purpose

Before getting deeper into JQL, take a moment to define exactly what you’re trying to find. If you know the end goal beforehand, you are bound to select suitable fields, operators and values of a query that will yield the desired output.

Choose The Right Tools

Not every combination of fields and operators will work smoothly together. Double-check that the ones you’re using are compatible to avoid confusion.

Test As You Go

Don’t wait until the end—run your query often to confirm it’s giving you the results you’re after. This can save you time and effort.

Save And Share Your Work

When a query is particularly useful, store it as a filter. It is simple to use it again later or to give it to your team to further optimize your team’s workflow.

Avoid These Common JQL Mistakes

When working with Jira Query Language (JQL), it’s easy to run into a few common errors that can lead to inaccurate or inefficient results. Avoiding these errors will save you time and lead to more consistent outcomes. Here are some key things to watch for:

Mismatch Between Fields and Operators

Make sure the operator you’re using is appropriate for the field you’re querying. For example, the ” operator is valid for many fields, but for fields (e.g., “labels” you should instead use “IN.

Using Invalid or Non-Existent Fields

Double-check that the field you’re referencing exists in your Jira setup. Simple typos or field usages that do not exist can lead to errors or misleading outcomes.

Skipping Quotation Marks for Text Values

When looking for text-based categories, such as summaries or labels, please enclose the value in double quotes. E.g., use summary=”Bug fix” rather than just using an unquoted summary).

Ignoring Field Types

Fields in Jira have different data types (e.g., text, numbers, dates), and the operators must match the type. If the operator selection for a field is incorrect, it will either fail or will produce inaccurate results.

Conclusion

With our guide, we hope you have learned how to master JQL and use it in a way that’s efficient for project management in Jira. This cheat sheet will help you learn from basic syntax to handling linked issues so you can optimize your workflow. 

FAQs