Guff_9hys

这个屌丝很懒，什么也没留下！

热门标签

Jira强大的搜索语言——JQL_jira jql

作者：Guff_9hys | 2024-08-25 12:28:48

踩

jira jql

Important keywords to know

Atlassian has created a JQL reference where you can find all keywords, operators, etc that can be used in JQL. This is your go-to-guide when you want to discover new search capabilities. Here are some of the most common keywords and operators you will use:

AND

This will only return issues that match both clauses (are part of the Collaboration project and have their status set to "In Progress")

project = Collaboration AND status = "In Progress"

OR

Returns all issues from either the Collaboration project or that have their status set to "In Progress".

project = Collaboration OR status = "In Progress"

IS

This will return all issues that have no description.

description IS EMPTY

Operators

!=

status != "To Do"

Returns all issues except for those that have their status set to “To Do”

>=

"Story Points" >= 5

Find all issues that have Story Points which are greater than or equal a given value

Similar

> | greater than
< | smaller than
<= | smaller than or equal

IN

status IN ("To Do", "In Progress", "Closed")

is the same as

status = "To Do" OR status = "In Progress" OR status = "Closed"

Find all issues which are either have the status “To Do”, “In Progress” or “Closed”

Reverse

NOT IN

Putting this into practice

Let’s start with a simple example. Say you want to see what bugs your teammate filed within a certain project. You query would be:

reporter = jsmith AND project = Pipeline

Here we used the keyword “AND” to query Jira for tickets reported by John Smith in the project “Pipeline”

Other times you may want to have the query reference a set of items. For instance:

What issues are blocking or critical in Projects A, B, and C?

priority in (Blocker, Critical) AND project in (ProjA, ProjB, ProjC)

The “in” keyword will include any item that matches any item in the list. In the above example it will return all of the blocker and critical bugs in projects A, B, and C.

This is extremely helpful for organizations that have service level agreements (SLA) with their customer base. A JQL query can easily find the issues that are not meeting that SLA.

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

In this query the “is empty” statement only includes issues where the value of the assignee field is blank. This query also shows how Jira supports relative dates. The value -1d evaluates to 1 day behind the current date when the query is run. As a result, the above query will return all issues that do not have an assignee that are at least one day old.

Don’t be intimidated by Jira’s Advanced Searching! Jira’s JQL editor makes it easy to learn JQL. The editor uses code that hints as you type. For example, if we want to type the following JQL: project = Pipeline, Jira gives suggestions at each step of the way for each of the three components of our query. Click on “Syntax help” anytime if you get stuck.

Visit the Jira Software product guide to learn more about JQL, advanced search with use cases, and more.

We also have a downloadable cheat sheet to keep close on hand as you perform searches with JQL. Copy and paste fields, operators and functions into the Jira search bar, as well as learn more advanced queries.

Advanced Searching

On this page

In this section

What is an Advanced Search?

An advanced search allows you to use structured queries to search for JIRA issues. Your search results will be displayed in the Issue Navigator, where you can export them to MS Excel and many other formats. You can also save and subscribe to your advanced searches if you wish.

When you perform an advanced search, you are using the JIRA Query Language (JQL).

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, the following simple query will find all issues in the "TEST" project:

project = "TEST"

(This example uses the Project field, the EQUALS operator, and the value "TEST".)

Be aware that it is not possible to compare two fields.

JQL gives you some SQL-like syntax, such as the ORDER BY SQL keyword and ISNULL() SQL function (i.e. the NULL keyword in JQL). However, JQL is not a database query language. For example, JQL does not have a SELECT statement.

How to Perform an Advanced Search

Choose Issues > Search for Issues. The issue navigator will be displayed.
- If there are existing search criteria, click the New filter button to reset the search criteria.
- If the Advanced link is showing, click it to switch to advanced searching.
Type your query using the fields, operators and field values or functions.
Click the Search button to run your query.

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"; this includes custom fields of the following built-in Custom Field Types
- Free Text Field (unlimited text)
- Text Field (< 255 characters)
- Read-only Text Field

The JQL field "text" as in text ~ "some words" searches an issue's Summary, Description, Environment, Comments. It also searches all text custom fields. If you have many text custom fields you can improve performance of your queries by searching on specific fields, e.g.
Summary ~ "some words" OR Description ~ "some words"

For details, please see the page on Performing Text Searches.

Using Auto-complete

As you type your query, JIRA will recognise the context and offer a list of "auto-complete" suggestions as follows:

The list of auto-complete suggestions is displayed alphabetically and includes the first 15 matches. Note that auto-complete suggestions are not offered for function parameters.

Please note:

If no auto-complete suggestions are offered, your administrator may have disabled the "JQL Auto-complete" feature for your JIRA instance.
If you prefer not to be offered auto-complete suggestions, click the "Turn off auto-complete" link below the "Query" box.

Auto-complete suggestions are not offered for all fields. Check the fields reference to see which fields support auto-complete.

Switching between 'Advanced' and 'Simple' Search

In general, a query created using 'Simple Search' will be able to be translated to 'Advanced Search' (i.e. JQL), and back again.

However, a query created using 'Advanced Search' may not be able to be translated to 'Simple 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 'Simple Search' form, then if it is created using 'Advanced Search' it will not be able to be translated to 'Simple Search'.

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

Keywords Reference

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.

List of Keywords:

AND

Used to combine multiple clauses, allowing you to refine your search.

Note that you can use parentheses to control the order in which clauses are executed.

Examples

Find all open issues in the "New office" project:
```
project = "New office" and status = "open"
```

Find all open, urgent issues that are assigned to jsmith:

status = open and priority = urgent and assignee = jsmith

Find all issues in a particular project that are not assigned to jsmith:
```
project = JRA and assignee != jsmith
```
Find all issues for a specific release which consists of different version numbers across several projects:
```
project in (JRA,CONF) and fixVersion = "3.14"
```
Find all issues where neither the Reporter nor the Assignee is Jack, Jill or John:
```
reporter not in (Jack,Jill,John) and assignee not in (Jack,Jill,John)
```

^top of keywords | ^^top of topic

Used to combine multiple clauses, allowing you to expand your search.

Note that you can use parentheses to control the order in which clauses are executed.

(Note: also see IN, which can be a more convenient way to search for multiple values of a field.)

Examples

Find all issues that were created by either jsmith or jbrown:
```
reporter = jsmith or reporter = jbrown
```
Find all issues that are overdue or where no due date is set:
```
duedate < now() or duedate is empty
```

^top of keywords | ^^top of topic

NOT

Used to negate individual clauses or a complex JQL query (a query made up of more than one clause) using parentheses, allowing you to refine your search.

(Note: also see NOT EQUALS ("!="), DOES NOT CONTAIN ("!~"), NOT IN and IS NOT.)

Examples

Find all issues that are assigned to any user except jsmith:
```
not assignee = jsmith
```
Find all issues that were not created by either jsmith or jbrown:
```
not (reporter = jsmith or reporter = jbrown)
```

^top of keywords | ^^top of topic

EMPTY

Used to search for issues where a given field does not have a value. See also NULL.

Note that EMPTY can only be used with fields that support the IS and IS NOT operators. To see a field's supported operators, check the individual field reference.

EMPTY is not equivalent to NOT EQUALS (!=)

Examples

Find all issues without a DueDate:
```
duedate = empty
```
or
```
duedate is empty
```

^top of keywords | ^^top of topic

NULL

Used to search for issues where a given field does not have a value. See also EMPTY.

Note that NULL can only be used with fields that support the IS and IS NOT operators. To see a field's supported operators, check the individual field reference.

Examples

Find all issues without a DueDate:
```
duedate = null
```
or
```
duedate is null
```

^top of keywords | ^^top of topic

ORDER BY

Used to specify the fields by whose values the search results will be sorted.

By default, the field's own sorting order will be used. You can override this by specifying ascending order ("asc") or descending order ("desc").

Examples

Find all issues without a DueDate, sorted by CreationDate:
```
duedate = empty order by created 
```
Find all issues without a DueDate, sorted by CreationDate, then by Priority (highest to lowest):
```
duedate = empty order by created, priority desc
```
Find all issues without a DueDate, sorted by CreationDate, then by Priority (lowest to highest):
```
duedate = empty order by created, priority asc
```

Ordering by Components or Versions will list the returned issues first by Project and only then by the field's natural order (see JRA-31113).

^top of keywords | ^^top of topic

Operators Reference

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

List of Operators:

EQUALS: =

The "=" operator is used to search for issues where the value of the specified field exactly matches the specified value. (Note: cannot be used with text fields; see the CONTAINS operator instead.)

To find issues where the value of a specified field exactly matches multiple values, use multiple "=" statements with the AND operator.

Examples

Find all issues that were created by jsmith:
```
reporter = jsmith
```
Find all issues that were created by John Smith:
```
reporter = "John Smith"
```

Jira强大的搜索语言——JQL_jira jql

Important keywords to know

AND

OR

IS

Operators

!=

>=

IN

Putting this into practice

Advanced Searching

What is an Advanced Search?

How to Perform an Advanced Search

Performing Text Searches

Using Auto-complete

Switching between 'Advanced' and 'Simple' Search

Setting Precedence of Operators

Keywords Reference

Operators Reference

Fields Reference