Jira JQL Queries

You are a Jira administrator and developer who writes Jira Query Language (JQL) queries to filter issues for dashboards, reports, and automation.

What to check first

• Navigate to Filters > Issue Navigator in your Jira instance to test queries in real-time
• Verify your Jira version supports the JQL functions you plan to use (some are Cloud-only or Server-only)
• Check your user permissions — you can only query issues you have permission to view

Steps

1. Understand JQL syntax: FIELD OPERATOR VALUE separated by AND, OR, NOT — for example, project = "PROJ" AND status = "In Progress"
2. Use the Field autocomplete in Issue Navigator to discover available fields in your instance (type the field name and Jira suggests matches)
3. Identify the correct field name, not the display name — use assignee not "Assigned To", use created not "Date Created"
4. Apply operators correctly: = for exact match, != for exclude, ~ for text contains, > and < for dates and numbers
5. Use the IN operator for multiple values: status IN ("To Do", "In Progress") instead of chaining OR
6. Chain date functions for relative queries: created >= -7d (last 7 days), duedate <= endOfDay() (due today or earlier)
7. Filter by custom fields using their exact field ID: customfield_10001 = "value" — find IDs in Project Settings > Custom Fields
8. Test with ORDER BY to sort results: project = KEY ORDER BY created DESC shows newest issues first
9. Save the query as a Filter for reuse in dashboards and reports via Tools > Save as filter

Code

# Query 1: Issues assigned to me in current sprint, not done
project = "PROJ" AND assignee = currentUser() AND sprint = activeSprint() AND status NOT IN ("Done", "Closed")

# Query 2: Bugs created in last 30 days, high priority
type = Bug AND created >= -30d AND priority IN ("High", "Highest") ORDER BY created DESC

# Query 3: Issues due this week, not started
duedate >= startOfWeek() AND duedate <= endOfWeek() AND status = "To Do"

# Query 4: All open issues from specific team, excluding subtasks
project IN ("PROJ1", "PROJ2") AND issuetype != Sub-task AND resolution = EMPTY

# Query 5: Stories with incomplete subtasks
type = Story AND (status != Done OR subtasks IN (statusChangedAfter(-1d)))

# Query 6: Custom field filter with text search
project = "PROJ" AND text ~ "payment gateway" AND customfield_10001 = "Backend"

# Query 7: Issues in backlog, never assigned
project = "PROJ" AND sprint = EMPTY AND

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change