Introduction to JQL: Standard & advanced search in Jira
Is Jira part of your daily business? Then you probably will have stumbled upon the search function in Jira. Be it while looking for a specific ticket, to automate workflows or to create reports. The developers among you might have had a look at the advanced search in Jira as well.
With the help of JQL (Jira Query Language) the search can be set up effectively. This is essential for developers, but project managers, team leads and other users might benefit from knowledge in JQL as well. Simply because a lot of ticket and processes are displayed in Jira and could be filtered via JQL easily, since it allows searching for specific issues by setting up a structure search request. So it's safe to say that ideally every team working with Jira is able to use the advanced search with JQL.
In this introduction we will explain:
- What is JQL and what it is used for?
- How does the advanced JQL search in Jira Core, Jira Software and Jira Service Management look like?
- How is the advanced JQL search extended with apps like ScriptRunner, Xray and Power JQL?
What is JQL & what is it used for?
Definition: Jira search allows structured requests to find issues via Jira Query Language (JQL).
Benefits: JQL helps to find specific issues quickly, to be used for better overview, boards or reports. Due to JQL storage it is possible to conduct recurring tasks easily, for example if you need the same type of issues listed on a weekly basis.
Structure: JQL queries are also called clauses. They have a specific structure (syntax), which will be changed accordingly the goal of the search request.
Standard search: In Jira’s standard search you can look for a specific issue, for example display all issues linked to a specific user. Therefore, you will fill in the existing fields in the standard search. But the standard search reaches its limits quickly, because only visible filters are available and search can only be done with AND-operators. This is where the advanced search comes into use.
Advanced search with JQL: In the advanced search you benefit from additional functions in your request. You’re able to define the syntax individually with more operators and details, save your syntax for further usage in your filter list and add it to your dashboard with a gadget. In your dashboard you will then find some exporting options for your JQL query as well.
The basics of JQL Syntax
To create JQL queries in the right way, you have to keep some syntax rules in mind:
- Your standard operator “=” can be used to find single values (see example 1)
- Operator “IN” is used to get a list of values (see example 2)
- With “AND” you will be able to set up a search with two criteria. Both of them will be relevant for your search (see example 1 and 2)
- With “OR” either one or the other value will have to be true (see example 3)
Example 1: Looking for issues belonging to the current user with due date “now”
Example 2: Searching for tickets in project Marketing with resolution “done” or “unresolved”
Example 3: Looking for tickets belonging to either the current user or another employee and any other resolution than “done”
JQL search in systems like Jira
By default, Jira Core, Jira Software and Jira Service Management offer JQL search functions. This means: You will start tipping in your syntax and a quick selection of possible values will appear in your index.
JQL search in Jira Core
| Issues connected to time | Issues connected to projects & users |
| Issues with due day today:
due < endOfDay() | Issues assigned to current user:
assignee = currentUser() |
Issues with due day on the 15th of next month: due < endOfMonth(“+15d”) | Issues where user has a specific role: projectsWhereUserHasRole() |
| Unresolved, overdue issues:
duedate < now() AND status NOT IN (closed, resolved) | |
| Issues created in last 3 days:
created > startOfDay(“-3d”) |
JQL search in Jira Software
Issues connected to sprints |
| Issues belonging to a closed sprint:
sprint in closedSprints() |
| Issues belonging to an open sprint:
sprint in openSprints() |
JQL search in Jira Service Management
SLAs |
| Issues with SLAs that were not met
“Time to First Response” = breached() |
| Issues with more than 1 hour Response Time
“Time to First Response” > elapsed(“1h”) |
Additional JQLs with Atlassian Marketplace apps
To meet user expectations, Atlassian Marketplace offers some additional apps with JQL functions. ScriptRunner and Xray were developed with another purpose in mind, but in our example they offer valuable JQL additions to the advanced search in Jira as well as more reporting options. With ScriptRunner you can also not only use more JQL values but create your own as well. Actonic has also developed an app called Power JQL, with additional JQL functions to be used for the extended search.
Quick dive into ScriptRunter functions | Quick dive into Xray functions | |
| Find issues via links
hasLinks | Displaying list of issues connected to specific testset testTestSet | Find all issues with pdf-attachments containing “android” in the title.
issue in powerAttachment(“.*(?=android).*(?=pdf).*”) |
Find issues via attachments fileAttached | Displaying list of test without execution testsWithoutTestExecution | Find issues whose summary or description contain any of the listed words in a test project. issue in powerIssue(“project=test”, “summary, description”, “(?i).*(text1|text2).*”) |
As you can see, JQL is offering multiple possibilities for Jira users to search for issues, but at the same time JQL usage requests some knowledge to be conducted correctly. We would be happy to assist you with your requests. As an Atlassian partner we’ve done so in the past with multiple customers through JQL consultations or training sessions.
Were you able to get a first introduction into JQL and its possibilities? Would you like to learn more? Simply contact our experts for a Jira training session with JQL focus.
Was this helpful?
Thanks!
Andrei Pisklenov _Actonic_
5 comments