North Query Language (NQL)

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.

Getting Started

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

For example,

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.

Operators

The following operators are available in NQL:

1. Equals, i.e. =
2. Less than, <
3. Less than or equal: <=
4. Greater than: >
5. Greater than or equal: >=
6. Is, i.e. is. Can be used to check if a value is set (is set) or not set (is null).

System Fields

The following system fields are available in NQL.

Note: is set and is null in the available operators implies that is not set and is not null can also be used.

Field	Description	Available operators	Examples
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 true or false.	=	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 "High", "Mid" or "Low"	=	priority = “High”
status	Status of the initiative. Possible values are "Not Started", "In Progress", "Behind", "At Risk", "Done"	=	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

Custom Fields

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

Ordering Results

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.

The 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.

Examples:

owner = 3 ORDER BY status
team = 3 AND due_date <= 2023-06-30 ORDER BY owner ASC, status DESC
ORDER BY status DESC

Auto Complete

NQL provides auto complete functionality for the following:

1. Field name
2. Users (e.g. owner or custom fields with user type)
3. Custom fields dropdown options
4. KRs
5. Status
6. Priority

To ensure that queries can survive renames, auto complete replaces the following with system generated ids:

1. Custom field names
2. Users
3. KRs
4. Custom field dropdown options