NQL syntax overview

Specifying table

Every NQL query starts with a short statement specifying the table to select data from. The syntax to specify the table is:

<namespace>.<table>

For example, listing all records in the events table from the execution namespace translates into the following statement:

execution.events

Syntax shortcuts

Instead of typing the namespace and the table, you can also use the predefined shortcuts. Type the table name only, without a namespace first to retrieve data from the following tables:

Namespace	Table	Shortcut
application	applications	applications
binary	binaries	binaries
campaign	campaigns	campaigns
device	devices	devices
user	user	users

For example, type devices instead of device.devices to list all the records within the devices table in the device namespace.

devices

You do not need to specify the table fields included in the results to query data from the table. The system includes default fields that are most relevant to identify the records. For more information about fields contained in specific table, refer to the NQL data model page. Use the NQL list keyword to access other fields in the specific table.

Specifying time frame

You have the option to filter your results over a specific period of time by putting a time frame selection right after the table name in your NQL statement. Depending on what you need, you can choose from various data selection formats and time precisions. For example you can specify the number of days back:

execution.crashes during past 7d

Or specific date:

execution.crashes on Feb 8, 2024

You can also use a time selection when querying the following inventory objects: devices, users, binaries. If you specify the time frame for the inventory objects, the system refers to the events behind the object's activity.

For example, the following queries refer to the same set of data.

devices during past 7d

devices 
| with device_performance.events during past 7d

For more information regarding the time selection formats refer to the NQL time selection

Customizing Query Results

After specifying the table and timeframe, you can further refine your query by providing additional instructions to the system using keywords, operators and functions. These refinements allow you to organize, filter or aggregate your results to gather more comprehensive insights.

For example:

1. Filter the results using the where clause

   binaries during past 24h
   | where binary.name == "dllhost.exe"

2. Select specific data to display using the list clause

   binaries during past 24h
   | where binary.name == "dllhost.exe"
   | list name, version, platform, architecture, size

3. Order results using the sort ... desc clause

   binaries during past 24h
   | where binary.name == "dllhost.exe"
   | list name, version, platform, architecture, size
   | sort size desc

4. Set a maximum number of results using the limit clause

   binaries during past 24h
   | where binary.name == "dllhost.exe"
   | list name, version, platform, architecture, size
   | sort size desc
   | limit 10

For more information about specific instructions, refer to the NQL keywords section.

Pattern matching

Use wildcard characters such as * and ? for text filters.

* replaces any number of characters

? replaces any single character

For example, listing all binaries with a name starting with dll and finishing with .exe translates into the following query:

binaries during past 24h
| where binary.name == "dll*.exe"
| list size,name,version 
| sort size desc 
| limit 100

• NQL time selection
• NQL data types

Escaping characters

Use the backslash (\) as an escape character in literal strings.

Common escape sequences:

• \": Escapes double quotes within string literals
• \': Escapes single quotes within string literals
• \\: Escapes the backslash character itself
• \\u####: Unicode escape sequences for special characters

The following example shows how to escape a set of Unicode characters, such as \u0022 used for the quotation mark ("):

devices
| with execution.events
| where binary.name in ["\\u0022", "\\u003c", "\\u005f"]

The following example shows how to use an escape character when searching in a Windows file path, such as C:\Program Files\:

devices
| compute program_files_path = "C:\\Program Files\\"
| where program_files_path != null

The following example shows how to use an escape character when searching in a Windows registry path HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft:

devices
| include remote_action.get_windows_registry_key_values_windows.executions
| where inputs.RegistryKey1 == "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft"
| compute c1 = outputs.ValueData1.last() | where c1 != null

Commenting

Use comments in your NQL queries to include explanatory notes that are ignored during execution. Comments help clarify the intent of the query, making it easier to read, maintain, and understand.

Use /* to begin a comment and */ to end it. All text between these symbols will be ignored during execution.

devices during past 7d 
/* This comment spans
multiple lines and is ignored */
| list device.name, device.entity

Keyboard shortcuts for commenting

Use the following keyboard shortcuts to quickly add or remove comments in your NQL queries.

Line-based comment

Toggle comment on the current line or selected multiple lines.

The following shortcuts add or remove comment markers (/* ... */) around the entire line where your cursor is placed. If multiple lines are highlighted, it wraps full lines in a single comment block.

• Windows: Press Ctrl + /
• macOS: Press Cmd + /

Inline or block comment

Toggle comment on selected code.

The following shortcuts add or remove comment markers (/* ... */) around the highlighted portion of code, even if the selection starts or ends mid-line.

• Windows: Press Shift + Alt + A
• macOS: Press Shift + Option + A

Pressing either shortcut again will remove the comment block it added.

Valid comment placement

Comments can be added in most parts of an NQL query. However, there are specific cases where comments are not allowed.

The following table outlines invalid comment placements. If a comment is added in one of these locations, the NQL editor will display an error.

Description of invalid comment placement	Example of invalid comment placement
Between | and statement keyword	devices | /* comment */ where name == "test"
Inside expressions	devices | where name /* comment */ == "test"
Between operator and operand	devices | compute x = count /* comment */ ()
Inside function calls	devices | summarize c = count() by /* comment */ 1d, start_time

NQL naming rules

Metric names in NQL queries

NQL allows you to create computed metrics using keywords such as summarize and compute. These metrics are not stored in the data model. However, they can be referenced elsewhere in the query, displayed in the Results tab, and used in charts.

When assigning a custom name to a metric, follow these rules:

• Use only letters (a-z), numbers (0-9), dashes (-), and underscores (_).
• Do not use spaces.
• Do not start the name with a number or a special character.
• Do not use special characters other than dashes (-) and underscores (_).
• Letter case is ignored. For example, Licnese, license, and LICENSE are treated the same.

Metric names cannot match existing field names. To avoid conflicts, append an underscore (_) to the metric name, for example, cpu_usage_. In results and visualizations, the metric is displayed with the same header as the original field name, such as CPU usage, without the trailing underscore.

Refer to NQL compute and NQL summarize for more information.

NQL IDs for content items

When creating content items such as campaigns, custom fields, or monitors, you must define an NQL ID. NQL IDs allow you to reference content items in NQL queries and other parts of the product.

The system automatically generates an NQL ID from the content name using the rules below. You can also edit the generated value, provided it follows the same rules.

NQL IDs must:

• Start with #.
• Use only lowercase letters (a-z), numbers (0-9), and underscores (_).
• Use underscores (_) instead of spaces or other special characters.
• Replace accented characters with their non-accented equivalents. For example, é becomes e.

Example

Content name:

Application Survey – Québec

Generated NQL ID:

#application_survey_quebec

Refer to Understanding Nexthink content for more information.