---
title: "Nucleus Query Language (NQL)"
slug: "nucleus-query-language-nql"
updated: 2026-06-08T16:59:50Z
published: 2026-06-08T16:59:50Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.nucleussec.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nucleus Query Language (NQL)

## Overview

The Nucleus Query Language, or NQL is a semantic query language that flattens the Nucleus Data Core into a single, simple way to ask any question you need about your vulnerabilities, assets, threats, software, and more. Queries are built around **keywords, logical operators**, and **comparisons** to be able to ask any question that you wish.

## NQL Queries

Queries (or **NQL queries**) represents a question asked by a vulnerability management professional. One example might be:

*“Show me all vulnerabilities with a status of Waiting For 3rd Party that are due within the next 30 days.”*

The answer to this question from Nucleus helps vulnerability managers proactively communicate with vendors and track upcoming deadlines for third-party remediation. Results are returned to the user and are called a **result set**. NQL queries can be saved as different **saved searches** on the [All Findings Page](/v1/docs/explore-interface)**.**Once a search is saved it can be accessed again using the same All findings page.

NQL Queries follow a straightforward pattern:

1. Determine the question to ask. Example questions might be:
  1. "Show me high-priority overdue vulnerabilities requiring immediate attention”
  2. “Show me recently discovered critical vulnerabilities with exception requests”
  3. “I want to see all critical vulnerabilities across production assets”
2. Formulate the appropriate NQL query
3. Use the Explore Interface to execute the query
4. Take action on the results, which may include report generation or modifying findings

#### NQL Structure

NQL queries can be expressed using a Basic or Advanced structure depending on your needs. The first allows you to leverage the Nucleus UI to manage columns and sorting, and the more advanced version allows you to specify columns in your NQL expression itself as well as more advanced filtering and sorting using logical comparison operators and keywords.

#### Simple Format

`SELECT dataset WHERE condition1 AND condition2 …`

The above expression will use default columns (or whatever columns you choose in the UI) and will use a default sorting mechanism.

#### Advanced Format

**Default column names**

`SELECT field1, field2, field3 FROM dataset where condition1 AND condition2 ORDER by field1 DESC`

The above expression allows you to specify which columns you would like to return without needing to interact with the Nucleus UI controls

**Specify Column Names**

`SELECT field1 AS "field name", field2 AS "field name", field3 AS "field name" FROM dataset where condition1 AND condition2 ORDER by field1 DESC, field2 ASC`

The above expression allows you to do two additional things:

1. Name the columns for each field
2. Combine the ordering syntax so you can create advanced sorting logic, such as `ORDER BY severity DESC, nucleus_threat_rating DESC`

### Basic NQL Query

It may be useful to try out a simple query before diving deeper into the language. A simple query would return all findings with critical severity using the **simple NQL syntax.**

| **Vulnerability Management Question** | **NQL Query** |
| --- | --- |
| Show me all critical severity findings sorted by the Nucleus recommended prioritization methodology | ```plaintext SELECT Findings WHERE severity = "Critical" ``` |

This NQL query will show all **finding instances**in Nucleus where the severity is Critical in the **result set.**Notice the use of the equal sign (“=”) which is a **comparison operator**as well as the use of the *findings*dataset where we are pulling data from.

We can expand on this query to make it more specific to only identify critical findings on assets in the *Production*asset group. We can add some more columns and introduce sorting by the name of the finding:

| **Vulnerability Management Question** | **NQL Query** |
| --- | --- |
| **Simple Syntax:**Show me all critical severity findings on assets in the Production Asset group sorted by when they were discovered | ```plaintext SELECT findings WHERE severity = "Critical" AND asset_group IN ("Production") ORDER BY finding_discovered ASC ``` |
| **Advanced Syntax:** Same as above expression but adds sorting on severity (descending) and the finding discovered date (ascending) | ```plaintext SELECT finding_name, finding_risk_score, finding_source, asset_name, severity, nucleus_threat_rating, finding_discovered FROM findings WHERE severity = "Critical " AND asset_group IN ("Production") ORDER BY severity DESC, finding_discovered ASC ``` |

### Query Construction

The following picture shows a useful way of thinking about queries: ***Columns, Dataset, Filter, Sort*** for the advanced NQL syntax. First identify the columns to show, then the dataset, then apply filter logic on the selected fields. Finally, order the results in ascending order by when the finding was discovered.

![](https://cdn.document360.io/3888970a-6501-459e-acc9-c47b71c6d64c/Images/Documentation/image(511).png)

The following sections define the available keywords, logical operators, comparison operators and possible field types.

### NQL Keywords

| **Keyword** | **Description** |
| --- | --- |
| AS | Renames a field with an alias. Column aliasing is optional and does not affect the results |
| ASC | Sorts the result set in ascending order. |
| DESC | Sorts the result set in descending order. |
| EMPTY | Evaluated as an empty value when used in comparison operations, for example: ```sql SELECT finding_name FROM findings WHERE due_date = EMPTY ``` |
| FROM | Specifies the dataset to return data from. |
| LIMIT | Limits the result set to a particular value |
| ORDER BY | Sorts the result set in ascending or descending order. Valid sort directions are ASC, DESC and NONE. |
| SELECT | Specifies the fields from a dataset that you want to return. |
| TODAY | Resolves to the current date in the user's time zone for use in date functions, for example: ```sql SELECT finding_name, DATE_DIFF(TODAY, finding_discovered) AS 'Calculated Age' FROM findings ``` Format: YYYY-MM-DD (e.g., "2025-01-15") |
| WHERE | Filters results to include only records that fulfill specified condition(s). |

### NQL Comparison Operators

| **Operator** | **Description** |
| --- | --- |
| = | Equal to. Also used with EMPTY for NULL checking. Example: = EMPTY |
| > | Greater than |
| < | Less than |
| >= | Greater than or equal to |
| <= | Less than or equal to |
| != | Not equal to |
| <> | Not equal to (alternative) |

### NQL Special Operators

| **Operator** | **Description** |
| --- | --- |
| CONTAINS | TRUE if the value IS a substring match |
| NOT CONTAINS | TRUE if the value IS NOT a substring match |
| IN | TRUE if the value IS equal to one of a list of expressions |
| NOT IN | TRUE if the value IS NOT equal to one of a list of expressions |

### NQL Logical Operators

| **Logical Operator** | **Description** |
| --- | --- |
| AND | The value is TRUE if all conditions separated by the AND are TRUE |
| OR | The value is TRUE if at least one condition separated by OR is TRUE |

> NQL supports AND & OR logical operators with parentheses () for grouping conditions in WHERE clauses for more powerful and flexible queries, for example:
> 
> 
> 
> ```sql
> SELECT finding_name, severity, finding_source, cves, asset_name
> FROM findings 
> WHERE (finding_source = "Nessus" OR finding_source = "Nexpose" OR finding_source = "Rapid7") 
>   AND (severity = "Critical" OR severity = "High") 
>   AND cve_count > 0  
> ```

### Calculation Functions (non‑aggregate)

NQL supports a set of non‑aggregate calculation functions you can use in both `SELECT` and `WHERE` clauses. These functions operate on each row individually (they do **not** require `GROUP BY`). You can assign a column alias using `AS` in the `SELECT` clause and then reuse that alias in both the `WHERE` and `ORDER BY` clauses, for example:

```sql
SELECT MULTIPLY(finding_risk_score, 10) AS ten_x_risk
FROM findings
WHERE ten_x_risk > 1000
ORDER BY ten_x_risk DESC
```

**Alias rules**

- Alias names must be unique within the query.
- An alias must not have the same name as an existing field in the dataset (for example, severity AS severity is invalid).
- If an alias conflicts with a field name or another alias, the query will return an error.

**Nested functions**

You can also nest functions as long as the input and output types are compatible, for example:

```sql
SELECT ADD(MULTIPLY(finding_risk_score, 10), 5) AS 'ten_x_risk_plus_five'
FROM findings
```

#### String Functions

| Function | Description |
| --- | --- |
| `CONCAT(str1, str2, ...)` | Concatenates two or more strings. |
| `SUBSTRING(str, pos, len)` | Returns a substring of `str`, starting at position `pos` for `len` characters. |

#### Numeric Functions

| Function | Description |
| --- | --- |
| `ADD(num1, num2, ...)` | Adds two or more numbers. |
| `SUBTRACT(num1, num2)` | Subtracts `num2` from `num1`. |
| `MULTIPLY(num1, num2, ...)` | Multiplies two or more numbers. |
| `DIVIDE(num1, num2)` | Divides `num1` by `num2`. |
| `ROUND(num, decimals)` | Rounds a number to the specified number of decimals. |

These all expect numeric arguments (either numeric fields or numeric literals like `10` or `0.5`).

#### Date and Datetime Functions

| Function | Description |
| --- | --- |
| `DATE_ADD(date, value, unit)` | Adds or subtracts time from a date/datetime field. Example units: `DAY`, `WEEK`, `MONTH`, `YEAR`, `HOUR`, `MINUTE`, `SECOND`. |
| `DATE_DIFF(date1, date2)` | Returns the difference between `date1` and `date2` in **days**. |
| `DATE_FORMAT(date, format)` | Converts a date/datetime field to a string, using the supplied format string. |
| `DAY(date)`, `MONTH(date)`, `YEAR(date)` | Extract the corresponding part of a date. |

You can pass date/datetime fields, the keyword `TODAY`, or quoted date literals (for example, `"2026-12-31"`).

#### List Functions

Some fields, such as `asset_group`, are lists. You can use list functions to work with them:

| Function | Description |
| --- | --- |
| `LIST_LENGTH(list_field)` | Returns how many values are in the list. |
| `IN_LIST(list_field, value)` | Returns `true` if `value` appears in `list_field`. |

### Field Types

| **Type** | **Description** | **Supported Operators** |
| --- | --- | --- |
| String | Text | =, !=, CONTAINS, NOT CONTAINS, IN, NOT IN |
| Number | A positive number | =, >, <, >=, <=, !=, CONTAINS, NOT CONTAINS, IN, NOT IN |
| Date | A date in the format YYYY-MM-DD | =, >, <, >=, <=, !=, CONTAINS, NOT CONTAINS, IN, NOT IN |
| Datetime | A date-time | =, >, <, >=,<=, !=, CONTAINS, NOT CONTAINS, IN, NOT IN |
| List | A list of values | =, CONTAINS, NOT CONTAINS, IN, NOT IN **NOTE:**CONTAINS performs an exact group-path match (equivalent to IN/NOT IN), not a substring search. The value must match the full group path (i.e. /Business Units/IT). Using IN/NOT IN is recommended over CONTAINS/NOT CONTAINS when filtering List type columns. |
| Boolean | Yes or No | =, != |

### Relative Date and Datetime Filters

For date and datetime fields (such as `finding_discovered`, `finding_last_seen`, and `host_last_seen_date`), NQL supports both **absolute** and **relative** values in `WHERE` clause comparisons.

#### Absolute Values

You can compare directly to a specific date:

```sql
...
WHERE finding_discovered >= "2026-01-01"
...
```

#### Relative Values

You can also filter relative to the current date using:

```sql
...
WHERE due_date < TODAY  //Overdue findings
...
WHERE finding_discovered > '-7d' //Findings discovered in the last 7 days
...
WHERE due_date < '7d'  //Findings due in the next 7 days
...
```

Relative offsets are supported in the range of **1–365 days** and are evaluated with second‑level precision.

### NQL Datasets

This section describes the available datasets

| **Dataset** | **Description** |
| --- | --- |
| findings | All finding instances in the current project |

> **NOTE:** Only findings of type vulnerability are currently supported by NQL

#### Findings Dataset: Fields

This section describes the available fields for the *findings*dataset.

| **Field Name** | **Data Type** | **Description** | **Possible Values** |
| --- | --- | --- | --- |
| age | Number | Number of days since the discovered date | N/A |
| asset_business_owner_team | List | Business Owner Team on asset | List of defined teams |
| asset_group | Array | The list of asset groups an asset belongs to | Varies based on the asset groups in your project |
| asset_info | Object | Collection of asset metadata fields | Varies by asset and scan source. |
| asset_name | String | The name of the asset associated with a finding instance | Includes the host name and IP when available. Ex: [localhost](http://localhost).localdomain (192.168.1.3) |
| asset_support_team | List | Support Team on asset | List of defined teams |
| asset_type | List | The type of asset | Various asset types |
| assigned_team | List | Team assigned to a finding instance | Varies based on the teams in your project |
| business_criticality | List | Business criticality level of the asset | Critical, High, Moderate, Low |
| compliance_scope | List | Compliance scope of the asset | In-Scope, Out-of-Scope |
| cve_count | Number | Count of CVEs associated with the finding | N/A |
| cves | String | CVEs associated with the finding | Varies by vulnerability and CVE |
| data_sensitivity | List | Data sensitivity level of the asset | Critical, High, Moderate, Low |
| due_date | Date | The due date set on a finding | N/A |
| exploitable | Boolean | Whether or not Nucleus has determined if the finding is exploitable | Yes/No |
| finding_discovered | Datetime | Date and time a finding was discovered (as reported by the finding source) | N/A |
| finding_last_seen | Date | The last time a scanner saw this finding in a scan | N/A |
| finding_name | String | The name of a finding instance | N/A |
| finding_risk_score | Number | The Nucleus risk score for a finding instance | 0 to 1000 |
| finding_source | String | The source/scan type that discovered the finding | N/A |
| finding_status | List | Status of the finding for a finding instance | Active: Active, Exception Requested, Fixed, In Progress, Potential, Waiting for 3rd Party, Waiting for Verification. |
| host_name | String | The host name of the asset associated with a finding instance | Ex: [localhost](http://localhost).localdomain |
| ip_address | String | Primary IP address for the asset | N/A |
| mandiant_exploit_in_the_wild | Boolean | Finding has known exploits reported to be found in the wild by Mandiant | Yes/No |
| mandiant_exploit_rating | List | Mandiant's exploit rating for a finding | Wide, Confirmed, Available, Anticipated, No Known |
| mandiant_exploited_by_malware | Boolean | Finding has known malware exploits available according to Mandiant | Yes/No |
| mandiant_risk_rating | List | Mandiant's risk rating for a finding | Critical, High, Medium, Low |
| mandiant_zero_day | Boolean | Finding is a Zero Day vulnerability according to Mandiant | Yes/No |
| network_exposure | List | Network exposure level of the asset | Internal, External |
| nucleus_ease_of_exploitation | List | The determined ease of exploitation based on the threat insights feed | Very Easy, Easy, Moderate, Hard, Very Hard, Unknown |
| nucleus_exploitation_consequence | List | The consequence of exploiting this vulnerability | The contents of this field vary based on the consequence. For Example: Code Execution, Command Execution, etc. |
| nucleus_exploited | Boolean | Whether or not the vulnerability has been exploited based on the threat insights feed | Yes/No |
| nucleus_exploited_by_malware | Boolean | Whether or not Nucleus has determined if the finding has been exploited by malware in the wild | Yes/No |
| nucleus_exploited_by_malware | Boolean | Whether or not the vulnerability has been exploited by malware based on the threat insights feed | Yes/No |
| nucleus_exploited_by_ransomware | Boolean | Whether or not the vulnerability has been exploited by ransomware based on the threat insights feed | Yes/No |
| nucleus_impacts_ot | Boolean | Whether or not Nucleus has determined if the finding impacts operational technology/IT | Yes/No |
| nucleus_patch_available | Boolean | Whether or not the vulnerability has a patch available based on the threat insights feed | Yes/No |
| nucleus_private_exploit_available | Boolean | Whether or not the vulnerability has a private exploit based on the threat insights feed | Yes/No |
| nucleus_public_exploit_available | Boolean | Whether or not the vulnerability has a public exploit based on the threat insights feed | Yes/No |
| nucleus_public_exploit_available | Boolean | Whether or not Nucleus has determined if the finding has a public exploit available | Yes/No |
| nucleus_remote_exploitation | Boolean | Whether or not the vulnerability can be remotely exploited based on the threat insights feed | Yes/No |
| nucleus_threat_rating | List | The determined threat rating of the vulnerability based on the threat insights feed | Existential, Critical, High, Medium, Low |
| nucleus_zero_day | Boolean | Whether or not the vulnerability is a zero day based on the threat insights feed | Yes/No |
| nucleus_zero_day_previously | Boolean | Whether or not the vulnerability was a zero day based on the threat insights feed | Yes/No |
| severity | List | The Nucleus severity of a finding instance | Critical, High, Medium, Low, Informational |