A guide to Jira Query Language
Share on socials
A guide to Jira Query Language
JQL can be tricky to get your head around, we get it! So whether you're a new user or a seasoned pro, this guide will give you the foundation you need to become a JQL Jedi.
The JQL awakens...
Sometimes working with Jira search can feel like trying to convince Darth Vader to fork over the keys to the Death Star. Without a dash of The Force or a Jedi mind trick or two, it’s just not happening.
Here’s where JQL comes in.
Jira Query Language (JQL) is a great tool that allows the wielder to search for issues within Jira. Mastering it will leave you with unlimited Jira power at your fingertips. But with great power comes great… learning curves? Learning curves lead to anger, anger leads to hate and hate leads to a backlog of world-ending proportions.
This guide has you covered, with this foundational guide you'll be querying like a JQL Jedi in no time.
What is JQL?
Jira Query Language allows you to create complex queries using a ‘simple', structured syntax. JQL is similar to SQL (Structured Query Language) but is bespoke for Jira. It enables you to filter issues based on various criteria, making it easy to find exactly what you're looking for.
How to query in Jira?
JQL is versatile, allowing you to search for issues using various criteria, and querying in Jira is actually quite straightforward once you get the hang of it. Here’s how you can get started:
1. Navigate to the "Issues" drop-down menu and select "Search for issues."
2. By default, Jira opens in basic search mode. Switch to advanced search by clicking on the "Advanced" link.
3. In the advanced search bar, you can start typing your JQL query. Jira will provide auto-suggestions to help you build your query.
How to write a JQL query?
Your first attempts at writing a query might start out looking like some noise Jabba the Hutt would spit out, but with a little practice you’ll be a fast and fluent user in no time! Here are some tips on how to write a Jira query:
1. A JQL query is composed of fields, operators, and values. For example, `project = "ProjectName"` is a simple JQL query where "project" is the field, "=" is the operator, and "ProjectName" is the value.
2. Keywords like `AND`, `OR`, and `NOT` help you combine multiple criteria. For instance, `project = "ProjectName" AND status = "Open"` will return all open issues in the specified project.
3. Functions like `currentUser()`, `now()`, and `startOfDay(-7d)` can make your queries more dynamic. For example, `assignee = currentUser() AND created >= startOfDay(-7d)` will find all issues assigned to the current user that were created in the last week.
Jira query examples
Here are some tried and true examples to get you going:
1. Find issues assigned to a specific user:
assignee = "username"
This query returns all issues assigned to the specified user.
2. Search for issues in a specific project:
project = "ProjectName"
This query lists all issues within the specified project.
3. Filter issues by status:
status = "In Progress"
This query retrieves all issues that are currently in progress.
4. Combine multiple criteria:
project = "ProjectName" AND status = "Open" AND priority = "High"
This query finds all high-priority, open issues within a specific project.
5. Use date functions:
created >= startOfMonth()
This query returns all issues created since the start of the current month.
From padawan to master
Advancing your JQL skills from beginner to expert is a journey worth taking. If you're using Data Center and looking to delve deeper into the advanced capabilities of JQL, we have just the resource for you. Take a look at our top 10 most commonly used Jira Query Language functions.
Jira Cloud users, there's something special for you too. Have you tried Enhanced Search for Jira Cloud yet? Available as part of your ScriptRunner for Jira Cloud license, or as a standalone app, this tool is designed to refine and expedite your search queries. Take part in the Jira Search bootcamp and learn how to find what you need in Jira faster with Enhanced Search.
Get ready for unlimited JQL power
Ready for more? Push your JQL potential even further with these resources.
Published on 4 May 2025
Authors
Charlie McCormack
Share this tutorial
Related content
Discover more like this
The Top 10 Jira Query Language (JQL) functions from ScriptRunner
Looking for JQL queries to conduct advanced searches in Jira? Create your own with this tool, or check out the top 10 most used ScriptRunner JQL functions now.
by Jamie Echlin
on 12 Jan 2024
10 easy Jira Cloud automation wins with ScriptRunner
Need to get below your Cloud automation limits fast? Want to use ScriptRunner for your “simple” use cases as well as your complex ones? Here are 10 example scripts for quick wins in Jira Cloud!
by Andrei Cuzuioc
on 26 Jan 2024