Set up Jira Cloud
Learn how to set up Jira Cloud and integrate it with other products and applications.
This page describes information about functions that are used for advanced searching.
A function in JQL appears as a word followed by parentheses, which may contain one or more explicit values or Jira fields. In a clause, a function is preceded by an operator, which in turn is preceded by a field. A function performs a calculation on either specific Jira data or the function's content in parentheses, such that only true results are retrieved by the function, and then again by the clause in which the function is used.
Unless specified in the search query, note that JQL searches do not return empty fields in results. To include empty fields (e.g. unassigned issues) when searching for issues that are not assigned to the current user, you would enter (assignee != currentUser() OR assignee is EMPTY) to include unassigned issues in the list of results.
Only applicable for sites with Jira Service Management subscriptions.
Search for all requests that have an approval with a final decision of ‘approved’.
Syntax | 1
approved() |
---|---|
Supported fields | Custom fields of type Approval |
Supported operators | = |
Unsupported operators | ~ , != , !~ , > , >= , < , <= IS , IS NOT , IN , NOT IN , WAS, WAS IN, WAS NOT, WAS NOT IN , CHANGED |
Examples |
|
Only applicable for sites with Jira Service Management subscriptions.
Search for requests where a specific user is an approver for a pending or completed approval step, and may or may not have already approved or declined the approval. This uses an OR operator, and you must specify a username.
Syntax | 1
approver(user,user) |
---|---|
Supported fields | Custom fields of type Approval |
Supported operators | = |
Unsupported operators | ~ , != , !~ , > , >= , < , <= |
Examples |
|
Only applicable for sites with Jira Service Management subscriptions.
Returns issues that whose most recent SLA has missed its goal.
Syntax | 1
breached() |
---|---|
Supported fields | SLA |
Supported operators | = , != |
Unsupported operators | ~ , !~ , > , >= , < , <= IS , IS NOT , WAS , WAS IN , WAS NOT , WAS NOT IN , CHANGED |
Examples |
|
Search for issues that match the selected values of a 'cascading select' custom field.
The parentOption parameter matches against the first tier of options in the cascading select field. The childOption parameter matches against the second tier of options in the cascading select field, and is optional.
The keyword "none" can be used to search for issues where either or both of the options have no value.
Syntax | 1
2
cascadeOption(parentOption)
cascadeOption(parentOption,childOption) |
---|---|
Supported fields | Custom fields of type 'Cascading Select' |
Supported operators | IN , NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= IS , IS NOT, WAS , WAS IN , WAS NOT , WAS NOT IN , CHANGED |
Examples |
|
Provides the underlying ID of an option in a multiple choice or dropdown custom field. For example, in a multiple choice field with options Yes, No, Unknown, searching for No will return 2.
Requires at least one argument. For multiple arguments, returns the ID of each one. Arguments must be valid option values.
Syntax | 1
2
choiceOption(ValueOption)
choiceOption(ValueOption1,ValueOption2,ValueOption3) |
---|---|
Supported fields | Custom fields of type multiple choice and dropdown |
Supported operators | IN , NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= , IS , IS NOT, WAS , WAS IN , WAS NOT , WAS NOT IN , CHANGED |
Examples |
|
Search for issues that are assigned to a completed Sprint.
It is possible for an issue to belong to both a completed Sprint(s) and an incomplete Sprint(s). See also openSprints().
Syntax | 1
closedSprints() |
---|---|
Supported fields | Sprint |
Supported operators | IN , NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= |
Examples |
|
Only applicable for sites with Jira Service Management subscriptions.
Returns issues that have an SLA that has completed at least one cycle.
Syntax | 1
completed() |
---|---|
Supported fields | SLA |
Supported operators | = , != |
Unsupported operators | ~ , !~ , > , >= , < , <= IS , IS NOT , WAS , WAS IN , WAS NOT , WAS NOT IN , CHANGED |
Examples |
|
Find issues in components that are led by a specific user. You can optionally specify a user, or if the user is omitted, the current user (i.e. you) will be used.
If you are not logged in to Jira, a user must be specified.
Syntax | 1
2
componentsLeadByUser()
componentsLeadByUser(username) |
---|---|
Supported fields | Component |
Supported operators | IN , NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= IS , IS NOT, WAS , WAS IN , WAS NOT , WAS NOT IN , CHANGED |
Examples |
|
Perform searches based on the time at which the current user's session began. Also, see lastLogin.
Syntax | 1
currentLogin() |
---|---|
Supported fields | Created, Due, Resolved, Updated, custom fields of type Date/Time |
Supported operators | = , != , > , >= , < , <= WAS* , WAS IN* , WAS NOT* , WAS NOT IN* , CHANGED* * Only in predicate |
Unsupported operators | ~ , !~ IS , IS NOT , IN , NOT IN |
Examples |
|
Perform searches based on the currently logged-in user.
This function can only be used by logged-in users. So if you are creating a saved filter that you expect to be used by anonymous users, do not use this function.
Syntax | 1
currentUser() |
---|---|
Supported fields | Assignee, Reporter, Voter, Watcher, Creator, custom fields of type User |
Supported operators | = , != |
Unsupported operators | ~ , !~ , > , >= , < , <= IS , IS NOT , IN , NOT IN , WAS , WAS IN , WAS NOT , WAS NOT IN , CHANGED |
Examples |
|
Perform searches based on the customers details.
To use this JQL function, turn on Customer service management on the Features page in Project settings.
This function will return up to 32000 customers.
Syntax | 1
customerDetail( ) |
---|---|
Supported fields | Assignee, Reporter, Voter, Watcher, custom fields of type User |
Supported operators | IN , NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= IS , IS NOT , WAS , WAS IN , WAS NOT IN, WAS NOT , CHANGED |
Examples |
|
Perform searches based on the earliest unreleased version in a project. See also unreleasedVersions.
Version order is determined by the order versions are placed in on the Releases page in the project. The version at the bottom of the list is considered the "earliest." To change the order of versions, drag and drop them to a new place in the list.
Syntax | 1
earliestUnreleasedVersion(project) |
---|---|
Supported fields | AffectedVersion, FixVersion, custom fields of type Version |
Supported operators | = , != , ~ , !~ , > , >= , < , <= IS, IS NOT, WAS, WAS NOT |
Unsupported operators | IN, NOT IN, WAS IN, WAS NOT IN, CHANGED |
Examples |
|
Only applicable for sites with Jira Service Management subscriptions.
Returns issues whose SLA clock is at a certain point relative to a cycle's start event.
Syntax | 1
everbreached() |
---|---|
Supported fields | SLA |
Supported operators | = , !=, > , >= , < , <= |
Unsupported operators | ~ IS , IS NOT , WAS , WAS IN , WAS NOT , WAS NOT IN , CHANGED |
Examples |
|
Perform searches based on the end of the current day.
See also endOfWeek, endOfMonth, and endOfYear; and startOfDay, startOfWeek, startOfMonth, and startOfYear.
Syntax | 1
2
endOfDay()
endOfDay("inc") where inc is an optional increment of (+/-)nn(y|M|w|d|h|m). If the time unit qualifier is omitted, it defaults to the natural period of the function, e.g. endOfDay("+1") is the same as endOfDay("+1d"). If the plus/minus (+/-) sign is omitted, plus is assumed. |
---|---|
Supported fields | Created, Due, Resolved, Updated, custom fields of type Date/Time |
Supported operators | = , != , > , >= , < , <= WAS* , WAS IN* , WAS NOT* , WAS NOT IN* , CHANGED** Only in predicate |
Unsupported operators | ~ , !~ IS , IS NOT , IN , NOT IN |
Examples |
|
Perform searches based on the end of the current month.
See also endOfDay, endOfWeek, and endOfYear; and startOfDay, startOfWeek, startOfMonth, and startOfYear.
Syntax | 1
2
endOfMonth()
endOfMonth("inc") where inc is an optional increment of (+/-)nn(y|M|w|d|h|m). If the time unit qualifier is omitted, it defaults to the natural period of the function, e.g. endOfMonth("+1") is the same as endOfMonth("+1M"). If the plus/minus (+/-) sign is omitted, plus is assumed. |
---|---|
Supported fields | Created, Due, Resolved, Updated, custom fields of type Date/Time |
Supported operators | = , != , > , >= , < , <= WAS* , WAS IN* , WAS NOT* , WAS NOT IN* , CHANGED** Only in predicate |
Unsupported operators | ~ , !~ IS , IS NOT , IN , NOT IN |
Examples |
|
Search for issues that are due by the end of the last day of the current week. By default, this function considers Saturday to be the last day of the week. You can use a different day (for example, Sunday) as the end of the week. See the syntax in the examples mentioned below.
See also endOfDay, endOfMonth, and endOfYear; and startOfDay, startOfWeek, startOfMonth, and startOfYear.
Syntax | 1
2
endOfWeek()
endOfWeek("inc") where inc is an optional increment of (+/-)nn(y|M|w|d|h|m). If the time unit qualifier is omitted, it defaults to the natural period of the function, e.g. endOfWeek("+1") is the same as endOfWeek("+1w"). If the plus/minus (+/-) sign is omitted, plus is assumed. |
---|---|
Supported fields | Created, Due, Resolved, Updated, custom fields of type Date/Time |
Supported operators | = , != , > , >= , < , <= WAS* , WAS IN* , WAS NOT* , WAS NOT IN* , CHANGED** Only in predicate |
Unsupported operators | ~ , !~ IS , IS NOT , IN , NOT IN |
Examples |
|
Perform searches based on the end of the current year.
See also startOfDay, startOfWeek, and startOfMonth; and endOfDay, endOfWeek, endOfMonth, and endOfYear.
Syntax | 1
2
endOfYear()
endOfYear("inc") where inc is an optional increment of (+/-)nn(y|M|w|d|h|m). If the time unit qualifier is omitted, it defaults to the natural period of the function, e.g. endOfYear("+1") is the same as endOfYear("+1y"). If the plus/minus (+/-) sign is omitted, plus is assumed. |
---|---|
Supported fields | Created, Due, Resolved, Updated, custom fields of type Date/Time |
Supported operators | = , != , > , >= , < , <= WAS* , WAS IN* , WAS NOT* , WAS NOT IN* , CHANGED** Only in predicate |
Unsupported operators | ~ , !~ IS , IS NOT , IN , NOT IN |
Examples |
|
Only applicable for sites with Jira Service Management subscriptions.
Perform searches based on the entitlement’s details.
To use this JQL function, turn on Customer service management and Products and entitlements on the Features page in Project settings.
This function will return up to 32000 entitlements.
Syntax | 1
entitlementDetail("Field Name", "Field Value") |
---|---|
Supported fields | Entitlement |
Supported operators | IN , NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= IS , IS NOT , WAS , WAS IN , WAS NOT IN, WAS NOT , CHANGED |
Examples |
|
Only applicable for sites with Jira Service Management subscriptions.
Perform searches based on a product.
To use this JQL function, turn on Customer service management and Products and entitlements on the Features page in Project settings.
Syntax | 1
entitlementProduct("ProductName") |
---|---|
Supported fields | Entitlement |
Supported operators | IN , NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= IS , IS NOT , WAS , WAS IN , WAS NOT IN, WAS NOT , CHANGED |
Examples |
|
Only applicable for sites with Jira Service Management subscriptions.
Returns issues that have missed one of their SLA goals.
Syntax | 1
everbreached() |
---|---|
Supported fields | SLA |
Supported operators | = , != |
Unsupported operators | ~, > , >= , < , <= IS , IS NOT , WAS , WAS IN , WAS NOT , WAS NOT IN , CHANGED |
Examples |
|
Search for issues that are assigned to a sprint that hasn't been started yet.
It is possible for an issue to belong to both a completed sprint(s) and an incomplete sprint(s).
Syntax | 1
futureSprints() |
---|---|
Supported fields | Sprint |
Supported operators | IN , NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= |
Examples |
|
Find issues that you have recently viewed, i.e. issues that are in the 'Recent Issues' section of the 'Issues' drop-down menu.
Note:
issueHistory() returns up to 50 issues, whereas the 'Recent Issues' drop-down returns only 5.
if you are not logged in to Jira, only issues from your current browser session will be included.
Syntax | 1
issueHistory() |
---|---|
Supported fields | Issue |
Supported operators | IN , NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= IS , IS NOT , WAS , WAS IN , WAS NOT , WAS NOT IN , CHANGED |
Examples |
|
Perform searches based on issues that are associated with remote links that have any of the specified global ids.
This function accepts 1 to 100 globalIds. Specifying 0 or more than 100 globalIds will result in errors.
Syntax | 1
issuesWithRemoteLinksByGlobalId() |
---|---|
Supported fields | Issue |
Supported operators | IN , NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= IS , IS NOT , WAS , WAS IN , WAS NOT , WAS NOT IN , CHANGED |
Examples |
|
Perform searches based on the time at which the current user's previous session began. See also currentLogin.
Syntax | 1
lastLogin() |
---|---|
Supported fields | Created. Due, Resolved, Updated, custom fields of type Date/Time |
Supported operators | = , != , > , >= , < , <= WAS* , WAS IN* , WAS NOT* , WAS NOT IN* , CHANGED** Only in predicate |
Unsupported operators | ~ , !~ IS , IS NOT , IN , NOT IN |
Examples |
|
Perform searches based on the latest released version (i.e. the most recent version that has been released) of a specified project. See also releasedVersions().
The "latest" is determined by the ordering assigned to the versions, not by actual Version Due Dates.
Syntax | 1
latestReleasedVersion(project) |
---|---|
Supported fields | AffectedVersion, FixVersion, custom fields of type Version |
Supported operators | = , != |
Unsupported operators | ~ , !~ , > , >= , < , <= IS , IS NOT , IN , NOT IN, WAS , WAS IN , WAS NOT , WAS NOT IN , CHANGED |
Examples |
|
Searches for epics and subtasks. If the issue is not an epic, the search returns all subtasks for the issue.
Only applicable for company-managed projects.
Syntax | 1
linkedissue = issueKey |
---|---|
Supported fields | Issue |
Supported operators | =, != |
Examples |
|
Searches for issues that are linked to an issue. You can restrict the search to links of a particular type.
Syntax | 1
2
3
linkedIssues(issueKey)
linkedIssues(issueKey,CaseSensitiveLinkType)
linkedIssues(issueKey,CaseSensitiveLinkType, CaseSensitiveLinkType) |
---|---|
Supported fields | Issue |
Supported operators | IN , NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= IS , IS NOT , WAS , WAS IN , WAS NOT , WAS NOT IN , CHANGED |
Examples |
|
Perform searches based on the members of a particular group.
Syntax | 1
membersOf(Group) |
---|---|
Supported fields | Assignee, Reporter, Voter, Watcher, Creator, custom fields of type User |
Supported operators | IN , NOT IN , WAS IN , WAS NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= IS , IS NOT , WAS , WAS NOT , CHANGED |
Examples |
|
Only applicable for sites with Jira Service Management subscriptions.
Search for requests where the current user is the approver for a pending or completed approval step, and may or may not have already approved or declined the request.
Syntax | 1
myApproval() |
---|---|
Supported fields | Custom fields of type Approval |
Supported operators | = |
Unsupported operators | 1
2
~ , != , !~ , > , >= , < , <=
IS , IS NOT , IN , NOT IN , WAS, WAS IN, WAS NOT, WAS NOT IN , CHANGED |
Examples | Find all requests that required my approval |
Only applicable for sites with Jira Service Management subscriptions.
Search for requests where the current user is the approver for a pending approval step and is yet to approve or decline the approval.
Syntax | 1
myPendingApproval() |
---|---|
Supported fields | Custom fields of type Approval |
Supported operators | = |
Unsupported operators | ~ , != , !~ , > , >= , < , <= |
Examples | Find all requests that currently require my approval |
Only applicable for sites with Jira Service Management subscriptions.
Search for requests where the current user is the approver for a pending approval step, and may or may not have already approved or declined the approval.
Syntax | 1
myPending() |
---|---|
Supported fields | Custom fields of type Approval |
Supported operators | = |
Unsupported operators | ~ , != , !~ , > , >= , < , <= |
Examples | Find all requests that currently or previously required my approval |
Perform searches based on the current time.
Syntax | 1
now() |
---|---|
Supported fields | Created. Due, Resolved, Updated, custom fields of type Date/Time |
Supported operators | = , != , > , >= , < , <= WAS* , WAS IN* , WAS NOT* , WAS NOT IN* , CHANGED** Only in predicate |
Unsupported operators | ~ , !~ IS , IS NOT , IN , NOT IN |
Examples |
|
Search for issues that are assigned to a sprint that was started, but has not yet been completed.
It is possible for an issue to belong to both a completed sprint(s) and an incomplete sprint(s). See also closedSprints().
Syntax | 1
openSprints() |
---|---|
Supported fields | Sprint |
Supported operators | IN , NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= |
Examples |
|
Perform searches based on the organization details.
To use this JQL function, turn on Customer service management on the Features page in Project settings.
This function will return up to 32000 organizations.
Syntax | 1
organizationDetail() |
---|---|
Supported fields | Organizations |
Supported operators | IN , NOT IN |
Unsupported operators | = , != , ~ , !~ , > , >= , < , <= IS , IS NOT , WAS , WAS IN , WAS NOT IN, WAS NOT , CHANGED |
Examples |
|
Only applicable for sites with Jira Service Management subscriptions.
Search for all requests sent by the members of an organization. Returns requests that the members have shared with or kept private from that organization, and with any other organizations they're a member of.