Write advanced JQL queries with functions and multiple clauses
15 min
By the end of this lesson, you'll be able to:
- Use common functions in JQL queries
- Find work items using exact dates, date functions, and calendar functions
- Find work items using words or phrases in text-based fields
- Write JQL queries with multiple clauses using parentheses
What are functions?
Functions replace values that would need to be regularly updated, like dates and field values. This is quicker and more flexible than searching for a specific value every time.
👉 For example: Let’s say you want to search for all work items created before the beginning of the current month. You could use an exact value the date of the first day of the current month to carry out your search. But, you'd need to manually update the date value each month. However, if you used a function for this search, such as startOfMonth(), the JQL function will automatically update to search in the current month.
👇 Click the boxes below to explore examples of several popular functions.
You can see a list of all JQL functions in Atlassian Documentation.
We're updating terminology in Jira, moving from "issue" to "work item", and "project" to "space".
As we roll out these changes, some JQL entries using the new terms may not work yet. If you come across this, try using the old term instead.
There are no changes to existing JQL queries.
Use date functions
You can search for a work item from an exact date using JQL.
👉 For example: You want to find a work item due on September 1, 2026.
due = 2026-09-01
You can write dates using hyphens or slashes in the order year, month, day. If you use slashes, you'll need to use quotation marks around the date.
If you don’t want to use an exact date, you can use date functions. The date can be in the past or future and can use minutes, hours, days, weeks, months, and years.
👉 For example: You want to find all work items that were last updated more than two weeks ago.
updated < “-2w”
The minus sign indicates you’re searching in the past, while a plus sign would indicate your date is in the future.
Use calendar functions
Calendar functions use more relative criteria to search by date, such as start of week or end of year. These results represent fixed dates in times in the calendar relative to your current login date and time. Jira defines when these dates start and end.
👉 For example: You want to find all work items within your spaces that have been resolved since the start of the week.
resolved >= startOfWeek()
Jira will use your account’s time zone to inform the search.
Use increments with calendar functions
You can combine increments and calendar functions to find work items from specific points in the past. Increments move the value you’re searching for up or down using a unit, like days or weeks.
👉 For example: You want to find work items created before the start of a specific week.
created >= startOfWeek(“-5”)
The -5 nested inside of the calendar function searches for work items created before the start of a week, five weeks in the past. Jira assumes you mean week without adding a W to the -5 because the function is based on weeks.
You can also use an increment that doesn't match the function.
👉 For example: You want to find work items updated in the final two days of last week and this current week.
updated >= startOfWeek(“-2d”)
Search with text-based fields
Text-based fields enable users to enter text values on work items. Description and Summary are two common text fields. There are four operators available for searching in text fields:
- Contains ~
- Does not contain !~
- Is
- Not
You can use the contains operator to locate work items by searching for any word or phrase that appears within an work item's Summary, Description, comments, or custom text fields.
👉 For example: You want to locate all the work items across your spaces that relate to finance reports.
summary ~ “finance report”
Specify exact and fuzzy matches
👇 Click the tabs below to learn how to specify whether you want exact or fuzzy matches.
Using quotation marks will return work items that have both exact matches and fuzzy matches , words that are almost the same but slightly different.
👉 For example: If you use the keyword “finance,” Jira would return the fuzzy matches “financed” and “financing.”
summary ~ “finance”
You'll always need to use quotation marks for text searches with more than one word and for certain words like “a,” “an,” “any,” and “are.” Jira will show an error message when these words aren’t in quotes.
Search in any text field
What if you want to search for a word or phrase that appears in any text field on a work item? You can use the text field.
👉 For example: You want to find all work items related to a crash in a space called Lima.
space = LIMA AND text ~ “crash”
The text value is non-case-sensitive, meaning “CRASH” and “crash” return the same results.
Use EMPTY to find blank text fields
You can pair is and is not operators with EMPTY to find work items where a text field is or is not populated.
👉 For example: You want to find all work items that don't have a description.
description is EMPTY
👉 Another example: Let's say you have a custom text field called Stakeholder summary, and you want to find work items where that field has been populated.
“Stakeholder summary[Paragraph]” is not EMPTY
Search with multiple clauses
Parentheses are used to contain arguments, items that adjust how the function operates. You can use parentheses with multiple clauses to indicate how different parts of your query relate to one another.
👉 For example: Let’s say you want to find all unresolved work items in the Lima space as well as all high priority work items in the Alpha Space.
(space = LIMA AND resolution is EMPTY) OR (space = ALPHA AND priority = High)
Since each part of the query is unique, you enclose each part in parentheses.
In this example, it’s important that you use OR, not AND, because work items can only be in one space, not multiple.
👉 Another example: Let's say you're managing a space with multiple work items in progress that need further investigation. Unfortunately, your team has used the term investigation in different ways. Some people have marked the work items with an investigation label. Others have used the word investigation or investigate in the description of the work item.
space = DUBLIN AND (description ~ investigation OR labels = investigation)
This searches for work items in the DUBLIN space that have either a description containing "investigation" or the "investigation" label. If you didn't use parentheses, the results would include work items that have an "investigation" label in other spaces as well.