Learn Jira JQL - A short guide to the Jira Query Language


JQL represents Jira Query Language and is the most flexible and powerful approach to look for your issues in Jira.

Example: you need to find issues with type story

JQL: issuetype= Story




How JQL works


JQL have two type of search 
  • Basic Search
  • Advanced Search

Basic Search

Jira basic search is very simple, it have user interface where you can simply select the values and it will show you the results. You can add as many as filters and your results will be displayed as per filters.

  • Choose Search > View all issues.
  • If the advanced search is shown instead of basic, click Switch to basic.
  • Set your search criteria
  • Optionally, enter text to search for and add more criteria by clicking +more.
  • Click Search.

 

 For example we you to search all issues assigned to you, so you will select the filters as

Project= All

Assignee: current user (or you can select your username)

 

Advanced Search

The advanced search permits you to build structured queries using the Jira Query Language to look for issues. You can specify criteria that you cannot use in the basic search (the ORDER BY clause, for example).

 

  • 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).

Example: search issues with type story

JQL: issuetype=story

Queries are a series of simple elements strung together to form a more complex question. A query has three basic parts:

·       Fields - are different types of jira issues information in the system. Jira fields include assignee, project etc.)

·        Operators - Operators are the core of the query. They narrate the field to the value. For example few operators include equals (=), not equals (!=), less than (<) (>), etc.)

·       Values - are the actual data in the query. They are usually the item for which we are looking, for example project a is a value to search issues for project a

There are other parameters in JQL which depends on the needs, lets discuss all of them

 

 


·        Keyword - are special words in JQL that perform actions like joining two or more clauses together, or altering the logic of a clause, for example need to search issuetype is story and assigned to user1

·       Function - are special calculations used to access specific data within Jira that are not distinct fields or static values. Examples of functions include values for the current user, linked issues, or date calculations like the first day of this month. Few third party plugins available provide rich functions to use if not available in core jira.

 Examples:

Find issues are unassigned and have not been updated in the last day?
 assignee is EMPTY and created < -1d

Find issues which are resolved and belongs to project a or have no assignee 
status=resolved AND (project="project a" OR assignee is EMPTY )

Precedence in JQL queries

Ref: https://confluence.atlassian.com/jirasoftwareserver/advanced-searching-939938733.html


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

This 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=captainjoe

This 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=captainjoe

When 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=captainjoe

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 special characters in text searches, precede them with two backslashes. This will let you run the query that contains a reserved character, but the character itself will be ignored in your query. For more info, see Special characters in Search syntax for text fields.


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.

"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"


JQL Cheat Sheet 


0 Comments