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 you can't define in the quick or basic searches (the ORDER BY clause, for example).
If you don't have complex search criteria, try quick search instead.
JQL is not a database query language, even though it uses SQL-like syntax.
Using Jira's team-managed projects? Team-managed projects are being actively developed, which means you may not (yet) have access to the features described below.
Search for issues using JQL
- Choose Filters in the navigation bar.
- Select Advanced issue search.
If basic search is shown instead of advanced search, click Advanced (next to the
icon). If advanced is already enabled, you'll see the option of switching to basic.
Enter your JQL query. As you type, Jira will offer a list of "autocomplete" suggestions based on the context of your query. Note, autocomplete 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 to run your query. Your search results will be displayed in the issue navigator.
Search for issues using JQL in a project
You can build structured queries using the Jira Query Language (JQL) to search for issues in a project. You can specify criteria that you can't define in the quick or basic searches (the ORDER BY clause, for example).
JQL is not a database query language, even though it uses SQL-like syntax.
To search for issues using JQL:
From your project’s sidebar, select Issues.
If you're in the Basic search mode, select JQL.
Enter your JQL query.
Press Enter or click 🔍 to run your query. Your search results will be displayed in the issue navigator.
Using JQL, you could search for all issues in your project “Assassin’s guild” that:
have “weaponry” in a text field, and
are ordered by when they were
createdin ascending or descending order
Basic or JQL toggle
JQL editor
Expand/Collapse editor
Syntax help
Search button
Line numbers when your JQL query is longer than a line
Autocomplete suggestions based on context
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.
Learn more about fields, operators, keywords and functions below.
Setting the precedence of operators
You can use parentheses in complex JQL statements to enforce the precedence of operators.
For example, if you want to find all resolved issues in the 'SysAdmin' project, as well as all issues (any status, any project) currently assigned to the system administrator (bobsmith), you can use parentheses to enforce the precedence of the boolean operators in your query, i.e.
(status=resolved AND project=SysAdmin) OR assignee=bobsmithNote that if you do not use parentheses, the statement will be evaluated left-to-right.
You can also use parentheses to group clauses, so that you can apply the NOT operator to the group.
Restricted 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]"
You can't search for many special characters in text fields using this method. Learn more about using search syntax for text fields.
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:
"a", "an", "abort", "access", "add", "after", "alias", "all", "alter", "and", "any", "are", "as", "asc", "at", "audit", "avg", "be", "before", "begin", "between", "boolean", "break", "but", "by", "byte", "catch", "cf", "char", "character", "check", "checkpoint", "collate", "collation", "column", "commit", "connect", "continue", "count", "create", "current", "date", "decimal", "declare", "decrement", "default", "defaults", "define", "delete", "delimiter", "desc", "difference", "distinct", "divide", "do", "double", "drop", "else", "empty", "encoding", "end", "equals", "escape", "exclusive", "exec", "execute", "exists", "explain", "false", "fetch", "file", "field", "first", "float", "for", "from", "function", "go", "goto", "grant", "greater", "group", "having", "identified", "if", "immediate", "in", "increment", "index", "initial", "inner", "inout", "input", "insert", "int", "integer", "intersect", "intersection", "into", "is", "isempty", "isnull", "it", "join", "last", "left", "less", "like", "limit", "lock", "long", "max", "min", "minus", "mode", "modify", "modulo", "more", "multiply", "next", "no", "noaudit", "not", "notin", "nowait", "null", "number", "object", "of", "on", "option", "or", "order", "outer", "output", "power", "previous", "prior", "privileges", "public", "raise", "raw", "remainder", "rename", "resource", "return", "returns", "revoke", "right", "row", "rowid", "rownum", "rows", "select", "session", "set", "share", "size", "sqrt", "start", "strict", "string", "subtract", "such", "sum", "synonym", "table", "that", "the", "their", "then", "there", "these", "they", "this", "to", "trans", "transaction", "trigger", "true", "uid", "union", "unique", "update", "user", "validate", "values", "view", "was", "when", "whenever", "where", "while", "will", "with"
Performing text searches
You can use 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).
Fields
A field in JQL is a word that represents a Jira field (or a custom field that has already been defined in Jira). Learn more about using fields for advanced searching.
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. Learn more about using operators for advanced searching.
Keywords
A keyword in JQL is a word or phrase that does (or is) any of the following:
- joins two or more clauses together to form a complex JQL query
- alters the logic of one or more clauses
- alters the logic of operators
- has an explicit definition in a JQL query
- performs a specific function that alters the results of a JQL query.
Learn more about using keywords for advanced searching.
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.
Learn more about using functions for advanced searching.
Running a saved search
Saved searches (also known as Saving your search as a filter) are shown in the sidebar when using advanced search. If the sidebar isn't showing, hover your mouse over the left side of the screen and click to expand it.
To run a filter, like My open issues, simply click it. The JQL for the advanced search will be set and the search results will be displayed.
Troubleshooting
Why can't I switch between basic and advanced search?
In general, a query created using the basic search can be translated to advanced JQL search, and back again. However, a complex query created using advanced JQL criteria may not be translated to basic search, particularly if:
- the query contains an OR operator. Instead, you can use an IN operator and it will be translated. For example:
project in (A, B) - the query contains a NOT operator
- the query contains an EMPTY operator
- the query contains any of the comparison operators: !=, IS, IS NOT, >, >=, <, <=
- the query specifies a field and value that is related to a project (e.g. version, component, custom fields) and the project is not explicitly included in the query (e.g.
fixVersion = "4.0", without theAND project=JRA). This is especially tricky with custom fields since they can be configured on a Project/Issue Type basis. The general rule of thumb is that if the query cannot be created in the basic search form, then it will not be able to be translated from advanced search to basic search.
Why can't I see autocomplete suggestions?
- Your administrator may have disabled the "JQL Auto-complete" feature for your Jira instance.
- Auto-complete suggestions are not offered for function parameters.
- Auto-complete suggestions are not offered for all fields. Check the fields reference to see which fields support autocomplete.
Where can I see the error in my JQL query?
While typing, you can hover over the invalid text of your query to know more about the JQL error. Alternatively, if your JQL query has an error, you can hit search and Jira will display the specifics of the error below the JQL editor, along with the line and character number of the invalid text in the query.