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.

This page provides provides a reference for usage and supported syntax of NQL.

NOTE: For a list of available datasets in NQL, see Available Datasets (NQL).

NQL Queries (Searches)

NQL queries (or Search/Saved Searches) represent 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 Saved Searches on the All Findings Page. 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.

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:

SELECT findings 
WHERE severity = "Critical" AND asset_group IN ("Production") 
ORDER BY finding_discovered ASC

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.

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

NQL Keywords

SELECT finding_name FROM findings WHERE due_date = EMPTY

SELECT finding_name, DATE_DIFF(TODAY, finding_discovered) AS 'Calculated Age'
FROM findings

NQL Comparison Operators

NQL Special Operators

NQL Logical Operators

NQL supports AND & OR logical operators with parentheses () for grouping conditions in WHERE clauses for more powerful and flexible queries, for example:

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:

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:

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

String Functions

Numeric Functions

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

Date and Datetime Functions

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:

Field Types

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:

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

Relative Values

You can also filter relative to the current date using:

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

Related Topics

• Available Datasets (NQL): reference of available datasets and fields.

• NQL Query Library:  example use cases and corresponding NQL queries.