NQL (North Query Language) is an advanced query language that gives users greater power and flexibility in filtering results as compared to the filters UI.
To get started with NQL, click on the “+ Filter” link on the “All Initiatives” page. Select “Add NQL” from the dropdown.
On selecting this option, the NQL input field appears. You can now start writing your NQL query. Press enter to trigger a search based on your NQL query.
Important: NQL can run alongside other UI based filters – the result set is filtered based on both NQL and other filters. It is up to the user to ensure that the filtering criteria specified in the two does not conflict. If that happens it is quite likely that no results will be returned.
Syntax and Examples
The basic syntax of an NQL expression is:
field operator value
status = "In Progress" owner = 3 priority = "High" created_at > "2023-02-06" due_date < "2023-01-01" owner IS NULL owner IS NOT NULL due_date IS SET due_date IS NOT SET due_date is SET ORDER BY owner
One can also combine multiple NQL expressions using the AND, OR or NOT operators:
status = "In Progress" AND owner = 3 updated_at < "2023-01-01" AND NOT status = "Done" priority = "High" AND (owner = 3 OR owner = 4) priority = "High" AND NOT (owner = 3 OR owner = 4)
As the last example shows, expressions can be grouped together using parenthesis, if required.
The following operators are available in NQL:
- Equals, i.e.
- Less than,
- Less than or equal:
- Greater than:
- Greater than or equal:
- Is, i.e.
is. Can be used to check if a value is set (
is set) or not set (
The following system fields are available in NQL.
is set and
is null in the available operators implies that
is not set and
is not null can also be used.
|created_at||Date on which initiative was created||=, <, <=, >, >=||created_at = “2023-01-31”|
created_at >= “2020-01-01”
|updated_at||Date on which initiative was last updated||=, <, <=, >, >=||updated_at = “2023-01-31”|
updated_at >= “2020-01-01”
|last_updated_by||Id of the user who last updated the initiative||=||last_updated_by = 123|
|owner||User id of any of the initiative’s owners||=, is set, is null||owner = 123|
|team||id of the team to which the initiative belongs||=||team = 456|
|is_closed||Whether an initiative is closed or not. Possible values are ||=||is_closed = true|
is_closed = false
|closed_on||Date on which the initiative was closed||=, <, <=, >, >=||closed_on = “2023-01-31”|
closed_on >= “2020-01-01”
|priority||Priority of the initiative. Possible values are ||=||priority = “High”|
|status||Status of the initiative. Possible values are ||=||status = “Not Started”|
status = “Done”
|due_date||Due date of the initiative.||=, is set, is null||due_date <= “2023-03-31”|
due_date is null
|comment_count||Count of comments on the initiative||=, <, <=, >, >=||comment_count > 0|
|last_comment_on||Date on which the last comment was made||=, <, <=, >, >=||last_comment_on = “2023-01-31”|
last_comment_on >= “2020-01-01”
|key_result||id of the Key Result (KR) to which the initiative belongs||=||key_result = 345|
NQL supports custom fields too. Just start typing the custom field name and auto complete will give you a list of all available fields, including custom fields. Once you select a custom field, it’s field name in NQL is replaced by “cf_<id>” where <id> is the sytem generated id for the custom field. Using ids ensures that your queries can survive custom field renames.
|Custom Field Type||Description||Available Operators||Examples|
|Text||Text value||=, is set, is null||cf_123 = “foo”|
|Number||Number value||=, <, <=, >, >=, is set, is null||cf_234 = 1|
cf_234 >= 10
|Date||Date value||=, <, <=, >, >=, is set, is null||cf_345 = “2020-01-01”|
cf_345 <= “2023-03-31”
|User||id of the user set in the custom field||=, is set, is null||cf_456 = 1|
cf_456 is set
|Dropdown||id of the custom field dropdown option||=, is set, is null||cf_567 = 1|
cf_567 is null
NQL can also be used to order results by using the
ORDER BY clause. It’s general form is as follows:
ORDER BY field1, field2, ... ORDER BY field1 ASC, field2 DESC, ...
Fields can be any system or custom fields.
ORDER BY clause must come last in an NQL query. A query containing a single
ORDER BY clause and noting else is also valid and will work as expected.
Important: If an
ORDER BY clause is added to the NQL query, then ordering results by clicking via field headers in the result table will not work.
owner = 3 ORDER BY status team = 3 AND due_date <= 2023-06-30 ORDER BY owner ASC, status DESC ORDER BY status DESC
NQL provides auto complete functionality for the following:
- Field name
- Users (e.g. owner or custom fields with user type)
- Custom fields dropdown options
To ensure that queries can survive renames, auto complete replaces the following with system generated ids:
- Custom field names
- Custom field dropdown options