Quickstart Guide to Jira Query Language JQL for Beginners


Following keywords are available to use in Jira – AND, OR, NOT, EMPTY, NULL, ORDER BY. The entire list of operators along with their usage can be found here. These are nothing but a medium to compare the fields & corresponding values. Since the purpose of JQL queries is to retrieve information from Jira based on advanced user needs, it needs to follow a certain pattern or structure.

Well, now if your JQL is complex it will say something like ‘This JQL query is complex & cannot be converted into a basic search’. For example, the default priority field has possible values of Blocker, Critical, jql query Major, Minor, Trivial. Similarly, assignee field will have the users as possible values. Well, as it turns out – the above logic also applies to the popular project management tool, Atlassian Jira.

Only show your bugs in a bug fix team

JQL, short for Jira Query Language, is the preeminent and exceptionally versatile method for locating issues within the Jira platform. JQL caters to a diverse user base, encompassing developers, testers, agile project managers, and business stakeholders. Its utility extends beyond mere issue retrieval; a proficient mastery of JQL empowers users to conduct nuanced searches and queries of Jira issues.

jira query language cheat sheet

This function will only work when an issue is selected, and refers to the reporter that appears in the current issue. You can use a range of functions to write queries which involve date and time. You may use operators such as AND/OR to create larger and more complex AQL expressions. Excludes values which match with any subset of input in the query.

JQL search in Jira Service Management

Please note that the field list above is the built-in list in JIRA. If you have installed JIRA extensions, some extensions may customize certain fields. The “WAS” operator is used to find issues that currently have or previously had the specified value for the specified field.

  • The connectedTickets() function does not work with the Assets macro in Confluence.
  • The list of JQL keywords is actually small & pretty much self-explanatory.
  • Easiest way to navigate to the issue navigator is by using the ‘View all issues’ menu item available under the ‘Filters’ dropdown in the top navigation of Jira.

It goes beyond the basic search & lets you dig deeper into the data with advanced features such as operators, functions, customizations & more. We also have a downloadable cheat sheet to keep close on hand as you perform searches with JQL. Copy and paste fields, operators and functions into the Jira search bar, as well as learn more advanced queries. Using this, you can filter the outbound referenced objects further by providing the Reference Type as a single or multiple value(s). Using this, you can filter the inbound referenced objects further by providing the Reference Type as a single or multiple value(s). Reference functions are functions that take two arguments – AQL and/or a reference-type argument.

Instantly Generate JQL

Will return objects which have outbound referenced objects of Employees and only for those Employees objects whose Reference Type is “Location”. Will return objects which have inbound referenced objects of “File System” and only for those File System objects whose Reference Type is “Depends”. The dot operator here navigates to the referenced object Office in the attribute Country and compares Office with the value Stockholm. Instead of the objectId, you can always use the Key attribute on any object type to search for a particular object. You can limit the search to the object, e.g. “object having inboundReferences()” will search all objects having any inbound references to it. This basic AQL query would return all objects for which the Owner is “Ted Anderson”.

jira query language cheat sheet

The value -1d evaluates to 1 day behind the current date when the query is run. As a result, the above query will return all issues that do not have an assignee that are at least one day old. Filter objects based on the object type specified by the ID and its children. Filter objects based on the object type specified by the Name and its children. If the name contains spaces, make sure you enclose it within a pair of double quotes.

Functions in Jira Query Language

These features help you get more out of the tool than to write the same queries repetitively. We also discussed the importance of using parentheses for complex queries and leveraging functions to enhance your jql queries further. Having a JQL cheat sheet can be incredibly helpful for quick references. Download our comprehensive PDF cheat sheet below and keep it handy.

Note the quotations around “Ted Anderson”, since there is a space in the value name. AQL can be used in the Advanced AQL search, or within an Assets object custom field. Do thought experiments & try to guess what a Scrum master might ask from you as opposed to a project manager who is managing 3 different projects. This list does not end here, but it should definitely give you an idea into the depth of function availability for advanced search in Jira. Tip – One easy way to see the limitations of basic search is to try & switch to the Basic search from JQL search. Remember how Jira itself converted basic search into the JQL query?

We noted the convenience of natural language query builders while acknowledging the limitations and ongoing need for human oversight. Even as AI evolves, understanding and verifying JQL queries will remain a valuable skill, especially in complex and highly regulated environments. Here are some practical tips to help you enhance your Jira advanced search abilities.

jira query language cheat sheet

First, you should break down your complex query into several individual query conditions. Start by writing the JQL for each query condition separately, and then try combining them together. To perform a more complex query, you can link clauses together with keywords. @Andrei Pisklenov _Actonic_, thank you for sharing this post! This is really helpful for new Jira users who want to learn about Jira’s JQL search capabilities.

Select all issues you are interested in

When constructing your JQL query, it’s important to tell Jira where it should search for issues by including or excluding specific projects or boards. In Basic mode, you can combine search criteria by selecting different options for the field in order to find issue lists. To meet user expectations, Atlassian Marketplace offers some additional apps with JQL functions. With ScriptRunner you can also not only use more JQL values but create your own as well. Actonic has also developed an app called Power JQL, with additional JQL functions to be used for the extended search. This function is used to return objects (and their children) of a specific object type.

jira query language cheat sheet


Leave a Reply

Your email address will not be published. Required fields are marked *