Worklog Query Language (WQL)

Owned by Dan Mihalache
Last updated: Jun 05, 2024 by Praveena Manohar
4 min read

Rich Filters::Time Tracking Dashboards is an extension of the Rich Filters for Jira Dashboards app. 

Rich Filters::Time Tracking Dashboards allows you to build structured work log queries using the Worklog Query Language (WQL). The work log queries are embedded in JQL through the rfWorklogs custom field, which is automatically added by the app. When used in rich filters and rich filter gadgets, JQL queries containing work log queries will filter the issues and their work logs based on work log attributes. The results can then be aggregated by issue values (issue count, issue numeric custom fields, issue time tracking fields) or work log values (Worklog Time Spent).

The WQL queries are always embedded in JQL through the rfWorklogs custom field, and they follow either the operator '~' (CONTAINS) or '~!' (DOES NOT CONTAIN). The JQL query: 

rfWorklogs ~ "WQL query"

returns:

  • when used to aggregate issue values (issue count or issue value fields) or when used in Jira's issue navigator – all the issues containing at least one work log satisfying the WQL query

  • when used to aggregate work log values (Worklog Time Spent) – all the work logs (belonging to the above issues) satisfying the WQL query

On this page:

Constructing WQL queries

The WQL syntax is very similar to the JQL syntax. A simple query in WQL (also known as a 'clause') consists of a work log attribute, followed by an operator, followed by one or more values or functions. For example:

rfWorklogs ~ "author = abrown"

The query uses the 'author' work log attribute, the EQUALS operator, and the value 'abrown'. This query will find all issues having work logged (at least one work log) by the user 'abrown'. Or from a functional point of view, we would say, all the issues on which 'abrown' has worked. The same query, when used to aggregate work log values, will return only the work logs having 'abrown' as author.

A more complex query might look like this:

This query will find all the issues having work logged (at least one work log) by the user 'abrown' since September 1st, 2018, inclusive. From a functional point of view, we would say, all the issues on which 'abrown' has worked since September 1st, 2018. When used to aggregate work log values, the same query will return only the work logs containing work performed by 'abrown' since September 1st, 2018.

Setting the precedence of operators in WQL queries

You can use parentheses in complex WQL statements to enforce the precedence of operators. For example, the JQL query

returns the issues containing at least one work log and the work logs from the author 'abrown' containing work started before or after August 2018 (in other words, it excludes August 2018).

Note that if you do not use parentheses, the AND operator takes precedence over the OR operator. 

Supported work log attributes and operators

WQL supports the following work log attributes and operators:

Attribute Type

Work Log Attributes

Supported Operators

Values / Supported Functions

Examples

Attribute Type

Work Log Attributes

Supported Operators

Values / Supported Functions

Examples

User

  • author: the user who has performed the work.
    This is shown as Worklog Author in rich filter gadgets and dynamic filters.

  • updateAuthor: the last user who has edited the work log after its creation

  • =

  • !=

  • IN

  • NOT IN

  • username

  • native JQL functions available for user issue fields

  • work logs where the work is performed by 'abrown': author = abrown

  • work logs where the work is performed either by 'abrown' or 'ejones': author IN (abrown, ejones)

  • work logs where the work is performed by any member of the group 'jira-developers': author IN membersOf('jira-developers')

  • work logs where the work is performed by the logged-in user: author = currentUser()

Date time

  • dateStarted: date when the unit of work has started
    This is shown as Worklog Date in dynamic filters.

  • dateCreated: date when the work log was created

  • dateUpdated: date when the work log was last updated

  • >

  • >=

  • <

  • <=

  • Date/time values – valid formats include: 'yyyy/MM/dd HH:mm', 'yyyy-MM-dd HH:mm', 'yyyy/MM/dd', 'yyyy-MM-dd', period format e.g. '-5d', '4w 2d'. See the Quote-marks in WQL note below.

  • native JQL functions available for date/time issue fields

  • work logs started before September 1st 2018: dateStarted < 2018-09-01

  • work logs started during the last 5 days: dateStarted >= -5d

  • work logs that have been edited this week: dateUpdated >= startOfWeek()

Duration

  • timeSpent: the time spent to perform the work

  • =

  • !=

  • >

  • >=

  • <

  • <=

  • IN

  • NOT IN

  • duration values

  • work logs where the time spent is more than 2 hours: timeSpent > 2h

Text

  • comment: the work description added in the work log

  • ~

  • !~

  • IS

  • IS NOT

Text searches need to be surrounded by quote-marks (single or double). See the Quote-marks in WQL note below.

  • work logs with work descriptions containing the word "test": comment ~ 'test'

  • work logs with work descriptions containing any word starting with "win": comment ~ 'win*'

  • work logs without any work description: comment IS empty

Flag

  • wasUpdated: true if the work log has been edited after its creation

  • =

  • !=

  • YES, NO

  • 0, 1

  • TRUE, FALSE

  • SET, UNSET

TRUE, FALSE and SET are reserved JQL words. When used in queries, you need to surround them by quote-marks (single or double). See the Quote-marks in WQL note below.

  • work logs that have ever been edited: wasUpdated = yes