What is JQL?

A single Jira application may contain millions of issues. So, how do you search through all of them to find the few you’re looking for? The answer is Atlassian’s query language called JQL. A query is a question you ask Jira, such as, “How many bugs did we fix on the website this month?” or “Which issues are currently assigned to members of my team?” JQL (“Jira query language”) is the language you use to ask. It’s also how to determine which issues to show in a filter, board, dashboard, or report.

JQL is super powerful, and you don’t need special coding skills or experience to use it!

JQL Syntax

Once you master the format, JQL queries are easy to write and use. All queries start with a field, followed by an operator (like the equals sign) and one or more values. Here’s an example.

‍

‍

The screenshot shows a simple query: project = Development. This query returns all issues within the Development (DEV) project.

In the query, project is the field, equals is the operator, and Development is the value.

Clauses

You can improve the query by combining multiple search clauses. Try adding “AND” or “OR” between them. For example:

• project = Development AND status = Done

Adding additional clauses with “AND” lowers the scope of the search result from many issues to a few.

• project = Development OR project = Marketing

Adding additional clauses with “OR” expands the search result. Keep adding clauses until the information you’re looking for is returned.

Operators

The above examples use the “equals” operator but there are many more to choose from. Here’s a handy chart of the possibilities.

‍

‍

‍

Auto Complete

As you type a query, Jira will help you format it correctly and suggest fields, operators, and values.

‍

‍

In the example, I typed “status,” and Jira suggested any standard or custom fields containing the term.

‍

‍

After selecting the “Status” field, Jira suggested a list of operators available for the specific field.

‍

‍

After selecting the “equals” operator, Jira suggested that the application’s statuses be in alphabetical order.

When the query is complete, type the enter key to execute the search. If there are no syntax errors, Jira will display a results list. If there are query problems, Jira will alert you with a red message.

‍

‍

In the above example, the status name entered doesn’t match a valid selection in Jira. The status name should be singular, not plural. Simply fix the error and test the query by re-running it.

Tip: Always test queries before saving them or using them in boards, apps, or automations. Ensure the syntax is correct, and sanity check the amount of issues returned. If more issues are returned than expected, you might have a logic error (like using OR instead of AND) or an order of operations error caused by missing or misplaced parenthesis.

‍

JQL Examples

Here are some helpful queries, formats, and functions for Jira Software and Service Management.

Estimation

Jira has two built-in estimation methods. Stories often use story point estimates. Tasks often use time estimates.

Examples

• originalEstimate is not empty
• remainingEstimate > 1d
• timespent > 8h
• "story points" = 2
• "story point estimate" >= 2

Versions

A version is a grouping of issues in a specific release.

Examples

• fixversion = version-name
• fixversion in (version1, version2)
• fixversion is not empty
• fixversion in unreleasedVersions()
• fixversion = earliestUnreleasedVersion()
• fixversion = latestReleasedVersion()
• affectedVersion = version-name

Sprints

A sprint is a time-boxed iteration of rapid work.

Examples

• sprint in futureSprints()
• sprint = sprint-ID
• sprint = sprint-name
• sprint in (sprint1, sprint2, sprint3)
• sprint is empty

Approvals

Approvals in Jira Service Management workflows.

Examples

• approvals = approved()
• approvals = approver("rachel wright")
• approvals = pending()
• approvals = pendingBy("rachel wright")
• approvals = myPendingApproval()

Organizations

Organizations are used to group customers and determine which requests they can view in the JSM customer portal.

Examples

• reporter in organizationMembers(organization-name)
• organizations = organization-name
• organizations in (organization1, organization2) 

Service Level Agreements (SLAs)

SLAs represent a goal or commitment between service providers and customers.

Examples

• SLA-name = breached()
• SLA-name = paused()
• SLA-name = running()
• SLA-name = completed()
• "Time to Resolution" > elapsed("8h")
• "Time to Resolution" > remaining("8h")

Managing Filter Breakage in Salto

Have you ever renamed or removed a custom field or field selection? As you likely know, any filters referencing that information immediately break. Reports, boards, and dashboards either return partial information or don’t display any information at all. Wouldn’t it be nice if you could know the impact of a removal or rename before you did it? With Salto, you can! Simply search for the field or value you want to change, see where that information is used, and update any saved filter JQL. Here’s how to do it.

‍

‍

Let’s say I want to rename a custom field called “Business Owner.” In Salto, simply simply search for that phrase. All the elements found are shown in the light gray sidebar. Expand the “Filter” section to see any impacted saved filters. Then click on a filter to see the details. The filter owner’s name and the impacted JQL query are shown.

With this information, I can alert the owner that an upcoming field rename will break their filter. If I’m feeling especially nice, I can temporarily change the owner to myself in Jira and update the query for them. This experience is much better than making configuration changes and waiting for users to report their views are broken!

Activities to Try

Now it’s your turn! Try out some of the example JQL queries above to see how they work and what you can find. Looking for a harder challenge? Try writing the JQL for the following scenarios:

Ideas

• Find all high-priority bugs reported by the product team last quarter
• Find all unresolved incidents that impact the email service
• Find all user stories in the backlog with a high-effort estimate
• Find all service requests from a specific organization where the “time to resolution” goal was not met

Resources

• Use advanced search with Jira Query Language (JQL) — https://support.atlassian.com/jira-service-management-cloud/docs/use-advanced-search-with-jira-query-language-jql/ 
• JQL operators — https://support.atlassian.com/jira-service-management-cloud/docs/jql-operators