Jira Jql

Jira Query Language (JQL) — Expert Reference

JQL is Atlassian's structured query language for searching Jira issues (now called "work items"). Every clause is Field + Operator + Value, chained with keywords.

Use this skill when:

• The user asks for help writing or debugging a JQL query
• They need to find issues across projects, sprints, versions, components
• They want to use history operators (WAS, CHANGED) for trend/sprint analysis
• Performance optimization or saved filter design is needed
• They're building automation rules, REST API calls, or dashboard gadgets with JQL

---

1. Core Syntax

field OPERATOR value [AND|OR field OPERATOR value ...] [ORDER BY field [ASC|DESC]]

Operators

| Operator | Meaning | Example | |----------|---------|---------| | =, != | Equals, not equals | assignee = currentUser() | | >, =, = -7d | | IN, NOT IN | Set membership | status IN ("To Do", "In Progress") | | IS, IS NOT | Null check — only with EMPTY or NULL | assignee IS EMPTY | | ~, !~ | Contains (text search) | summary ~ "login*" | | WAS, WAS NOT | Historical value | assignee WAS "jsmith" | | WAS IN, WAS NOT IN | Historical set | fixVersion WAS IN ("Sprint 1", "Sprint 2") | | CHANGED | Field transition | status CHANGED FROM "Open" TO "Done" |

Keywords

| Keyword | Purpose | |---------|---------| | AND | Both conditions must be true (binds tighter than OR) | | OR | At least one condition must be true | | NOT | Negates a clause | | ORDER BY | Sorting — add ASC or DESC (default ASC) | | EMPTY / NULL | Used with IS / IS NOT |

Precedence

AND binds tighter than OR. A OR B AND C = A OR (B AND C). Always parenthesize OR groups:

-- Correct
(project = A OR project = B) AND status = Open

-- Wrong — reads as project = A OR (project = B AND status = Open)
project = A OR project = B AND status = Open

---

2. Available Fields (System)

Common indexed fields that JQL accepts:

project, issuetype, status, assignee, reporter, creator, priority, resolution, resolutiondate, created, updated, duedate, fixVersion, affectedVersion, component, labels, sprint, votes, watchers, workRatio, parentEpic, issueLinkType, statusCategory

Custom fields work by name — quote if they contain spaces: "Story Points".

Pro tip: Prefer IDs over names for project/sprint/version when possible — names change, IDs (project = 1001) don't.

---

3. Functions (Complete Catalog)

Date/Time Relative Functions

All accept optional increment strings in (+/-)nn(y|M|w|d|h|m) format. Default unit matches the function's natural period.

| Function | Default Unit | Example | |----------|-------------|---------| | startOfDay() / endOfDay() | d | created > startOfDay("-1") = yesterday | | startOfWeek() / endOfWeek() | w | due startOfMonth("-1") = start of last month | | startOfYear() / endOfYear() | y | resolutiondate > startOfYear() | | now() | — | Current timestamp | | currentLogin() | — | When session began | | lastLogin() | — | Previous login |

User Functions

| Function | Fields | Operators | Behavior | |----------|--------|-----------|----------| | currentUser() | Assignee, Reporter, Voter, Watcher, Creator + custom User | =, != | Your identity | | membersOf("group") | Assignee, Reporter, Voter, Watcher, Creator | IN, NOT IN, WAS IN, WAS NOT IN | Group members. For teams: membersOf(id:) | | componentsLeadByUser(user) | Component | IN, NOT IN | Omit user = current user | | spacesLeadByUser(user) | Project (Space) | IN, NOT IN | Omit user = current user | | spacesWhereUserHasPermission(p) | Project | IN, NOT IN | e.g. "Edit work items" | | spacesWhereUserHasRole(role) | Project | IN, NOT IN | e.g. "Administrators" |

Sprint/Version Functions

| Function | Fields | Behavior | |----------|--------|----------| | openSprints() | Sprint | Active, not yet completed | | closedSprints() | Sprint | Completed sprints | | earliestUnreleasedVersion(project) | AffectedVersion, FixVersion, custom Version | Earliest unreleased in release order | | latestReleasedVersion(project) | Same | Most recently released version | | releasedVersions(project) | Same | All released. Omit project for all | | unreleasedVersions(project) | Same | All unreleased. Omit project for all |

Issue Functions

| Function | Syntax | Description | |----------|--------|-------------| | linkedIssues(key, linkType?) | issue in linkedIssues("ABC-44") | Link type optional — e.g. "is blocked by" | | parentEpic (field) | parentEpic = DEMO-123 | Stories/subtasks in an epic | | issueHistory() | issue in issueHistory() | Recently viewed | | votedWorkItems() | issue in votedWorkItems() | You voted on these | | watchedWorkItems() | issue in watchedWorkItems() | You watch these | | updatedBy(user, from?, to?) | issue in updatedBy(jsmith, "-8d") | Updated by user. Rounds = -7d -- Last 7 days duedate >= startOfWeek() AND duedate = startOfDay(-3M) AND resolutiondate startOfMonth("-1") -- Since start of last month updated = startOfMonth()`

Scope-Sort Pattern

Start broad, narrow iteratively:

-- Step 1: all open issues
project = PWC AND status = open

-- Step 2: narrow by sprint
project = PWC AND status = open AND fixVersion = "Current Sprint"

-- Step 3: carried-over issues only
project = PWC AND status = open AND fixVersion = "Current Sprint" AND fixVersion WAS "Last Sprint"

-- Step 4: sort by priority then assignee
... ORDER BY priority, assignee

---

7. Role-Based Ready Queries

Developers

-- My unresolved issues by priority
assignee = currentUser() AND resolution = Unresolved ORDER BY priority DESC

-- Bugs I reported
reporter = currentUser() AND status != Done

-- My completed work this week
resolution = Fixed AND resolutiondate >= -7d AND assignee = currentUser()

-- Where I'm mentioned in comments
comment ~ currentUser()

Scrum Masters

-- Unassigned in active sprint
sprint IN openSprints() AND assignee IS EMPTY

-- Stale tickets
status NOT IN (Closed, Done) AND updated = startOfMonth() AND duedate = -180d

---

8. Gotchas & Known Limitations

• Standard JQL has no aggregation — no COUNT, SUM, AVG. Use dashboard gadgets or marketplace apps.
• Can't check linked issue status — issueLinkType = "is blocked by" finds links but can't check if the blocker is resolved. Needs ScriptRunner.
• No recursive hierarchy traversal — epics+stories+subtasks need separate queries.
• updatedBy() rounds < 1 day up to 1 day — updatedBy(jsmith, "-1h") becomes 1 day.
• membersOf() does NOT support project roles — only groups and teams.
• IS EMPTY works for fields that exist — can't find issues where a field was never created.
• Atlassian is renaming "issue" to "work item" — old terms (project, issue, fixVersion) still work; no migration needed.
• Starting a text search with * is very expensive — put wildcards after the first few chars.

Marketplace Extensions for Advanced Needs

| Extension | What It Adds | |-----------|-------------| | JQL Tricks Plugin | 50+ extra functions | | JQL Search Extensions (Cloud) | Find comments, attachments, subtasks, epics | | JQL Booster Pack (Server/DC) | 15+ user-related functions | | ScriptRunner (Adaptavist) | Custom Groovy JQL functions — most powerful |

---

9. JQL in REST API

Query via Jira REST API v3:

curl -u email:token \
  "https://your-domain.atlassian.net/rest/api/3/search?jql=project=PWC+AND+status=Open&fields=summary,assignee"

Returns structured JSON. Use jql parameter, URL-encode when needed. Also supports startAt, maxResults, fields, expand params.

---

10. Edge Cases & Troubleshooting

Query is valid but slow: Check for leading wildcards, unindexed custom fields, or missing project filter.

Query returns 0 results unexpectedly: Verify field names haven't changed (esp. custom fields), check for case sensitivity in values (depends on Jira config), and ensure you're in the right project scope.

"Filter not found" when using filter =: The user doesn't have permission to that saved filter.

CHANGED returns nothing: Ensure the field actually has tracking enabled. Some custom fields don't log history.

Jira says "Field 'X' does not exist": The field name is wrong, disabled for this project, or requires a marketplace app.

---

Key Reference URLs

• Official JQL Functions: https://support.atlassian.com/jira-software-cloud/docs/jql-functions/
• JQL Operators: https://support.atlassian.com/jira-software-cloud/docs/jql-operators/
• JQL Fields: https://support.atlassian.com/jira-software-cloud/docs/jql-fields/
• JQL Keywords: https://support.atlassian.com/jira-software-cloud/docs/jql-keywords/
• JQL Performance KB: https://confluence.atlassian.com/jirakb/understanding-jql-performance-720416549.html
• Free Atlassian University Intro to JQL: https://www.youtube.com/watch?v=BcHKXSiOHqw

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: magnus919
• Source: magnus919/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.