What is advanced search in Jira Cloud?

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. For example, you can use the ORDER BY clause in JQL when you’re searching for issues. JQL can help gain key project insights and help you find not just issues but also important information in projects.

JQL is not a database query language, even though it uses SQL-like syntax. In advanced search, you can use queries to find your issues. Queries are a series of elements or parts, like fields, operators, and values, that are strung together to form a structure. Learn more about constructing JQL queries.

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 created in ascending or descending order

1. Switch between Basic and JQL

2. JQL editor

3. Expand or Collapse editor

4. Syntax help

5. Search button

6. Line numbers when your JQL query is longer than a line

7. Autocomplete suggestions based on context

Perform advanced searching with JQL queries

The syntax-powered advanced search or JQL is a powerful tool for getting specific information from projects. Learn more about constructing JQL queries.

To use advanced search or JQL to find your issues:

1. Select Search 🔍 in the navigation bar (or press / on your keyboard). Alternatively, select Filters in the navigation bar.

2. Select View all issues.

   • If the basic search is shown instead of the advanced search, select JQL (next to the 🔍  icon). If advanced or JQL search is already enabled, you'll see the option to switch to basic.

3. Enter your JQL query.

4. Press Enter or select 🔍 to run your query. Your search results will be displayed based on the criteria in your JQL query.

Construct JQL queries

Get the most out of advanced searching by learning how to structure your JQL query. 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:

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:

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.

Set 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.

Restricted words and characters

Special characters

In general, non-alphanumeric characters, such as + . , * / % ^ $ # @ [ ], aren't indexed for search and are ignored in queries. Exceptions include email addresses and URLs.

When building queries, make sure to surround phrases with special characters or spaces with single ' or double " quotation marks, for example: field ~ "email@atlassian.com". Additionally, some characters may need to be preceded by two backslashes \\, for example, field ~ "\\(text".

Reserved words

JQL also has a list of reserved words. These words need to be surrounded by quotation 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"

Types of JQL

Bounded JQL query

A bounded JQL is a JQL that requires a search restriction. The JQL must have at least one condition with field on the left side followed by an operator and then by one or more values (or functions). Here are some examples of bounded queries:

• project = TEST order by key; here, project = TEST is a search restriction in the JQL query.

• reporter = currentUser(); here, reporter = currentUser() is a search restriction in the JQL query.

• status IN ("To Do", "IN PROGRESS") AND priority >= Medium ORDER BY created; here status IN ("To Do", "IN PROGRESS") and priority >= Medium are the search restrictions in the JQL query.

Unbounded JQL query

On the other hand, unbounded JQL is a JQL that doesn't have any search restrictions. They can be an empty query or one that solely lists order by clauses, such as:

• order by createdDate

• order by key

Perform a text search

You can use text-searching features when performing searches on the following fields, using the CONTAINS operator:

Summary, Description, Environment, Comments, and custom fields that use the "Free Text Searcher"

Learn more about using search syntax for text fields

Troubleshooting in advanced search

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 the AND 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.