Skip to main content

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

FunctionSyntaxDescription
Averageavg()Returns the average of a set of numeric values.
Countcount()Returns the total count of a given set of values.
Maximummax()Returns the maximum value in a set of values.
Minimummin()Returns the minimum value in a set of values.
Sumsum()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

FunctionSyntaxDescription
Absoluteabs()Returns the absolute value of the given number.
Ceilingceil()Returns the smallest floating point number greater than or equal to the given number.
Floorfloor()Returns the largest floating point number that is less than or equal to the given number.
Randomrand()Returns a random floating point number.
Roundround()Returns the value of the given number rounded to the nearest integer.
Round with Precisionround(expression, precision)Returns the value of the given number rounded with the specified precision, with half-values rounded up.
Round with Precision and Rounding Moderound(expression, precision, mode)Returns the value of the given number rounded with the specified precision and specified rounding mode.
Signumsign()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

FunctionSyntaxDescription
Coalescecoalesce(expression, expression)Returns the first non-null value in the given list of expressions.
End NodeendNode(relationship)Returns the end node of a relationship.
Headhead(list)Returns the first element in a list.
Identifierid(expression)Returns a node or a relationship identifier.
Lastlast(list)Returns the last element in a list.
Lengthlength(path)Returns the length of a path.
Randomly Generated Universally Unique IdentifierrandomUUID()Returns a randomly-generated Universally Unique Identifier (UUID).
Sizesize(list)Returns the number of elements in a list.
Timestamptimestamp()Returns the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.
BooleantoBoolean(expression)Converts a string or integer value to a boolean value.
To Boolean or NulltoBooleanOrNull(expression)Converts a string, integer, or boolean value to a boolean value. Returns null for any other input value.
To FloattoFloat(expression)Converts an integer, floating point number, or a string value, to a floating point number.
To Float or NulltoFloatOrNull(expression)Converts an integer, floating point number, or a string value to a floating point number. Returns null for any other input value.
To IntegertoInteger(expression)Converts a boolean, integer, floating point number, or a string value to an integer.
To Integer or NulltoIntegerOrNull(expression)Converts a boolean, integer, floating point number, or a string value to an integer. Returns null for any other input value.
Typetype(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

FunctionSyntaxDescription
Leftleft(original, length)Returns a string containing the specified number of leftmost characters of the original string.
lTrimlTrim(original)Returns the original string with leading whitespace removed.
Replacereplace(original, search, replace)Returns a string in which all occurrences of a specified string in the original string have been replaced by another string.
Reversereverse(original)Returns a string in which the order of all characters in the original string have been reversed.
Rightright(original, length)Returns a string containing the specified number of rightmost characters of the original string.
rTrimrTrim(original)Returns the original string with trailing whitespace removed.
Splitsplit(original, splitDelimiter)Returns a list of strings as a result from the split of the original string around matches of the given delimiter.
Sub Stringsubstring(original, start, length)Returns a substring of the original string.
To LowertoLower(original)Returns the original string in lowercase.
To StringtoString(expression)Converts an integer, float, boolean, string, point, duration, date, time, localtime, localdatetime, or datetime value to a string.
To String or NulltoStringOrNull(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 UppertoUpper(original)Returns the original string in uppercase.
Trimtrim(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)