JQL - Jira Query Language

Introduction to JQL

JQL (Jira Query Language) (J Query Language) is a powerful query language designed by Atlassian for searching and filtering issues in Jira, a popular project management tool. Using JQL allows users to search issues by specific fields, conditions, and other criteria.

With JQL, you can construct queries to manage tasks, monitor projects, and generate custom views for teams. This guide will provide an overview of syntax, query examples, and tips to help you master JQL.

Understanding JQL Syntax

JQL queries consist of field, operator, and value components. You can combine these using logical operators.

1. Basic Syntax

JQL queries consist of field, operator, and value components. You can combine these using logical operators.

General Structure

field operator value

Logical Operators

AND: Combines multiple conditions; all must be true.

project = "PROJ" AND status = "Open"

OR: Returns issues matching either condition.

status = "Open" OR status = "In Progress"

NOT: Excludes conditions.

NOT status = "Closed"

2. Fields

Fields are the attributes of issues in Jira, like status, assignee, priority, etc.

Common Fields:

Project: project
Status: status
Assignee: assignee
Reporter: reporter
Priority: priority
Resolution: resolution
Issue Type: issuetype
Created Date: created
Due Date: duedate
Summary: summary

Example:

project = "PROJ" AND assignee = "username"

3. Operators

Operators define how conditions are compared.

Operator	Description	Example
=	Equals	`status = "Open"`
!=	Not equal to	`status != "Closed"`
>	Greater than	`duedate > "2023-12-31"`
<	Less than	`duedate < "2023-12-31"`
IN	Matches any value in a list	`priority IN (High, Critical)`
NOT IN	Excludes values in a list	`priority NOT IN (Low, Medium)`
~	Text search (case-insensitive)	`summary ~ "login"`
!~	Excludes text match summary	`!~ "login"`

4. Functions

JQL has predefined functions to make searches dynamic.

Function	Description	Example
`currentUser()`	Refers to the logged-in user.	`assignee = currentUser()`
`now()`	Represents the current date and time.	`created >= now() - 7d`
`membersOf("group")`	Matches members of a specific group.	`assignee in membersOf("dev-team")`
`openSprints()`	Finds issues in currently open sprints.	`sprint in openSprints()`
`resolved()`	Finds issues that are resolved.	`resolution = Resolved`
`recentlyUpdated()`	Matches issues updated recently.	`updated >= -1d`

5. Combining Queries with Logical Operators

In JQL, logical operators like AND, OR, and NOT can combine multiple conditions to create complex queries.

Using AND

The AND operator ensures that all conditions must be true for an issue to match the query.

project = "PROJ" AND status = "Open"

Using OR

The OR operator returns issues that meet at least one of the conditions specified.

status = "Open" OR status = "In Progress"

Using NOT

The NOT operator excludes issues that meet the condition specified.

NOT status = "Closed"

Combining Multiple Logical Operators

Logical operators can be combined with parentheses to create even more refined queries.

assignee = currentUser() AND (priority = High OR priority = Critical) AND resolution = Unresolved

6. Advanced Search Examples

Search by Date

created >= "2023-12-01" AND created <= "2023-12-15"

Search by Multiple Status

status in (Open, "In Progress", "Reopened")

Search by Multiple Projects

project in (PROJ1, PROJ2, PROJ3)

7. Working with Jira Dashboards and Saved Filters

Once you’ve created a useful query, you can:

Save the search: Use the “Save as” button after running a query.
Use this filter in Jira Dashboards: Visualize data using gadgets like pie charts or issue breakdowns.

8. Tips for Effective JQL Queries

Start simple: Test a query in parts to ensure it works before building on it.
Use parentheses for clarity to organize logical combinations.
Refer to fields by their exact names in Jira.
Leverage autocomplete suggestions when writing JQL in the search bar.
Test filters to ensure expected results.

9. Error Handling

If you get unexpected results:

Check for typos in field names or operators.
Ensure your permissions allow viewing the issues you’re querying.
Verify date formats (Jira uses yyyy-MM-dd by default).

10. Resources for Learning More

Atlassian JQL Documentation
Practice with the JQL Search Bar in Jira itself.
Explore examples on community forums or your team's best practices.

JQL: Jira Query Language