Jira’s Query Language, or Jira JQL, is a powerful tool that allows users to create detailed queries to filter and report data within Jira and Jira Service Management (JSM). From simple tasks like finding all the issues assigned to you to more complex queries spanning multiple projects, JQL is a key skill for any Jira user. Whether you’re new to JQL or looking to deepen your understanding, this guide is here to help. Let’s dive in.

What is Jira JQL?

JQL stands for Jira Query Language also known simple as Jira JQL. It’s a structured command language that allows you to retrieve specific information from Jira based on certain criteria. Think of it as the “Google search” for Jira. Instead of sifting through countless tasks, bugs, or updates manually, you can use JQL to pinpoint exactly what you need.

Before diving into JQL queries and unleashing their power, it’s essential to know how to access the JQL search interface within Jira. Here’s a step-by-step guide:

1. Login to Your Jira Instance

  • Begin by logging into your Jira account. Make sure you have the appropriate permissions to perform searches.

2. Access the ‘Issues’ Dropdown

  • Once logged in, look for the ‘Issues’ dropdown in the top navigation bar.

3. Choose ‘Search for Issues’

  • From the ‘Issues’ dropdown, select ‘Search for Issues’. This will lead you to the issue search interface.

4. Switch to Advanced Search

  • By default, Jira opens the ‘Basic Search’ interface. To use JQL, you need the ‘Advanced Search’.
  • Directly above the search filters, there’s a switch to toggle between ‘Basic’ and ‘Advanced’ search. Click on ‘Advanced’.

5. Start Writing Your JQL Query

  • Once in ‘Advanced Search’, you’ll see a text box where you can write or paste your JQL query. As you type, Jira will offer auto-complete suggestions to help formulate your query.

6. Execute the Query

  • After entering your JQL query, press the ‘Search’ button (or simply hit ‘Enter’) to execute the search. The results matching your query will be displayed below.

Tips:

  • Saving Queries: After creating a JQL query, you can save it as a filter for future access. This is especially handy for searches you’ll perform regularly.
  • Modifying the View: Once you get your search results, you can modify the displayed columns by clicking on the ‘Columns’ dropdown. This allows you to see the fields most relevant to your search.
  • Sharing Queries: If you’ve created a useful query, you can share its results with teammates by sharing the filter.

Remember, while JQL is a powerful tool, always ensure that your queries are precise to avoid overwhelming the system, especially in large Jira instances.

The Basics of Jira JQL:

Basic Search vs. Advanced Search

  • Explanation: Jira offers two main types of search: Basic and Advanced. The Basic search provides a user-friendly interface where you can select criteria from drop-down menus. Advanced search, on the other hand, lets you input JQL queries directly for more specific and complex searches.
  • Example: Imagine you’re quickly skimming through tasks assigned to you. A basic search would suffice. But if you’re trying to find all high-priority tasks created in the last week across multiple projects? That’s where advanced search comes in.
Check Atlassian’s Jira Complete JQL Documentation Here

Fields and Operators

Understanding Standard Fields

  • Explanation: Fields in Jira are essentially categories or attributes that each issue has.
  • Query: reporter = john.doe
  • Example: Want to see all the issues John Doe reported? This query will do the trick.

Using Operators for Precision

Operators help refine searches. Here’s a breakdown of some commonly used operators:

  • = : Equal to
  • != : Not equal to
  • > : Greater than
  • < : Less than
  • >= : Greater than or equal to
  • <= : Less than or equal to
  • IN : Matches any of the specified values
  • NOT IN : Does not match any of the specified values
  • ~ : Contains (for text fields)
  • !~ : Does not contain (for text fields)
  • IS : Is empty
  • IS NOT : Is not empty
  • Query: created >= "2023-09-01" AND priority IN ("High", "Critical")
  • Example: To find high-priority tasks from September 2023 onward, this query is your go-to.

Intermediate JQL Techniques

While you’ve mastered the basics, there’s a lot more JQL has to offer. As you delve deeper into JQL, you’ll discover functions that can provide even more tailored results, aiding in various team and project scenarios.

Working with Date and Time Functions

  • Explanation: Jira allows you to query based on dates using functions like startOfDay, endOfDay, startOfWeek, and more.
  • Query: updatedDate > startOfMonth()
  • Example: To see what issues were updated this month, use the above query.

Using the “WAS” and “CHANGED” Operators

  • Explanation: These operators are used to find issues based on their historical data.
  • Query: status WAS "In Progress" DURING ("2023-09-01", "2023-09-15")
  • Example: Curious about which tasks were “In Progress” during the first half of September 2023? This query has you covered.

Using JQL Functions for Specific Searches

membersOf() Function

  • Explanation: Often, teams in Jira are grouped for permissions or notifications. The membersOf() function lets you query issues based on these team groups, making it easier to see tasks allocated to a whole team or department.
  • Syntax: membersOf("group-name")
  • Example: If you want to fetch all issues assigned to the QA team represented by the group “jira-qa”: assignee in membersOf("jira-qa")

lastLogin() Function

  • Explanation: Sometimes, you might want to track issues based on user activity. The lastLogin() function allows you to fetch issues created, updated, or resolved since a user’s last login, aiding in triage or follow-up scenarios.
  • Syntax: fieldName >= lastLogin()
  • Example: To get bugs reported since your last login: issuetype = Bug AND createdDate >= lastLogin()

filter Function

Credits for Images go to Atlassian
  • Explanation: Jira allows you to save certain searches as filters. With the filter function, you can reference these saved searches in your JQL queries, letting you build upon pre-existing searches.
  • Syntax: filter = "Filter Name"
  • Example: If you have a filter named “High Priority Bugs” and you want to find those which are unresolved: filter = "High Priority Bugs" AND resolution = Unresolved

changed Function

  • Explanation: Tracking field changes can be critical in certain workflows. The changed function lets you query issues where a particular field’s value has been modified.
  • Syntax: fieldName changed DURING ("startDateTime", "endDateTime")
  • Example: To find issues where priority was changed in the last week: priority changed DURING (startOfWeek(), endOfWeek())
  • Explanation: Issues in Jira can be linked for various reasons like blockers, duplicates, or dependencies. The issueLinkType function allows you to find issues based on these link types.
  • Syntax: issueLinkType in (linkType)
  • Example: To fetch all issues that are blocking other tasks: issueLinkType in (blocks)
  • Explanation: For agile teams using epics to group tasks, these functions allow you to search based on epic linkages. It’s a great way to see the broader picture or drill down into specific epics.
  • Syntax (Cloud): issueKey in parentEpic("EPC-123")
  • Syntax (Server/DC): issueKey in "Epic Link" = EPC-123
  • Example: To retrieve all tasks under the epic “EPC-123”: issueKey in parentEpic("EPC-123") (for Cloud)

Advanced Jira JQL Techniques for Service Management (JSM)

Approval Flow Functions

  • Explanation: These functions help in sorting out Jira Service Management queues related to approvals.
  • Query: approval = approved()
  • Example: To find out tickets that have been approved and are ready to be worked upon, this is your query.

SLA Timer Functions

  • Explanation: JSM allows you to monitor Service Level Agreement (SLA) timers. These functions help you track active SLAs or those close to breach.
  • Query: "Time to First Response" = paused()
  • Example: Need a list of tickets where the SLA timer is paused? Here’s how.

JQL is a versatile tool in the Jira toolkit. With practice and understanding, you can tailor it to extract precise information, optimize workflows, and make data-driven decisions. As you advance in your Jira journey, remember that mastering Jira JQL is about understanding its logic and structure. With this guide in hand, you’re well on your way.

Categorized in:

Jira

Tagged in:

, , ,