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	Description	Examples	Expected Results
Exists	attribute EXISTS	Checks if an attribute has a value for a given record.	FIND Asset AS a WHERE a.privateIpAddresses EXISTS	This example returns assets with a private IP address.
Not Exists	attribute NOT EXISTS	Checks if an attribute does not have a value for a given record.	FIND Finding AS f WHERE f.dueDate NOT EXISTS	This example returns findings with no due date.
Equals to Attribute	attribute1 EQUALS TO ATTRIBUTE attribute2	Checks if the value of one attribute equals the value of another attribute.	FIND Finding AS f WHERE f.riskScore EQUALS TO ATTRIBUTE f.baseRiskScore	This example returns findings where the risk score equals the base risk score.
Not Equals to Attribute	attribute1 NOT EQUALS TO ATTRIBUTE attribute2	Checks if the value of one attribute does not equal the value of another attribute.	FIND Finding AS f WHERE f.riskScore NOT EQUALS TO ATTRIBUTE f.baseRiskScore	This example returns findings where the risk score does not equal the base risk score.
Greater Than Attribute	attribute1 GREATER THAN ATTRIBUTE attribute2	Checks if the value of one attribute is greater than the value of another attribute.	FIND Finding AS f WHERE f.riskScore GREATER THAN ATTRIBUTE f.baseRiskScore	This example returns findings where the risk score is greater than the base risk score.
Less Than Attribute	attribute1 LESS THAN ATTRIBUTE attribute2	Checks if the value of one attribute is less than the value of another attribute.	FIND Finding AS f WHERE f.riskScore LESS THAN ATTRIBUTE f.baseRiskScore	This example returns findings where the risk score is less than the base risk score.
Greater Than or Equals to Attribute	attribute1 GREATER THAN OR EQUALS TO ATTRIBUTE attribute2	Checks if the value of one attribute is greater than or equal to the value of another attribute.	FIND Finding AS f WHERE f.riskScore GREATER THAN OR EQUALS TO ATTRIBUTE f.baseRiskScore	This example returns findings where the risk score is greater than or equal to the base risk score.
Less Than or Equals to Attribute	attribute1 LESS THAN OR EQUALS TO ATTRIBUTE attribute2	Checks if the value of one attribute is less than or equal to the value of another attribute.	FIND Finding AS f WHERE f. riskScore LESS THAN OR EQUALS TO ATTRIBUTE f.baseRiskScore	This example returns findings where the risk score is less than or equal to the base risk score.

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	Description	Examples	Expected Results
And	AND, &	Combines two conditions and returns records where both conditions are true. AND and & can be used interchangeably when querying for "and".	FIND Finding AS f WHERE f.riskRating = "Critical" AND severity = "Critical"	This example returns findings with a risk rating of "Critical" and a severity of "Critical".
Not	NOT	Negates a condition and returns records where the condition is not true.	FIND Finding AS f WHERE f.firstFound NOT IN LAST 3 months	This example returns findings that were not initially found in the last 3 months.
Or	OR	Combines two conditions and returns records where either condition is true.	FIND Asset AS a WHERE a.categories CONTAINS "Virtual Machine" OR a.categories CONTAINS "PCI"	This example returns assets that are either categorized as "Virtual Machine" or "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	Description	Examples	Expected Results
Equals To	=	Checks if the value of an attribute equals a specified value.	FIND Finding AS f WHERE f.riskRating = "Critical"	This example returns findings with a risk rating of "Critical".
Not Equal To	!=, <>	Checks if the value of an attribute does not equal a specified value. != and <> can be used interchangeably when querying for "not equal to".	FIND Finding AS f WHERE f.severity != "Critical" FIND Finding AS f WHERE f.severity <> "Critical"	This example returns findings with a severity not equal to "Critical".
Greater Than	>	Checks if the value of an attribute is greater than a specified value.	FIND Finding AS f WHERE f.severity > "High"	This example returns findings with a severity greater than "High".
Greater Than Or Equals To	>=	Checks if the value of an attribute is greater than or equal to a specified value.	FIND Finding AS f WHERE f.riskScore >= 7	This example returns findings with a risk score greater than or equal to 7.
Less Than	<	Checks if the value of an attribute is less than a specified value.	FIND Finding AS f WHERE f.riskRating < "Critical"	This example returns findings with a risk rating lower than "Critical".
Less Than Or Equals To	<=	Checks if the value of an attribute is less than or equal to a specified value.	FIND Finding AS f WHERE f.riskRating <= "Low"	This example returns findings with a risk rating lower than or equal to "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 in list views and explorer graphs. For example, 2022-04-20. You can use additional date formats in report charts and visualizations. For additional information, see Supported date formats.

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	Description	Examples	Expected Results
Is	IS date	Checks if a date attribute matches a specified date.	FIND Ticket AS t WHERE t.lastUpdated IS 2017-01-31	This example returns tickets last updated on 2017-01-31.
Is Not	IS NOT date	Checks if a date attribute does not match a specified date.	FIND Ticket AS t WHERE t.lastUpdated IS NOT 2017-01-31	This example returns tickets that were last updated on a date other than 2017-01-31.
Since	SINCE date	Checks if a date attribute is after a specified date.	FIND Vulnerability AS v WHERE v.lastUpdated SINCE 2022-02-02	This example returns vulnerabilities last updated since 2022-02-02.
Before	BEFORE date	Checks if a date attribute is before a specified date.	FIND Vulnerability AS v WHERE v.lastUpdated BEFORE 2022-02-02	This example returns vulnerabilities last updated before 2022-02-02.
Between	BETWEEN [date1 TO date2]	Checks if a date attribute is between two specified dates.	FIND Finding AS f WHERE f.dateCreated BETWEEN [2020-01-01 TO 2023-11-11]	This example returns findings created between 2020-01-01 and 2023-11-11.
Not Between	NOT BETWEEN [date1 TO date2]	Checks if a date attribute is not between two specified dates.	FIND Finding AS f WHERE f.dateCreated NOT BETWEEN [2020-01-01 TO 2023-11-11]	This example returns findings not created between 2020-01-01 and 2023-11-11.
In Next	IN NEXT date	Checks if a date attribute is within a specified upcoming time period.	FIND Finding AS f WHERE f.dueDate IN NEXT 1 month	This example returns findings with a due date in the next month.
Not In Next	NOT IN NEXT date	Checks if a date attribute is not within a specified upcoming time period.	FIND Ticket AS t WHERE t.dueDate NOT IN NEXT 3 weeks	This example returns tickets with a due date not in the next 3 weeks.
In Last	IN LAST date	Checks if a date attribute is within a specified past time period.	FIND Vulnerability AS v WHERE v.dateCreated IN LAST 1 day	This example returns vulnerabilities created in the last day.
Not In Last	NOT IN LAST date	Checks if a date attribute is not within a specified past time period.	FIND Vulnerability AS v WHERE v.dateCreated NOT IN LAST 1 month	This example returns vulnerabilities not created in the last 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 in as many terms as you'd like.

The following table describes the list operators in BQL:

Table 5: List operators

Operator	Syntax	Description	Examples	Expected Results
In	IN [value1, value2]	Checks if a value exists in a specified list.	FIND Finding AS f WHERE f.severity IN ["Critical", "High"]	This example returns findings with a severity of "Critical" or "High".
Not In	NOT IN [value1, value2]	Checks if a value does not exist in a specified list.	FIND Finding AS f WHERE f.severity NOT IN ["Critical", "High"]	This example returns findings with a severity not equal to "Critical" or "High".
Contains Any	CONTAINS ANY ["term1", "term2"]	Checks if any element of the list contains any of the specified values. This operator uses a partial search and is case-sensitive.	FIND Asset AS a WHERE a.tags CONTAINS ANY ["Development", "External", "PCI"]	This example returns assets that have any tag in a.tags that contains any of the following substrings: "Development", "External", or "PCI".
Contains All	CONTAINS ALL ["term1", "term2"]	Checks if the list contains all specified values. This operator uses a partial search and is case-sensitive.	FIND Host AS h WHERE h.privateIpAddresses CONTAINS ALL ["127.0.0.1", "127.0.0.2"]	This example returns all hosts with private IP addresses of "127.0.0.1" and "127.0.0.2".
Does Not Contain Any	NOT CONTAINS ANY ["term1", "term2"]	Checks if none of the elements of the list contain any of the specified values.	FIND Host AS h WHERE h.publicIpAddresses NOT CONTAINS ANY ["192.168.145.141", "90.57.128.178"]	This example returns hosts where the public IP address list does not contain "192.168.145.141" or "90.57.128.178".
Contains None Of	NOT CONTAINS ALL ["term1", "term2"]	Checks if the list does not contain all the specified values.	FIND Host AS h WHERE h.privateIpAddresses NOT CONTAINS ALL ["127.0.0.1", "127.0.0.2"]	This example returns hosts where the private IP address list does not contain either "127.0.0.1" or "127.0.0.2".
Like Any	LIKE ANY ["term1*", "term2*"]	Checks if any element of the list matches any of the specified patterns after the supported wildcard characters (*). This operator uses a regular expression and is case-insensitive. For additional information and an interactive tool on how wildcard characters work, see SQL Wildcards.	FIND Asset AS a WHERE a.complianceFlags LIKE ANY ["PCI*", "PI*"]	This example returns any assets whose compliance flags start with "PCI*" or "PI*".
Not Like Any	NOT LIKE ANY ["term1*", "term2*"]	Checks if none of the elements of the list match any of the specified patterns after the supported wildcard characters (*). This operator uses a regular expression and is case-insensitive. For additional information and an interactive tool on how wildcard characters work, see SQL Wildcards.	FIND Finding AS f WHERE f.displayName NOT LIKE ANY ["OpenSSH*", "SSL*"]	This example returns any findings where the display name does not start with "OpenSSH*" or "SSL*".

note

You can also use CONTAINS. Although CONTAINS can't be followed by a list, the attribute you use it on can be a list.

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. Math operators always return numeric values and not the individual records themselves.

Important

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

The following table describes the math operators in BQL:

Table 6: Math Operators

Operator	Syntax	Description	Examples	Expected Results
Addition	+, ADD	Adds a specified value to an attribute.	FIND Vulnerability AS v RETURN DISTINCT (v.ageInDays + 4) AS "Age in days" LIMIT 100	This example returns the calculated age-in-days for vulnerabilities, increased by 4.
Subtraction	-, SUB	Subtracts a specified value from an attribute.	FIND Host AS h RETURN DISTINCT (h.riskScore - 2) as "Risk score" LIMIT 100	This example returns the calculated risk score for hosts, decreased by 2.
Multiplication	*, MULT	Multiplies an attribute by a specified value.	FIND Asset AS a RETURN DISTINCT (a.baseRiskScore * 2) as "Doubled risk" LIMIT 100	This example returns the asset base risk score multiplied by 2.
Division	/, DIV	Divides an attribute by a specified value.	FIND Finding AS f RETURN DISTINCT (f.ageInDays + 10) / 5 as "Adjusted age" LIMIT 100	This example returns the adjusted age for findings.

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	Description	Examples	Expected Results
Is Current User	IS CURRENT USER	Checks if an attribute matches the current user.	FIND Asset AS a THAT OWNS Person AS p WHERE p IS CURRENT USER	This example returns assets owned by the current user.
Not Is Current User	NOT IS CURRENT USER	Checks if an attribute does not match the current user.	FIND Asset AS a THAT OWNS Person AS p WHERE p NOT IS CURRENT USER	This example returns assets not owned by the 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	Description	Examples	Expected Results
Contains	CONTAINS "string"	Checks if an attribute contains a specified substring. This operator uses a partial search and is case-sensitive.	FIND Asset AS a WHERE a.name CONTAINS "Okta"	This example returns assets with name containing "Okta".
Not Contains	NOT CONTAINS "string"	Checks if an attribute does not contain a specified substring.	FIND Finding AS f WHERE f.severity NOT CONTAINS "Low"	This example returns findings with severity that isn’t "Low".
Like	LIKE "string*"	Checks if an attribute matches a specified pattern after the supported wildcard characters (*). This operator uses a regular expression and is case-insensitive. LIKE is similar to CONTAINS, but also allows wildcard characters. For additional information and an interactive tool on how wildcard characters work, see SQL Wildcards.	FIND Asset AS a WHERE a.displayName LIKE "Google*"	This example returns any assets with display names that start with "Google*".
Not Like	NOT LIKE "string*"	Checks if an attribute does not match a specified pattern after the supported wildcard characters (*). For additional information and an interactive tool on how wildcard characters work, see SQL Wildcards.	FIND Asset AS a WHERE a.displayName NOT LIKE "Salesforce*"	This example returns any assets with display names that do not start with "Salesforce*".
Starts With	STARTS WITH "string"	Checks if an attribute starts with a specified substring.	FIND Asset AS a WHERE a.name STARTS WITH "Zoom"	This example returns assets with name starting with "Zoom".
Does Not Start With	NOT STARTS WITH "string"	Checks if an attribute does not start with a specified substring.	FIND Asset AS a WHERE a.name NOT STARTS WITH "Microsoft"	This example returns assets with name not starting with "Microsoft".
Ends With	ENDS WITH "string"	Checks if an attribute ends with a specified substring.	FIND Asset AS a WHERE a.createdBy ENDS WITH "admin"	This example returns assets created by users ending with "admin".
Does Not End With	NOT ENDS WITH "string"	Checks if an attribute does not end with a specified substring.	FIND Asset AS a WHERE a.createdBy NOT ENDS WITH "admin"	This example returns assets created by users not ending with "admin".