BQL Functions

This article details the functions in Brinqa Query Language (BQL) that can be used to perform various calculations on your data. You can use these functions in Return statements within Reports, but they are ignored in list views such as findings, assets, or tickets.

Aggregate functions

It is beneficial to perform calculations on data returned from a query. You can execute queries to retrieve a count, min, max or perform other calculations to provide you with more ways to understand your data.

The following table describes the aggregate functions in BQL:

Table 1: Aggregate functions

Function	Syntax	Description
Average	avg()	Returns the average of a set of numeric values.
Count	count()	Returns the total count of a given set of values.
Maximum	max()	Returns the maximum value in a set of values.
Minimum	min()	Returns the minimum value in a set of values.
Sum	sum()	Returns the sum of a set of numeric values.

For example, to return the average risk score of all open vulnerabilities in a report, you can use the following aggregate function in your query:

FIND Vulnerability WHERE status != "fixed" RETURN DISTINCT avg(riskScore)

Numeric functions

Numeric functions perform operations on numbers and return numbers. Numeric functions operate on numeric expressions only and return an error if used on any other values. The following table describes the numeric functions that BQL supports:

Table 2: Numeric functions

Function	Syntax	Description
Absolute	abs()	Returns the absolute value of the given number.
Ceiling	ceil()	Returns the smallest floating point number greater than or equal to the given number.
Floor	floor()	Returns the largest floating point number that is less than or equal to the given number.
Random	rand()	Returns a random floating point number.
Round	round()	Returns the value of the given number rounded to the nearest integer.
Round with Precision	round(expression, precision)	Returns the value of the given number rounded with the specified precision, with half-values rounded up.
Round with Precision and Rounding Mode	round(expression, precision, mode)	Returns the value of the given number rounded with the specified precision and specified rounding mode.
Signum	sign()	Returns the sign of the given number.

For example, you can use the following query in a report to return the ceiling of the risk score of your findings:

FIND Finding as f RETURN ceil(f.riskScore) as c

In addition to numeric functions, BQL also supports logarithmic and trigonometric functions.

Scalar functions

Scalar functions take one or more parameters from an input value and return a single value. The following table describes the scalar functions that BQL supports:

Table 3: Scalar functions

Function	Syntax	Description
Coalesce	coalesce(expression, expression)	Returns the first non-null value in the given list of expressions.
End Node	endNode(relationship)	Returns the end node of a relationship.
Head	head(list)	Returns the first element in a list.
Identifier	id(expression)	Returns a node or a relationship identifier.
Last	last(list)	Returns the last element in a list.
Length	length(path)	Returns the length of a path.
Randomly Generated Universally Unique Identifier	randomUUID()	Returns a randomly-generated Universally Unique Identifier (UUID).
Size	size(list)	Returns the number of elements in a list.
Timestamp	timestamp()	Returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.
Boolean	toBoolean(expression)	Converts a string or integer value to a boolean value.
To Boolean or Null	toBooleanOrNull(expression)	Converts a string, integer, or boolean value to a boolean value. Returns null for any other input value.
To Float	toFloat(expression)	Converts an integer, floating point number, or a string value, to a floating point number.
To Float or Null	toFloatOrNull(expression)	Converts an integer, floating point number, or a string value to a floating point number. Returns null for any other input value.
To Integer	toInteger(expression)	Converts a boolean, integer, floating point number, or a string value to an integer.
To Integer or Null	toIntegerOrNull(expression)	Converts a boolean, integer, floating point number, or a string value to an integer. Returns null for any other input value.
Type	type(relationship)	Returns the string representation of the relationship type.

For example, in the following query, r is the last name of a user whose lastName and firstName are not null. Coalesce is typically used to avoid null values.

FIND User as u RETURN coalesce(u.lastName, u.firstName) as r

String functions

String functions are used primarily for string manipulation and to convert an input string into an output string.

note

String functions operate on string expressions only and return an error if used on any other values.

The following table describes the string functions that BQL supports:

Table 4: String functions

Function	Syntax	Description
Left	left(original, length)	Returns a string containing the specified number of leftmost characters of the original string.
lTrim	lTrim(original)	Returns the original string with leading whitespace removed.
Replace	replace(original, search, replace)	Returns a string in which all occurrences of a specified string in the original string have been replaced by another string.
Reverse	reverse(original)	Returns a string in which the order of all characters in the original string have been reversed.
Right	right(original, length)	Returns a string containing the specified number of rightmost characters of the original string.
rTrim	rTrim(original)	Returns the original string with trailing whitespace removed.
Split	split(original, splitDelimiter)	Returns a list of strings as a result from the split of the original string around matches of the given delimiter.
Sub String	substring(original, start, length)	Returns a substring of the original string.
To Lower	toLower(original)	Returns the original string in lowercase.
To String	toString(expression)	Converts an integer, float, boolean, string, point, duration, date, time, localtime, localdatetime, or datetime value to a string.
To String or Null	toStringOrNull(expression)	Converts an integer, float, boolean, string, point, duration, date, time, localtime, localdatetime, or datetime value to a string. Returns null for any other input value.
To Upper	toUpper(original)	Returns the original string in uppercase.
Trim	trim(original)	Returns the original string with leading and trailing whitespace removed.

For example, you can use the following string function in a report to return all users with failed login attempts:

FIND User as u RETURN toString(u.failedLogins)