📖 Jira JQL | Searching for what you need in Jira like Pro | Jira Guru
Hello, Welcome back!
This is Wednesday again, and Weekly knowledge growth with Jira Guru!
Today's topic is "Jira JQL"
1. Understanding Jira Query Language
Jira Query Language, fondly abbreviated to Jira JQL, is an exceptionally flexible query language created by Atlassian specifically for Jira software. This language is designed to help users construct precise search queries to sift through the multitude of issues within their projects. If you've ever worked with SQL (Structured Query Language) for database management, you'll find JQL very familiar.
Why is JQL so crucial in the Jira ecosystem, you might ask? It's simple. JQL gives you the power to create custom search filters, which dramatically streamlines the project management process. With JQL, you can pinpoint specific tasks, monitor the progress of a project, generate detailed reports, and so much more. Irrespective of the size of your project or the number of issues you're dealing with, JQL lets you zero in on the issues that are relevant to you.
Think of it this way: JQL is your secret weapon in Jira, helping you to navigate smoothly through a sea of issues and tasks. With this powerful tool in your hands, you can tackle project management like a pro. So, let's dive deeper into the JQL world and understand its basic elements and syntax.
2. Getting Started with Jira Query Language
A. The Syntax of Jira JQL
The syntax of a JQL query follows a straightforward format: “field operator value”. This structure allows you to define what you're looking for in clear, logical terms.
For example, let's say you want to find all issues in a project that is currently in progress. Your JQL query might look like this: ‘status = "In Progress".’
In this example:
- ‘status’ is the field you're interested in.
- ‘=’ is the operator, which is used here to mean "equals".
- "In Progress" is the value, which is the specific status you're looking for.
B. JQL fields
In JQL, fields are the specific issue attributes you want to search for. They can be almost any property associated with an issue in Jira, such as
- ‘project’
- ‘issue type’
- ‘Priority’
- ‘Fix Version’
- ‘Epic tag’
- ‘status’
- ‘due date’
- Many more. …
The fields you can use in your JQL queries will depend on your Jira configuration and the specific fields available in your instance.
Atlassian Documentation: Lis of all field
C. JQL operators
Operators are the link between fields and values in a JQL query. They define the relationship between the field and the value.
The basic operators you can use in JQL include:
- Equals ‘=’
- Not equals ‘!=’
- Greater than ‘>’
- Less than ‘<’
- Greater than or equal to ‘>=’
- Less than or equal to ‘<=’
- In ‘IN’
- Not in ‘NOT IN’
- Is ‘IS’
- Is not ‘IS NOT’
- Like ‘~’
- Not like ‘!~’
Atlassian Documentation: JQL operators
D. JQL functions
Functions are special instructions that can be used in JQL queries to search for issues in a more dynamic or complex way. They can be used to find issues based on the current user (‘currentUser()’), the current time (‘now()’), members of a particular group (‘membersOf()’), and more.
Atlassian Documentation: JQL functions
F. Sample Basic Queries
Here are some sample basic JQL queries to get you started:
- 'project = "My Project"': This will return all issues in the "My Project" project.
- 'assignee = currentUser()': This will return all issues assigned to the currently logged-in user.
- 'status = "In Progress":' This will return all issues with the status "In Progress".
Remember, the best way to learn JQL is by trying it out yourself. So, don't be afraid to experiment with different queries and see what results you get. The more you practice, the more comfortable you'll become with JQL.
3. Advanced Jira Query Language Techniques
A. Complex Queries in Jira JQL
Advanced JQL usage often involves combining multiple conditions within a single query. You can do this using logical operators such as ‘AND’, ‘OR’, and ‘NOT’.
For instance, suppose you want to find all open or in-progress issues assigned to you. Your JQL query might look like this: ‘status = "In Progress" AND assignee = currentUser()’. This query uses the AND operator to combine two conditions: the issue's status and its assignee.
B. Advanced Search in Jira JQL
Jira's advanced search functionality allows you to refine your JQL queries further. For example, you can use the ‘ORDER BY’ clause to sort your search results, the ‘CHANGED’ operator to find issues with a field value that changed during a specific time frame, and much more.
Atlassian Documentation: JQL keywords
C. Building JQL Queries Using the Advanced Search Page
Jira's Advanced Search page provides a user-friendly interface for building complex JQL queries. Here, you can combine multiple fields, operators, and values using an intuitive dropdown system. The page also provides auto-complete suggestions, helping you avoid syntax errors and construct your queries more easily.
JQL is for everyone: developers, testers, agile project managers, and business users. However, you need to know how to construct structured queries using JQL to use this feature.
Atlassian Documentation: advanced search
D. Sample Advanced JQL Queries
To give you a sense of what advanced JQL looks like, here are a couple of complex query examples:
- Parent link: Get the child issues from multiple Parent Links
- "Parent Link" IN (EX-000, EX-001, EX-002, EX-003)
- Child issues: To get all child issues below INIT-00 and not just the child issues at the epic hierarchy level
- issuekey in portfolioChildIssuesOf("INIT-001")
- Team field: Get the list of issues assigned to a team
- "Team" = "shared team name"
- Target start or Target end: Find all issues with target start after 25 Jun 2023
- "Target start" >= "2020-01-02"
4. Tips for Using Jira Query Language Like a Pro
A. Jira JQL Best Practices
- Start with a clear goal: Before you start crafting a JQL query, know what you want to find. Having a clear goal makes it easier to select the right fields, operators, and values for your query.
- Use the right fields and operators: Not all fields and operators will yield results when paired together. Always ensure the field and operator you're using are compatible.
- Test your query: Regularly test your query to ensure it delivers the expected results.
- Reuse and share queries: If you create a particularly useful query, save it as a filter for future use. You can also share these filters with your team members, boosting overall productivity.
B. Common Pitfalls to Avoid
While working with Jira Query Language (JQL), it's important to be aware of common pitfalls to ensure accurate and efficient query execution. By avoiding these pitfalls, you can save time and obtain more reliable results. Here are some common pitfalls to watch out for:
- Field and Operator Mismatch: Ensure that you use the correct operator for the specific field you are querying. Different fields may require different operators. For example, the "=" operator is used for most fields, but for the labels field, you should use the "IN" operator instead.
- Using Non-Existing Fields: Verify that the field you are using in your JQL query actually exists in your Jira instance. A misspelling or using non-existing fields will result in errors or incorrect results.
- Missing Quote Marks for Text Values: When searching for text values, such as issue names or labels, make sure to enclose them in double quotation marks (" "). For example, summary = "Bug fix".
- Not Considering Field Types: Different fields have different data types (e.g., text, number, date). Ensure that you use the correct data type and corresponding operators when querying specific fields.
C. Using Saved Filters
Jira allows you to save your JQL queries as filters for future use. These filters can be referenced in various areas of Jira, such as on Dashboards, in Agile Boards, or in other queries using the ‘filter’ keyword.
To save your current filter, click on the “Save As” button near the top left – you’ll be prompted to name your filter:
Note that this feature is also available for basic searches.
D. Sharing Your JQL Queries
You can also share your queries and filters with other team members. Sharing filters allows others to use the same set of criteria to view issues. Moreover, Jira filters can be embedded into Confluence pages, making it easy to share the insights from your JQL queries with your entire organization.
You can do this in several ways:
- Use the “Share” button at the top right corner
- Export the filter in another format using the “Export” button (next to “Share”)
- Changing permissions on your filter to add more users
Conclusion
Jira Query Language is an invaluable tool for anyone using Jira. It provides powerful search capabilities that can streamline your workflow, provide valuable insights, and ultimately help you manage your projects more efficiently.
So go ahead, get your hands dirty with JQL. Practice, experiment, and don't be afraid to make mistakes. The more you use JQL, the more comfortable you'll get, and the more powerful your Jira usage will become.
Stay tuned for more Jira Information and remember, being a 'JIRA GURU' is all about continuous learning!
------------
Learn more about Jira, Confluence and Atlassian with Jira Guru
💬 If you have any questions or suggestions for the next topic please leave a comment below 👇
🙌 Please like, and share this article with new beginners
Was this helpful?
Thanks!
Teresa_DevSamurai
3 comments