JQL Tips: Your new friend in searching Jira 4

Being one of the developers working on JQL for Jira 4, I have become very familiar with the language and I’m really excited about the feature getting more and more use as users discover its true power. So in order to help you make these discoveries, I’ve written a few tips on some of the finer points of the language that I make use of every day (and you probably should too!).

1. It’s a really fast way to search
When thinking of something they want a program to do, most computer users can probably type the instructions faster than they can click the relevant interface elements. This works particularly well when the instructions to type are in the form of an intuitive language.
The reason we designed (and named) JQL the way we did was because we knew it would greatly benefit users to have something similar to a common query language that they probably already know (SQL). It’s also so simple that you can literally create the query as you think of it – no more searching a potentially large list of searchers in the filter form for the field you want to set. Using the Autocomplete feature speeds you up further, as you don’t even need to type the full name of fields or values to complete your query. And by specifying your results ordering in the query, as opposed to clicking on column headings, you can find the most relevant issues to your search even faster.
2. The ‘text’ clause
The idea for this clause came late in the piece, but it’s been one of the most useful clauses in my daily usage of JQL. Often when supporting our customers, I have to search our public Jira instance for issues that refer to a specific exception or log message, to see if it has previously been raised as a bug. But, as much as we’d like them to be, our Jira issues aren’t all organised neatly. The important details of an issue could be split across multiple fields: summary, description, environment, comments, or even a custom text field. To query them all for the possibility of containing a search string, you would need a query like this: “summary ~ Exception OR description ~ Exception OR customTextField ~ Exception OR …”
This approach is flawed for a number of reasons. Firstly, it’s very long-winded. Secondly, we have to explicitly list all the text fields we want to search – if we save this search and run it again later, it won’t include any new text fields added since creation. Thirdly, retyping “Exception” for each clause is bound to cause some typos.
Enter the ‘text’ clause. This clause will implicitly search across all the system text fields and custom text fields, returning any issues that match the input in at least one of the fields. Our long-winded query (too long for me even to copy-paste here!) becomes a very succinct “text ~ Exception”. Plus, there’s no way to achieve the same search through the old-style filter form, as you can’t create a search with “OR” semantics. The ‘text’ clause is yet another powerful reason to use JQL.
3. The ‘watched issues’ function
Prior to Jira 4, the only view you could have on your watched issues was from a portlet on your dashboard, or from the Watched Issues page in your profile. These views couldn’t be customised or ordered in any way. But now with the advent of the ‘watchedIssues()’ JQL function, you can specify these issues as part of a more complex search to get the exact data you need.
For example, each day I need to check on the issues I am watching in our public Jira instance, but I am only interested in the unresolved issues which have either been updated in the last week or are of critical priority. This query is quite simple to construct using JQL: “issue in watchedIssues() AND resolution = unresolved AND (priority = Critical OR updated >= “-1w”)”. I have even saved this search and use it in a gadget on my dashboard so I have easy access to the results.