Jira Query Language (JQL) Complete Guide 2026: Advanced Filters, Boards & Reporting

Most teams treating Jira JQL as a search box feature are leaving significant operational capability on the table. Jira JQL — Jira Query Language — is not just how you find issues: it is the engine behind every Agile board, every dashboard gadget, every scheduled report email, and every automation trigger condition in Jira. Understanding it at the level of a senior admin transforms how you run projects: boards stop showing the wrong issues, dashboards start reflecting reality, and reports run themselves.

This guide covers JQL from syntax fundamentals through to the features most guides miss entirely: dynamic functions that make queries role-aware without hardcoding usernames, the board-filter relationship that explains why issues “disappear” from boards, subqueries for cross-project dependency tracking, and Jira’s 2026 chart-level filtering that enables multi-team comparative reporting in a single gadget. It is written from the perspective of someone who writes JQL daily and has debugged enough misconfigured boards to know where the traps are.

What Jira JQL Is and Why It Matters More Than Basic Search

Jira’s basic search — the dropdown filters for project, status, assignee — is fine for simple one-off lookups. JQL is what you use when you need precision, repeatability, or power. It is a purpose-built query language that exposes every field in Jira’s data model and supports Boolean logic, comparisons, text matching, date arithmetic, and nested functions.

The key insight that most teams miss: saved JQL queries are first-class infrastructure in Jira. A saved filter is not just a shortcut to a search result. It can be assigned as the scope of an Agile board, attached to a dashboard gadget as its data source, subscribed to for automated email delivery, and referenced inside other JQL queries as a subquery. This means a single well-crafted JQL filter can simultaneously power a board, feed three gadgets on two different dashboards, and send a Monday morning email summary to your team lead — all without duplicating any configuration.

JQL is also the only way to do certain things in Jira. Basic search cannot compare dates relative to today, cannot filter by whether a field is empty or populated, cannot find issues linked to a specific issue, and cannot scope results to the current user dynamically. Every one of those capabilities requires JQL.

For teams using Jira’s automation rules, JQL literacy is doubly important — automation rule conditions use JQL syntax directly, and understanding filters is prerequisite knowledge for building useful automations. See our Jira automation rules setup guide for how JQL-based conditions work in that context.

JQL Syntax: Fields, Operators, Values, ORDER BY

A JQL query is made up of one or more clauses joined by AND, OR, and NOT. Each clause follows a fixed structure:

FIELD OPERATOR VALUE

A complete query with ordering looks like this:

project = BACKEND AND assignee = currentUser() AND status != Done ORDER BY priority ASC

Breaking that down:

• FIELD: the Jira field to query against — project, assignee, status, priority, created, etc.
• OPERATOR: how to compare — =, !=, IN, ~, <, >, IS EMPTY, etc.
• VALUE: what to match — a literal value, a list, a function call, or a quoted string.
• ORDER BY (optional): one or more fields with ASC or DESC direction.

Multiple clauses connect with Boolean operators:

project IN (BACKEND, FRONTEND) AND issuetype = Bug AND priority IN (High, Critical) ORDER BY created DESC

Parentheses control precedence exactly as in standard Boolean algebra:

(project = BACKEND OR project = FRONTEND) AND (priority = High OR priority = Critical) AND status != Done

How to Write a JQL Query in Jira

1. Open Advanced Search — In Jira Cloud, click the Filters menu in the top navigation and select Advanced issue search. Alternatively, press / (the global search shortcut) and type “Advanced search.” This opens Jira’s JQL editor with autocomplete support — it will suggest field names, operators, and values as you type.
2. Write your first clause — Start with the most scoping clause first, typically the project: type project = and Jira’s autocomplete will offer your available projects. Select one and press space to move to the operator. For a single-project query, project = MYPROJECT is your foundation.
3. Add conditions with AND — Type AND and continue adding clauses. A practical starting query for daily standup prep: project = MYPROJECT AND assignee = currentUser() AND status != Done ORDER BY priority ASC. This shows your open work, prioritised, nothing more.
4. Add ORDER BY for sorting — Append ORDER BY created DESC to sort newest first, or ORDER BY priority ASC for priority-sorted queues where Critical appears at the top. You can order by multiple fields: ORDER BY priority ASC, created DESC.
5. Test by pressing Enter or clicking Search — Jira runs the query immediately. If the JQL contains a syntax error, a red error banner identifies which clause is invalid and what it expected. Fix and rerun until results match your intent.
6. Save as a filter — Once the query returns what you need, click Save filter above the results, give it a descriptive name (not “My Filter” — something like “Backend Open Bugs – P1 and P2”), and click Submit. The filter is now available in your Filters menu and as a data source for boards and dashgets.
7. Share the filter with your team — Click the filter name in the Filters menu, then the three-dot menu next to it, and select Edit permissions. Set it to be viewable by your project or group so teammates can reuse the same filter in their own boards and dashboards without creating duplicates.

Most Useful JQL Fields

Jira exposes dozens of fields in JQL. These are the ones that do the most work in practice.

Operators Reference

Choosing the right operator is as important as choosing the right field. Using = when you need ~, or IN when you need NOT IN, produces either empty results or far more issues than intended.

Dynamic Functions: currentUser, startOfDay, membersOf and More

Dynamic functions are where JQL moves from useful to genuinely powerful. Instead of hardcoding a username or a date, you use a function that resolves to the correct value at query runtime. A filter using currentUser() returns different results for every person who runs it — their own issues — without any change to the query itself.

This is the capability most JQL guides skip entirely, and it is the capability that makes the difference between a filter that works for one person and a filter that works for an entire team.

currentUser()

Returns the currently logged-in user. Every Jira user who runs a filter containing currentUser() sees their own data. This is the foundation of every personal queue filter.

assignee = currentUser() AND status NOT IN (Done, Cancelled) ORDER BY priority ASC

startOfDay(), endOfDay(), startOfWeek(), endOfWeek(), startOfMonth(), endOfMonth()

Date boundary functions that resolve to midnight at the start or end of the specified period, relative to now. You can also pass offsets: startOfWeek(-1) means the start of last week, endOfMonth(1) means the end of next month.

created >= startOfWeek() AND created <= endOfWeek() ORDER BY created ASC

duedate >= startOfDay() AND duedate <= endOfDay(3) AND status != Done

membersOf('group-name')

Returns all members of a specified Jira group. This is indispensable for team-scoped filters that do not require listing every team member by name -- if the group membership changes, the filter automatically reflects the updated team without any modification.

assignee in membersOf("backend-engineers") AND sprint in openSprints() AND status NOT IN (Done, Cancelled)

releasedVersions() and unreleasedVersions()

Functions that return all released or unreleased fix versions for a project. Used for version-based reporting without hardcoding version numbers -- critical for teams that release frequently and would otherwise need to update their filters every release cycle.

project = MYAPP AND fixVersion in unreleasedVersions() AND issuetype = Bug ORDER BY priority ASC

project = MYAPP AND fixVersion in releasedVersions() AND created >= startOfMonth(-3) ORDER BY fixVersion DESC

openSprints(), closedSprints(), futureSprints()

Return all active, completed, or planned-but-not-started sprints respectively. Essential for sprint-scoped queries that need to remain valid across sprint cycles.

sprint in openSprints() AND issuetype = Bug AND priority = Critical ORDER BY created ASC

Saving Filters and Using Them in Boards, Dashboards, and Subscriptions

A JQL query becomes reusable infrastructure the moment you save it as a filter. Here is how to save a filter and deploy it across all three use cases.

Saving a Filter

1. Run your JQL query in Advanced search and confirm it returns the correct issues.
2. Click "Save filter" in the bar above the search results. A dialog box appears asking for a filter name.
3. Name it descriptively -- use a convention that identifies the scope and purpose: "Backend Team -- Open Sprint Issues" not "Filter 1." You will thank yourself when you have 30 filters six months from now.
4. Click Submit -- the filter is saved to your personal filters list and immediately accessible from the Filters menu in the top navigation.
5. Set sharing permissions -- Find the filter in Filters > View all filters, click its name, then the three-dot menu, then Edit permissions. Share with the relevant group or project role so teammates can use the same filter without creating duplicates.

Using a Saved Filter on a Dashboard Gadget

1. Open your dashboard and click Add gadget or click the gear icon on an existing gadget to open its configuration.
2. In the gadget configuration panel, look for the Filter or Saved filter input field.
3. Type the first few characters of your filter name and select it from the autocomplete dropdown.
4. Save the gadget. It will now pull data from your JQL filter in real time.

For a full walkthrough of dashboard gadget configuration, see our Jira dashboards and custom gadgets setup guide.

Setting Up an Email Subscription

1. Navigate to Filters > View all filters and click your saved filter.
2. Click the three-dot menu next to the filter name and select Subscribe.
3. Set the schedule -- daily, weekly, on a custom day/time -- and choose whether to receive the email even if the filter returns zero results.
4. Add other recipients from your team by entering their usernames. Each recipient must have permission to view the filter.
5. Click Subscribe. Jira will email the full list of matching issues on the configured schedule, formatted as an HTML table with clickable issue links.

The Board-Filter Relationship: Every Board IS a JQL Filter

This is the single most important structural fact about Jira boards that most teams do not know, and it is the explanation for the majority of "broken board" support requests I have seen over years of Jira administration: every Agile board in Jira -- Scrum or Kanban -- is fundamentally just a view on top of a JQL filter.

When you create a board, Jira generates a JQL filter behind the scenes that defines the board's scope. That filter determines which issues can ever appear on the board, on the backlog, or in any sprint on that board. If an issue does not match the board's filter, it is invisible to the board -- full stop. It does not matter if it is in the right project, the right sprint, assigned to the right person. If it does not match the filter, the board cannot see it.

You can view and edit this filter directly:

1. Open Board Settings -- Navigate to your board and click the three-dot menu in the top right, then Board settings. Alternatively, if you are a board admin, the settings link appears in the board header.
2. Click "General" in the left sidebar -- This shows the board's core configuration.
3. Find the "Filter" section -- You will see a field labeled Filter query with the JQL that defines this board's scope. There is also a link to the underlying saved filter -- click it to open the full filter editor.
4. Edit the filter to fix scope issues -- If issues are missing from your board, this is where you fix it. The most common cause: the filter specifies a single project key, but issues were created in a slightly different project. Update the filter to project IN (PROJECT-A, PROJECT-B) or add the missing project.

The board-filter relationship also means you can build boards for cross-project work, multi-team views, or specialised workflows simply by crafting the right JQL filter -- there is no need for a board to map one-to-one to a project. A single board can span five projects if the filter captures the right issues from all five. This is one of the most powerful and underused architectural patterns in Jira.

For guidance on how boards connect to sprint planning workflows, see our Jira sprint planning guide.

Advanced: Subqueries and Cross-Project Queries

JQL supports a form of subquery syntax using the issue in operator combined with specific functions. These enable dependency tracking and cross-project reporting that basic search cannot touch.

linkedIssues() -- Dependency Mapping

The linkedIssues() function returns all issues that are linked to a specified issue, optionally filtered by link type. This is the foundation of cross-project dependency reporting.

issue in linkedIssues("PROJECT-123")

This returns every issue that has a link relationship with PROJECT-123 -- whether it "blocks," "is blocked by," "duplicates," "relates to," or any other configured link type. You can narrow by link type:

issue in linkedIssues("PROJECT-123", "is blocked by")

Combined with cross-project scoping, this becomes a programme-level dependency view:

issue in linkedIssues("PLATFORM-456", "blocks") AND project != PLATFORM AND status != Done ORDER BY priority ASC

That query finds all open issues in other projects that the PLATFORM-456 epic is blocking -- exactly the kind of dependency visibility that programme managers need when a platform team's work gates multiple downstream teams.

Cross-Project Queries

JQL has no concept of project boundaries -- you can query across any projects your account has permission to view. The IN operator on the project field is the primary mechanism:

project IN (FRONTEND, BACKEND, MOBILE) AND issuetype = Bug AND priority = Critical AND status != Done ORDER BY project ASC, priority ASC

This returns all open critical bugs across three projects, sorted by project then priority -- a practical all-hands triage view that would take three separate searches in basic search mode.

You can also reference saved filters in cross-project queries using the filter field:

filter = "All Team Projects" AND issuetype = Bug AND created >= startOfWeek()

This delegates the project scope to the saved filter, keeping the query readable while reusing centrally maintained scope definitions.

2026 Chart-Level Filtering in Dashboards

One of the most significant additions in Jira's 2026 dashboard update is chart-level filtering -- the ability to apply multiple independent filters to a single chart gadget and display them side by side for comparative reporting. This was previously impossible in Jira's native dashboard tooling, requiring either Marketplace apps or exporting data to external BI tools.

With the 2026 update, the Velocity Chart and certain other gadgets now accept up to 5 separate JQL filters per chart. Each filter appears as a distinct series on the chart. The practical application: you can compare sprint velocity across five different teams in a single gadget, each team represented by its own JQL filter, rendered as a separate line or bar series.

Setting Up Multi-Filter Chart Gadgets

1. Create individual team filters -- Before configuring the chart, build a saved JQL filter for each team you want to compare. For example:
   • Filter "Backend Team -- Sprint Issues": assignee in membersOf("backend-team") AND sprint in closedSprints() ORDER BY sprint ASC
   • Filter "Frontend Team -- Sprint Issues": assignee in membersOf("frontend-team") AND sprint in closedSprints() ORDER BY sprint ASC
2. Add a Velocity Chart gadget to your dashboard via Add gadget.
3. Open the gadget configuration by clicking the gear icon on the gadget.
4. Enable multi-filter mode -- In the 2026 gadget configuration UI, click Add comparison filter. This reveals additional filter slots alongside the primary filter input. You will see up to 5 slots in total.
5. Assign a filter to each slot -- Select one of your team filters for each slot. Give each filter a display label (the label appears in the chart legend) -- "Backend," "Frontend," "Mobile," etc.
6. Set the sprint range -- Choose how many sprints to include in the historical comparison window. For meaningful velocity trends, a minimum of 6 sprints is recommended.
7. Save the gadget -- The chart renders with one series per filter, colour-coded and labelled, making cross-team velocity comparison immediate and visual without leaving the dashboard.

This capability directly addresses a common reporting gap: engineering managers who previously had to export to spreadsheets or use Jira Align to compare velocity across multiple teams can now do it natively in a dashboard gadget. Combined with the Jira roadmap features for programme-level planning, chart-level filtering makes Jira's native reporting competitive with dedicated BI integrations for most team-level analytics use cases.

10 Essential Jira JQL Queries Every User Should Save

These are the ten filters I recommend every Jira user -- from developer to engineering manager -- saves on day one. Each one is immediately useful and each uses the JQL features described in this guide.

1. My Open Work (Personal Queue)

assignee = currentUser() AND resolution = Unresolved AND status NOT IN (Done, Cancelled) ORDER BY priority ASC, updated DESC

2. Current Sprint -- All Issues

sprint in openSprints() AND project = MYPROJECT ORDER BY status ASC, priority ASC

3. Blocked Issues in Active Sprint

sprint in openSprints() AND status = "Blocked" ORDER BY priority ASC, created ASC

4. Unassigned Open Bugs

issuetype = Bug AND assignee IS EMPTY AND resolution = Unresolved AND status NOT IN (Done, Cancelled) ORDER BY priority ASC, created ASC

5. Critical Issues Due This Week

priority in (Critical, High) AND duedate >= startOfDay() AND duedate <= endOfWeek() AND status != Done ORDER BY duedate ASC

6. Team Open Issues (Group-Based)

assignee in membersOf("backend-engineers") AND sprint in openSprints() AND status NOT IN (Done, Cancelled) ORDER BY assignee ASC, priority ASC

7. Issues Updated More Than 7 Days Ago (Staleness Check)

status NOT IN (Done, Cancelled) AND updated <= -7d AND assignee IS NOT EMPTY ORDER BY updated ASC

8. Open Bugs Against Unreleased Versions

issuetype = Bug AND fixVersion in unreleasedVersions() AND resolution = Unresolved ORDER BY priority ASC, fixVersion ASC

9. Issues Created This Week

created >= startOfWeek() AND created <= endOfWeek() ORDER BY created DESC

10. Cross-Project Dependency View

issue in linkedIssues("PLATFORM-100", "blocks") AND status NOT IN (Done, Cancelled) ORDER BY priority ASC, project ASC

Troubleshooting: Issues "Missing" From Boards Due to Misconfigured Filters

The number one Jira support ticket in most organisations is some variation of "my issue isn't showing on the board." In almost every case, the cause is a JQL filter mismatch -- the board's underlying filter is not capturing that issue. Here is a systematic approach to diagnosing and fixing it.

Step-by-Step Diagnosis

1. Identify the issue key of the "missing" issue -- note it down (e.g., BACKEND-245). Confirm the issue exists by navigating to it directly via the issue URL.
2. Open the board's filter -- Go to Board Settings > General > Filter and note the JQL. Click View filter to open it in the full filter editor.
3. Test the filter against the missing issue -- Add AND issue = BACKEND-245 to the filter query and run it. If it returns zero results, the issue does not match the board filter. If it returns one result, the issue does match and the problem is elsewhere (most likely a swimlane configuration or column mapping).
4. Identify the exclusion cause -- Remove clauses one at a time from the modified filter until BACKEND-245 appears in the results. The last clause you removed before it appeared is the one excluding the issue.
5. Common causes and fixes:
   • Wrong project key: the filter specifies project = BACKEND but the issue was created in BACKEND-TEMP. Fix: change to project IN (BACKEND, BACKEND-TEMP).
   • Issue type excluded: the filter includes issuetype != Epic but the missing issue is a Sub-task. Fix: review and broaden the issuetype clause.
   • Status excluded: the filter has status NOT IN ("Won't Fix", Duplicate) and the issue was mistakenly moved to one of those statuses. Fix: correct the issue status, or review whether that status should be excluded.
   • Sprint mismatch: the issue is in a future sprint but the filter uses sprint in openSprints(). The issue will not appear until the sprint starts -- this is correct behaviour, not a bug.
   • Label or component filter: the filter restricts to labels = "platform" and the issue lacks that label. Fix: add the label to the issue or broaden the filter.
6. Update the board filter -- Once you have identified the cause, update the filter in Board Settings > General. Changes take effect immediately -- refresh the board and verify the previously missing issue now appears.

For issues related to automation rules that feed into board states, cross-reference with the Jira automation rules guide -- automations that move issues to states excluded by the board filter are a common hidden culprit.

Verdict

Frequently Asked Questions