What is a Jira JQL?

JQL stands for Jira Query Language. It's the SQL-like query syntax used to search and filter issues in Jira - 'project = WEB AND status = Open AND assignee = currentUser()'. JQL powers saved filters, dashboard gadgets, agile boards, automation conditions, and the issue search bar. Learning JQL is the single highest-leverage Jira skill.

Category: Querying & Reporting Also called: Jira Query Language

Short definition

JQL stands for Jira Query Language. It's the SQL-like query syntax used to search and filter issues in Jira - 'project = WEB AND status = Open AND assignee = currentUser()'. JQL powers saved filters, dashboard gadgets, agile boards, automation conditions, and the issue search bar. Learning JQL is the single highest-leverage Jira skill.

Anatomy of a JQL query

JQL queries are built from three things:

  • Fields - any built-in field (project, status, assignee, priority) or custom field (by name in quotes or by cf[id]).
  • Operators - =, !=, >, <, >=, <=, IN, NOT IN, IS, IS NOT, ~ (text match), !~, WAS, WAS NOT, CHANGED, plus the boolean connectives AND, OR, NOT.
  • Values - literals, lists, or function calls.

Example combining all three:

project IN (WEB, MOBILE)
  AND status WAS "In Progress"
  AND "Story Points" >= 5
  AND assignee = currentUser()
  AND created >= -30d
ORDER BY priority DESC, updated DESC

Historic operators - WAS, CHANGED, DURING

JQL is one of the only systems where you can query historic field values, not just current ones.

  • status WAS "In Progress" - true if the issue has ever been In Progress.
  • status CHANGED FROM "In Progress" TO "Done" AFTER -7d - state transitions in the last 7 days.
  • assignee CHANGED DURING ("2026-05-01", "2026-05-21") - assignee changes inside a date range.

These are essential for SLA reports, cycle-time queries, and audit reports - none of which can be expressed on the current state alone.

Date math

Dates support relative arithmetic:

  • -7d, -2w, -1M, -1y - relative offsets.
  • startOfDay(), endOfWeek("+1w") - boundaries.
  • "2026-05-21" - absolute ISO dates.

updated >= -7d is “updated in the last 7 days.” This is the form to prefer over absolute dates in saved filters, so the filter stays correct without manual updates.

ORDER BY

JQL supports ORDER BY (one or more fields, ASC/DESC). It does not support GROUP BY, SELECT, or aggregation. Aggregations happen in dashboard gadgets, the Issue Statistics report, and external BI tools that consume Jira’s REST API - not in JQL itself.

Where JQL shows up

The same JQL syntax drives:

  • The issue search bar.
  • Saved filters (which back agile boards and dashboards).
  • Automation rule conditions (JQL: status = Done AND fixVersion = 4.12.0).
  • Project board filter queries.
  • REST API search (/rest/api/2/search?jql=...).

Investing time in JQL pays back in every one of these contexts.

Common questions

What is JQL in Jira?

JQL stands for Jira Query Language. It's the SQL-like query syntax used to search and filter issues in Jira - 'project = WEB AND status = Open AND assignee = currentUser()'. JQL powers saved filters, dashboard gadgets, agile boards, automation conditions, and the issue search bar. Learning JQL is the single highest-leverage Jira skill.

Is JQL the same as SQL?

No. JQL is SQL-like in syntax but it doesn't query a database - it queries Jira's issue index. There's no JOIN, no GROUP BY, no aggregation. Every JQL query returns a list of issues; reporting on those issues happens through dashboard gadgets and reports, not through JQL itself.

How do I search by custom field in JQL?

Two ways. By name: `"Severity" = "S1 - Critical"` (quotes if the name has spaces). By internal ID: `cf[12345] = "S1 - Critical"`. The ID form survives field renames - good for saved filters that need to be stable across configuration changes.

What are JQL functions?

JQL functions are built-in helpers that compute dynamic values. Common ones: `currentUser()`, `now()`, `startOfDay()`, `endOfWeek()`, `linkedIssues(KEY)`, `openSprints()`, `unreleasedVersions()`, `membersOf('group-name')`. Functions let one saved filter work for every user or every sprint without manual updates.

← Back to the full Jira glossary