Exploring Jira functionality: Making JQL work for you

In project and issue management, Jira creates a valuable repository of information to help managers assess process efficiency and team productivity. However, locating and aggregating that data into a usable format can be labor and time-intensive. That’s why Atlassian created Jira Query Language (JQL), which allows users to conduct simple, quick search queries of the Jira database that filter and return customized results. 

It might sound like complex computing, but JQL is actually quite intuitive. You start by conducting basic searches using dropdown menus that guide query development before beginning to create advanced searches using language and syntax that even non-developers find user-friendly. 

Learning to code individualized search queries unlocks Jira’s capacity to streamline project management and establish efficient workflows for your team. With some practice, you’ll be running Jira queries like a pro.   

Searching in Jira

There are two ways to search Jira: the basic search function and Jira Query Language (JQL). Both methods sort and aggregate information within the Jira platform to deliver the requested data onto a result summary page. 

Jira’s built-in functionality is excellent for a quick search, allowing you to choose the data fields you’re interested in from dropdown menus. It offers additional guidance if you need to implement advanced criteria, like sorting the results by date. 

Here’s an example of the basic search results for issues assigned to Morgan Folsom within the Support project:

You can further refine the results from the search summary page by selecting categories to show or hide, ensuring you only see relevant data.

So, what is JQL? JQL facilitates more user flexibility by taking personalization to another level. Instead of working with the front end of the search function, you can go behind the scenes and define your own filters.

If that sounds intimidating, don’t worry. Atlassian makes JQL advanced search functionality easier by including an auto-complete feature within the search box that offers suggestions to guide your coding.

If you’re interested in Jira JQL, you’ll benefit from mastering the basic search operation first. Once you’re proficient, start getting a feel for JQL by building your searches in basic and then clicking the “Switch to JQL” button next to the search bar. This feature will translate your basic search into JQL so you can see your query’s back-end programming. 

In the case of the above basic search, the JQL version looks like this:

Not so intimidating, is it? Once you become a Jira search pro, you can save and share your filters with others and learn to leverage the databases created in Jira and Confluence further.  

Jira JQL: Where to start

As you jump back and forth between basic and JQL, you’ll notice that each search request follows a similar format. The key to coding an advanced search query is understanding its sequence and terms.

Queries

Advanced searches in JQL are a series of simple elements strung together to form a query. Each query comprises three fundamental parts: fields, operators, and values. For more complex searches, you can add an additional element (the keyword) that refines the output. 

(Source: Atlassian)

Fields

The field term defines the type of information you wish to locate. In Jira, fields include:

• Priority

• Project

• Issue type

• Status

• Epic tag

Which field you use to create a query depends on your Jira configuration and the fields available within your instance.

Operators

The operator term in a JQL query establishes the relationship between the field and the values you want the search to return. The most common operators used in query development are:

• Equals “=”

• Not equals “!=”

• Greater than “>”

• Less than “<”

• Greater than or equal to “>=”

• Less than or equal to “<=”

Values

A query’s value is the data you’re actually looking for in the search. In the earlier example, JQL requested a list of issues from the Support project assigned to Morgan Folsom, meaning the query’s values were “SUP” (the project’s designation in Jira) and “morgan” (her Jira username). 

Keywords

Keywords are specialized terms within JQL that further refine a query. For example, the keyword “AND” from the exemplar will only return data that matches both the project and assignee clauses. 

“OR” is another common keyword. A query using this term:

project = Collaboration OR status = "In Progress"

will return issues from the “Collaboration” project or those labeled with the “In Progress” status. 

Other common keywords include the following:

• Is

• Not

• Empty

• Null

• Order By

You can even specify the display order by using keywords “asc” and “desc” to override the data field’s default priority and list results in ascending or descending order.  

The breadth of terminology may seem like a lot to take in all at once, but you don’t have to. Atlassian has created a handy JQL Cheat Sheet and product guide for you to use as a reference. 

The syntax of JQL

JQL’s syntax is very straightforward. The field+operator+value format allows users to define a query logically. For example, if you wanted to find all the issues logged in a project that’s currently in progress, the JQL query would look like:

(Source: DevSamurai)

The code tells Jira that you’re interested in 

• Data contained within the “status” field

• Defined by the operator “=” as being equal to

• “In Progress,” which is the status value you’re looking for  

Again, don’t stress over syntax. Atlassian offers predictive text to support learning JQL by offering suggestions for each element of your query. If you’re stuck, click “Syntax Help” in the JQL menu or the question mark next to the text search box for additional support. 

Tips to make the most of Jira Query Language

As simple as JQL is, there are still some tricks of the trade you should learn to speed up your searches and optimize the quality of your results.

Best practices

When creating a filter, you should always:

• Define the goal: Before beginning to code, identify the precise data you want to find. Clarifying your goal makes choosing the correct fields, operators, and values easier.

• Include the correct fields and operators: Double-check that your fields and operators are compatible and will yield the desired results.

• Validate your results: Test your query regularly to ensure it delivers the desired outcome.

• Save, reuse, and share: Useful queries are time savers, so save them for future use. Saved filters can also be shared among team members, improving workflows and boosting productivity. 

Practices to avoid

• Mismatched fields and operators: Operators and fields don’t always work together, so double-check their compatibility. For example, although “=” is the appropriate operator for most fields, when searching the “Labels” field, use the operator “IN” instead.

• Non-existing fields: Ensure the field you’re searching for exists in the database and that you’re using the correct spelling. A mistake will return either an error message or incorrect results. 

• Forgetting quote marks: When searching for text values, such as issue names or labels, enclose the term in double quotation marks, like this: summary = “Bug fix”

• Failing to consider field types: Fields are compatible with multiple values, like text, numbers, and dates. When querying a specific field, use the proper data type and corresponding operator. 

Saving filters

If you use the same filter regularly, save it by clicking the “Save As” button at the top left of your screen and giving it an easily identifiable name. You can even define who can search for and use your filter by updating the sharing settings.

Filter subscriptions

Keep individual teammates or groups apprised of specific search results (e.g., a weekly update of missed due dates) by creating a filter subscription to send them updates based on a saved query. Test your query thoroughly before use to ensure you don’t blow up your colleagues’s inboxes with unnecessary emails.  

Use of filters on Jira dashboards

Along with saving them for future use, the basic search function allows you to view saved searches in various areas, including your Confluence or Jira dashboard, Agile boards, and other locations, using the “FILTER” keyword. 

To view multiple filters at once, you’ll need to click “Add Gadget” from your Jira dashboard and select “Filter Results” to choose from existing saved queries.

Make the most of JQL with Tempo

JQL functionality extends beyond Jira software to integrate seamlessly with Tempo’s resource and time management platform, Timesheets. JQL advanced functions can search for a range of data, from Tempo Teams and Accounts to internal issues. You can even use JQL to automate custom reporting for your team. Take advantage of the full scope of JQL’s capabilities by including data generated by Tempo in your query development.