Jira JQL 101: Mastering the Art of Jira Query Language
Danish Nadeem
Dynamic | Certified | Agile Transformation Coach | Kanban Coach & TKP | Agile Facilitator | Agile Coach | CSM-CSPO | Enterprise Agility Coach | Management Consulting | Jira SME | Agile Management Coaching
Discover the power of JQL with Jira JQL 101: Mastering Advanced Searches in Jira Cloud. Whether you're a beginner or a seasoned Jira user, this comprehensive book will guide you through the intricacies of JQL, empowering you to harness its full potential.
With step-by-step instructions and numerous examples, you'll learn how to effectively use JQL to search and filter your Jira issues.
Learn More: https://agilexjira.gumroad.com/l/jira
Introduction to JQL
1.1 What is JQL?
Jira Query Language (JQL) is a powerful and flexible search language used in Jira Cloud to retrieve and filter issues based on specific criteria. It allows users to perform advanced searches and create custom filters to find the information they need quickly and efficiently. JQL is a fundamental tool for Jira users, enabling them to navigate through large datasets and locate relevant issues with ease.
JQL operates on a simple yet effective syntax that consists of keywords, operators, and functions. By combining these elements, users can construct complex queries to narrow down their search results and obtain precise information. JQL queries can be executed in various areas of Jira, including the issue navigator, filters, dashboards, and reports.
With JQL, users can search for issues based on a wide range of criteria, such as issue type, status, assignee, reporter, priority, labels, components, and more. It also supports advanced features like searching by date, subtasks, linked issues, epics, sprints, and custom fields. JQL provides a comprehensive set of tools to meet the diverse needs of Jira users across different projects and workflows.
JQL is not only a search language but also a powerful reporting tool. It allows users to generate reports and visualize data by aggregating and summarizing issue information. By leveraging JQL’s functions and operators, users can create dynamic and interactive dashboards that provide real-time insights into project progress, team performance, and issue trends.
JQL is designed to be user-friendly and intuitive, even for those with limited technical knowledge. Its syntax is straightforward and easy to understand, making it accessible to both beginners and experienced Jira users. With a little practice and familiarity, users can quickly become proficient in crafting complex JQL queries to meet their specific requirements.
1.2 Why use JQL?
Jira Query Language (JQL) is a powerful tool that allows users to search and filter issues in Jira based on various criteria. It provides a flexible and efficient way to retrieve the specific information you need from your Jira instance. Whether you are a project manager, developer, or any other role involved in managing projects and tasks, JQL can greatly enhance your productivity and help you make informed decisions.
1.2.1 Simplify Issue Tracking
One of the primary reasons to use JQL is to simplify issue tracking. Jira is a robust project management tool that allows you to create and track issues throughout their lifecycle. However, as the number of issues grows, it becomes increasingly challenging to find the information you need. JQL enables you to narrow down your search and quickly locate the relevant issues based on specific criteria such as issue type, status, assignee, and more.
1.2.2 Efficiently Manage Workloads
JQL empowers you to efficiently manage workloads by providing a comprehensive set of search capabilities. With JQL, you can filter issues based on their priority, due date, and other custom fields. This allows you to prioritize and allocate resources effectively, ensuring that critical tasks are addressed promptly. By leveraging JQL’s advanced querying capabilities, you can create custom filters and saved searches to monitor workloads and track progress.
1.2.3 Gain Insights and Generate Reports
JQL enables you to gain valuable insights into your projects and generate reports with ease. By querying issues based on specific criteria, you can analyze trends, identify bottlenecks, and track key performance indicators. JQL’s ability to aggregate data and perform calculations using functions and operators allows you to create meaningful reports that provide actionable insights to stakeholders.
1.2.4 Customize and Personalize Your Jira Experience
JQL offers a high degree of customization, allowing you to tailor your Jira experience to meet your specific needs. By creating custom filters and saved searches, you can save time and effort by quickly accessing the information you frequently require. JQL also enables you to create custom dashboards and boards, providing a personalized view of your projects and tasks.
1.2.5 Streamline Collaboration and Communication
JQL plays a crucial role in streamlining collaboration and communication within teams. By using JQL to filter issues based on assignees, reporters, or specific labels, you can easily identify tasks that require attention or involve specific team members. This promotes effective communication and coordination, ensuring that everyone is on the same page and working towards common goals.
1.2.6 Enhance Issue Tracking Workflows
JQL allows you to enhance your issue tracking workflows by creating complex queries that reflect your specific business requirements. By leveraging JQL’s logical operators, you can combine multiple criteria to create sophisticated filters. This enables you to define intricate workflows and automate processes, ensuring that issues are routed to the appropriate teams or individuals based on specific conditions.
1.2.7 Improve Decision-Making
JQL provides the necessary tools to improve decision-making by enabling you to retrieve the precise information you need. Whether you are a project manager assessing project progress or a developer troubleshooting a specific issue, JQL allows you to query issues based on relevant attributes. This empowers you to make informed decisions based on accurate and up-to-date data.
1.2.8 Increase Productivity and Efficiency
By mastering JQL, you can significantly increase your productivity and efficiency in managing Jira projects. JQL’s ability to quickly retrieve the information you need, create custom filters, and automate workflows saves valuable time and effort. With JQL, you can focus on the tasks that matter most and streamline your project management processes.
1.2.9 Unlock the Full Potential of Jira
JQL is a fundamental component of Jira’s powerful capabilities. By understanding and utilizing JQL effectively, you can unlock the full potential of Jira as a project management tool. Whether you are a beginner or an experienced Jira user, mastering JQL will enable you to harness the full power of Jira and optimize your project management workflows.
In the following chapters, we will delve deeper into the various aspects of JQL, exploring its syntax, operators, functions, and keywords. We will provide numerous examples and best practices to help you become proficient in using JQL for basic and advanced searches. So, let’s embark on this journey to master the art of Jira Querying Language and unlock the true potential of Jira!
1.3 JQL Syntax
Jira Query Language (JQL) is a powerful tool that allows you to search and filter issues in Jira based on specific criteria. To effectively use JQL, it is important to understand its syntax, which consists of various elements and operators. This section will provide an overview of the JQL syntax and its components.
1.3.1 Keywords
Keywords are the building blocks of JQL queries. They represent specific entities or actions within Jira. Some commonly used keywords include:
?????????? project: Specifies the project(s) to search within.
?????????? issueType: Filters issues based on their type.
?????????? status: Searches for issues with a specific status.
?????????? assignee: Filters issues based on the assignee.
?????????? reporter: Searches for issues reported by a specific user.
?????????? priority: Filters issues based on their priority.
?????????? labels: Searches for issues with specific labels.
?????????? component: Filters issues based on the component(s) they belong to.
?????????? created: Searches for issues created within a specific date range.
?????????? updated: Filters issues based on their last update date.
?????????? resolution: Searches for issues with a specific resolution.
1.3.2 Operators
Operators are used to define relationships between different elements in a JQL query. They allow you to combine multiple criteria to create more complex search conditions. Some commonly used operators in JQL include:
?????????? =: Matches the exact value.
?????????? !=: Does not match the value.
?????????? ~: Matches the value using a regular expression.
?????????? IN: Matches any of the specified values.
?????????? NOT IN: Does not match any of the specified values.
?????????? IS EMPTY: Matches fields that have no value.
?????????? IS NOT EMPTY: Matches fields that have a value.
?????????? >, <, >=, <=: Matches values greater than, less than, greater than or equal to, or less than or equal to the specified value.
?????????? AND, OR: Combines multiple criteria using logical operators.
1.3.3 Field Names
Field names represent the different attributes or properties of an issue in Jira. They are used to specify which fields to search or filter on. Some commonly used field names include:
?????????? summary: Represents the summary or title of an issue.
?????????? description: Represents the description of an issue.
?????????? comment: Represents the comments added to an issue.
?????????? duedate: Represents the due date of an issue.
?????????? resolutiondate: Represents the date when an issue was resolved.
?????????? issuetype: Represents the type of an issue.
?????????? status: Represents the status of an issue.
?????????? assignee: Represents the assignee of an issue.
?????????? reporter: Represents the user who reported the issue.
?????????? priority: Represents the priority of an issue.
?????????? labels: Represents the labels associated with an issue.
?????????? component: Represents the component(s) an issue belongs to.
1.3.4 Field Values
Field values are the specific values associated with a field in Jira. They can be used to filter or search for issues based on specific criteria. Field values can be:
?????????? Text: Any alphanumeric value or a string enclosed in quotes.
?????????? Numbers: Numeric values.
?????????? Dates: Dates in a specific format.
?????????? Users: Usernames or user keys.
?????????? Issue keys: Unique identifiers for issues in Jira.
?????????? Labels: Labels associated with an issue.
?????????? Components: Names of the components an issue belongs to.
1.3.5 Functions
JQL also supports functions that allow you to perform more advanced operations on fields or values. Functions can be used to calculate durations, perform date arithmetic, extract specific parts of a field value, and more. Some commonly used functions in JQL include:
?????????? startOfDay(): Returns the start of the current day.
?????????? endOfDay(): Returns the end of the current day.
?????????? startOfWeek(): Returns the start of the current week.
?????????? endOfWeek(): Returns the end of the current week.
?????????? startOfMonth(): Returns the start of the current month.
?????????? endOfMonth(): Returns the end of the current month.
?????????? startOfYear(): Returns the start of the current year.
?????????? endOfYear(): Returns the end of the current year.
?????????? now(): Returns the current date and time.
1.3.6 Examples
To illustrate the JQL syntax, let’s consider a few examples:
?????????? To search for all open issues in the “Project X” project, you can use the following query: project = "Project X" AND status = Open.
?????????? To find all issues assigned to a specific user, you can use the following query: assignee = "John Doe".
?????????? To search for issues created in the last 7 days, you can use the following query: created >= -7d.
?????????? To filter issues based on their priority and status, you can use the following query: priority = High AND status = "In Progress".
These examples demonstrate how different elements of the JQL syntax can be combined to create powerful and targeted queries.
In the next section, we will explore the various operators available in JQL and how they can be used to refine your search criteria.
Conclusion
Understanding the syntax of JQL is essential for effectively searching and filtering issues in Jira. In this section, we covered the keywords, operators, field names, field values, and functions that make up the JQL syntax. By mastering these elements, you will be able to construct complex queries to retrieve the exact information you need from your Jira instance. In the next section, we will delve deeper into the different operators available in JQL and explore how they can be used to create more advanced queries.
1.4 JQL Operators
JQL operators are an essential component of the Jira Query Language (JQL) that allow you to perform specific actions and comparisons in your search queries. By understanding and utilizing these operators effectively, you can refine your searches and retrieve the precise information you need from your Jira issues.
1.4.1 Comparison Operators
Comparison operators in JQL enable you to compare values and perform actions based on the result. These operators include:
?????????? = (equals): Matches issues with a specific value.
?????????? != (not equals): Matches issues that do not have a specific value.
?????????? > (greater than): Matches issues with a value greater than the specified value.
?????????? < (less than): Matches issues with a value less than the specified value.
?????????? >= (greater than or equals): Matches issues with a value greater than or equal to the specified value.
?????????? <= (less than or equals): Matches issues with a value less than or equal to the specified value.
?????????? ~ (contains): Matches issues that contain a specific value.
?????????? !~ (does not contain): Matches issues that do not contain a specific value.
?????????? IN: Matches issues with a value that is within a specified set of values.
?????????? NOT IN: Matches issues with a value that is not within a specified set of values.
For example, if you want to find all issues with a priority level of “High,” you can use the equals operator (=) as follows:
priority = "High"
1.4.2 Logical Operators
Logical operators in JQL allow you to combine multiple conditions in your search queries. These operators include:
?????????? AND: Matches issues that satisfy all the specified conditions.
?????????? OR: Matches issues that satisfy at least one of the specified conditions.
?????????? NOT: Matches issues that do not satisfy the specified condition.
By using logical operators, you can create complex queries to narrow down your search results. For example, if you want to find all issues assigned to either “John” or “Jane,” you can use the OR operator as follows:
assignee = "John" OR assignee = "Jane"
1.4.3 Mathematical Operators
Mathematical operators in JQL allow you to perform calculations and comparisons on numerical values. These operators include:
?????????? + (addition): Adds two or more values together.
?????????? - (subtraction): Subtracts one value from another.
?????????? * (multiplication): Multiplies two or more values.
?????????? / (division): Divides one value by another.
?????????? % (modulus): Returns the remainder of a division operation.
These operators can be used in combination with other JQL elements to create dynamic queries. For example, if you want to find all issues with a story point value greater than 5, you can use the greater than operator (>) as follows:
storyPoints > 5
1.4.4 String Operators
String operators in JQL allow you to perform actions and comparisons on text values. These operators include:
?????????? ~ (matches): Matches issues that contain a specific pattern or regular expression.
?????????? !~ (does not match): Matches issues that do not contain a specific pattern or regular expression.
These operators are useful when searching for issues based on specific text patterns or keywords. For example, if you want to find all issues with a summary that contains the word “bug,” you can use the matches operator (~) as follows:
summary ~ "bug"
1.4.5 Date Operators
Date operators in JQL allow you to perform actions and comparisons on date values. These operators include:
?????????? = (equals): Matches issues with a specific date.
?????????? != (not equals): Matches issues that do not have a specific date.
?????????? > (after): Matches issues with a date after the specified value.
?????????? < (before): Matches issues with a date before the specified value.
?????????? >= (on or after): Matches issues with a date on or after the specified value.
?????????? <= (on or before): Matches issues with a date on or before the specified value.
?????????? IN: Matches issues with a date that is within a specified range.
?????????? NOT IN: Matches issues with a date that is not within a specified range.
These operators are useful when searching for issues based on specific dates or date ranges. For example, if you want to find all issues created after a certain date, you can use the after operator (>) as follows:
created > "2022-01-01"
1.4.6 Aggregate Operators
Aggregate operators in JQL allow you to perform calculations and aggregations on fields that contain numerical values. These operators include:
?????????? SUM: Calculates the sum of the values in a field.
?????????? AVG: Calculates the average of the values in a field.
?????????? MIN: Retrieves the minimum value from a field.
?????????? MAX: Retrieves the maximum value from a field.
?????????? COUNT: Counts the number of values in a field.
These operators are useful when you need to perform calculations or retrieve statistical information from your Jira issues. For example, if you want to calculate the total story points for all issues in a project, you can use the SUM operator as follows:
project = "Project X" AND issuetype = "Story" RETURN SUM(storyPoints)
1.4.7 Membership Operators
Membership operators in JQL allow you to search for issues based on their membership in a specific group or project role. These operators include:
?????????? MEMBERS OF: Matches issues that are assigned to members of a specific group or project role.
?????????? NOT MEMBERS OF: Matches issues that are not assigned to members of a specific group or project role.
These operators are useful when you need to search for issues based on their assignment to specific groups or project roles. For example, if you want to find all issues assigned to members of the “Developers” group, you can use the MEMBERS OF operator as follows:
assignee IN membersOf("Developers")
1.4.8 Existence Operators
Existence operators in JQL allow you to search for issues based on the presence or absence of a specific field or value. These operators include:
?????????? IS EMPTY: Matches issues that have a specific field empty.
?????????? IS NOT EMPTY: Matches issues that have a specific field populated.
These operators are useful when you need to search for issues based on the presence or absence of certain information. For example, if you want to find all issues without a description, you can use the IS EMPTY operator as follows:
description IS EMPTY
1.4.9 Negation Operator
The negation operator in JQL allows you to negate a condition or expression in your search query. This operator is represented by the exclamation mark (!). It can be used with any other operator to invert the result. For example, if you want to find all issues that are not assigned to the user “John,” you can use the negation operator as follows:
assignee != "John"
By utilizing these JQL operators effectively, you can construct powerful and precise search queries to retrieve the exact information you need from your Jira issues. Experiment with different combinations of operators and explore the possibilities to master the art of JQL querying.
1.5 JQL Functions
JQL functions are powerful tools that allow you to perform complex searches and calculations in Jira. They provide additional functionality beyond what is available with JQL operators alone. In this section, we will explore the various JQL functions and how they can enhance your Jira querying experience.
1.5.1 Built-in Functions
Jira provides a set of built-in functions that you can use in your JQL queries. These functions cover a wide range of use cases and can help you retrieve the information you need more efficiently. Some of the commonly used built-in functions include:
?????????? issueFunction: This function allows you to search for issues based on specific criteria, such as issues that have subtasks or issues that are linked to a particular issue.
?????????? dateCompare: With this function, you can compare dates and perform date-based calculations in your JQL queries. For example, you can find issues that were created before a certain date or issues that are due within a specific time frame.
?????????? currentUser: This function enables you to search for issues that are assigned to the currently logged-in user. It is particularly useful for personal task management and tracking.
?????????? project: You can use this function to search for issues that belong to a specific project or projects. It allows you to narrow down your search scope and focus on a particular project’s issues.
?????????? sprint: This function is specifically designed for Agile projects and allows you to search for issues that are associated with a particular sprint. It helps you track the progress of your Agile development efforts.
1.5.2 Custom Functions
In addition to the built-in functions, Jira also allows you to create custom functions to meet your specific needs. Custom functions can be created using Jira’s scripting capabilities, such as Jira ScriptRunner or Jira Automation. These functions can perform complex calculations, automate repetitive tasks, or integrate with external systems.
Creating custom functions requires some programming knowledge, but it opens up a world of possibilities for extending Jira’s functionality. You can create functions to calculate custom metrics, generate reports, or automate workflows. The flexibility of custom functions allows you to tailor Jira to your unique requirements.
1.5.3 Function Syntax
JQL functions have a specific syntax that you need to follow when using them in your queries. The general syntax for a JQL function is as follows:
functionName(arguments)
The functionName is the name of the function you want to use, and the arguments are the parameters or values that the function requires. The number and type of arguments vary depending on the function.
For example, if you want to use the dateCompare function to find issues that were created within the last 7 days, you would use the following syntax:
createdDate >= dateCompare(-7d)
In this example, the dateCompare function is used to subtract 7 days from the current date, and the createdDate field is compared against the result.
1.5.4 Function Examples
To better understand how JQL functions work, let’s explore some examples:
?????????? Example 1: Finding issues assigned to the current user
????? assignee = currentUser()
??????????? This query will return all issues that are currently assigned to the logged-in user.
?????????? Example 2: Searching for issues in a specific project
????? project = project("My Project")
??????????? This query will retrieve all issues that belong to the project named “My Project.”
?????????? Example 3: Filtering issues based on their due date
????? dueDate <= endOfDay()
??????????? This query will return all issues that are due today or earlier.
These examples demonstrate how JQL functions can be used to perform advanced searches and filter issues based on specific criteria.
1.5.5 Best Practices for Using JQL Functions
To make the most of JQL functions, consider the following best practices:
1.??????? Understand the available functions: Familiarize yourself with the built-in functions provided by Jira and explore any additional functions offered by plugins or custom scripts.
2.??????? Read the documentation: Refer to the official Jira documentation or relevant plugin documentation to understand the syntax and usage of each function.
3.??????? Test your queries: Before using complex JQL functions in production, test them in a test environment to ensure they return the expected results.
4.??????? Combine functions with operators: JQL functions can be combined with operators to create more precise queries. Experiment with different combinations to refine your search results.
5.??????? Use functions sparingly: While JQL functions can be powerful, excessive use of functions in your queries can impact performance. Use them only when necessary and consider alternative approaches if possible.
By following these best practices, you can leverage JQL functions effectively and unlock the full potential of Jira’s querying capabilities.
In the next section, we will explore the various keywords used in JQL and how they can enhance your search queries.
1.6 JQL Keywords
JQL (Jira Query Language) is a powerful tool that allows you to search and filter your Jira issues based on specific criteria. In this section, we will explore the various keywords that you can use in JQL to enhance your search capabilities and retrieve the desired results.
1.6.1 Basic Keywords
JQL provides a set of basic keywords that form the foundation of your search queries. These keywords include:
?????????? project: Allows you to search for issues within a specific project.
?????????? issueType: Enables you to filter issues based on their type, such as bug, task, or story.
?????????? status: Helps you find issues that are in a particular status, such as open, in progress, or resolved.
?????????? assignee: Allows you to search for issues assigned to a specific user.
?????????? reporter: Enables you to find issues reported by a particular user.
?????????? priority: Helps you filter issues based on their priority level, such as high, medium, or low.
?????????? labels: Allows you to search for issues that have specific labels assigned to them.
?????????? components: Enables you to filter issues based on the components they are associated with.
?????????? created: Helps you find issues created within a specific date range.
1.6.2 Advanced Keywords
In addition to the basic keywords, JQL also provides advanced keywords that allow for more complex and precise searches. These advanced keywords include:
?????????? resolution: Enables you to filter issues based on their resolution status, such as fixed, won’t fix, or duplicate.
?????????? updated: Helps you find issues that have been updated within a specific date range.
?????????? due: Allows you to search for issues that are due within a specific date range.
?????????? watcher: Enables you to find issues that are being watched by a specific user.
?????????? comment: Helps you search for issues that have specific text in their comments.
?????????? linkedIssue: Allows you to filter issues based on their relationship with other issues.
?????????? epic: Enables you to search for issues that are part of a specific epic.
?????????? sprint: Helps you find issues that are associated with a particular sprint.
?????????? board: Allows you to search for issues that belong to a specific board.
1.6.3 Time-based Keywords
JQL provides several keywords that allow you to search for issues based on their time-related attributes. These keywords include:
?????????? createdDate: Enables you to search for issues created on a specific date.
?????????? updatedDate: Helps you find issues that have been updated on a specific date.
?????????? resolvedDate: Allows you to search for issues that have been resolved on a specific date.
?????????? dueDate: Enables you to filter issues based on their due date.
?????????? startDate: Helps you find issues that have a specific start date.
?????????? endDate: Allows you to search for issues that have a specific end date.
1.6.4 Text-based Keywords
JQL provides several keywords that allow you to search for issues based on their text attributes. These keywords include:
?????????? summary: Enables you to search for issues that have specific text in their summary.
?????????? description: Helps you find issues that have specific text in their description.
?????????? comment: Allows you to search for issues that have specific text in their comments.
?????????? environment: Enables you to filter issues based on the environment in which they occur.
?????????? issueKey: Helps you find issues with a specific issue key.
1.6.5 User-based Keywords
JQL provides keywords that allow you to search for issues based on their association with users. These keywords include:
?????????? assignee: Enables you to search for issues assigned to a specific user.
?????????? reporter: Helps you find issues reported by a particular user.
?????????? watcher: Allows you to search for issues that are being watched by a specific user.
?????????? currentUser(): Enables you to search for issues that are assigned to or reported by the current user.
1.6.6 Field-specific Keywords
JQL provides keywords that are specific to certain fields in Jira. These keywords include:
?????????? project: Enables you to search for issues within a specific project.
?????????? component: Helps you find issues that are associated with a specific component.
?????????? label: Allows you to search for issues that have specific labels assigned to them.
?????????? fixVersion: Enables you to filter issues based on the version in which they are fixed.
?????????? affectedVersion: Helps you find issues that are affected by a specific version.
?????????? sprint: Allows you to search for issues that are associated with a specific sprint.
?????????? epicLink: Enables you to filter issues based on their association with a specific epic.
1.6.7 Logical Keywords
JQL provides logical keywords that allow you to combine multiple criteria in your search queries. These keywords include:
?????????? AND: Enables you to combine multiple criteria using the logical AND operator.
?????????? OR: Helps you combine multiple criteria using the logical OR operator.
?????????? NOT: Allows you to negate a specific criterion using the logical NOT operator.
1.6.8 Comparison Keywords
JQL provides comparison keywords that allow you to compare values in your search queries. These keywords include:
?????????? =: Enables you to search for issues with a specific value.
?????????? !=: Helps you find issues that do not have a specific value.
?????????? >: Allows you to search for issues with a value greater than a specific value.
?????????? <: Enables you to filter issues with a value less than a specific value.
?????????? >=: Helps you find issues with a value greater than or equal to a specific value.
?????????? <=: Allows you to search for issues with a value less than or equal to a specific value.
1.6.9 Miscellaneous Keywords
JQL provides several miscellaneous keywords that enhance your search capabilities. These keywords include:
?????????? EMPTY: Enables you to search for issues that have an empty value for a specific field.
?????????? NULL: Helps you find issues that have a null value for a specific field.
?????????? ORDER BY: Allows you to sort the search results based on a specific field.
?????????? ASC: Enables you to sort the search results in ascending order.
?????????? DESC: Helps you sort the search results in descending order.
?????????? LIMIT: Allows you to limit the number of search results displayed.
With these keywords at your disposal, you can construct powerful and precise JQL queries to search and filter your Jira issues effectively. In the next section, we will explore the various fields that you can use in JQL to further refine your search queries.
1.7 JQL Fields
JQL Fields are an essential component of Jira Query Language (JQL) that allow you to specify the criteria for your search. Fields represent different attributes or properties of an issue in Jira, such as its status, assignee, priority, or project. By using JQL Fields, you can narrow down your search and retrieve the specific issues that meet your requirements.
1.7.1 Understanding JQL Fields
JQL Fields are the building blocks of JQL queries. They provide a way to specify the attributes you want to search for in your Jira issues. Each field corresponds to a specific piece of information associated with an issue. For example, the “summary” field represents the summary or title of an issue, while the “assignee” field represents the person assigned to work on the issue.
1.7.2 Built-in JQL Fields
Jira comes with a set of built-in fields that you can use in your JQL queries. These fields cover a wide range of attributes, including issue details, project information, time tracking, and more. Some commonly used built-in fields include:
?????????? Summary: Represents the summary or title of an issue.
?????????? Description: Represents the detailed description of an issue.
?????????? Assignee: Represents the person assigned to work on the issue.
?????????? Reporter: Represents the person who reported the issue.
?????????? Status: Represents the current status of the issue (e.g., Open, In Progress, Resolved).
?????????? Priority: Represents the priority level of the issue (e.g., High, Medium, Low).
?????????? Project: Represents the project to which the issue belongs.
?????????? Issue Type: Represents the type of issue (e.g., Bug, Task, Story).
?????????? Created: Represents the date and time when the issue was created.
?????????? Updated: Represents the date and time when the issue was last updated.
1.7.3 Custom JQL Fields
In addition to the built-in fields, Jira also allows you to create custom fields to capture specific information that is unique to your organization or project. Custom fields can be created to track additional attributes, such as customer name, release version, or department. These custom fields can then be used in JQL queries to search for issues based on their values.
1.7.4 Referencing JQL Fields
To reference a JQL Field in your query, you need to use the field’s name enclosed in square brackets ([]). For example, to search for all issues assigned to a specific user, you would use the “assignee” field as follows:
assignee = "John Doe"
Similarly, to search for all issues with a specific priority, you would use the “priority” field:
priority = High
1.7.5 Combining JQL Fields
JQL allows you to combine multiple fields in a single query to create more complex search criteria. For example, you can search for all open issues assigned to a particular user using the “status” and “assignee” fields together:
status = Open AND assignee = "John Doe"
You can also use logical operators such as “OR” and “NOT” to further refine your search criteria.
1.7.6 Searching with JQL Field Operators
JQL Field Operators provide a way to perform specific comparisons or operations on JQL Fields. These operators allow you to search for issues based on their field values. Some commonly used field operators include:
?????????? =: Matches issues with an exact field value.
?????????? !=: Matches issues with a field value that is not equal to the specified value.
?????????? >:: Matches issues with a field value greater than the specified value.
?????????? <: Matches issues with a field value less than the specified value.
?????????? >=: Matches issues with a field value greater than or equal to the specified value.
?????????? <=: Matches issues with a field value less than or equal to the specified value.
?????????? IN: Matches issues with a field value that is one of the specified values.
?????????? NOT IN: Matches issues with a field value that is not one of the specified values.
1.7.7 Using JQL Field Functions
JQL Field Functions provide additional capabilities to search and filter issues based on field values. These functions allow you to perform calculations, transformations, or aggregations on JQL Fields. Some commonly used field functions include:
?????????? EMPTY: Matches issues with an empty field value.
?????????? NOT EMPTY: Matches issues with a non-empty field value.
?????????? CHANGED: Matches issues where the field value has changed.
?????????? WAS: Matches issues where the field value was a specific value in the past.
?????????? CHANGED FROM: Matches issues where the field value has changed from a specific value.
?????????? CHANGED TO: Matches issues where the field value has changed to a specific value.
?????????? STARTOFDAY: Matches issues where the field value is at the start of the day.
?????????? ENDOFDAY: Matches issues where the field value is at the end of the day.
1.7.8 JQL Field Examples
To illustrate the usage of JQL Fields, let’s consider a few examples:
?????????? To search for all open issues assigned to a specific user, you can use the following query:
????? status = Open AND assignee = "John Doe"
?????????? To find all issues created in the last 7 days, you can use the following query:
????? created >= -7d
?????????? To search for all issues with a specific label, you can use the following query:
????? labels = "bug"
1.7.9 Best Practices for Using JQL Fields
When using JQL Fields, it is important to keep the following best practices in mind:
?????????? Use the appropriate field for your search criteria to ensure accurate results.
?????????? Use field operators and functions effectively to refine your search criteria.
?????????? Combine multiple fields and operators to create complex queries when needed.
?????????? Test your queries before using them in production to ensure they return the expected results.
?????????? Regularly review and update your queries as your project evolves and new fields are added.
By understanding and effectively using JQL Fields, you can unleash the full power of JQL and perform advanced searches in Jira to find the information you need quickly and efficiently.
1.8 JQL Examples
In this section, we will explore various JQL examples to demonstrate how to effectively use JQL to search and filter your Jira issues. Each example will highlight different aspects of JQL syntax, operators, functions, and keywords, providing you with a comprehensive understanding of how to construct powerful queries.
1.8.1 Simple Issue Searches
Let’s start with some basic JQL queries to search for specific issues. For example, to find all open issues assigned to you, you can use the following query:
assignee = currentUser() AND status = Open
This query will return a list of issues that are currently assigned to you and have an open status.
1.8.2 Filtering by Issue Type
If you want to filter issues based on their type, you can use the issueType field in your JQL query. For instance, to find all bugs in your project, you can use the following query:
issueType = Bug
This query will retrieve all issues that have the issue type set to “Bug.”
1.8.3 Searching by Status
To search for issues based on their status, you can utilize the status field in your JQL query. For example, to find all resolved issues in your project, you can use the following query:
status = Resolved
This query will return all issues that have been marked as resolved.
1.8.4 Querying by Assignee
If you want to find issues assigned to a specific user, you can use the assignee field in your JQL query. For instance, to find all issues assigned to John Doe, you can use the following query:
assignee = "John Doe"
This query will retrieve all issues that are assigned to the user “John Doe.”
1.8.5 Finding Issues by Reporter
To search for issues reported by a specific user, you can utilize the reporter field in your JQL query. For example, to find all issues reported by Jane Smith, you can use the following query:
reporter = "Jane Smith"
This query will return all issues that have been reported by the user “Jane Smith.”
1.8.6 Searching by Priority
If you want to filter issues based on their priority, you can use the priority field in your JQL query. For instance, to find all high-priority issues in your project, you can use the following query:
priority = High
This query will retrieve all issues that have been assigned a high priority.
领英推荐
1.8.7 Filtering by Labels
To search for issues with specific labels, you can utilize the labels field in your JQL query. For example, to find all issues labeled as “bug” and “critical,” you can use the following query:
labels in ("bug", "critical")
This query will return all issues that have been labeled as both “bug” and “critical.”
1.8.8 Querying by Components
If you want to filter issues based on their components, you can use the component field in your JQL query. For instance, to find all issues associated with the “UI” component, you can use the following query:
component = UI
This query will retrieve all issues that have been assigned to the “UI” component.
1.8.9 Basic JQL Examples
To further illustrate the power of JQL, let’s combine multiple criteria in our queries. For example, to find all open issues assigned to you and labeled as “bug,” you can use the following query:
assignee = currentUser() AND status = Open AND labels = bug
This query will return all open issues that are assigned to you and labeled as “bug.”
These examples provide a glimpse into the versatility of JQL and how it can be used to search and filter your Jira issues. As you progress through the book, you will learn more advanced techniques and best practices for using JQL effectively in various scenarios.
1.9 Best Practices for Using JQL
Jira Query Language (JQL) is a powerful tool that allows you to search and filter your Jira issues with precision. To make the most out of JQL and optimize your workflow, it’s important to follow some best practices. In this section, we will explore some key recommendations for using JQL effectively.
1.9.1 Understand Your Data Model
Before diving into JQL queries, it’s crucial to have a solid understanding of your Jira data model. Familiarize yourself with the different issue types, fields, and their relationships. This knowledge will help you construct more accurate and efficient queries. Take the time to explore your Jira instance and identify the relevant fields and their values.
1.9.2 Start with Simple Queries
When starting with JQL, it’s best to begin with simple queries and gradually build upon them. Start by searching for issues based on a single criterion, such as issue type or status. As you become more comfortable with JQL, you can add more criteria and operators to refine your searches. Starting simple allows you to understand the basics and gradually increase the complexity of your queries.
1.9.3 Use the Right Operators
JQL provides a wide range of operators to perform different types of comparisons and logical operations. It’s important to choose the right operator for each query to ensure accurate results. For example, use the “=” operator for exact matches, the “!=” operator for inequality, and the “IN” operator for multiple values. Understanding and utilizing the appropriate operators will enhance the precision of your queries.
1.9.4 Utilize Functions and Keywords
JQL offers various functions and keywords that can significantly enhance your query capabilities. Functions like “startOfDay()” and “endOfDay()” allow you to search for issues based on specific timeframes. Keywords like “ORDER BY” and “GROUP BY” help you sort and group your search results effectively. Familiarize yourself with these functions and keywords to unlock the full potential of JQL.
1.9.5 Use Parentheses for Complex Queries
When constructing complex queries with multiple criteria and logical operators, it’s essential to use parentheses to define the order of operations. By using parentheses, you can control the precedence of operators and ensure that your query behaves as intended. This practice is particularly important when combining different logical operators like “AND” and “OR” in a single query.
1.9.6 Leverage JQL Autocomplete
Jira’s JQL autocomplete feature is a valuable tool that can save you time and prevent syntax errors. As you type your query, Jira suggests field names, operators, and values based on your Jira instance’s configuration. Take advantage of this feature to ensure the accuracy of your queries and to discover available options that you may not be aware of.
1.9.7 Test and Refine Your Queries
Before using a complex JQL query in a production environment, it’s crucial to test and refine it. Start by running your query in Jira’s issue navigator and reviewing the results. Make sure the query returns the expected issues and that the results align with your requirements. If necessary, iterate on your query, making adjustments and refinements until you achieve the desired outcome.
1.9.8 Document Your Queries
As you develop and refine your JQL queries, it’s important to document them for future reference. Maintain a repository or a document where you can store your queries along with their descriptions and use cases. This documentation will not only help you remember your queries but also enable you to share them with your team, fostering collaboration and knowledge sharing.
1.9.9 Stay Up to Date with Jira Updates
Jira is a dynamic platform, and Atlassian regularly introduces updates and improvements. Stay informed about new features, changes to JQL syntax, and enhancements to ensure that you are leveraging the latest capabilities. By staying up to date, you can take advantage of new functionalities and optimize your JQL queries accordingly.
By following these best practices, you can become a proficient JQL user and unlock the full potential of Jira’s search and filtering capabilities. Remember to start with simple queries, understand your data model, and utilize the right operators, functions, and keywords. Test and refine your queries, document them for future reference, and stay informed about Jira updates. With these practices in place, you’ll be well-equipped to master the art of JQL and streamline your Jira workflows.
2 Basic JQL Queries
2.1 Simple Issue Searches
In this chapter, we will explore the basics of JQL and learn how to perform simple issue searches in Jira. Simple issue searches allow you to quickly find and filter issues based on specific criteria. By mastering these fundamental JQL queries, you will be able to efficiently navigate through your Jira projects and locate the information you need.
2.1.1 Searching by Issue Key
The issue key is a unique identifier assigned to each issue in Jira. It consists of a project key followed by a numerical value. To search for a specific issue by its key, you can use the following JQL query:
key = "PROJECT-123"
Replace “PROJECT-123” with the actual issue key you want to search for. This query will return the issue with the specified key.
2.1.2 Filtering by Summary
The summary field in Jira provides a brief description of an issue. To filter issues based on their summary, you can use the following JQL query:
summary ~ "keyword"
Replace “keyword” with the specific word or phrase you want to search for in the summary field. This query will return all issues whose summary contains the specified keyword.
2.1.3 Querying by Description
The description field in Jira allows you to provide additional details about an issue. To query issues based on their description, you can use the following JQL query:
description ~ "keyword"
Replace “keyword” with the specific word or phrase you want to search for in the description field. This query will return all issues whose description contains the specified keyword.
2.1.4 Finding Issues by Reporter
The reporter field in Jira identifies the user who reported an issue. To find issues reported by a specific user, you can use the following JQL query:
reporter = username
Replace “username” with the username of the reporter you want to search for. This query will return all issues reported by the specified user.
2.1.5 Searching by Assignee
The assignee field in Jira represents the user who is currently responsible for an issue. To search for issues assigned to a specific user, you can use the following JQL query:
assignee = username
Replace “username” with the username of the assignee you want to search for. This query will return all issues assigned to the specified user.
2.1.6 Filtering by Issue Type
The issue type field in Jira categorizes issues into different types, such as “Bug,” “Task,” or “Story.” To filter issues based on their type, you can use the following JQL query:
issuetype = "Bug"
Replace “Bug” with the specific issue type you want to search for. This query will return all issues of the specified type.
2.1.7 Querying by Priority
The priority field in Jira indicates the importance or urgency of an issue. To query issues based on their priority, you can use the following JQL query:
priority = "High"
Replace “High” with the specific priority level you want to search for. This query will return all issues with the specified priority.
2.1.8 Searching by Status
The status field in Jira represents the current stage of an issue, such as “Open,” “In Progress,” or “Resolved.” To search for issues based on their status, you can use the following JQL query:
status = "In Progress"
Replace “In Progress” with the specific status you want to search for. This query will return all issues with the specified status.
2.1.9 Filtering by Labels
Labels in Jira allow you to categorize issues with descriptive keywords. To filter issues based on their labels, you can use the following JQL query:
labels = "label"
Replace “label” with the specific label you want to search for. This query will return all issues with the specified label.
By mastering these simple issue searches, you will be able to quickly locate and filter issues in Jira based on various criteria. These foundational JQL queries will serve as building blocks for more complex searches and enable you to effectively manage your projects in Jira. In the next chapter, we will explore filtering issues by issue type, providing you with additional flexibility in your JQL queries.
2.2 Filtering by Issue Type
Filtering by issue type is a fundamental aspect of JQL that allows you to narrow down your search results based on the specific type of issues you are interested in. By specifying the issue type in your JQL query, you can focus on a particular category of issues and exclude others that are not relevant to your current task or analysis.
To filter by issue type, you need to understand the different issue types available in your Jira instance. Issue types represent the various types of work items or tasks that can be tracked in Jira, such as bugs, user stories, tasks, epics, and more. Each issue type has its own unique set of attributes and workflow transitions.
When constructing a JQL query to filter by issue type, you can use the issuetype field along with the appropriate operator and value. The issuetype field represents the issue type of an issue and can be used in combination with other JQL clauses to create more complex queries.
Here are some examples of how you can filter by issue type using JQL:
?????????? To find all issues of a specific issue type, you can use the following query:
????? issuetype = Bug
??????????? This query will return all issues that have the issue type “Bug”.
?????????? To find all issues of multiple issue types, you can use the IN operator:
????? issuetype IN (Bug, Task, Story)
??????????? This query will return all issues that have the issue types “Bug”, “Task”, or “Story”.
?????????? To exclude certain issue types from your search results, you can use the NOT operator:
????? issuetype != Epic
??????????? This query will return all issues except those that have the issue type “Epic”.
?????????? To find all subtasks of a specific issue type, you can use the subtaskOf function:
????? issuetype = Sub-task AND subtaskOf("PROJ-123")
??????????? This query will return all subtasks of the issue with the key “PROJ-123”.
Filtering by issue type is particularly useful when you want to focus on a specific type of work or when you need to analyze the distribution of issues across different types. By combining the issuetype field with other JQL clauses, you can create more advanced queries to further refine your search results.
It’s important to note that the available issue types may vary depending on the Jira project and configuration. Some projects may have custom issue types that are specific to their workflow and requirements. Therefore, it’s essential to familiarize yourself with the issue types available in your Jira instance before constructing JQL queries based on issue types.
In the next section, we will explore how to search and filter issues based on their status, allowing you to track the progress of your work items effectively.
2.3 Searching by Status
In Jira, the status of an issue represents its current stage in the workflow. It indicates where the issue is in terms of progress, whether it is open, in progress, resolved, or closed. Searching by status is a fundamental aspect of JQL, as it allows you to find issues based on their current state.
2.3.1 Basic Status Search
To perform a basic search by status, you can use the “status” field in your JQL query. The “status” field represents the current status of an issue. Here’s an example of a basic JQL query to search for all open issues:
status = Open
This query will return all issues that are currently in the “Open” status. You can replace “Open” with any other status name to search for issues in different states.
2.3.2 Searching by Multiple Statuses
Sometimes, you may need to search for issues that are in multiple statuses. JQL allows you to search for issues that match any of the specified statuses using the “IN” operator. Here’s an example:
status IN (Open, In Progress)
This query will return all issues that are either in the “Open” or “In Progress” status. You can include as many statuses as you need within the parentheses.
2.3.3 Excluding Specific Statuses
In some cases, you may want to exclude certain statuses from your search results. JQL provides the “NOT” operator to achieve this. Here’s an example:
status NOT IN (Closed, Resolved)
This query will return all issues that are not in the “Closed” or “Resolved” status. You can exclude any number of statuses by listing them within the parentheses.
2.3.4 Searching by Status Category
Jira organizes statuses into different categories, such as “To Do,” “In Progress,” and “Done.” If you want to search for issues based on their status category, you can use the “statusCategory” field in your JQL query. Here’s an example:
statusCategory = "In Progress"
This query will return all issues that are currently in the “In Progress” status category. You can replace “In Progress” with any other status category name.
2.3.5 Combining Status and Other Criteria
JQL allows you to combine status search with other criteria to narrow down your search results. For example, you can search for all open issues assigned to a specific user using the following query:
status = Open AND assignee = "John Doe"
This query will return all issues that are in the “Open” status and assigned to the user “John Doe.” You can combine status search with any other JQL criteria to create more specific queries.
2.3.6 Searching by Status Change Date
In addition to searching by the current status of an issue, you can also search based on when the status was last changed. JQL provides the “status changed” field to perform this type of search. Here’s an example:
status changed AFTER startOfDay(-7d)
This query will return all issues whose status was changed within the last 7 days. You can adjust the number of days as needed.
2.3.7 Searching by Resolved Status
When working with resolved issues, you can search specifically for issues that have been resolved using the “resolution” field in your JQL query. Here’s an example:
resolution = "Fixed"
This query will return all issues that have been resolved with the “Fixed” resolution. You can replace “Fixed” with any other resolution name.
2.3.8 Searching by Status History
If you need to track the history of an issue’s status changes, JQL allows you to search for issues based on their status change history. You can use the “status WAS” operator to perform this type of search. Here’s an example:
status WAS "Open" BEFORE startOfDay(-7d)
This query will return all issues that were previously in the “Open” status but have since changed within the last 7 days. You can modify the status and time frame according to your requirements.
2.3.9 Best Practices for Searching by Status
When searching by status in JQL, it’s important to keep a few best practices in mind:
1.??????? Use specific status names: Be precise when specifying status names in your queries to avoid ambiguity and ensure accurate search results.
2.??????? Combine status search with other criteria: Utilize the flexibility of JQL by combining status search with other criteria to create more targeted queries.
3.??????? Consider status categories: If you’re interested in searching by status category rather than individual statuses, make use of the “statusCategory” field.
4.??????? Regularly review and update queries: As your project progresses and statuses change, periodically review and update your JQL queries to reflect the current state of your issues.
By mastering the art of searching by status in JQL, you’ll be able to effectively track and manage your issues in Jira, ensuring efficient workflow management and improved productivity.
2.4 Querying by Assignee
In Jira, the assignee field represents the person who is responsible for working on a particular issue. Being able to query issues based on the assignee is crucial for effective project management and task allocation. In this section, we will explore various techniques to query issues using the assignee field in JQL.
2.4.1 Searching for Issues Assigned to a Specific User
One of the most common use cases is to find all the issues assigned to a specific user. To achieve this, you can use the assignee field in your JQL query. For example, to find all the issues assigned to John Doe, you can use the following query:
assignee = "John Doe"
This query will return all the issues where the assignee field is set to “John Doe”. You can replace “John Doe” with the actual username or display name of the assignee you are searching for.
2.4.2 Finding Unassigned Issues
Sometimes, it’s important to identify issues that are not assigned to anyone. This can help in identifying tasks that need to be assigned or redistributed. To find unassigned issues, you can use the assignee field with the IS EMPTY operator. Here’s an example:
assignee IS EMPTY
This query will return all the issues where the assignee field is empty, indicating that they are unassigned.
2.4.3 Querying for Issues Assigned to a Group
In some cases, you may want to find all the issues assigned to a specific group of users. JQL allows you to query issues based on the assignee’s group membership. To achieve this, you can use the assignee in operator followed by the group name. For example:
assignee in membersOf("Developers")
This query will return all the issues assigned to any member of the “Developers” group. Replace “Developers” with the actual name of the group you want to query.
2.4.4 Searching for Issues Assigned to Current User
To quickly find all the issues assigned to the currently logged-in user, you can use the currentUser() function in your JQL query. Here’s an example:
assignee = currentUser()
This query will return all the issues assigned to the user who is currently logged in to Jira.
2.4.5 Querying for Issues Assigned to Multiple Users
In some scenarios, you may need to find issues that are assigned to multiple users. JQL provides the flexibility to query for such cases using the IN operator. For example:
assignee in ("John Doe", "Jane Smith")
This query will return all the issues assigned to either John Doe or Jane Smith. You can add more usernames or display names within the parentheses to include additional assignees.
2.4.6 Filtering by Assignee’s Active Status
Jira allows you to deactivate users who are no longer active in the system. To filter issues based on the assignee’s active status, you can use the assignee was operator followed by the active keyword. Here’s an example:
assignee was active
This query will return all the issues that were assigned to users who are currently active in the system.
2.4.7 Querying for Issues Assigned to a Specific User in a Project
If you want to narrow down your search to a specific project, you can combine the assignee field with the project field in your JQL query. For example:
project = "Project X" AND assignee = "John Doe"
This query will return all the issues assigned to John Doe within the “Project X” project. Replace “Project X” with the actual name of your project.
2.4.8 Finding Issues Assigned to a User in a Specific Timeframe
JQL allows you to search for issues assigned to a user within a specific timeframe. You can use the assignee changedoperator along with the AFTER or BEFORE keywords to achieve this. For example:
assignee changed AFTER "2022-01-01" BEFORE "2022-02-01" by "John Doe"
This query will return all the issues that were assigned to John Doe between January 1, 2022, and January 31, 2022.
2.4.9 Combining Assignee Queries with Other Criteria
JQL provides the flexibility to combine assignee queries with other criteria to create more complex and targeted searches. You can use logical operators such as AND, OR, and NOT to combine multiple conditions. For example:
assignee = "John Doe" AND status = "In Progress"
This query will return all the issues assigned to John Doe that are currently in progress. You can customize the conditions based on your specific requirements.
By mastering the art of querying by assignee in JQL, you can efficiently manage and track issues assigned to different team members. These techniques will help you streamline your workflow, allocate tasks effectively, and ensure that nothing falls through the cracks.
2.5 Finding Issues by Reporter
The “Finding Issues by Reporter” feature in JQL allows you to search for issues based on the person who reported them. This can be particularly useful when you want to track the progress of specific individuals or analyze the workload of different team members. By using JQL to filter issues by reporter, you can easily identify the issues that have been reported by a particular user or group of users.
To find issues by reporter, you can use the reporter keyword in your JQL query. The reporter keyword is followed by the username or user key of the reporter you want to search for. Here’s an example of a basic JQL query that finds all issues reported by a specific user:
reporter = johndoe
In this example, johndoe is the username of the reporter. By executing this query, you will retrieve all the issues that have been reported by John Doe.
You can also use the reporter keyword in combination with other JQL operators and functions to create more complex queries. For instance, you can use the IN operator to find issues reported by multiple users. Here’s an example:
reporter IN (johndoe, janedoe)
In this query, we are searching for issues reported by either John Doe or Jane Doe. By using the IN operator, you can specify multiple reporters within parentheses.
Additionally, you can use JQL functions to further refine your search. For example, you can use the currentUser() function to find issues reported by the currently logged-in user. Here’s an example:
reporter = currentUser()
By executing this query, you will retrieve all the issues that have been reported by the user who is currently logged in.
Furthermore, you can combine the reporter keyword with other JQL fields, operators, and functions to create even more specific queries. For instance, you can use the AND operator to find issues reported by a specific user and assigned to another user. Here’s an example:
reporter = johndoe AND assignee = janedoe
In this query, we are searching for issues reported by John Doe and assigned to Jane Doe. By using the AND operator, you can specify multiple criteria that must be met.
It’s important to note that the reporter field in JQL refers to the person who initially reported the issue, not the person who is currently assigned to it. This means that even if the issue has been reassigned to another user, it will still be considered as reported by the original reporter.
In conclusion, the “Finding Issues by Reporter” feature in JQL allows you to search for issues based on the person who reported them. By using the reporter keyword in your JQL queries, you can easily filter and analyze issues reported by specific users or groups of users. Whether you want to track the progress of individual team members or analyze the workload distribution, this feature provides a powerful tool for managing and organizing your Jira issues.
2.6 Searching by Priority
In Jira, priority is an important aspect of managing issues. It helps teams prioritize their work and ensures that critical tasks are addressed promptly. With JQL, you can easily search for issues based on their priority level, allowing you to focus on the most important tasks at hand. In this section, we will explore how to effectively search for issues by priority using JQL.
2.6.1 Understanding Priority in Jira
Before we dive into searching by priority, let’s first understand how priority is defined in Jira. Priority represents the importance or urgency of an issue and is typically categorized into several levels such as “Highest,” “High,” “Medium,” “Low,” and “Lowest.” Each priority level is assigned a numerical value, with the highest priority having the lowest numerical value.
2.6.2 Searching for High Priority Issues
To search for high priority issues, you can use the JQL keyword “priority” followed by the desired priority level. For example, to find all issues with a priority level of “High,” you can use the following JQL query:
priority = High
This query will return all issues that have been assigned a priority level of “High.” You can further refine your search by combining it with other JQL criteria, such as project, status, or assignee.
2.6.3 Filtering by Priority Range
In addition to searching for specific priority levels, you can also filter issues based on a range of priorities. This can be useful when you want to focus on a specific range of importance. To filter by priority range, you can use the JQL operators “>=,” “<=,” and “BETWEEN.” Here are a few examples:
?????????? To find all issues with a priority level equal to or higher than “Medium,” you can use the following query:
????? priority >= Medium
?????????? To find all issues with a priority level lower than or equal to “Low,” you can use the following query:
????? priority <= Low
?????????? To find all issues with a priority level between “Medium” and “High,” you can use the following query:
????? priority BETWEEN Medium AND High
2.6.4 Searching for Highest Priority Issues
Sometimes, you may need to identify the most critical issues in your project. To search for the highest priority issues, you can use the JQL keyword “priority” followed by the lowest numerical value. For example, if the highest priority level in your project is “Highest” with a numerical value of 1, you can use the following query:
priority = 1
This query will return all issues that have been assigned the highest priority level.
2.6.5 Combining Priority with Other Criteria
JQL allows you to combine the priority criteria with other search criteria to further refine your search. For example, you can search for high priority issues assigned to a specific user or within a particular project. Here are a few examples:
?????????? To find all high priority issues assigned to a user named “John Doe,” you can use the following query:
????? priority = High AND assignee = "John Doe"
?????????? To find all high priority issues within a project named “Project X,” you can use the following query:
????? priority = High AND project = "Project X"
By combining priority with other criteria, you can create powerful JQL queries to precisely search for the issues that matter to you.
2.6.6 Searching for Unassigned Priority Issues
In some cases, you may want to identify issues that have a priority level but are not yet assigned to anyone. To search for unassigned priority issues, you can use the JQL keyword “priority” combined with the operator “IS EMPTY.” Here’s an example:
priority IS EMPTY
This query will return all issues that have a priority level but are not assigned to any user.
2.6.7 Searching for Issues with No Priority
On the other hand, you may also want to find issues that do not have a priority level assigned. To search for issues with no priority, you can use the JQL keyword “priority” combined with the operator “IS NULL.” Here’s an example:
priority IS NULL
This query will return all issues that do not have a priority level assigned.
2.6.8 Searching for Issues by Priority Change
Jira allows you to track the history of priority changes for each issue. If you need to search for issues based on their priority change, you can use the JQL keyword “priority” combined with the operator “WAS.” Here’s an example:
priority WAS "High"
This query will return all issues that had a priority level of “High” at some point in their history.
2.6.9 Best Practices for Searching by Priority
When searching by priority in Jira, it’s essential to follow some best practices to ensure accurate and efficient results:
?????????? Use specific priority levels: Instead of searching for a broad range of priorities, try to be specific and search for individual priority levels. This will help you narrow down your search and focus on the most relevant issues.
?????????? Combine priority with other criteria: To get more precise results, combine the priority criteria with other search criteria such as project, assignee, or status. This will help you filter the issues that meet multiple criteria.
?????????? Regularly review and update priorities: Priorities can change over time, so it’s important to regularly review and update them as needed. This will ensure that your search results accurately reflect the current state of your project.
By following these best practices, you can effectively search for issues by priority and streamline your workflow in Jira.
In the next section, we will explore how to filter issues by labels using JQL.
2.7 Filtering by Labels
Labels are a powerful way to categorize and organize your Jira issues. They allow you to add descriptive keywords or tags to your issues, making it easier to search for and filter specific sets of issues. In this section, we will explore how to effectively filter your issues using labels in JQL.
2.7.1 Using the “labels” Field
In JQL, the “labels” field is used to search for issues based on their labels. You can use the “labels” field in combination with other JQL operators and functions to create complex queries. For example, you can search for issues that have a specific label, multiple labels, or even exclude certain labels from your search results.
To search for issues with a specific label, you can use the “=” operator followed by the label name. For example, to find all issues with the label “bug”, you can use the following JQL query:
labels = bug
2.7.2 Searching for Multiple Labels
If you want to search for issues that have multiple labels, you can use the “IN” operator followed by a list of label names enclosed in parentheses. For example, to find all issues that have either the label “bug” or “feature”, you can use the following JQL query:
labels IN (bug, feature)
2.7.3 Excluding Labels from Search Results
Sometimes, you may want to exclude certain labels from your search results. In such cases, you can use the “!=” operator followed by the label name. For example, to find all issues that do not have the label “bug”, you can use the following JQL query:
labels != bug
2.7.4 Combining Labels with Other Criteria
Labels can be combined with other JQL criteria to create more specific queries. For example, you can search for issues with a specific label and a particular status using the “AND” operator. Here’s an example:
labels = bug AND status = "In Progress"
This query will return all issues that have the label “bug” and are currently in the “In Progress” status.
2.7.5 Using Wildcards in Label Searches
JQL also supports the use of wildcards in label searches. You can use the “*” wildcard to match any characters or the “?” wildcard to match a single character. For example, to find all issues that have labels starting with “bug”, you can use the following JQL query:
labels ~ "bug*"
2.7.6 Searching for Labels in Specific Projects
If you want to search for labels within specific projects, you can use the “project” field in combination with the “labels” field. For example, to find all issues with the label “bug” in the project “ABC”, you can use the following JQL query:
project = ABC AND labels = bug
2.7.7 Filtering by Labels and Issue Types
Labels can also be used in combination with other JQL criteria, such as issue types. For example, to find all issues of type “Bug” with the label “critical”, you can use the following JQL query:
issuetype = Bug AND labels = critical
2.7.8 Using Labels in Subqueries
Labels can be used in subqueries to further refine your search results. Subqueries allow you to search for issues based on the results of another query. For example, you can search for all issues that have the same label as another specific issue. Here’s an example:
labels = (labels of ABC-123)
This query will return all issues that have the same labels as the issue with the key “ABC-123”.
2.7.9 Best Practices for Using Labels in JQL
When using labels in JQL, it’s important to follow some best practices to ensure accurate and efficient searches:
1.??????? Use meaningful labels: Choose labels that accurately describe the content or purpose of the issue. This will make it easier to search for and filter issues based on their labels.
2.??????? Consistency is key: Establish a consistent labeling convention across your projects and teams. This will ensure that labels are used consistently and make it easier to search for related issues.
3.??????? Avoid excessive labels: Use labels sparingly and avoid adding too many labels to an issue. Too many labels can make it difficult to search for and filter issues effectively.
4.??????? Regularly review and update labels: Periodically review your labels and remove any that are no longer relevant. This will help keep your label list clean and ensure accurate search results.
By effectively using labels in JQL, you can streamline your issue management process and quickly find the information you need. Experiment with different label combinations and explore the full potential of JQL to enhance your Jira experience.
2.8 Querying by Components
Components in Jira are a great way to categorize and organize your issues. They allow you to group related issues together based on a specific feature, module, or functionality. By querying by components, you can easily find and filter issues that are associated with a particular component. This can be especially useful when you want to track the progress or status of specific components within your project.
2.8.1 Searching for Issues with a Specific Component
To search for issues with a specific component, you can use the component field in your JQL query. The component field allows you to specify the name of the component you want to search for. For example, if you have a component named “Authentication”, you can search for issues that are associated with this component by using the following JQL query:
component = Authentication
This query will return all the issues that have the “Authentication” component assigned to them.
2.8.2 Searching for Issues with Multiple Components
In some cases, you may want to search for issues that have multiple components assigned to them. To achieve this, you can use the IN operator along with the component field. For example, if you want to find issues that have either the “Authentication” or “Authorization” component assigned to them, you can use the following JQL query:
component IN ("Authentication", "Authorization")
This query will return all the issues that have either the “Authentication” or “Authorization” component assigned to them.
2.8.3 Excluding Issues with a Specific Component
Sometimes, you may want to exclude issues that have a specific component assigned to them from your search results. To achieve this, you can use the NOT operator along with the component field. For example, if you want to find all the issues that do not have the “Authentication” component assigned to them, you can use the following JQL query:
component != Authentication
This query will return all the issues that do not have the “Authentication” component assigned to them.
2.8.4 Searching for Unassigned Components
If you want to find all the issues that do not have any component assigned to them, you can use the IS EMPTY operator along with the component field. For example, the following JQL query will return all the issues that do not have any component assigned to them:
component IS EMPTY
This query will help you identify any issues that have not been categorized into any specific component.
2.8.5 Combining Component Queries with Other Criteria
You can also combine component queries with other JQL criteria to further refine your search results. For example, if you want to find all the open issues that are assigned to the “Authentication” component, you can use the following JQL query:
status = Open AND component = Authentication
This query will return all the open issues that have the “Authentication” component assigned to them.
2.8.6 Searching for Issues in Specific Components and Versions
In addition to components, you can also search for issues based on specific versions. This can be useful when you want to track the progress of issues within specific components and versions. To achieve this, you can use the AND operator to combine the component and fixVersion fields in your JQL query. For example, if you want to find all the issues that are assigned to the “Authentication” component and have the “1.0” version fixed, you can use the following JQL query:
component = Authentication AND fixVersion = 1.0
This query will return all the issues that have the “Authentication” component assigned to them and the “1.0” version fixed.
2.8.7 Searching for Issues in Subcomponents
If you have subcomponents within your components, you can also search for issues that are assigned to specific subcomponents. To achieve this, you can use the IN operator along with the component field and specify the subcomponents within quotes. For example, if you have a component named “Authentication” with subcomponents “Login” and “Registration”, you can search for issues that are assigned to either of these subcomponents using the following JQL query:
component IN ("Authentication/Login", "Authentication/Registration")
This query will return all the issues that are assigned to either the “Login” or “Registration” subcomponent of the “Authentication” component.
2.8.8 Searching for Issues in Components Across Projects
By default, JQL searches for issues within the current project. However, if you want to search for issues in components across multiple projects, you can use the project field along with the component field in your JQL query. For example, if you want to find all the issues that have the “Authentication” component assigned to them in the projects “Project A” and “Project B”, you can use the following JQL query:
project IN ("Project A", "Project B") AND component = Authentication
This query will return all the issues that have the “Authentication” component assigned to them in the projects “Project A” and “Project B”.
2.8.9 Saving and Sharing Component Queries
Once you have created a JQL query to search for issues based on components, you can save it as a filter in Jira. This allows you to easily access and reuse the query in the future. You can also share the saved filter with other users, enabling them to view the same set of issues based on the component criteria.
To save a JQL query as a filter, simply click on the “Save as” button when viewing the search results. Give the filter a name and choose the appropriate visibility settings. Once saved, the filter will be available in the “Filters” section of your Jira instance.
In conclusion, querying by components in Jira using JQL provides a powerful way to search and filter issues based on specific features or modules. By mastering the art of querying by components, you can effectively track and manage the progress of different components within your projects.
2.9 Basic JQL Examples
In this section, we will explore some basic JQL examples to help you get started with querying and filtering your Jira issues. These examples will cover various aspects of JQL syntax, operators, and functions, providing you with a solid foundation for more advanced searches.
2.9.1 Searching by Issue Key
One of the most common ways to search for an issue in Jira is by its unique issue key. The issue key is a combination of the project key and a unique number assigned to each issue. To search for a specific issue, you can simply use the key field followed by the issue key. For example, to find an issue with the key “PROJ-123”, you would use the following JQL query:
key = PROJ-123
This query will return the issue with the specified key.
2.9.2 Filtering by Issue Summary
The summary field in Jira provides a brief description of an issue. You can use the summary field to filter issues based on their summary. For example, if you want to find all issues with the word “bug” in their summary, you can use the following JQL query:
summary ~ "bug"
This query will return all issues where the summary contains the word “bug”.
2.9.3 Querying by Issue Type
Jira allows you to categorize issues into different types such as “Bug,” “Task,” or “Story.” You can use the issuetype field to query issues based on their type. For example, if you want to find all issues of the type “Bug,” you can use the following JQL query:
issuetype = Bug
This query will return all issues that are categorized as bugs.
2.9.4 Searching by Assignee
The assignee field in Jira represents the person who is responsible for resolving an issue. You can use the assignee field to search for issues assigned to a specific user. For example, if you want to find all issues assigned to the user “John Doe,” you can use the following JQL query:
assignee = "John Doe"
This query will return all issues assigned to the specified user.
2.9.5 Filtering by Issue Status
The status field in Jira represents the current state of an issue, such as “Open,” “In Progress,” or “Resolved.” You can use the status field to filter issues based on their status. For example, if you want to find all open issues, you can use the following JQL query:
status = Open
This query will return all issues that are currently in the “Open” status.
2.9.6 Querying by Issue Priority
The priority field in Jira allows you to prioritize issues based on their importance. You can use the priority field to query issues based on their priority. For example, if you want to find all high-priority issues, you can use the following JQL query:
priority = High
This query will return all issues that have been assigned a high priority.
2.9.7 Searching by Issue Labels
Labels in Jira are used to categorize issues based on specific keywords or tags. You can use the labels field to search for issues with specific labels. For example, if you want to find all issues with the label “documentation,” you can use the following JQL query:
labels = documentation
This query will return all issues that have been labeled as “documentation”.
2.9.8 Filtering by Components
Components in Jira represent the different parts or features of a project. You can use the component field to filter issues based on their assigned components. For example, if you want to find all issues assigned to the component “UI,” you can use the following JQL query:
component = UI
This query will return all issues that have been assigned to the specified component.
2.9.9 Combining Multiple Criteria
In JQL, you can combine multiple criteria to create more complex queries. For example, if you want to find all open issues assigned to the user “John Doe” with the label “bug,” you can use the following JQL query:
status = Open AND assignee = "John Doe" AND labels = bug
This query will return all open issues assigned to “John Doe” that have been labeled as “bug”.
These basic JQL examples should give you a good starting point for querying and filtering your Jira issues. As you become more comfortable with JQL, you can explore more advanced queries and leverage the full power of Jira’s search capabilities.
3 Advanced JQL Queries
3.1 Combining Multiple Criteria
In Jira Query Language (JQL), you have the flexibility to combine multiple criteria to create complex and powerful queries. By combining different search parameters, you can narrow down your search results and find the exact issues you are looking for. This section will explore various techniques for combining multiple criteria in JQL.
3.1.1 Combining Criteria with Logical Operators
Logical operators allow you to combine multiple criteria using logical AND, OR, and NOT operations. These operators enable you to create more complex queries by specifying multiple conditions.
AND Operator
The AND operator is used to combine multiple criteria, and it requires all conditions to be true for an issue to be included in the search results. For example, if you want to find all open issues assigned to a specific user, you can use the following query:
assignee = "John Doe" AND status = Open
This query will return all issues that are assigned to “John Doe” and have an open status.
OR Operator
The OR operator is used to combine multiple criteria, and it requires at least one condition to be true for an issue to be included in the search results. For example, if you want to find all issues assigned to either “John Doe” or “Jane Smith,” you can use the following query:
assignee = "John Doe" OR assignee = "Jane Smith"
This query will return all issues that are assigned to either “John Doe” or “Jane Smith.”
NOT Operator
The NOT operator is used to exclude issues that meet a specific condition. For example, if you want to find all issues that are not assigned to “John Doe,” you can use the following query:
NOT assignee = "John Doe"
This query will return all issues that are not assigned to “John Doe.”
3.1.2 Combining Criteria with Parentheses
Parentheses can be used to group criteria and control the order of evaluation in a query. By using parentheses, you can create more complex queries and specify the precedence of different conditions.
For example, if you want to find all issues assigned to “John Doe” and either have a high priority or are in the “In Progress” status, you can use the following query:
assignee = "John Doe" AND (priority = High OR status = "In Progress")
This query will return all issues that are assigned to “John Doe” and either have a high priority or are in the “In Progress” status.
Conclusion
In this section, we explored various tips and tricks for advanced queries in JQL. By utilizing parentheses, leveraging the “NOT” operator, using wildcards, and combining multiple operators, you can create more sophisticated queries and get more precise results. Finally, saving and sharing your queries as filters allows for easy access and collaboration. By mastering these tips and tricks, you can become a JQL expert and unlock the full potential of Jira for your project management needs.
Agile Coach
11 个月I don't often save LinkedIn posts. But this is now in my saved list. Thanks for the article Danish!
Scrum Master at T-Systems | MBA | German A1 | SAFe 6.0 Certified Advanced Scrum Master | Google and AWS Certified
11 个月Thanks for Sharing