Advanced searching
The advanced search allows you to build structured queries using the Jira Query Language (JQL) to search for issues. You can specify criteria that cannot be defined in the quick or basic searches (e.g. ORDER BY clause).
- If you don't have complex search criteria, you may want to use quick search instead.
- If you are not comfortable with the Jira Query Language (JQL), you may want to use basic search instead.
Note, JQL is not a database query language, even though it uses SQL-like syntax.
Screenshot: Advanced search
On this page:
Advanced searching
- Navigate to Issues (in header) > Search for issues.
- If there are existing search criteria, click the New filter button to reset the search criteria.
If the basic search is shown instead of the advanced search, click Advanced (next to the Search button).
Enter your JQL query. As you type, Jira will offer a list of "auto-complete" suggestions based on the context of your query. Note, auto-complete suggestions only include the first 15 matches, displayed alphabetically, so you may need to enter more text if you can't find a match.
- Press Enter or click Search to run your query. Your search results will display in the issue navigator.
Understanding advanced searching
Read the following topics to learn how to get the most out of advanced searching:
Constructing JQL queries
A simple query in JQL (also known as a 'clause') consists of a field, followed by an operator, followed by one or more values or functions. For example:
project = "TEST"This query will find all issues in the "TEST" project. It uses the "project" field, the EQUALS operator, and the value "TEST".
A more complex query might look like this:
project = "TEST" AND assignee = currentuser()This query will find all issues in the "TEST" project where the assignee is the currently logged in user. It uses the "project" field, the EQUALS operator, the value "TEST",the "AND" keyword and the "currentuser()" function.
For more information on fields, operators, keywords and functions, see the Reference section below.
Precedence in JQL queries
Precedence in JQL queries depends on keywords that you use to connect your clauses (a clause being e.g. project = “Teams in Space”). The easiest way to look at this is to treat the AND keyword as the one grouping clauses, and OR as the one separating them. The AND keyword takes precedence over other keywords, because it groups clauses together, essentially turning them into one combined clause.
Example 1
status=resolved AND project=“Teams in Space” OR assignee=captainjoeThis query will return all resolved issues from the “Teams in Space” project (clauses grouped by AND), and also all existing issues assigned to captainjoe. The clause after the OR keyword is treated as separate.
Example 2
status=resolved OR project="Teams in Space" AND assignee=captainjoeThis query, on the other hand, will return captainjoe’s issues from the “Teams in Space” project (clauses grouped by AND), and also all existing resolved issues (a clause separated by OR).
Example 3
status=resolved OR projects="Teams in Space" OR assigne=captainjoeWhen you only use the OR keyword, all clauses will be treated as separate, and equal in terms of precedence.
Setting the precedence
You can set precedence in your JQL queries by using parentheses. Parentheses will group certain clauses together and enforce precedence.
Example 1
As you can see below, parentheses can turn our example JQL query around. This query would return resolved issues that either belong to the “Teams in Space” project, or are assigned to captainjoe.
status=resolved AND (project="Teams in Space" OR assignee=captainjoe)Example 2
If you used parentheses like in the following example, they wouldn’t have any effect, because the clauses enclosed in parentheses were already connected by AND. This query would return the same results with or without the parentheses.
(status=resolved AND project="Teams in Space") OR assignee=captainjoeRestricted words and characters
Reserved characters
JQL has a list of reserved characters:
space (" ") | + | . | , | ; | ? | | | * | / | % | ^ | $ | # | @ | [ | ] |
If you wish to use these characters in queries, you need to:
- surround them with quote-marks (you can use either single quote-marks (
') or double quote-marks ("));
and, if you are searching a text field and the character is on the list of reserved characters for text searches, - precede them with two backslashes.
For example:
version = "[example]"
summary ~ "\\[example\\]"
Reserved words
JQL also has a list of reserved words. These words need to be surrounded by quote-marks (single or double) if you wish to use them in queries.
Note for Jira administrators: this list is hard coded in the JqlStringSupportImpl.java file.
Performing text searches
You can use Lucene's text-searching features when performing searches on the following fields, using the CONTAINS operator:
Summary, Description, Environment, Comments, custom fields that use the "Free Text Searcher" (i.e. custom fields of the following built-in custom field types: Free Text Field, Text Field, Read-only Text Field).
For more information, see Search syntax for text fields.
Reference
| Description | Reference | |
|---|---|---|
| Fields | A field in JQL is a word that represents a Jira field (or a custom field that has already been defined in Jira). | |
| Operators | An operator in JQL is one or more symbols or words that compare the value of a field on its left with one or more values (or functions) on its right, such that only true results are retrieved by the clause. Some operators may use the NOT keyword. | |
| Keywords | A keyword in JQL is a word or phrase that does (or is) any of the following:
| |
| Functions | A function in JQL appears as a word followed by parentheses, which may contain one or more explicit values or Jira fields. A function performs a calculation on either specific Jira data or the function's content in parentheses, such that only true results are retrieved by the function, and then again by the clause in which the function is used. |
Running a saved search
Saved searches (also known as Saving your search as a filter) are shown in the left panel, when using advanced search. If the left panel is not showing, hover your mouse over the left side of the screen to display it.
To run a filter, e.g. My Open Issues, simply click it. The JQL for the advanced search will be set, and the search results will be displayed.
Next steps
Read the following related topics:
- Searching for issues
- Basic searching
- Search syntax for text fields
- JQL: The most flexible way to search Jira (on the Atlassian blog)
- Saving your search as a filter
- Working with search results—find out how to use the issue navigator, export your search results, bulk modify issues, and share your search results.