Jira Query Language (JQL) is a versatile and powerful tool that allows users to create sophisticated queries to find issues in Jira. To get the most out of JQL, it’s important to follow some best practices. Here, we will explore advanced JQL best practices that can help you write efficient, maintainable, and effective queries.
Understanding the Basics
Before diving into advanced best practices, ensure you have a solid grasp of JQL basics:
- Fields: Familiarize yourself with common fields such as
project, issuetype, status, assignee, priority, etc.
- Operators: Learn the operators like
=, !=, >, <, >=, <=, ~ (contains), !~ (does not contain), IN, NOT IN, IS, and IS NOT.
- Keywords: Know how to use
AND, OR, NOT, and ORDER BY.
Advanced JQL Techniques
Using Wildcards
Wildcards can be very useful when you’re searching for issues with fields that contain certain patterns. The asterisk (*) is used as a wildcard in JQL.
Example:
summary ~ "roadmap*"
description ~ "log*"
This query finds all issues where the summary and description contains words starting with "roadmap" and "log".
Use Descriptive Names for Saved Filters
When saving filters for reuse, use clear and descriptive names. This makes it easier for you and others to understand the purpose of the filter and easy for searching the filter names when we search them while adding them on the Dashboard Gadgets, Roadmap, Board, etc as filters in Jira can have same name and Jira does not restrict users from creating the filters with same name.
Use Relative Dates for Dynamic Queries
Relative dates (-7d, startOfWeek()) keep your filters dynamic and up-to-date.
Example:
created >= startOfMonth()
This query returns issues created from the start of the current month.
Using Functions
JQL provides several functions that can be very powerful when used correctly.
membersOf(): Finds issues assigned to members of a specific group.currentUser(): Finds issues related to the current user.startOfDay(), endOfDay(), startOfWeek(), endOfWeek(), etc.: These functions help filter issues based on specific time frames.
Example:
assignee in membersOf("jira-system-administrators")
This query finds issues assigned to member of "jira-system-administrators" groups, memberOf() function does not support to use the Project Role it only supports group
Searching for Linked Issues
If you want to find issues that are linked to a particular issue, use the linkedIssues() function.
Example:
issue in linkedIssues("ABC-44")
This query will show all issues linked to ABC-44 Issue.
Optimize Queries with Field Indexing
Use indexed fields for better performance. Common indexed fields include project, issuetype, status, and assignee.
Example:
project = "ABC" AND issuetype="Bug" AND status = "Review" AND assignee= currentUser()
This query performs better than using non-indexed fields.
Sub-Queries for Better Filtering
Break down complex queries into simpler saved filters and combine them.
Example: Save filter "Unresolved Bug issues from the ABC Proejct":
project = "ABC" and resolution is EMPTY
Use this filter in another query
filter = "Unresolved Bug issues from the ABC Project" AND (assignee = "xyz@example.com" OR reporter = "abc@example.com")
This makes queries easier to understand and maintain.
Avoid Negations for Better Performance
Negations (!=, !~, NOT) can slow down queries. Use positive conditions where possible.
Text Searching with ~ and !~
Use the ~ operator to perform a text search within fields.
Regularly Review and Clean Up Filters
Regularly review saved filters to ensure they are still relevant and performing well. Clean up or optimize outdated filters.
These are some of best practices to used when working on Advance JQL queries
You can also follow the below Atlassian documents for deep understanding about the advance JQL functions, Keyworkds, Fields, Operators etc
Also, you can refer the below free Atlassian university courses for JQL
1 comment