JQL stands for Jira Query Language and is the most powerful and flexible way to search for your issues in Jira. JQL is for everyone: developers, testers, agile project managers, and business users. This blog is intended to be a tutorial for those who have no experience with database queries to those who want faster access to information in Jira. So basically if you work in Jira this blog is for you.

Searching in Jira: how do I start?

The search box

The most simple search feature in Jira is the search box at the top right of your screen.

You can use this search box to:

  • search a particular issue
    JiraKEY-15
  • search on text (searches in issue summary, description and comments)
    atlassian
  • Finally, the field supports Smart Querying
    my open bugs

    This will give you a list with all Bugs that are in the status Open and assigned to you

Search for Issues

You can also search issues from the “Issues” section in the dropdown menu.

search for issues JQL

In the screen that just opened you’ll be able to easily filter issues based on the value(s) of certain fields. A quick example search:

You can filter on any field available in Jira (depending on the selected project(s)).

 

Basic and Advanced Searches

There are two types of searches in Jira: basic and advanced. Basic searches, like the ones above, present you with a set of forms that you can fill in, such as Project name, Issue Type, Status, and Assignee. Basic search can be useful for getting a high-level view of your issues and status.

Now Advanced Searching is where you will get into JQL, using it to form queries. Queries are a series of simple elements strung together to form a more complex question. A query has three basic parts: fields, operators, and values.

  • Field – Fields are different types of information in the system. Jira fields include priority, fixVersion, issue type, etc.
  • Operator – Operators are the heart of the query. They relate the field to the value. Common operators include equals (=), not equals (!=), less than (<), etc.
  • Value – Values are the actual data in the query. They are usually the item for which we are looking.
  • Keyword – Keywords are specific words in the language that have special meaning. In this post we will be focused on AND and OR.

JQL blog_image 1_v2

Important keywords to know

Atlassian has created a JQL reference where you can find all keywords, operators, etc that can be used in JQL. This is your go-to-guide when you want to discover new search capabilities. Here are some of the most common keywords and operators you will use:

AND

This will only return issues that match both clauses (are part of the Collaboration project and have their status set to "In Progress")
project = Collaboration AND status = "In Progress"

OR

Returns all issues from either the Collaboration project or that have their status set to "In Progress".
project = Collaboration OR status = "In Progress"

IS

This will return all issues that have no description.
description IS EMPTY

Operators

!=

status != "To Do"

Returns all issues except for those that have their status set to “To Do”

>=

"Story Points" >= 5

Find all issues that have Story Points which are greater than or equal a given value

Similar

  • > | greater than
  • < | smaller than
  • <= | smaller than or equal

IN

status IN ("To Do", "In Progress", "Closed")

is the same as

status = "To Do" OR status = "In Progress" OR status = "Closed"

Find all issues which are either have the status “To Do”, “In Progress” or “Closed”

Reverse

  • NOT IN

Putting this into practice

Let’s start with a simple example. Say you want to see what bugs your teammate filed within a certain project. You query would be:

reporter = jsmith AND project = Pipeline

Here we used the keyword “AND” to query Jira for tickets reported by John Smith in the project “Pipeline”

Other times you may want to have the query reference a set of items. For instance:

What issues are blocking or critical in Projects A, B, and C?

priority in (Blocker, Critical) AND project in (ProjA, ProjB, ProjC)

The “in” keyword will include any item that matches any item in the list. In the above example it will return all of the blocker and critical bugs in projects A, B, and C.

This is extremely helpful for organizations that have service level agreements (SLA) with their customer base. A JQL query can easily find the issues that are not meeting that SLA.

What issues are unassigned and have not been updated in the last day?
assignee is EMPTY and created < -1d

In this query the “is empty” statement only includes issues where the value of the assignee field is blank. This query also shows how Jira supports relative dates. 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.

Don’t be intimidated by Jira’s Advanced Searching! Jira’s JQL editor makes it easy to learn JQL. The editor uses code that hints as you type. For example, if we want to type the following JQL: project = Pipeline, Jira gives suggestions at each step of the way for each of the three components of our query. Click on “Syntax help” anytime if you get stuck.

Maarten Cautreels, AUG Leader and Community Champion, also contributed his expert advice to this post. Thank you, Maarten!  You can read Maarten’s articles and ask him questions on Atlassian Community.


This is the first of a four-part series aimed at making you a JQL dynamo. Take a read through the next posts in this series:

And, to get even more JQL training, check out our tutorial videos.

Fresh ideas, announcements, and inspiration for your team, delivered weekly.

Subscribe now