Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 29 ยท Boards, Sprints and Reporting

JQL and Filters

Learn JQL, the Jira Query Language: fields, operators, functions like currentUser() and openSprints(), ORDER BY and saved filters, with a runnable mini evaluator.

A real project quickly holds thousands of issues. Clicking through boards will not answer questions such as "Which high-priority bugs are still open and assigned to me?" or "What did we finish last sprint?" For that, Jira has a search language called JQL, the Jira Query Language. A JQL query is a line of text that describes a set of issues. Jira returns every issue that matches.

JQL is also what powers the rest of Jira: a board is a saved query, a dashboard gadget is a saved query, and an automation rule often starts with a query. Learn JQL once and you can control all of them. The real search engine runs only inside Jira, so the queries below are shown as read-only code. The runnable examples are stand-ins: a small evaluator written in JavaScript that understands a subset of JQL over sample issues. It is not Jira's parser, and real JQL has many more fields and functions.

Anatomy of a query

Field What to look at, like status.
Operator How to compare: =, !=, in, ~.
Value What to compare against.
AND / OR Combine several clauses.

Example: project = SHOP AND status = "In Progress"

1 / 2

Writing your first queries

A JQL clause has three parts: a field, an operator and a value.

TEXT
project = SHOP
status = "In Progress"
priority = High
assignee = currentUser()

Clauses are joined with AND and OR, and parentheses control grouping. AND is stronger than OR, so add parentheses whenever you mix them:

TEXT
project = SHOP AND (priority = High OR priority = Highest) AND status != Done

Values that contain spaces are quoted: status = "In Review". Field names and keywords are not case sensitive, and most text values compare without regard to case.

The most useful operators

Operator Meaning Example
= and != Equals, not equals type = Bug
>, >=, <, <= Order comparisons (numbers, dates, priority) priority >= High
IN, NOT IN Matches any value of a list status IN ("To Do", "In Progress")
~ Contains text (text fields such as summary) summary ~ "login"
IS EMPTY, IS NOT EMPTY The field has no value, or has one assignee IS EMPTY

For a multi-valued field such as labels, labels = checkout means "has the label checkout". To find issues with no label at all, write labels IS EMPTY.

Use status != Done carefully. It also returns issues with other finished statuses if you have them. To say "not finished" regardless of status names, use the field statusCategory != Done.

Functions

Functions are written with parentheses and compute a value when the query runs. They let a saved query stay correct as time and people change. The ones you will meet first:

  • currentUser(): whoever is running the search. assignee = currentUser() shows each person their own work.
  • openSprints(): the sprints that are currently active. sprint in openSprints() is the query behind most "current sprint" views.
  • startOfWeek(), startOfDay(), now(): dates relative to today, used as in created >= startOfWeek().
  • membersOf("group"): all users of a group, for example assignee in membersOf("qa-team").

Relative date values such as -7d mean "seven days ago" and are very common: created >= -7d means created in the last week, and resolved >= -14d means finished in the last two weeks.

ORDER BY

ORDER BY goes at the very end and sorts the result. You can name several fields, each with ASC or DESC:

TEXT
project = SHOP AND statusCategory != Done ORDER BY priority DESC, created ASC

That query lists everything unfinished, most urgent first, and oldest first within the same priority. Without ORDER BY, Jira orders by its own default, so add one whenever order matters. Sorting by Rank shows the backlog order (see Boards, Backlogs and Sprints in Jira).

A mini JQL evaluator

Below is a compact stand-in with a tokenizer, a recursive-descent parser and an evaluator. It supports =, !=, >, >=, <, <=, ~, IN, NOT IN, IS EMPTY, IS NOT EMPTY, AND, OR, parentheses, currentUser(), openSprints() and ORDER BY. Priorities compare by rank, as in Jira. Run it, then change the queries at the bottom to see how clauses change the result.

JS A mini JQL evaluator (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice what the evaluator does not do: it does not know about projects, users who do not exist, or custom fields, and it has no date functions. Real Jira validates every field name and tells you when a query is wrong, usually with a red message under the search box.

Filters and where they are used

When a query is useful, save it as a filter. A saved filter has a name, an owner and sharing: private, shared with a project, a group or everyone. Saving a filter gives you three things:

  1. A stable link that updates as issues change.
  2. A source for other features: a board is built on a filter, a dashboard gadget (see Jira Reports and Dashboards) shows a filter's results, and a subscription can email you a filter every morning.
  3. A way to lock down logic. If ten gadgets use one filter, you fix the query once.

A few filters worth having in almost every project:

TEXT
-- My open work
assignee = currentUser() AND statusCategory != Done ORDER BY priority DESC

-- Unassigned bugs, newest first
project = SHOP AND type = Bug AND assignee IS EMPTY AND statusCategory != Done ORDER BY created DESC

-- Done in the last two weeks
project = SHOP AND statusCategory = Done AND resolved >= -14d

The stand-in below shows the idea of "a board is a filter plus columns": one predicate function picks the issues, and a column map groups them by status. Change the predicate and the board changes, without touching a single issue.

JS A board is a filter plus columns

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Remember that changing a shared filter changes every board and gadget built on it. Treat filters used by boards like configuration: change them with care and tell your team.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which query returns issues assigned to whoever runs the search?

    currentUser() is a JQL function that returns the user running the query, so the same saved filter works for everyone.
  2. 2. What does the query: type = Bug OR type = Task AND priority = High return, in JQL's evaluation order?

    AND is evaluated before OR, so this means type = Bug OR (type = Task AND priority = High). Add parentheses to make your intent clear.
  3. 3. Where does ORDER BY go in a JQL query?

    ORDER BY always closes the query and can list several fields with ASC or DESC.
  4. 4. Why is a board's filter worth treating like configuration?

    Boards and gadgets read from saved filters. Edit one and every place that uses it updates.

Summary

  • JQL is Jira's search language: field, operator, value, joined by AND and OR.
  • Common operators are =, !=, comparisons, IN, ~ and IS EMPTY; add parentheses when you mix AND with OR.
  • Functions such as currentUser() and openSprints() keep saved queries current; ORDER BY goes last.
  • Saved filters power boards, dashboard gadgets, subscriptions and automation.
  • The JavaScript evaluator is a stand-in for a subset of JQL; Jira's own engine has many more fields and checks.

Next, turn filters into charts: Jira Reports and Dashboards.