JQL, the Jira Query Language, is how you write precise searches in Jira's advanced search. Each clause is a field, an operator and a value, such as reporter = currentUser(), and you join clauses with AND or OR, then add ORDER BY to sort the results in ascending or descending order.
The trap worth knowing first: not equals and NOT IN skip work items where the field is empty. Atlassian's own example is that component != fred only returns items that have a component and it isn't fred. To include items with no component, you have to write component != fred or component is empty.
How a JQL query is put together
An operator compares the value of a field on its left with one or more values, or functions, on its right, and only true results come back. Some operators can take the NOT keyword. Atlassian is clear that JQL is for everyone, from developers and testers to agile project managers and business users, but you do need to learn the structure to use it.
- Start with a field, such as assignee, reporter, status, priority, votes or duedate.
- Add an operator, such as =, !=, IN or ~.
- Add a value or a function, such as currentUser() or now().
- Join more clauses with AND or OR, for example reporter = currentUser() and assignee != currentUser().
- Finish with ORDER BY if you want the results sorted.
Jira is renaming issue to work item and project to space. Atlassian says existing queries don't change, but some JQL using the new terms may not work yet, so if a query fails, try the old term.
JQL operators with examples
| Operator | Finds work items where the field | Example |
|---|---|---|
| = | Exactly matches the value. Not for text fields | reporter = "abcde-12345-fedcba" |
| != | Doesn't match, and has a value | assignee != abcde-12345-fedcba or assignee is empty |
| > >= < <= | Is above or below the value. Only for fields that support ordering, such as dates and versions | votes >= 4 |
| IN | Matches any value in a list | reporter in (jsmith,jbrown,jjones) |
| NOT IN | Matches none of the list, and has a value | assignee not in (Jack,Jill,John) or assignee is empty |
| ~ | Contains the text, exactly or as a fuzzy match | summary ~ win |
| !~ | Doesn't contain the text | summary !~ run |
| IS / IS NOT | Is empty, or has a value. Only works with EMPTY or NULL | fixVersion is empty |
| WAS / WAS NOT | Has or once had the value, or never had it | status WAS "In Progress" |
| CHANGED | Has had its value changed | status CHANGED FROM "In Progress" TO "Open" |
Using IN is the same as writing several = clauses joined with OR, just shorter. NOT IN is the same as several != clauses joined with AND. Typing field != value is the same as NOT field = value.
Searching text fields
The = and != operators don't work on text fields. Use ~ and !~ instead. The special field text, as in text ~ "some words", searches a work item's Summary, Description, Environment and Comments, plus every text custom field. If you have a lot of text custom fields, Atlassian suggests searching specific fields to speed things up, for example Summary ~ "some words" OR Description ~ "some words".
A few examples from the operator guide: summary ~ win finds the word win and simple derivatives like wins, while summary ~ "win*" is a wild-card match. To match an exact phrase, escape the inner quote marks. One warning on !~: if a work item has more than one comment, the operator fails, because all comments are included in the search.
Dates, numbers and functions
- duedate < now() and resolution is empty finds overdue work that's still open.
- created >= "-5d" finds work items created in the last five days.
- updated <= "-4w 2d" finds work items that haven't been updated in the past month.
- priority > normal finds anything with a higher priority than Normal.
- votes > 4 finds work items with more than four votes.
Searching a field's history
WAS, WAS IN, WAS NOT, WAS NOT IN and CHANGED look at what a field used to be, not only what's there now. They only work with the Assignee, Fix Version, Priority, Reporter, Resolution and Status fields. You can narrow them with predicates such as BY, BEFORE, AFTER and DURING.
- status WAS "Resolved" BY jsmith BEFORE "2019/02/02" finds items Joe Smith resolved before 2 February.
- status WAS IN ("Resolved","In Progress") finds items that have or once had either status.
- status WAS NOT IN ("Resolved","In Progress") finds items that never had either.
- priority CHANGED BY freddo BEFORE endOfWeek() AFTER startOfWeek() finds priority changes one user made this week.
WAS matches the value name that was set up in your system at the time of the change, and also its ID, so it matches 4 as well as Resolved. If a work item has more than 10,000 changes, WAS only searches the most recent ones. For older history, Atlassian points you to the work item view or a data export.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
My verdict on Jira JQL
Learn five operators first: =, !=, IN, ~ and IS EMPTY. That covers most searches a busy team runs. Then build the habit of adding or field is empty whenever you use != or NOT IN, because that's where saved filters quietly miss work. Statuses in your queries come from your Jira workflow, and the type field depends on how your Jira issue types are set up, so check both when a query returns nothing.
A good query saves your team a meeting. Showing teams where AI and automation save the most time is the work I do. I run AI training and workshops for teams, and help businesses with AI and workflow enablement, AI automation and GEO, which is about getting your business seen and cited in AI answers. Most of that work is with SaaS marketing teams and small businesses. Here's how we can work together.
Frequently asked questions
What does JQL stand for in Jira?
Jira Query Language. It's the structured search language used in Jira's advanced search.
Why does my JQL != query miss some work items?
The != operator won't match a field that has no value. Add or field is empty, for example assignee != abcde-12345-fedcba or assignee is empty.
Can I use = to search text in JQL?
No. The = operator can't be used with text fields. Use the ~ operator, which matches exact or fuzzy text.
Which fields work with the JQL WAS operator?
Assignee, Fix Version, Priority, Reporter, Resolution and Status only.
How do I sort JQL results?
Add an ORDER BY clause to display the results in ascending or descending order.
