How to jql search in jira

Overview

Jira is a popular project management and issue tracking tool used by software development teams and many other organizations. To effectively manage and find the specific information you need within Jira, mastering its search capabilities is crucial. The primary way to perform advanced searches in Jira is by using JQL, which stands for Jira Query Language. JQL is a flexible and powerful language that allows you to construct precise queries to pinpoint the exact issues, tasks, bugs, or stories you're looking for.

What is JQL?

JQL is a proprietary query language developed by Atlassian, the creators of Jira. It's designed to be human-readable and intuitive, making it accessible even for users who are not deeply technical. Unlike simple keyword searches, JQL allows you to combine multiple criteria using logical operators, specify fields, and use various functions to refine your search results. This makes it an indispensable tool for anyone who regularly works with Jira.

Getting Started with JQL Search

There are two primary ways to start using JQL in Jira:

1. Quick Search Bar: Most Jira instances have a search bar prominently displayed at the top of the interface. You can often type simple JQL queries directly into this bar.
2. Advanced Search: For more complex queries or to build them visually, Jira offers an "Advanced Search" feature. This is typically accessed via the "Issues" or "Search" menu. Advanced search often provides a "JQL" mode where you can type your query, and sometimes a "Basic" mode that helps you construct JQL queries using dropdown menus and text fields.

Basic JQL Syntax and Operators

JQL queries are structured as a series of fields, operators, and values. Here's a breakdown of common components:

Fields

Fields represent the different attributes of a Jira issue. Some of the most commonly used fields include:

• project: The project the issue belongs to (e.g., project = "MyProject").
• issuetype: The type of issue (e.g., issuetype = Bug).
• status: The current status of the issue (e.g., status = "In Progress").
• assignee: The user assigned to the issue (e.g., assignee = currentUser()).
• reporter: The user who created the issue (e.g., reporter = "john.doe").
• summary: The title or brief description of the issue (e.g., summary ~ "login error").
• description: The detailed description of the issue.
• created: The date the issue was created.
• updated: The date the issue was last updated.
• priority: The priority level of the issue (e.g., priority = High).
• labels: Labels attached to the issue (e.g., labels = "performance").

Operators

Operators are used to define the relationship between a field and its value. Common operators include:

• = (equals): Matches exactly (e.g., project = "MyProject").
• != (not equals): Does not match (e.g., status != Closed).
• <, >, <=, >=: For numerical or date comparisons (e.g., created > "2023/01/01").
• IN, NOT IN: Matches or does not match any value in a list (e.g., status IN (Open, "In Progress")).
• ~ (contains): For text fields, matches if the text is present (e.g., summary ~ "urgent").
• IS EMPTY, IS NOT EMPTY: Checks if a field has no value or has a value (e.g., assignee IS EMPTY).

Logical Operators

Combine multiple JQL clauses using logical operators:

• AND: Both conditions must be true (e.g., project = "MyProject" AND status = Open).
• OR: Either condition can be true (e.g., assignee = currentUser() OR reporter = currentUser()).
• NOT: Negates the following clause (e.g., project = "MyProject" AND NOT status = Closed).
• Parentheses (): Used to group clauses and control the order of operations, similar to mathematical expressions (e.g., project = "MyProject" AND (status = Open OR priority = High)).

Wildcards

Wildcards allow for flexible text matching:

• * (asterisk): Matches zero or more characters (e.g., summary ~ "error*" will match "error", "errors", "error message").
• ? (question mark): Matches exactly one character (e.g., summary ~ "err?r" will match "error" but not "errer").

Useful JQL Functions

Jira provides built-in functions that make your queries dynamic and powerful:

• currentUser(): Represents the currently logged-in user. Useful for finding issues assigned to you, reported by you, etc. (e.g., assignee = currentUser()).
• membersOf("groupName"): Finds issues where the assignee or reporter is a member of a specified Jira group (e.g., assignee IN membersOf("developers")).
• now(): Represents the current date and time.
• startOfDay(), endOfDay(), startOfMonth(), endOfMonth(), etc.: Useful for date-based queries (e.g., created > startOfDay("-7d") finds issues created in the last 7 days).
• linkedIssues(issueKey, "linkType"): Finds issues linked to a specific issue with a given link type.

Common JQL Use Cases and Examples

Here are some practical examples of JQL queries you might use:

• Find all open bugs in the "Website" project:
  project = "Website" AND issuetype = Bug AND status != Closed
• Find issues assigned to you that are not yet resolved:
  assignee = currentUser() AND resolution = Unresolved
• Find tasks created in the last week:
  issuetype = Task AND created >= startOfDay("-7d")
• Find issues with high priority or critical severity:
  priority = High OR priority = Critical
• Find issues that contain the word "performance" in the summary:
  summary ~ "performance"
• Find issues assigned to anyone in the "QA Team" group that are still open:
  assignee IN membersOf("QA Team") AND status = Open

Saving and Using JQL Filters

Once you've crafted a JQL query that returns the results you need, you can save it as a filter. This allows you to run the same search again with a single click. Saved filters can also be used in Jira dashboards, for notifications, and in automation rules, making your workflow much more efficient.

Tips for Effective JQL Searching

• Be Specific: The more specific your query, the better your results will be.
• Use Parentheses: Grouping clauses with parentheses is essential for complex queries to ensure the logic is applied correctly.
• Check Field Names: Ensure you are using the correct field names for your Jira instance, as custom fields can vary.
• Test Your Queries: Start with simpler queries and gradually add complexity. The "Advanced Search" mode often provides instant feedback on your query's validity.
• Leverage Functions: Functions like currentUser() and date functions save time and make your filters dynamic.

By understanding and utilizing JQL, you can significantly enhance your ability to navigate and manage information within Jira, leading to increased productivity and better project oversight.