Basic search is useful and will fulfill most of the users' search needs. However, there are still some limitations. One such limitation is that basic search allows you to perform searches based on inclusive logic but not exclusive logic. For example, if you need to search for issues in all but one project, with basic search, you will have to select every project except for the one to be excluded, since the basic search interface does not let you specify exclusions, and this is where advanced search comes in.
With advanced search, instead of using a field selection-based interface as in basic search, you will be using what is known as the JIRA Query Language (JQL). JQL is a custom query language developed by Atlassian. If you are familiar with the Structured Query Language (SQL), you will notice that it has a similar syntax; however, JQL is not the same as SQL.
One of the most notable differences between JQL and SQL is that JQL does not start with a select statement. A JQL query consists of a field followed by an operator, and then by a value or a function (which will return a value). You cannot specify what fields to return from a query with JQL, which is different from SQL. You can think of a JQL query as the part that comes after the where keyword in a normal SQL select statement. The following table summarizes the components in JQL:
|
JQL component |
Description |
|
Keyword |
Keywords in JQL are special reserved words that do the following:
|
|
Operator |
Operators are symbols or words that can be used to evaluate the value of a field on the left and the values to be checked on the right. Examples include the following:
|
|
Field |
Fields are JIRA system and custom fields. When used in JQL, the value of the field for issues is used to evaluate the query. |
|
Functions |
Functions in JQL perform specific calculations or logic and return the results as values that can be used for evaluation with an operator. |
Each JQL query is essentially made up of one or more components. A basic JQL query consists of the following three elements:
- Field: This can be an issue field (for example, status) or a custom field.
- Operator: This defines the comparison logic (for example,
=or>) that must be fulfilled for an issue to be returned in the result. - Value: This is what the field will be compared to; it can be a literal value expressed as text (for example,
Bug) or a function that will return a value. If the value you are searching for contains spaces, you need to put quotes around it, for example,issuetype = "New Feature".
Queries can then be linked together to form a more complex query with keywords such as logical AND or OR. For example, a basic query to get all the issues with a status of Resolved will look similar to the following:
status = Resolved
A more complex query to get all the issues with a Resolved status and a Bug issue type, which is assigned to the currently logged-in user, will look similar to the following (where currentUser() is a JQL function):
issuetype = Bug and status = Resolved and assignee = currentUser()
Discussing each and every JQL function and operator is out of the scope of the book, but you can get a full reference by clicking on the Syntax Help link in the advanced search interface. The full JQL syntax reference can be found at https://confluence.atlassian.com/x/ghGyCg.
You can access the advanced search interface from the Issue Navigator page, as follows:
- Browse to the Issue Navigator page.
- Click on the Advanced link on the right.
- Construct your JQL query.
- Click on the Search button or press the Enter key on your keyboard.
As JQL has a complex structure and it takes some time to get familiar with, the advanced search interface has some very useful features to help you construct your query. The interface has an autocomplete feature (which can be turned off from the General Configuration setting.) that can help you pick out keywords, values, and operators to use. It also validates your query in real time and informs you whether your query is valid, as shown in the following screenshot:
If there are no syntax errors with your JQL query, JIRA will display the results in a table below the JQL input box.
You can switch between the basic and advanced search by clicking on the Basic/Advanced link while running your queries, and JIRA will automatically convert your search criteria into and from JQL. In fact, this is a rather useful feature and can help you learn the basic syntax of JQL when you are first starting up, by first constructing your search in basic and then seeing what the equivalent JQL is. You need to a take note, however, that not all JQLs can be converted into basic search since you can do a lot more with JQL than with the basic search interface.