JQL Keywords

Custom field name duplicates

If you have custom fields with the same name as Jira default fields, Enhanced Search will prioritise Jira’s default fields during searches. We recommend renaming your custom fields before using them in search queries, as Jira’s default fields will be used instead of custom fields with the same name.

In this section, each JQL keyword is explained. JQL Keywords can be used in the Issue Search screen when searching in advanced mode.

Enhanced Search augments each issue in your Jira instance with additional metadata, and provides several JQL keywords. The provided keywords can be used within JQL queries to access this metadata. These keywords allow users to search for previously unavailable variables, such as the number of sub-tasks (numberOfSubtasks).

JQL keywords can be used in the Enhanced Search screen and all JQL fields within Jira. 

JQL keywords will not work until an initial metadata synchronization has been performed, as described in Synchronising Keywords.

Metadata Stored

The following metadata is stored for each issue:

  • The number of issue links.

  • Number of attachments on an issue.

  • List of file extensions from attachments.

  • Date on which the first attachment was added to an issue.

  • Date on which the last (most recent) attachment was added to an issue.

  • List of accountIDs that added attachments to an issue.

  • Number of sub-tasks of an issue.

  • List of project roles that worklogs were restricted to.

  • List of user groups that worklogs were restricted to.

  • Number of comments on an issue.

  • Date of the first comment on an issue.

  • Date of the last (most recent) comment on an issue.

  • List of all dates on which comments were added to an issue.

  • List of accountIDs that have added comments to an issue.

  • List of project roles that comments have been restricted to.

  • List of user groups that comments have been restricted to.

  • The accountID of the person who last (most recently) made a comment on an issue.

  • The project role that the last (most recent) comment was restricted to.

  • The user group that the last (most recent) comment was restricted to.

The Issue Updated field is not affected by the metadata stored against each issue.

The metadata stored against each issue is updated asynchronously when an issue is updated. Meaning search results may be out of date for a second or two after an issue is edited.

Required Permissions

Search results are incorrect if the user does not have permission to:

  • View and edit all issues (edit permission is required to store the additional metadata).

  • View all comments, including those restricted to a particular group/role.

  • View all worklogs, including those restricted to a particular group/role.

Attachments

numberOfAttachments

Find issues that have a certain number of file attachments.

status = Closed AND numberOfAttachments > 3

This keyword can be used with numeric comparison operators.

attachmentType

Search for issues that have a particular file type attached to them. File types are determined by the file extension. For example, a file called screenshot.png has a file type of 'png'.

numberOfAttachments > 0 AND attachmentType = 'jpg'
issuetype = Invoice AND attachmentType in ('pdf', 'docx', 'xls')

This keyword can use the =, !=, in and not in operators.

firstAttachmentDate

Find issues based on the date the first attachment was added:

project = STORAGE AND firstAttachmentDate < now()
project = STORAGE AND firstAttachmentDate >= '2016-04-01'
project = STORAGE AND firstAttachmentDate = '2000-01-01'

Relative date functions can be used as well as regular numeric comparison operators.

lastAttachmentDate

The lastAttachmentDate keyword can be used to find issues based on the date that the most recent attachment was added:

project = STORAGE AND lastAttachmentDate > startOfMonth()

In the same way as firstAttachmentDate, this keyword can use the numeric comparison operators and the relative date JQL functions.

fileAttachedBy

This keyword can be used to find issues that have a file attached by a particular user. You must use the accountID of the user you are interested in.

reporter = currentUser() AND fileAttachedBy = "012345-678912-34567-891011"

This keyword can also be compared using the !=, in and not in operators.

Comments

numberOfComments

The numberOfComments keyword can be used to find issues with a particular number of comments:

resolution = 'Wont Fix' AND numberOfComments > 0

This keyword can be used with the numeric comparison operators.

firstCommentedDate

The firstCommentedDate keyword can be used to search for issues based on the date of the first comment.

created > startOfDay() AND firstCommentedDate = now()
priority = High AND firstCommentedDate < startOfWeek()

This keyword can be used with the JQL relative date functions and also the numeric comparison operators.

lastCommentedDate

The lastCommentedDate keyword can be used to search for issues based on the date of most recent comment.

assignee = currentUser() AND lastCommentedDate < startOfMonth()
status = 'In Progress' AND lastCommentedDate = '2016-10-14'

This keyword can be used with the JQL relative date functions and also the numeric comparison operators.

commentedOn

This keyword can be used to find issues that had a comment made on them on a particular date.

commentedOn = '2016-02-14' AND project = VALENTINE
project = APOLLO AND component = 'Lunar Lander' AND commentedOn in ('1969-07-20', '1969-07-21')

The commentedOn keyword can be used with the following operators: in, not in, != AND =

commentedBy

The commentedBy keyword can be used to search for issues that have comments on them made by a particular user. You must specify an acccountID:

reporter = currentUser() AND commentedBy = '012345-678912-34567-891011'

This keyword can be used with the following operators: in, not in, != AND =

lastCommentBy

This keyword can be used to search for issues based on the user who made the most recent comment. You must provide a accountID:

reporter = '012345-678912-34567-891011' AND lastCommentBy = currentUser()
assignee = currentUser() AND lastCommentBy in ('012345-678912-34567-891011', '012345-678912-34567-891012')

This keyword can be used with the following operators: =, !=, in and not in

Linked Issues

The following keyword allows you to search based on linked issues.

Retrieve issues that have a certain number of issue links.

status = Open AND numberOfLinks = 3

Numeric comparison operators (>, <, !=, <=, >=, and =) can be used.

numberOfLinks > 5 AND numberOfLinks <= 10

Sub-tasks

numberOfSubtasks

The numberOfSubtasks keyword can be used to search for issues with a certain number of sub-tasks.

issuetype = Task AND numberOfSubtasks > 10

This keyword can also use the numeric comparison operators.


On this page