Cloud
Data Center
Versions

Advanced searching 1

Searching for issues 1

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

Are you on the right help page?

Using the classic Scrum and Kanban projects? You're in the right place!

Using a next-gen Software project as part of the new Jira Software? Check out these pages instead.

If you're unsure, check your project menu. If it has the Give feedback and Learn more menu items, you're on a next-gen Software project and this page isn't for you.




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 the quick search instead.
  • If you are not comfortable with the Jira Query Language (JQL), you may want to use the 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

  1. Click the Jira icon in the navigation bar

     
  2. Click Issues > Search.

    • If the basic search is shown instead of the advanced search, click Advanced (next to the  icon)

      Why can't I switch between basic and advanced search?

      In general, a query created using basic search will be able to be translated to advanced search, and back again. However, a query created using advanced search may not be able to be translated to basic search, particularly if:

      • the query contains an OR operator (note you can have an IN operator and it will be translated, e.g. project in (A, B))
        • i.e. even though this query: (project = JRA OR project = CONF) is equivalent to this query: (project in (JRA, CONF)), only the second query will be translated.
      • 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.

  3. Enter your JQL query. As you type, 

    Jira Software

     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.

    Why aren't the auto-complete suggestions being shown?
    • 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 auto-complete.
  4. Press Enter or click  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 | Setting the precedence of operators | Restricted words and characters | Performing text searches

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.

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=bobsmith

Note 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]"
  • 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.

Show me...

"abort", "access", "add", "after", "alias", "all", "alter", "and", "any", "as", "asc", "audit", "avg", "before", "begin", "between", "boolean", "break", "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", "join", "last", "left", "less", "like", "limit", "lock", "long", "max", "min", "minus", "mode", "modify", "modulo", "more", "multiply", "next", "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", "sum", "synonym", "table", "then", "to", "trans", "transaction", "trigger", "true", "uid", "union", "unique", "update", "user", "validate", "values", "view", "when", "whenever", "where", "while", "with"

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

Searching for issues with existing development information

Previously, searching for issues with existing commits and pull requests via a JQL filter included searches such as issue.property[development].commits and issue.property[development].prs.

Now, Jira's updated infrastructure requires these updated JQL searches:

  • development[pullrequests].all (or .open) 
  • development[commits].all
  • development[reviews].all (or .open)
  • development[builds].failing


Reference


DescriptionReferenceQuick links
FieldsA field in JQL is a word that represents a Jira field (or a custom field that has already been defined in Jira).Fields reference page 
Show list of fields

 

OperatorsAn operator in JQL is one or more symbols or words which compares 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.Operators reference page
Show list of operators

 

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.
Keywords reference page
Show list of keywords

 

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.

Functions reference page
Show list of functions

Error rendering macro 'excerpt-include'

No link could be created for '.Advanced searching - Functions reference vprepub'.

Running a saved search

Saved searches (also known as filters) 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

 Need help? If you can't find the answer you need in our documentation, we have other resources available to help you. See Getting help.

Read the following related topics:

Last modified on Jun 18, 2021

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.