A Quickstart Guide to JQL

Imagine you’re managing a rapidly growing software development team within a tech organization. Your team uses Jira to track hundreds of issues across multiple projects, from bugs to feature requests. 

Stakeholders frequently ask for updates: 

• “What’s the status of our high-priority tasks?”, 
• “Which bugs are still unresolved?”, 
• And “Who’s working on the sprint blockers?” 

Your emails & Slack messages already contain multiple project updates. Without an efficient way to extract this information, you’ll be drowning in manual searches and wasting valuable time.

With JQL or Jira Query Language, you can pinpoint exactly what you need, filter the noise, and deliver insights in seconds – giving you back the time to focus on your priorities. Let’s understand what JQL is and how you can use it.

What is Jira Query Language (JQL)?

JQL is like the magnifying lens for Jira users. When your project manager urgently needs a list of unresolved high-priority bugs, the last thing you want is to manually sift through hundreds of tickets. With JQL – your search assistant, you can fetch precise results within seconds.

JQL is a powerful search language designed for filtering and retrieving issues in Jira based on the criteria you define. Whether it’s filtering tasks by assignee, status, or even complex combinations of fields, JQL puts you in control. 

But here’s the thing—JQL is more than just a built-in tool. The Atlassian marketplace has apps designed to extend JQL’s power, enhancing team productivity. Some tools refine how queries are written, while others entirely build solutions on top of JQL, amplifying Jira’s capabilities. But how does it work?

How does JQL work within the Jira ecosystem?

JQL operates as the backbone of Jira’s search functionality, allowing users to interact dynamically with issues. Whether using Jira Software, Jira Service Management, or Jira Business Projects, JQL empowers users to streamline workflows and gain actionable insights. It is made up of 3 main components.

1. Fields: This is the type of project information in the Jira. It can be the project details, issue type, and fixVersion & so much more.
2. Operators: This can be “or”, “and”, “if”, etc. Basically, this helps relate fields to the value.
3. Keywords: These are specific words with which you can search the project for information that you are looking for

Overview of its role in project management

Think of JQL as your command center in Jira. For project managers, it’s like having a personalized GPS that guides you to the information you need when you need it. With JQL, teams can:

Locate and prioritize tasks with precision

Ever feel buried under an avalanche of tickets? 

JQL lets you filter tasks by priority, assignee, sprint, or custom field. For example, consider a query like:

priority = “Critical” AND status = “To Do”

This instantly highlights critical tasks still waiting to be tackled. This way, no critical-priority issue gets lost in the noise.

Monitor project progress with customized filters

Need a quick snapshot of where things stand? 

JQL helps create dynamic filters for dashboards and boards that adapt to your team’s unique needs. Imagine querying:

project = “Web App” AND status = “In Progress”

The above helps you monitor all open tasks across a specific project—ideal for morning stand-ups or quick status checks.

Optimize reporting for better decision-making

With JQL, you can zero in on patterns and bottlenecks. For example, identifying unresolved bugs assigned to a specific developer:

type = “Bug” AND resolution = Unresolved AND assignee = “John Doe”

This data can then feed into Jira dashboards or applications available on Atlassian to ease writing JQL for actionable insights.

Why use JQL in Jira?

We know now that JQL is useful for staying organized, saving time, and making smarter decisions in Jira. Here’s how it helps teams work faster and smarter, using relatable examples:

Find and filter specific issues instantly

Have you ever needed to track tasks from a specific project phase? 

JQL helps you zero in with laser-like precision.

For example, here is the query to pull all tasks in a “Review” stage:

status = “In Review” AND project = “Website Redesign”

In seconds, you’ll have a focused view of the issues needing attention—whether it’s for peer reviews, approval, or QA testing.

Need something more specific? 

Let’s say you’re tracking tasks assigned to a teammate in a sprint. The query would be:

sprint = “Sprint 12” AND assignee = “Alice”

JQL ensures Alice (and you) stay on top of priorities without digging through unrelated tickets.

Save time by automating queries

Keeping up with unfinished tasks at the end of a sprint can be a pain. JQL makes automating and visualizing spillover issues easy when planning the next sprint.

For instance, to list all incomplete tasks, you can use the following query:

sprint in openSprints() AND resolution = Unresolved

Save this query as a filter; every sprint retrospective will start with clarity, not chaos.

Monitor overdue work before it escalates

Missed deadlines happen, but JQL can help prevent them. If you want to find tasks that slipped past their due dates, use this query:

due < now() AND status != “Done”

Build dynamic reports for tracking performance

With JQL, you can dynamically generate reports that track performance metrics over time.

For instance, you can find all resolved issues in the last two weeks, categorized by team members, as shown below:

resolved >= -14d AND assignee IS NOT EMPTY

This gives you a ready-to-analyze report of tasks completed to identify top performers or teammates needing support.

Identify bottlenecks in your workflow

Sometimes, teams get stuck on a certain status, slowing delivery. JQL effortlessly pinpoints these bottlenecks.

For instance, to find tasks sitting in “To Do” for over a week, you can use the following query:

status = “To Do” AND created <= -7d

This query returns issues that need attention so teams can unblock tasks, improve turnaround times, and hit project milestones faster.

Stay organized with personalized queries

Each team member works differently. JQL allows you to create customized views tailored to specific roles.

For example, a product manager might use:

fixVersion = “Q4 Release” AND priority in (High, Critical)

While a developer could rely on:

assignee = currentUser() AND status != “Done”

JQL ensures every team member stays laser-focused on what’s relevant to their role, driving productivity without distractions.

Understanding the basics of JQL

Before exploring complex queries, let’s review some essential elements of JQL, such as fields, operators, values, and common keywords.

Fields

Fields represent attributes of an issue, like its status, assignee, or project. Think of fields as the specific data points you want to query.

For instance, consider the following query:

status = “In Progress”

This query fetches all issues currently being worked on. It is perfect for when your team needs a real-time view of ongoing tasks.

It’s worth remembering that popular fields include project, priority, assignee, status, and created.

Operators

Operators define relationships between fields and their values. These are like the connectors that give your query meaning.

• = means “is equal to”
• != means “is not equal to”
• AND combines multiple conditions
• OR  allows flexibility with conditions.

For example:

priority != “Low” AND status = “To Do”

This query finds all tasks except low priority ones sitting untouched—ideal for identifying areas requiring immediate focus.

Values

Values are the real-world inputs in your queries—names, dates, or statuses.

• Status values: To Do, In Progress, Done
• Names: Usernames like “JohnDoe”
• Priorities: High, Medium, Low
• Dates: Dynamic values like now() or specific formats like 2024-12-01

For example:

project = “Website Launch” AND due <= now()

This query finds overdue tasks in the “Website Launch” project. Values like now() make it dynamic and always up-to-date.

Common keywords

JQL keywords act as modifiers, helping you filter, organize, or sort results.

• ORDER BY: Sort query results (e.g., by created, priority)
• IN and NOT IN: Include or exclude multiple values
• IS EMPTY and IS NOT EMPTY: Find missing or filled fields

For instance, here is a query that fetches tasks from multiple projects and sorts by creation date:

project IN (“ProjectA”, “ProjectB”) ORDER BY created DESC

Now, let’s understand how you can use all the components together with a JQL code example.

Let’s say you’re managing a software release and want to:

• See all critical bugs
• In the “Mobile App” project
• Sorted by latest creation date

Here’s your query:

project = “Mobile App” AND priority = “Critical” AND type = “Bug” ORDER BY created DESC

With one line of JQL, you get a dynamic, actionable list of critical bugs—no scrolling or filtering required!

These basics ensure you query Jira like a pro. Now, let’s take a look at some important JQL syntax and operators. 

Key JQL syntax and operators

In the following sections, we will learn some basic operators, logical connectors, and functions that you can use to retrieve exactly what you need. Let’s break this down.

Basic operators

These are the foundational building blocks of any JQL query.

• = : Equal to
  Example: status = “Done” → Fetch all completed tasks.
• != : Not equal to
  Example: priority != “Low” → Exclude low-priority tasks.
• > : Greater than
  Example: created > startOfMonth() → Issues created after the start of the month.
• < : Less than
  Example: due < now() → Overdue tasks that are past the current date.
• >= : Greater than or equal to
  Example: updated >= -7d → Issues updated within the last 7 days.
• <= : Less than or equal to
  Example: votes <= 5 → Issues with 5 or fewer votes.

Logical Operators

Logical operators allow you to build complex queries by combining or excluding conditions. Let’s take a look at some important logical operators. 

AND

This operator matches multiple conditions simultaneously.

Example:

project = “Website Revamp” AND priority = “High”  

This fetches all high-priority tasks within the “Website Revamp” project.

OR

With this operator, you can match at least one condition.

Example:

status = “To Do” OR status = “In Progress”  

Retrieves tasks that are either pending or in progress.

NOT

This operator excludes specific conditions.

Example:

NOT assignee = currentUser()  

This excludes tasks assigned to the current user.

Wildcard operators

Wildcard operators are used when you don’t have precise details. Here are two wildcard operators to understand. 

~ (Contains)

It finds values that include the specified term.

Example:

summary ~ “bug”  

Here, this query retrieves all issues with “bug” somewhere in the summary (e.g., “critical bug fix” or “bug report”).

!~ (Does Not Contain)

This operator excludes matches with the specified term.

Example:

description !~ “UI”  

It will fetch issues where the description does not include “UI”.

Functions

JQL functions dynamically fetch results based on conditions such as users, timestamps, or groups. Let’s take a look at some critical functions and understand how they work with some practical examples.

currentUser()

It fetches issues assigned to the current user.

Example:

assignee = currentUser()  

Perfect for creating a personal dashboard of tasks you need to tackle.

now()

This function uses the current timestamp to retrieve time-sensitive issues.

Example:

updated >= now() – 1d  

You can use this function to find issues updated within the last 24 hours—handy for monitoring recent activity.

membersOf()

This function retrieves issues assigned to members of a specific group.

Example:

assignee IN membersOf(“QA Team”)  

It will display tasks assigned to everyone in the QA team—great for team-specific reporting.

Putting it together

Let’s say you’re a project manager preparing for a sprint review. You want to find:

1. All high-priority bugs assigned to the QA team.
2. That was updated in the last 3 days.

Here’s an example of a JQL query:

project = “Mobile App” AND priority = “High” AND type = “Bug” AND assignee IN membersOf(“QA Team”) AND updated >= -3d

With this query, you’re laser-focused on the right issues for your team—no digging or manual searches required!

Now, we have a basic idea about operators, logical connectors, and functions to level up your JQL game. The better you get at querying, the faster you’ll be able to find and act on critical information in Jira, so let’s not wait and see how you can write JQL queries.

A step-by-step guide to writing JQL queries

If you’re ready to dive into JQL, don’t worry—it’s easier than you think. Writing a JQL query follows a logical process that turns Jira into your ultimate productivity sidekick. Here’s a step-by-step approach:

Step 1: Define the query goal

Before you start typing, clarify what you’re trying to find.

• Example Goal: “Find unresolved, high-priority issues assigned to my team for this sprint.”

Think of this step as setting your search mission—are you looking for bugs, overdue tasks, or issues that require immediate attention? 

Clear goals make for sharper queries.

Step 2: Identify fields, operators, and values

Break your query down into three components, as we have mentioned before:

• Fields: The attributes of an issue you want to search (e.g., priority, status, assignee).
• Operators: How you define relationships (e.g., =, !=, IN).
• Values: The specific data you’re filtering for (e.g., “High,” “Unresolved,” “Team-Dev”).

Example Breakdown:

• Field: priority
• Operator: =
• Value: “High”
• Combine it with logical operators: AND
• Add a function: membersOf()

Step 3: Write and test the query

Now, it’s time to write and test your query. Use Jira’s search bar to type your query and hit enter. If it works, you’ll see relevant results; if not, Jira will let you know where you went wrong.

Pro Tip: Start simple and build your query step by step. 

For example:

1. Start with: priority = High
2. Add more filters: priority = High AND resolution = Unresolved
3. Add functions: priority = High AND resolution = Unresolved AND assignee IN membersOf(“Team-Dev”)

By building progressively, you can troubleshoot and ensure your query behaves as expected.

Step 4: Optimize for readability and save it

Keep your JQL queries clean and easy to understand—both for you and your teammates.

Tips for readability:

• Use consistent capitalization (e.g., AND, OR).
• Indent or space out longer queries for clarity.
• Use comments (e.g., in saved queries) to explain complex searches.

Save It: Once your query works perfectly, save it as a filter in Jira.

Saved queries can be reused for reports, dashboards, or team standups.

JQL query example in action

Goal: Find all open “Critical” bugs updated within the last 48 hours, assigned to the QA team.

Query:

project = “Website-Launch” AND type = Bug AND priority = Critical AND status != Done AND updated >= -2d AND assignee IN membersOf(“QA-Team”)

Breakdown:

• project = “Website-Launch” → Only tasks in the relevant project.
• type = Bug → Limit results to bugs.
• priority = Critical → Focus on critical tasks.
• status != Done → Exclude completed tasks.
• updated >= -2d → Updated within the last 2 days.
• assignee IN membersOf(“QA-Team”) → Assigned to QA team members.

By following this step-by-step guide, you’ll go from beginner to JQL power user in no time. 

Advanced JQL techniques

JQL isn’t just about finding issues—it’s about powering smarter workflows and insights. Here’s how to take it up a notch:

Combining JQL with Jira Dashboards

Think of JQL as the data engine for your Jira dashboards. Use saved filters to populate widgets with real-time insights tailored to your team’s needs. For example:

A widget showing “High-Priority Bugs for the Current Sprint” can be powered by a query like:

project = “Website-Launch” AND priority = High AND status != Done

Suddenly, your dashboard goes from generic charts to an actionable control center.

Automating workflows using JQL

Automation + JQL = Magic. Set up automation rules in Jira using JQL queries as triggers. For example:

• Trigger: When a task moves to “Done.”
• JQL Filter: status = Done AND assignee = currentUser()
• Action: Send a Slack notification to celebrate a completed task .

This saves manual effort and keeps everyone in the loop. Whether you’re automating reminders, status changes, or notifications—JQL does the heavy lifting.

Leveraging plugins for extended query capabilities

Sometimes, Jira’s native JQL isn’t enough. Plugins like ScriptRunner step in to supercharge your queries. For example:

• Subqueries: Fetch linked issues with additional filters.
• Enhanced Functions: Search for issues by specific SLA breaches, comments, or custom fields.

Best practices for writing JQL queries

To write JQL like a pro, keep these golden rules in mind:

1. Use consistent formatting for readability

Clear, well-formatted queries save time—both for you and your team. 

Example:

project = “Mobile-App” AND (status = “In Progress” OR status = “To Do”) AND priority = High

2. Test queries frequently for accuracy

Don’t assume your query works perfectly the first time. Test as you build, and tweak filters to ensure the results align with your expectations.

3. Use parentheses for logical groupings

When combining multiple conditions, parentheses ensure your query logic stays rock-solid.

Example:

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

This avoids any confusion in the order of operations.

4. Leverage saved filters for reuse

Why reinvent the wheel? 

Save your frequently used queries as filters to power dashboards, reports, and automation. It’s like having shortcuts to productivity at your fingertips.

Take charge with JQL and transform your workflow

Whether you’re a project manager juggling multiple sprints, a developer tracking critical bugs, or an operation lead optimizing workflows, JQL equips you with the precision and speed to uncover exactly what you need in Jira. This powerful query language is more than just a search tool—it’s your gateway to making Jira work smarter, not harder. All you need to do is to master its syntax, experiment with advanced operators, and customize queries to suit your unique needs. With that, you can unlock a whole new level of control and insight into your projects.

However, JQL doesn’t just help you find data. With a clever query, you can spot trends, track progress, and even identify potential roadblocks before they become critical issues. Moreover, It empowers you to turn raw data into actionable insights so that you can have a competitive edge in managing tasks and improving collaboration across teams.

Start small, learn as you go, and explore the endless possibilities JQL offers. Over time, you’ll discover how it can streamline workflows, boost efficiency, and enhance visibility across every aspect of your projects. Leverage its potential, experiment boldly, and watch as your projects transform into a seamless symphony of productivity.

FAQs

Q1: What is a JQL cheat sheet?

A cheat sheet is a quick reference guide with common queries, syntax, and operators to make writing JQL faster and easier.

Q2: What makes a good JQL query?

 A good query is:

• Clear and easy to understand.
• Concise without unnecessary filters.
• Accurate in retrieving exactly what you need.

Q3: How do I decide if a change is significant enough to include in JQL?

It is advisable to include changes that impact your team’s reporting, dashboards, or workflows. For example, update your JQL to reflect if a custom field or status affects task visibility.

Q4: What are some examples of useful JQL queries?

Here are some examples of JQL queries 

Issues assigned to me:
assignee = currentUser()  

Issues updated in the last 7 days:
updated >= -7d  

High-priority unresolved bugs:
project = “Website” AND type = Bug AND priority = High AND resolution = Unresolved  

Q5: What is an advanced JQL query example?

Here’s a query for a development team looking at tasks updated recently:

project = ABC AND assignee IN membersOf(“Team-Dev”) AND updated >= -14d

This pulls issues in project ABC, assigns them to developers, and updates within the last two weeks.