Skip to main content

BQL Keywords

This article details the basic keywords in Brinqa query language (BQL) that make up the clauses of a query statement, including sorting and pagination.

Before you begin to write Brinqa queries, note the following:

  • Wildcards (*) are only supported for the LIKE and NOT LIKE string functions.

  • The names of the data models in the queries are case sensitive, but keywords are not case sensitive.

  • String must be wrapped in double quotes ("string").

  • Boolean, Number, and Date values do not have to be wrapped in double quotes.

Basic keywords​

The following keywords make up the clauses of a query statement to perform various operations:

note

Keywords are not case sensitive in BQL, but they appear in uppercase letters in the examples to differentiate with other parts of the query.

FIND​

The FIND clause searches for an existing property or pattern in your data. It is followed by a data model. For example, the following query returns all vulnerabilities:

FIND Vulnerability

The above query is not specific and may not return useful results. To be more precise, you can add additional clauses to the query. See WHERE, THAT, and WITH.

AS​

The AS clause defines an aliased selector to be referenced in the WHERE or RETURN clause. An alias only exists for the duration of the specific query. For example, the following BQL statement creates an alias, f, for Finding and returns all findings with a critical risk rating:

FIND Finding AS f WHERE f.riskRating = "Critical"

You can create multiple aliases for different data models in a query as long as the two data models have a relationship. For example:

FIND Finding AS f THAT HAS Asset AS a WHERE f.severity = "Critical" AND a.status = "Active"

The above query creates an alias, f, for Finding and also an alias, a, for Asset and returns all critical findings on active assets.

For information about how to view data model relationships, see examine relationships between data models.

WHERE​

The WHERE clause adds constraints to the query and allows you to define specific criteria so you can find the exact data that you want to work with. WHERE is followed by an attribute that must exist on the target model. For example, the following query returns all users whose first name starts with "W":

FIND Person AS p WHERE p.firstName STARTS WITH "W"

The firstName attribute exists on the Person data model, so the query runs successfully.

The following query returns all active findings with a medium severity level:

FIND Finding AS f WHERE f.status = "Active" AND f.severity = "Medium"

Both the status and severity attribute exist on the Finding data model, so the query runs successfully. Check the data model reference for attributes and additional information.

RETURN​

The RETURN clause defines what to include in the query's result set. For example, the following query returns a number of unique vulnerabilities:

FIND Vulnerability AS v RETURN DISTINCT count(*)
note

RETURN can only be used in reports. It is ignored in list views such as findings, assets, or tickets.

THAT​

The THAT keyword must be followed by a relationship verb such as BELONGS, CONTAINS, HAS, IS, RELATES, SUPPORTS, etc. For more information on relationships and BQL, see query for relationships in BQL.

tip

In BQL, prepositions such as IN, ON, AT, TO, or BY can be used after relationship keywords for fluidity, but they are ignored in terms of query processing. Thus, RELATES TO and RELATES are functionally identical.

The relationship verbs are not case sensitive and you can use the relationship verb to reference any relationship between two data models. For example, the following query returns all hosts with vulnerabilities:

FIND Host AS h THAT HAS Vulnerability AS v

You can take the previous example and go a step further by returning all hosts with critical vulnerabilities:

FIND Host AS h THAT HAS Vulnerability AS v WHERE v.severity = "Critical"

Relationship verbs are bidirectional. For example, the following queries are both valid:

FIND Asset AS a THAT HAS Vulnerability AS v
FIND Vulnerability AS v THAT HAS Asset AS a

Furthermore, you can use RELATES TO or RELATES to express a relationship between data models without specifying or needing to know the exact name of the relationship.

For example, either of the following queries can be used to find Vulnerability records that contain any type of relationship with VulnerabilityDefinition:

FIND Vulnerability as v THAT RELATES TO VulnerabilityDefinition as v2

FIND Vulnerability as v THAT RELATES VulnerabilityDefinition as v2

On the other hand, the following query retrieves records where Vulnerability has a defined IS relationship with VulnerabilityDefinition:

Find Vulnerability as v THAT IS VulnerabilityDefinition as v2

While RELATES TO and RELATES offer broader query results, covering any relationship type, specific keywords like IS provide more targeted results based on a known relationship type.

WITH​

The WITH clause allows parts of the query statement to be tethered together, connecting the results from one to be used as starting points or criteria in the next. For example, the following query returns hosts with vulnerabilities in ascending order:

FIND Vulnerability AS v THAT HAS Host AS h WITH v, h.displayName AS order ORDER BY order ASC

Multi-labeling​

You can use the | symbol to query for different data models that share the same attributes. This is called multi-labeling. For example, the following query returns all hosts and vulnerabilities that are sourced from the Tenable.sc connector:

FIND Host|Vulnerability WHERE connectorNames CONTAINS ALL ["Tenable.sc"]

The above query returns the same results but is less complex and time-consuming than running multiple queries to achieve the same result. For example:

FIND Host as h where h.connectorNames CONTAINS ALL ["Tenable.sc"]
FIND Vulnerability as v WHERE v.connectorNames CONTAINS ALL ["Tenable.sc"]

Sorting and Pagination​

You can sort and page through your data by utilizing the ORDER BY, SKIP, and LIMIT subclauses in BQL. Sorting arranges records in either ascending or descending order to provide a more concise view, and pagination reduces the number of records returned from a query.

ORDER BY​

You can use the ORDER BY subclause to sort the queried data in either ascending or descending order. To sort the results in ascending order, use ASC; and for descending order, use DESC.

ORDER BY is followed by an expression or field to indicate how to sort the data. For example, ORDER BY riskRating DESC, sorts the records by their risk ratings in descending order.

SKIP​

The SKIP keyword is followed by a number to indicate how many records to skip in the output. For example, SKIP 20, skips the first 20 records and returns the queried data from the 21st record.

LIMIT​

The LIMIT keyword is followed by a number to limit the number of records to return. For example, LIMIT 5, returns five records from the queried data.

The following example uses ORDER BY, SKIP, and LIMIT in a query together:

FIND Asset ORDER BY riskRating DESC SKIP 20 LIMIT 5

The above query retrieves all assets in your data, sorts them in descending order by their risk ratings, and returns the 21st through 25th records from the sorted list.

note

If LIMIT is not set in the query, it could result in a large number of records to return.