BQL Operators

This article details the operators in Brinqa Query Language (BQL) that can be used to specify conditions and perform tasks in a query.

DISTINCT

You may come across situations where a query generates unneeded duplicates. This occurs if there are multiple paths of traversal between the entities referenced in the query. DISTINCT is used in conjunction with the RETURN keyword.

Important

You can only use the DISTINCT keyword in reports. The RETURN statement is overwritten in both Explorer and different list pages. You will not see any results unless used in reports.

You can use DISTINCT to only return discrete values or make all values unique before running them through an aggregate function. For example:

FIND Vulnerability AS v RETURN DISTINCT v.riskRating, count(*)

The above query counts the number of vulnerabilities by their risk rating. Without using DISTINCT, the query selects all values and may return duplicate results.

Attribute operators

The attribute operators in BQL can work with any attribute type.

Important

Attribute operators must be used with attributes from the same data model. They cannot be used across different data models.

The following table describes the attribute operators in BQL:

Table 1: Attribute operators

Operator	Syntax	Examples
Exists	attribute EXISTS	FIND Asset AS a WHERE a.privateIpAddresses EXISTS
Not Exists	attribute NOT EXISTS	FIND Finding AS f WHERE f.dueDate NOT EXISTS
Equals to Attribute	attribute1 EQUALS TO ATTRIBUTE attribute2	FIND Finding WHERE riskScore EQUALS TO ATTRIBUTE baseRiskScore
Not Equals to Attribute	attribute1 NOT EQUALS TO ATTRIBUTE attribute2	FIND Finding WHERE riskScore NOT EQUALS TO ATTRIBUTE baseRiskScore
Greater Than Attribute	attribute1 GREATER THAN ATTRIBUTE attribute-name attribute2	FIND Finding WHERE riskScore GREATER THAN ATTRIBUTE baseRiskScore
Less Than Attribute	attribute1 LESS THAN ATTRIBUTE attribute-name attribute2	FIND Finding WHERE riskScore LESS THAN ATTRIBUTE baseRiskScore
Greater Than or Equals to Attribute	attribute1 GREATER THAN OR EQUALS TO ATTRIBUTE attribute-name attribute2	FIND Finding WHERE riskScore GREATER THAN OR EQUALS TO ATTRIBUTE baseRiskScore
Less Than or Equals to Attribute	attribute1 LESS THAN OR EQUALS TO ATTRIBUTE attribute-name attribute2	FIND Finding WHERE riskScore LESS THAN OR EQUALS TO ATTRIBUTE baseRiskScore

Boolean Operators

You can use Boolean operators as conjunctions to combine or exclude conditions in a query. The following table describes the Boolean operators in BQL:

Table 2: Boolean Operators

Operator	Operator Symbol	Example
And	AND, &	FIND Finding AS f WHERE f.riskRating = "Critical" AND severity = "Critical" AND and & can be used interchangeably when querying for "and".
Not	NOT	FIND Finding AS f WHERE f.firstFound NOT IN LAST 3 months
Or	OR	FIND Asset AS a WHERE a.categories CONTAINS "Virtual Machine" OR a.categories CONTAINS "PCI"

In more complex BQL queries, AND and OR can be combined, but it's important to understand how they interact to ensure your BQL query yields the intended results:

• AND: The AND operator is used for specifying conditions that all need to be met, thereby narrowing the scope of the query and adding specificity.

• OR: The OR operator allows for flexibility and broadens the scope of the query by including records that meet any one of the specified conditions.

Consider the following BQL query, which uses both AND and OR operators along with parentheses to control evaluation precedence, designed to identify high and critical findings based on risk ratings, status, and host information:

FIND Finding AS f WHERE (f.riskRating IN ["High", "Critical"] AND f.status IN ["Reopened", "Active"]) THAT HAS Host AS h WHERE h.status = "active" AND h THAT OWNS_RISK RiskOwner AS r THAT OWNS User AS u WHERE (u.displayName = "Test User" OR h.tags = "Location: Austin")

This query demonstrates the combined use of AND and OR, employing parentheses to ensure the correct order of evaluation. The AND operators are used to filter findings by specific risk rating and status criteria, while the OR condition within parentheses adds an additional layer, retrieving results associated with either a specific user's display name or a host located in Austin.

info

The AND operation is performed before the OR operation, unless dictated otherwise by the use of parentheses. The precedence of the AND operator over the OR operator is a convention that's been adopted in many programming and query languages, and it mirrors the precedence of logical operators in formal logic and set theory.

Comparison operators

The comparison operators in BQL work for all attribute types. They compare values and return true or false.

note

You must use the comparison operator symbol (for example, >) rather than the name of the symbol (GREATER THAN) in the query. Using names of the operators is not supported.

The following table describes the comparison operators in BQL:

Table 3: Comparison operators

Operator	Operators Symbol	Example
Equals To	=	FIND Finding AS f WHERE f.riskRating = "Critical"
Not Equal To	!=, <>	FIND Finding AS f WHERE f.severity != "Critical" FIND Finding AS f WHERE f.severity <> "Critical" You can use != and <> interchangeably when querying for "not equal to".
Greater Than	>	FIND Finding AS f WHERE f. severity > "High"
Greater Than Or Equals To	>=	FIND Finding AS f WHERE f.riskScore >= 7
Less Than	<	FIND Finding AS f WHERE f.riskRating < "Critical"
Less Than Or Equals To	<=	FIND Finding AS f WHERE f.riskRating <= "Low"

Date and Time operators

The date and time operators in BQL can work with attributes whose type is Date, DateTime, Time, or any other calculated attribute that returns these attribute types.

note

BQL only allows for the date format of YYYY-MM-DD. For example, 2022-04-20.

The following date and time units are supported. They are not case sensitive and do not need to be wrapped in quotes:

• ms, milli, millis, milliseconds
• s, second, seconds
• minute, minutes
• hour, hours
• day, days
• week, weeks
• month, months
• year, years

The date and time operators are not case sensitive. The following tables describes the date and time operators in BQL:

Table 4: Date and Time operators

Operator	Syntax	Examples
Is	IS date	FIND Ticket AS t WHERE t.lastUpdated IS 2017-01-31
Is Not	IS NOT date	FIND Ticket AS t WHERE t.lastUpdated IS NOT 2017-01-31
Since	SINCE date	FIND Vulnerability AS v WHERE v.lastUpdated SINCE 2022-02-02
Before	BEFORE date	FIND Vulnerability AS v WHERE v.lastUpdated BEFORE 2022-02-02
Between	BETWEEN [date1 TO date2]	FIND Finding AS f WHERE f.dateCreated BETWEEN [2020-01-01 TO 2023-11-11]
Not Between	NOT BETWEEN [date1 TO date2]	FIND Finding AS f WHERE f.dateCreated NOT BETWEEN [2020-01-01 TO 2023-11-11]
In Next	IN NEXT date	FIND Finding AS f WHERE f.dueDate IN NEXT 1 month
Not In Next	NOT IN NEXT date	FIND Ticket AS t WHERE t.dueDate NOT IN NEXT 3 weeks
In Last	IN LAST date	Find Vulnerability AS v WHERE v.dateCreated IN LAST 1 day
Not In Last	NOT IN LAST date	FIND Vulnerability AS v WHERE v.dateCreated NOT IN LAST 1 month

List operators

List operators check if an element exists or does not exist in a list.

note

The examples in the table below contain just two terms to showcase how you can run BQL queries using list operators. You can put as many terms as you'd like.

The following table describes the list operators in BQL:

Table 5: List operators

Operator	Syntax	Examples
In	IN [value1, value2]	FIND Finding AS f WHERE f.severity IN ["Critical", "High"]
Not In	NOT IN [value1, value2]	FIND Finding AS f WHERE f.severity NOT IN ["Critical", "High"]
Contains Any	CONTAINS ANY ["term1", "term2"]	FIND Finding AS f WHERE f. severity CONTAINS ANY ["Critical", "High", "Medium"]
Contains All	CONTAINS ALL ["term1", "term2"]	FIND Host AS h WHERE h.privateIpAddresses CONTAINS ALL ["127.0.0.1", "127.0.0.2"]
Does Not Contain Any	NOT CONTAINS ANY ["term1", "term2"]	FIND Host AS h WHERE h.publicIpAddresses NOT CONTAINS ALL ["192.168.145.141", "90.57.128.178"]
Contains None Of	NOT CONTAINS ALL ["term1", "term2"]	FIND Host AS h WHERE h.privateIpAddresses NOT CONTAINS ALL ["127.0.0.1", "127.0.0.2"]
Like Any	LIKE ANY ["term1*", "term2*"]	FIND Finding AS f WHERE f.displayName LIKE ANY ["OpenSSH*", "SSL*"] LIKE ANY is similar to CONTAINS ANY, but also allows wildcard characters.
Not Like Any	NOT LIKE ANY ["term1*", "term2*"]	FIND Finding AS f WHERE f.displayName NOT LIKE ANY ["OpenSSH*", "SSL*"]

Math operators

Math operators can enhance the ability to perform arithmetic calculations within a query. These operators are used in conjunction with the RETURN keyword to compute values based on numeric attributes in the target data model.

Important

You can only use math operators in reports. The RETURN statement is overwritten in both Explorer and different list pages. You will not see any results unless used in reports.

The following table describes the math operators in BQL:

Table 6: Math Operators

Operator	Syntax	Example
Addition	+, ADD	FIND Vulnerability AS v RETURN DISTINCT (v.ageInDays + 4) AS "Age in days" LIMIT 100 FIND Vulnerability RETURN ADD(v.riskScore, 3) AS "Risk score"
Subtraction	-, SUB	FIND Host AS h RETURN (h.riskScore - 10) as "Risk score" FIND User RETURN SUB(u.riskScore, 1) as result
Multiplication	*, MULT	FIND Asset AS a RETURN (a.baseRiskScore * 2) as "Doubled risk" FIND Vulnerability RETURN MULT(v.riskScore, 6) as result
Division	/, DIV	FIND Finding AS f RETURN (f.ageInDays + 10) / 5 as "Adjusted age" FIND Host RETURN DIV(h.riskScore, 3) as result

Limitations and Tips

• You cannot use the WHERE clause with math operators. For example: FIND Vulnerability AS f WHERE v.riskScore > (2+3) is not a valid query.

• You can use the WITH keyword in conjunction with math operators. For example: FIND Finding AS f WITH ((f.riskScore * 2) + 1) as Result RETURN Result

• While parentheses are not mandatory when using math operators, their use is recommended to clearly define the order of evaluation. This ensures that the query evaluates the expression in the intended sequence.

Aliases and math operators

Aliases created as a result of math operations should not be reused in subsequent math expressions within the same query. Consider the following query:

FIND Vulnerability AS v WITH (v.riskScore * 2) as doubledScore RETURN (doubledScore + 1) as finalScore

In the above query, doubledScore is an alias created for the result of the math operation (v.riskScore * 2). However, this alias is then used in a subsequent math operation (doubledScore + 1). This usage is invalid because it involves using an alias from a math operation in another, leading to errors.

The correct approach is to perform all the math operations directly within a single expression, like so:

FIND Vulnerability AS v RETURN ((v.riskScore * 2) + 1) as finalScore

Here, the entire math operation ((v.riskScore * 2) + 1) is calculated in one step, and the result is then assigned to an alias finalScore. This avoids the usage of an intermediate alias, ensuring the query adheres to the proper syntax.

Multiple math operators

You can use multiple math operators and parentheses for complex calculations. For example, take the following query:

FIND Vulnerability AS v RETURN DISTINCT (v.ageInDays + 4) - (4 / 3 * 1) AS "Age in days" LIMIT 100

The above query calculates the age of vulnerabilities in days. It first adds 4 days to the ageInDays value of each vulnerability, then subtracts the result of a separate calculation (4 divided by 3, then multiplied by 1). The final Age in days is returned for each distinct vulnerability, limiting to the first 100 results.

Security operators

Security operators can be used with attributes whose type is related to a user or any calculated attributes that return a user. The following table describes the security operators in BQL:

Table 7: Security operators

Operator	Syntax	Examples
Is Current User	IS CURRENT USER	FIND Asset AS a THAT OWNS Person AS p WHERE p IS CURRENT USER
Not Is Current User	NOT IS CURRENT USER	FIND Asset AS a THAT OWNS Person AS p WHERE p NOT IS CURRENT USER

String operators

BQL offers a variety of string operators to compare strings stored either as a single string or multi-value field.

note

• BQL only supports using the name of the string operator in a query (for example, CONTAINS rather than ~= or STARTS WITH rather than ^=).

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

The following table describes the string operators in BQL:

Table 8: String operators

Operator	Syntax	Examples
Contains	CONTAINS "string"	FIND Asset AS a WHERE a.name CONTAINS "Okta"
Not Contains	NOT CONTAINS "string"	FIND Finding AS f WHERE f.severity NOT CONTAINS "Low"
Like	LIKE "string*"	FIND Asset AS a WHERE a.displayName LIKE "Google*" LIKE is similar to CONTAINS, but also allows wildcard characters.
Not Like	NOT LIKE "string*"	FIND Asset AS a WHERE a.displayName NOT LIKE "Salesforce*"
Starts With	STARTS WITH "string"	FIND Asset AS a WHERE a.name STARTS WITH "Zoom"
Does Not Start With	NOT STARTS WITH "string"	FIND Asset AS a WHERE a.name NOT STARTS WITH "Microsoft"
Ends With	ENDS WITH "string"	FIND Asset AS a WHERE a.createdBy ENDS WITH "admin"
Does Not End With	NOT ENDS WITH "string"	FIND Asset AS a WHERE a.createdBy NOT ENDS WITH "admin"