Jira is one of the most widely used project management and issue-tracking tools, helping teams organize, track, and manage their work efficiently. One of its most powerful features is Jira Query Language (JQL), a flexible and robust way to search for issues in Jira.
JQL allows users to create complex queries to filter issues based on various criteria such as status, assignee, project, priority, and more. Whether you’re a project manager, developer, or QA engineer, mastering JQL can significantly enhance your productivity in Jira.
In this guide, we’ll cover:
- What is JQL?
- Basic JQL Syntax
- How to Write JQL Queries
- Common JQL Functions & Operators
- Step-by-Step Examples
- Creating a Query for “In Progress” Tickets
- Advanced JQL Techniques
- Best Practices
Let’s dive in!
Contents
Mastering Jira Query Language (JQL) – A Comprehensive Guide.
Complete List of JQL Functions in Jira.
4. Issue Linking & References.
5. Aggregate & Statistical Functions.
7. Advanced JQL Functions (Plugins & ScriptRunner)
1. What is JQL?
JQL stands for Jira Query Language, a text-based search language used to query issues in Jira. Unlike the basic search filters, JQL provides advanced search capabilities, allowing users to construct precise queries using logical operators, keywords, and functions.
Key Benefits of JQL:
✔ Precise Filtering – Retrieve exact issues based on multiple conditions.
✔ Advanced Search – Go beyond basic filters with complex logic.
✔ Reusable Filters – Save queries as filters for future use.
✔ Integration with Dashboards & Reports – Use JQL filters in Agile boards and reports.
2. Basic JQL Syntax
A JQL query consists of fields, operators, and values structured in a logical format.
Basic Structure:
FIELD OPERATOR VALUE [AND|OR] [FIELD OPERATOR VALUE]…
- FIELD – A Jira field (e.g., status, assignee, project).
- OPERATOR – Defines the condition (e.g., =, !=, IN, NOT IN).
- VALUE – The data to match (e.g., “In Progress”, “John Doe”).
Example:
status = “In Progress” AND assignee = currentUser()
This query retrieves all issues assigned to the current user with a status of “In Progress.”
3. How to Write JQL Queries
Step 1: Accessing the Advanced Search in Jira
- Go to Issues → Search for issues.
- Click on Advanced to switch to JQL mode.
Step 2: Writing a Simple Query
Let’s start with a basic query:
project = “My Project” AND status = “Open”
This returns all open issues in “My Project.”
Step 3: Using Logical Operators (AND, OR, NOT)
Combine multiple conditions:
project = “My Project” AND (status = “Open” OR status = “In Progress”)
This retrieves all issues in “My Project” that are either “Open” or “In Progress.”
Step 4: Saving the Query as a Filter
After running a query:
- Click Save As.
- Give it a name (e.g., “My Open and In-Progress Issues”).
- Click Submit.
Now, you can reuse this filter in dashboards or reports.
4. Common JQL Functions & Operators
Comparison Operators
| Operator | Description | Example |
| = | Equals | status = “Done” |
| != | Not equals | status != “Done” |
| > | Greater than | dueDate > “2024-01-01” |
| < | Less than | created < “2024-01-01” |
| >= | Greater than or equal | priority >= “High” |
| <= | Less than or equal | votes <= 5 |
Logical Operators
| Operator | Description | Example |
| AND | Both conditions must be true | status = “Open” AND assignee = currentUser() |
| OR | Either condition must be true | status = “Open” OR status = “In Progress” |
| NOT | Excludes matching issues | NOT status = “Closed” |
Text Search Operators
| Operator | Description | Example |
| ~ | Contains | summary ~ “bug” |
| !~ | Does not contain | summary !~ “test” |
| IS EMPTY | Field is empty | description IS EMPTY |
| IS NOT EMPTY | Field is not empty | description IS NOT EMPTY |
Date Functions
| Function | Description | Example |
| currentUser() | Logged-in user | assignee = currentUser() |
| now() | Current time | dueDate > now() |
| startOfDay(), endOfDay() | Today’s start/end | created >= startOfDay() |
5. Step-by-Step JQL Examples
Example 1: Find All “In Progress” Tickets
status = “In Progress”
Explanation:
- status is the field.
- = is the operator.
- “In Progress” is the value.
Example 2: Find High-Priority Bugs Assigned to Me
project = “My Project” AND type = “Bug” AND priority = “High” AND assignee = currentUser()
Example 3: Find Issues Updated in the Last 7 Days
jql
Copy
updated >= -7d
- -7d means “7 days ago.”
Example 4: Find Unresolved Issues with No Assignee
status NOT IN (“Closed”, “Done”) AND assignee IS EMPTY
6. Advanced JQL Techniques
Using IN and NOT IN for Multiple Values
status IN (“Open”, “In Progress”, “Reopened”)
Using WAS to Track Historical Changes
status WAS “In Progress” DURING (“2024-01-01”, “2024-01-31”)
This finds issues that were “In Progress” at any point in January 2024.
Using ORDER BY to Sort Results
project = “My Project” ORDER BY created DESC
This sorts issues by creation date (newest first).
7. Best Practices for Writing JQL Queries
✅ Use Parentheses for Complex Logic – Improves readability and ensures correct evaluation.
✅ Leverage Saved Filters – Avoid rewriting common queries.
✅ Test Queries Incrementally – Start simple and add conditions gradually.
✅ Use JQL Functions – Like currentUser(), now(), etc., for dynamic queries.
✅ Optimize for Performance – Avoid overly broad queries (e.g., project IS NOT EMPTY).
Complete List of JQL Functions in Jira
Jira Query Language (JQL) provides several built-in functions to enhance search capabilities. Below is a comprehensive list of all JQL functions, categorized by their purpose.
1. User-Related Functions
These functions help filter issues based on user information.
| Function | Description | Example |
| currentUser() | Returns the currently logged-in user. | assignee = currentUser() |
| membersOf() | Finds users who are members of a group. | assignee IN membersOf(“developers”) |
| currentUserGroups() | Returns groups the current user belongs to. | assignee IN currentUserGroups() |
2. Date & Time Functions
These functions help filter issues based on dates and times.
| Function | Description | Example |
| now() | Current date and time. | dueDate > now() |
| startOfDay() | Start of the current day (midnight). | created >= startOfDay() |
| endOfDay() | End of the current day (11:59:59 PM). | dueDate <= endOfDay() |
| startOfWeek() | Start of the current week (Monday). | updated >= startOfWeek() |
| endOfWeek() | End of the current week (Sunday). | dueDate <= endOfWeek() |
| startOfMonth() | Start of the current month. | created >= startOfMonth() |
| endOfMonth() | End of the current month. | dueDate <= endOfMonth() |
| startOfYear() | Start of the current year. | created >= startOfYear() |
| endOfYear() | End of the current year. | dueDate <= endOfYear() |
3. Text & String Functions
These functions help with text-based searches.
| Function | Description | Example |
| ~ (Contains) | Searches for text in a field. | summary ~ “bug” |
| !~ (Not Contains) | Excludes text in a field. | summary !~ “test” |
4. Issue Linking & References
These functions help find linked issues.
| Function | Description | Example |
| linkedIssues() | Finds issues linked to a given issue. | issueFunction in linkedIssues(“ABC-123”) |
| issueHistory() | Searches issue change history. | status WAS “In Progress” |
5. Aggregate & Statistical Functions
These functions help with calculations and issue statistics.
| Function | Description | Example |
| count() | Counts matching issues. | issueFunction in count(“status = Open”) |
| sum() | Sums a numeric field. | issueFunction in sum(“timeSpent”) |
6. Special JQL Operators
These are not functions but powerful operators used in JQL.
| Operator | Description | Example |
| WAS | Checks if a field had a value in the past. | status WAS “In Progress” |
| CHANGED | Checks if a field changed. | status CHANGED AFTER startOfWeek() |
| DURING | Checks if a condition was true during a period. | status WAS “Done” DURING (“2024-01-01”, “2024-01-31”) |
| AFTER, BEFORE | Filters based on date ranges. | created AFTER “2024-01-01” |
7. Advanced JQL Functions (Plugins & ScriptRunner)
Some functions require Atlassian Marketplace plugins (like ScriptRunner):
| Function | Description | Example |
| issueFunction | (ScriptRunner) Allows complex queries. | issueFunction in subtasksOf(“ABC-123”) |
| hasAttachments() | (ScriptRunner) Checks for attachments. | issueFunction in hasAttachments() |
Final Notes
- Standard JQL functions (like currentUser(), now()) work in all Jira instances.
- Advanced functions (like issueFunction) may require plugins.
- Always test queries in Jira’s Advanced Search before saving.
Conclusion
JQL is an indispensable tool for Jira users who need precise control over issue tracking. By mastering JQL syntax, operators, and functions, you can create powerful queries to streamline workflows, generate reports, and improve productivity.
Final JQL Query Example (All “In Progress” Tickets)
status = “In Progress” ORDER BY updated DESC
This retrieves all issues in “In Progress” status, sorted by the most recently updated.
Start experimenting with JQL today, and unlock the full potential of Jira’s search capabilities!
For you
