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.
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.
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 attribute2 | FIND Finding WHERE riskScore GREATER THAN ATTRIBUTE baseRiskScore |
Less Than Attribute | attribute1 LESS THAN ATTRIBUTE attribute2 | FIND Finding WHERE riskScore LESS THAN ATTRIBUTE baseRiskScore |
Greater Than or Equals to Attribute | attribute1 GREATER THAN OR EQUALS TO ATTRIBUTE 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 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.
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
.
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.
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.
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.
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 |
-
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.
-
BQL only supports using the name of the string operator in a query (for example,
CONTAINS
rather than~=
orSTARTS 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" |