Use JQL to filter search results
15 min
Intermediate
By the end of this lesson, you’ll be able to:
- Access JQL searches using the search bar and filters
- Define JQL functions, fields, keywords, and operators
- Explain how the elements of JQL syntax work together to filter search results
- Use the autocomplete, Spacebar, and Syntax Help features in Jira to help write JQL queries
- Write a simple JQL query
What is JQL?
Jira Query Language, or JQL for short, is a text-based language that defines how Jira narrows down a search. You can search for complicated criteria that can’t be defined with a quick or basic search.
👇Here’s what JQL looks like.
All JQL queries do two things:
- Select a subset of work items.
- Order the results.
A query is the statement you use to run a search. JQL queries support complex searches to help you find work item data, across multiple fields in multiple projects.
Access JQL searches
There are two ways to access JQL searches. The first is by using the Search field.
👇 Click the tabs below to learn how to access JQL from the Search field.
Select Search from the main navigation bar. Then, select View all work items.
The second way to access JQL searches is in the sidebar. Under Filters, select Search work items. This brings you to the same list of work items.
👇 Here’s how to access JQL from the sidebar.
Learn the language of JQL queries
The easiest way to see how JQL is written is by moving from basic search to JQL.
👇 Click the tabs below to see how JQL is written by switching from Basic to JQL.
On the search page, click Basic.
JQL syntax may seem complicated, and you might feel like you have to remember all the syntax to use it. You don’t! Jira comes with three helpful features for writing syntax. These include the autocomplete feature, the spacebar feature, and the Syntax help feature.
👇Click through the tabs below to learn more about each feature.
As you type a query in JQL, Jira will provide a list of values to select.
👉 For example: If you typed 's' and 't', Jira would show the fields that start with 'st', like 'start date', 'status', 'statusCategory', and so on. You can then select the text you want to use.
Elements of JQL syntax
The entire JQL statement is called the query. A query is made up of multiple clauses. These clauses define the work items you’re searching for.
👇 Here’s an example of that query broken out into its clauses.
Each clause is made up of multiple elements. The elements of JQL syntax are:
- Field
- Operator
- Value
- Keyword
- Function
Let’s take a look at each element.
What is a field?
Jira uses fields to store data. All of your JQL statements start with fields, so that will always be the first element you enter. There are two types of fields in JQL. System fields, such as project, status, created date, and assignee, are included with every Jira instance. Custom fields are created by a Jira admin to expand the types of information Jira collects.
👇 Click through the tabs below to see examples of each field type.
👉 For example: Let’s say you wanted to show all work items with a status of 'In Progress.' ‘Status’ is the system field, because it is already included in the Jira instance.
What is an operator?
An operator is used to compare the field to a value within that field.
👉 For example: Let’s say you wanted to show all work items with a status of “In Progress.” The operator is =, which is used to search for work items with a field that has the exact value specified.
What is a value?
A value is the information that is being searched for in the field.
👉 For example: Let’s say you wanted to show all work items with a status of “In Progress.” The value we are looking for is “In Progress.” The value is in quotation marks because the value contains more than one word. Any search term that is longer than one word must be in quotes.
What is a keyword?
Keywords have several uses in JQL. They can join clauses together to form a complex JQL query. They can also sort the query results.
👇 Click through the tabs below to see some examples of using keywords.
Keywords can be used to join multiple clauses together to further define a query.
👉 For example: Let’s say you want to find all work items where the status is "In Progress" and the color is Red. Here’s how you would write the query:
status = “in progress” AND color = red
Only work items that meet the criteria in both clauses will be included in our search results. Now, let’s change the keyword to OR and see how it changes the search results.
status = “in progress” OR color = red
The search results will include work items that meet the criteria in either clause.
What is a function?
A function performs a calculation or gathers information based on the operator before it. These can be used in place of fields when you want to search, but not for a specific field value.
👉 For example: Let’s say you want to see all the work items that have a due date before or on the last day of the month. You would include the endOfMonth() function in your query.
Write a simple query
In this example, you want to see all the bugs assigned to your teammate Jennifer Evans within a project called 'Project B'. In the query, you'll need three clauses: one for the assignee, Jennifer Evans; another to define which project you're looking in; and a third for the work type, Bug.
👉 Your final query will look like this: assignee = Jennifer Evans AND project = “Project B” AND type = Bug
👇 Click the boxes below to see the steps to write this query.
How was this lesson?
next lesson
Write advanced JQL queries with functions and multiple clauses
- What are functions?
- Use date functions
- Use calendar functions
- Search with text-based fields
- Search with multiple clauses