A Quick Introduction to Using JQL with Jira

JQL, Jira Query Language. This is a quick intro to the power users approach to searching for issues in Jira. In this post we'll introduce you to the JQL basics and then in the next posts we'll start seeing just how powerful JQL is by looking at some specific use cases.

To start using the JQL search feature in Jira you can just search for text here…

Then you can switch to JQL mode by clicking on this link..

If you haven't used JQL before this will expose you to your first JQL statement that looks something like this.

Where the format or syntax all boils down to three parts:

You can think of the three parts as

field: where we're looking for it
operator: how we're looking for it
value: what we're looking for

If you want to search the 'summary' filed then type 'summary', “contains" this word

Or you could go broader and search all text fields with:

“Text" is a special keyword that tells Jira to search the summary, description, environment and comments text fields. It'll also search any 'text' based custom fields you might have. If you want to be more specific then you'd stick to searching with the specific field names. For example:

You can use “quotes" to search for phrases, ? for single chars and * to match many chars.

When it comes to searching text fields you have a few 'operators' you can use.

The tilde character used as the operator means search fields “containing" a value. Alternatively we could go with “!~" which means search where a field “does not contain" a value. For example:

Note this query is returning issues for ALL projects at the moment. Now is a good point to introduce the AND conditions. You can combine expressions with the logical operators AND and OR.

Perhaps you're only looking for issues without 'logout' in the summary but only in the ATC project. So we use AND

Note that because we're interested in a specific value we're using the 'equals' operator. Text fields we use '~' and fields with lists we select from we use the '=' operator.

However, we can take things a little further if we want to search based on a list of values. For example if you want to search across multiple projects use the 'in' operator and a list of values

Folding in another condition with the AND operator we might end up with something like:

We can take things even further and use “OR" too with something like…

Slightly more complex logic but you can start to see the power of JQL with this sort of statement. We're searching across two projects (ATC and DX) and we're looking for summaries that 'contain' either the word 'new' or the word 'newish'.

Three common 'fields' to search with are 'status', 'priority' and issue type

For these fields you'll find this JQL works

status = “To Do" and issueType = “Story"
status = “To Do" and issueType = “Story" and priority in (“High", “Medium")

Again if you have a range of values you can replace = with the 'in' operator …

And extending further by combining expressions

Finally if you're already familiar with the JQL basics then these TWO operators might be new to you 'WAS' and 'CHANGED'. Instead of using equals …

You might decide to use the 'was' operator

This covers issues currently in To Do and issues that were in a To Do state. You can use the history to validate what's being picked up here.

Take another more useful example….

This query is telling us about stories that have been worked on previously and have now gone back to a to do state

Another approach to this is the 'Changed' operator…

or going even further…

We've only scratched the surface of JQL here. Already you can see how much more powerful this is over the 'basic' search mode.

More JQL tips and tricks to follow soon.