Skip to content
W3S101

JIRA - Advanced Search

Jira - Advanced Search using JQL

Section titled “Jira - Advanced Search using JQL”

Beyond basic search filters, Jira offers powerful advanced search capabilities primarily through Jira Query Language (JQL). JQL is a flexible and structured query language that allows you to construct precise queries to find exactly the issues you need across your Jira instance. Mastering JQL is key to efficiently navigating and managing issues.

Key points about JQL and advanced search:

  • Structured Queries: JQL uses a specific syntax comprising fields, operators, values, and keywords to define search criteria.
  • Issue Navigator: Search results from JQL queries are displayed in the Issue Navigator, which offers various views (e.g., list view, detail view) and sorting options.
  • Export Options: Results from the Issue Navigator can typically be exported to formats like CSV, Excel (via XML/HTML), and Word, depending on your Jira configuration and permissions.
  • Saved Filters and Subscriptions: JQL queries can be saved as ‘Filters’. These filters can be reused, shared with other users or groups, subscribed to for periodic email notifications of matching issues, and used to populate gadgets on Jira Dashboards.
  • Not SQL: While JQL’s syntax may resemble SQL (e.g., it uses ORDER BY), it is not a database query language. JQL operates on Jira’s issue data index and has its own specific functions and limitations. For instance, JQL does not support GROUP BY for direct aggregation in the query itself; aggregations are typically handled by reports or dashboard gadgets using saved JQL filters.

A simple JQL query consists of a field, followed by an operator, and then one or more values or functions. For example, to find all issues in the project with key “WFT”:

project = "WFT"

To access advanced search (JQL):

  1. Navigate to ‘Filters’ or ‘Issues’ from the main Jira navigation menu, then select ‘Advanced issue search’ (the exact wording might vary, e.g., ‘Search issues’).
  2. If you are initially in ‘Basic’ search mode (with dropdowns and input fields), look for a link or button to switch to JQL mode. This is often labeled ‘Switch to JQL’, ‘Advanced’, or ‘JQL’.

Understanding JQL Components

Section titled “Understanding JQL Components”

A JQL query is built using fields, operators, values, and keywords.

1. Fields

Section titled “1. Fields”

A ‘field’ in JQL represents an issue attribute that you can query. Jira has many system fields and also supports custom fields created by administrators.

Common system fields include:

  • project: The project an issue belongs to.
  • issueType: The type of issue (e.g., Bug, Story, Task).
  • status: The current status of an issue in its workflow (e.g., Open, In Progress, Resolved).
  • assignee: The user to whom the issue is currently assigned.
  • reporter: The user who created the issue.
  • priority: The priority level of the issue (e.g., High, Medium, Low).
  • resolution: The reason an issue was closed (e.g., Fixed, Won’t Fix).
  • created, updated, dueDate: Date fields related to issue creation, last update, and due date.
  • summary, description, comment: Text fields for searching within issue content.
  • labels: Labels associated with an issue.
  • fixVersion: The version in which an issue is or was planned to be fixed.
  • component: The project component an issue relates to.

As you type in the JQL editor, Jira provides auto-completion suggestions for fields. For example, to search for an issue with a specific key:

issueKey = "WFT-107"

2. Operators

Section titled “2. Operators”

Operators are used to compare a field’s value with one or more values or functions on the right side of a JQL clause. They define the relationship or condition to be met.

Common operators include:

  • Equality: = (equals), != (not equals)
  • Comparison: > (greater than), < (less than), >= (greater than or equals), <= (less than or equals) - for numbers, dates, and versions.
  • Membership: IN (value is one of several specified), NOT IN (value is not one of several specified)
  • Text Matching: ~ (CONTAINS - for fuzzy text search), !~ (DOES NOT CONTAIN)
  • Existence: IS EMPTY (field has no value, or is null), IS NOT EMPTY (field has a value)

Example using operators:

priority = High
status != Closed
votes >= 5
summary ~ "authentication error"
assignee IS EMPTY

3. Values and Functions

Section titled “3. Values and Functions”

Values are the specific data you are searching for. They can be text strings (enclosed in quotes if they contain spaces or are reserved words), numbers, dates, or predefined Jira entities (like statuses or priorities).

Functions in JQL dynamically provide values. Examples:

  • currentUser(): Represents the currently logged-in user.
  • now(): Represents the current date and time.
  • membersOf("group_name"): Represents all members of a specified Jira group.
assignee = currentUser()
dueDate < now()
project = "Omega" AND status IN ("Open", "In Progress")

4. Keywords

Section titled “4. Keywords”

Keywords in JQL are used to combine multiple clauses, negate conditions, or order the results.

  • AND: Combines two clauses; both must be true. Ex: status = Open AND priority = High
  • OR: Combines two clauses; at least one must be true. Ex: dueDate < now() OR dueDate IS EMPTY
  • NOT: Negates the following clause. Ex: NOT assignee = "jsmith" (or assignee != "jsmith")
  • EMPTY: Used with IS or IS NOT to check for empty fields. Ex: fixVersion IS EMPTY
  • ORDER BY: Sorts the search results by one or more fields, optionally with ASC (ascending) or DESC (descending). Ex: project = "Omega" ORDER BY createdDate DESC, priority ASC

Jira’s JQL editor provides auto-completion for keywords, fields, operators, and known values, making it easier to construct valid queries. After typing your query, press Enter or click the search icon to execute it. For a comprehensive list of all JQL fields, operators, keywords, and functions, refer to the official Atlassian Jira documentation.