BQL Quick Reference
You can use the BQL functions listed here in report expressions in Designer and Visualizer, unless otherwise noted.
See Introduction to BQL, BQL Basics, and Advanced BQL.
For the functions that are supported by custom formulas when creating custom attributes and custom measures, see Formula Reference for Custom Attributes and Measures.
Use |
Syntax |
Example |
|
---|---|---|---|
ABS |
Absolute value of a measure value. |
ABS([measure]) |
ABS([OrderDate: Sum: Quantity]) |
ADD |
Adds a value to end of an existing list. |
ADD([ListVariable],10) |
|
ADDPARENTCHILD |
Adds a single parent-child pair to the current list of pairs. |
ADDPARENTCHILD([ParentID],[ChildID]) |
|
ARCCOS |
Returns the arc cosine of a number between ο and π. |
ARCCOS([logical_column]) |
ARCCOS([OrderDate: Sum: Quantity]) |
ARCSIN |
Returns the arc sine of a number between -π/2 and π/2. |
ARCSIN([logical_column]) |
ARCSIN([OrderDate: Sum: Quantity]) |
ARCTAN |
Returns the arc tangent of a number between -π/2 and π/2. |
ARCTAN([logical_column]) |
ARCTAN([OrderDate: Sum: Quantity]) |
ATAN2 |
Returns the arc tangent of x and y. |
ATAN2(x,y) |
|
Casting |
Convert data types. Expressions and variables can be cast to different data types. All data types implicitly cast to a varchar so no cast statement is needed. When a cast is not supported, such as casting ‘A’ to a float, a NULL is returned. See Data Type Casting. |
FLOAT() |
INTEGER(GETPROMPTVALUE('Stage 4 Probability')) |
CEILING |
Round up. Returns the closest integer greater than or equal to the given number. |
CEILING([measure]) |
CEILING([OrderDate: Sum: Quantity]) |
COS |
Returns the cosine of a given angle. |
COS([logical_column]) |
COS([OrderDate: Sum: Quantity]) |
DATEADD |
Adds or subtracts an integer from a date. |
DATEADD(Year|Month|Day|Hour|Minute|Second, integer, [date_attribute]) |
DATEADD(Day, 5, [Time.Date]) |
DATEDIFF |
Returns the difference in dates as an integer value. NULLS are interpreted as zero (0). See DATEDIFF. |
DATEDIFF(Year|Month|Day|Hour|Minute|Second, [start_date_attribute],[end_date_attribute]) |
DATEDIFF(Month,[Order_Details.OrderDate], |
DATEPART |
Returns integers from dates. |
DATEPART(Year|Month|Day|Hour|Minute|Second, [date_attribute]) |
DATEPART(Day, [Time.Date]) |
DEGREES |
Converts x radians to degrees. |
DEGREES(x) |
|
DISPLAY BY |
Sorts results after the result set has been generated and any other display operations have been performed. See Result Sets and Display Operations. |
SELECT [query] FROM [ALL] DISPLAY BY[attribute|measure]ASCENDING|DESCENDING |
|
Displays top n results of the returned dataset. To get the top n from the database, see Top N. |
SELECT DTOP n [query] FROM[all] ORDER BY [attribute|measure]Ascending|Asc|Descending|Desc |
To display the top 5 results of a newly-created expression: SELECT DTOP 5 USING OUTER JOIN [Time.Year]
'F9', |
|
A display filter. Filters on the returned data set (the data in cache). Use for dimension columns and measures. Returns entire query but only displays data that matches criteria. See Result Sets and Display Operations. |
SELECT [query] FROM [All] DISPLAY WHERE [attribute|measure]=value |
SELECT [Sales] FROM [All] DISPLAY WHERE [Sales]>10000 |
|
DRANK |
Dense rank returns the rank of each row within the result set, without any gaps in the ranking. |
DRANK([measure]) |
DRANK([OrderDate: Sum: Quantity]) |
EXP |
Returns e raised to the power of the number given. |
EXP([logical_column]) |
EXP([OrderDate: Sum: Quantity]) |
FIND |
Same as LOOKUPVALUE, but does not look for an exact match. If the match is exact that row is returned, otherwise, the first row that is greater than the lookup value is used. Parameters can be added before the logical query and referenced in the logical query using the %index syntax, starting with %0. |
FIND(index_of_column_to_lookup, value_to_lookup, index_of_column_to _return, logical_query) |
FIND(0,[Products.ProductName], 1, SELECT
[Products.ProductName], |
FLOOR |
Returns the closest integer less than or equal to a given number. |
FLOOR([logical_column]) |
FLOOR([OrderDate: Sum: Quantity]) |
Formats a measure or date to the particular string format provided. See FORMAT and Pattern String Formats. |
FORMAT([measure|date_attribute],'format_string') |
FORMAT([OrderDate: Sum: Quantity],'##,###,##0.00') |
|
Creates a custom function that can be used in any BQL query including an expression. See FUNCTION and FUNCTIONLOOKUP. |
FUNCTION(return_data_type, script_statement_block, logical_query) |
FUNCTION (Float, |
|
FUNCTIONLOOKUP |
Creates a custom function that executes a script over an entire result set to return a result. See FUNCTION and FUNCTIONLOOKUP. |
FUNCTIONLOOKUP(return_data_type, lookup_index, lookup_expression, script_statement_block, logical_query) |
|
GETDAYID |
Returns a unique integer signifying the day based on a date or datetime value. |
[ID Value] = GETDAYID([date_value]) |
|
GETLEVELATTRIBUTE |
Provides additional data either on the entire tree or on a given record that is being processed. Two options are supported. NumLevels returns the maximum depth of items in the tree. CurrentDepth returns the depth of the current item in the tree. |
GETLEVELATTRIBUTE('NumLevels')
GETLEVELATTRIBUTE('CurrentDepth') |
|
GETLEVELVALUE |
For the current pair, returns the ID n levels deep into the hierarchy. If there are fewer than n levels, it returns the ID of the lowest level available. The IDs will repeat for levels lower than their depth. |
GETLEVELVALUE(n) |
|
GETMONTHID |
Returns a unique integer signifying the month based on a date or datetime value. |
[ID Value] = GETMONTHID([date_value]) |
|
GETPROMPTFILTER |
Passes a user-selected prompt filter from a dashboard to a measure expression. See GETPROMPTFILTER and GETPROMPTVALUE. |
GETPROMPTFILTER('prompt_name') |
[OrderDate: Sum: Quantity] WHERE GETPROMPTFILTER('MyPrompt') |
Passes a prompt filter value from a dashboard to a measure expression. An optional second argument (such as null or a string such as '2012') can be used in the event that the first argument is not a currently defined prompt. See GETPROMPTFILTER and GETPROMPTVALUE. |
GETPROMPTVALUE('prompt_name', 'optional_default_value') |
[OrderDate: Sum: Quantity]*
|
|
Retrieves the value of a variable. See Variables and BQL. |
GETVARIABLE('variable_name') |
GetVariable('LoadDate') |
|
GETWEEKID |
Returns a unique integer signifying the week based on a date or datetime value. |
[ID Value] = GETWEEKID([date_value]) |
|
IFNULL |
Allows an expression to return a different result if it is null. |
IFNULL(evaluation, result_if_NULL) |
IFNULL([OrderDate: Sum: Quantity],0) |
IIF |
Immediate IF. Allows an expression to return one result if the specified condition is true and a different one if it is false. Can be nested. |
IIF(evaluation, result_if_TRUE, result _if_FALSE) |
IIF([OrderDate: Sum: Quantity] >6000,
0, |
ISINF |
Evaluates an expression and returns TRUE if the value is +/- infinity. The result can be used as a conditional check. |
ISINF(evaluation, result_if_TRUE, result _if_FALSE) |
IIF(ISINF([OrderDate: Sum: Quantity]),0, |
ISNAN |
Evaluates an expression and returns TRUE if it is not a number and FALSE if it is. The result can be used as a conditional check. |
ISNAN(evaluation) |
IIF(ISNAN([OrderDate: Sum: Quantity]),0, |
LENGTH |
Returns the number of characters in a string. This can also be used in an ETL script to return the number of elements in a List object. |
LENGTH([dimension]) |
LENGTH([Products.CategoryName])
ETL Script Example: LENGTH([myList]) - 1 |
LET |
Allows logic re-use with expression-level variables. See LET. |
LET(variable_declarations, expression_ body) |
LET(Dim [AvgPrice] As Float = LookupValue(0, |
LN |
Returns the natural logarithm of a given number in a specified base. |
LN([measure | numeric_attribute]) |
LN([OrderDate: Sum: Quantity]) |
LOG |
Log base e of X. Returns the logarithm of a given number in a specified base. |
LOG([measure | numeric_attribute]) |
LOG([OrderDate: Sum: Quantity]) |
LOG10 |
Log base 10 of x. |
LOG10([measure | numeric_attribute]) |
LOG10([OrderDate: Sum: Quantity]) |
LOOKUPROW |
Use instead of LOOKUPVALUE if the result set will be in the same order as the existing set. See LOOKUPROW. |
LOOKUPROW(index_of_the_row_to return, index_of_the_column_to_return, SELECT [query] FROM [All]) |
LOOKUPROW(0,1, SELECT [OrderDetail.OrderID],
|
LOOKUPVALUE |
Lookup based on value in the current result set to get a dimension or measure value from another result set. Looks for an exact match. See LOOKUPVALUE. |
LOOKUPVALUE(column_number_from _the_query, [value_in_the_current_query _to_look_at], column_number_of_the_new_query, SELECT[query] FROM [All]) |
LOOKUPVALUE(0,[Products.CategoryName],1, |
LTRIM |
Trims white space from x on the left. |
LTRIM(x) |
|
MEDIAN |
Returns the value in the middle of all measure values at the report grain. Supports an optional BY break by attribute. |
MEDIAN([measure] BY [attribute]) |
MEDIAN([OrderDate: Sum: Quantity] BY[Products.Products]) |
NEXTCHILD |
Once a set of parent-child pairs have been added, the list can then be iterated over one by one to flatten. NEXTCHILD positions the current record to the next available pair. If there are no more pairs left, it returns false. |
|
|
NOW |
Returns the current date and time. See NOW and NOWDATE. |
NOW |
yyyy-mm-dd hh:mm:ss for example: 2016-04-19 15:24:25 |
NOWDATE |
Returns current date at midnight. See NOW and NOWDATE. |
NOWDATE |
yyyy-mm-dd 12:00:00 for example: 2016-04-19 12:00:00 |
NUMROWS |
Returns the total number of rows in the current result set. This function is not available in ETL Services. |
NUMROWS() |
NUMROWS() |
ORDER BY |
Sort function. See BQL Basics - Controlling Sort Ordering. |
SELECT [query] FROM [All] ORDER BY [measure | attribute ] Ascending | Asc | Descending | Desc, [measure | attribute ] Ascending | Asc | Descending | Desc ... |
SELECT [Product.Category Name], [Time.Year],[Unit Sales] FROM [All] ORDER BY [Product.Category Name] Ascending, [Time.Year] Descending |
POSITION |
Returns the position of a string within an attribute. An optional parameter specifies the starting index to begin the search. |
POSITION('search string', [attribute], starting_position_number_to_begin_search) |
POSITION(‘Bev’, [Product.ProductCategory], 3) In this example, it would start looking for "Bev" in the product name at the 4th character. |
POW |
Raise x to the power of y. |
POW(x,y) |
POW(4,2) |
RADIANS |
Converts x degrees to radians. |
RADIANS(x) |
|
PI |
Returns Pi. |
PI() |
PI() |
PTILE |
Returns the percentile rank of each row within the result set. |
PTILE([measure]) |
PTILE([OrderDate: Sum: Quantity]) |
RANDOM |
Returns a double from 0.0 to 1.0. Ignores parameter values. |
RANDOM() |
RANDOM() |
RANK |
Returns the rank of each row within the result set. See Result Sets and Display Operations - Ranking Calculations. |
RANK([measure]) To rank within a group: RANK([measure]) BY ([attribute]) |
RANK([OrderDate: Sum: Quantity]) RANK([OrderDate: Sum: Quantity] BY [Products.CategoryName]) SELECT [Time.Year],[Product.Category
Name], |
REMOVEALL |
Removes all elements from a list. |
|
|
REMOVEAT |
Allows you to remove an item from a given position in a list. |
REMOVEAT([ListVariable],[IndexToRemove]) |
|
REPLACE |
Replaces a string with a string. |
REPLACE([attribute], 'part_of_string_to_replace', 'replacement_string') |
REPLACE([Products.CategoryName], 'ages', 'age') |
REPLACEALL |
Replaces a string using a regular expression. |
REPLACEALL([attribute],[regular_expression], replacement_string) |
REPLACEALL([Products.CategoryName],'P.*e','Organic Produce') |
Executes an R expression within a BQL query. Birst casts the results to the expected
return type. |
REXP(return_data_type, 'R_ expression_to_run'). |
REXP(Number,'predict(model, newdata= |
|
ROWNUMBER |
Returns the row number for the current result set. This function is not available in ETL Services. |
ROWNUMBER() |
ROWNUMBER() |
RSUM |
Returns the trailing sum of values, based on the window size, at the current report grain for the window provided. See RSUM. |
RSUM(window_size_integer, [ measure]) |
RSUM(10,[OrderDate: Sum: Quantity]) |
RTRIM |
Trims all white space from x on the right. |
RTRIM(x) |
|
SIGN |
Returns +1 for x > 0, 0 for x == 0, and -1 for x < 0 |
SIGN(x) |
|
SIN |
Returns the sine of a given angle. |
SIN([measure | numeric_attribute]) |
SIN([OrderDate: Sum: Quantity]) |
SPACE |
Returns x spaces. |
SPACE(x) |
|
SPARSE |
Shows dimension column values for which there is no fact data. Works with multiple attributes. See SPARSE. |
SPARSE([attribute, attribute...]) |
SPARSE([Time.Year])
|
SQRT |
Returns the square root of a measure. |
SQRT([measure]) |
SQRT([OrderDate: Sum: Discount]) |
STAT |
Aggregate stats based on another result set. STAT supports the PERCENTILE operator and percentile_value argument, where the value is between 0 and 1. See STAT. |
STAT(MEDIAN | AVG | MIN | MAX | SUM | COUNT | COUNTDISTINCT| STDDEV, index, [query])
STAT(PERCENTILE, percentile_value, index, [query])
|
STAT(MEDIAN, 1, SELECT [Products.CategoryName],
STAT(PERCENTILE, .50, 1, SELECT [Products.CategoryName],
|
SUBSTRING |
Returns a portion of a given string. Uses a zero-based index. Starting position is 0, ending position is the position after the last one that should be included. |
SUBSTRING([attribute], start_ position_number, end_position_ number) |
SUBSTRING([Products.ProductName], 2, 8) The example above returns "member"
for |
TAN |
Returns the tangent of a given angle. |
TAN([measure | numeric_attribute]) |
TAN([OrderDate: Sum: Quantity]) |
TOLOWER |
Returns a character expression after converting data to lower case. |
TOLOWER([attribute]) |
TOLOWER([Products.CategoryName]) |
Filter by the top n results from the database. See BQL Basics. To filter by top n results in cache, see DTOP. |
SELECT TOP number query |
SELECT TOP 10 USING OUTER JOIN [Order_Date: Sum: Unit Cost] 'Column1', [Products.Product] 'Column2' FROM [ALL] ORDER BY [Order_Date: Sum: Unit Cost] ASC |
|
TOTIME |
Converts integer values to a time format. Supported in ETL scripts and column expressions. Years and months are not supported. |
TOTIME(1000000000, 'hours,minutes,seconds', '%d:%02d:%02d') |
TOTIME(Integer([Order_Details.OrderID]+ |
TOUPPER |
Returns a character expression after converting data to upper case. |
TOUPPER([attribute]) |
TOUPPER([Products.CategoryName]) |
Directly manipulate or create from scratch the report-level result set. See TRANSFORM. |
TRANSFORM(script) |
TRANSFORM( |
|
TREND |
Uses the least squares method to extrapolate values based on a linear trend. See TREND. |
TREND(index_of_column_to_return, index_of_column_to_lookup, value_to_lookup, query) |
TREND(1, 0, [Time.Month Seq Number], |
TRIM |
Trims leading and trailing spaces. Can be used in a constant to pad a value. |
TRIM([attribute]) |
TRIM([Products.CategoryName]) |
Absolute |
Performs calculation based on specific value. |
[measure]/[measure] {[attribute] = value} |
[OrderDate: Sum: Quantity]/[OrderDate:
Sum: Quantity] |
Share |
Relative measure value calculation. |
[measure]/[measure] {[attribute]} |
[OrderDate: Sum: Quantity]/[OrderDate:
Sum: Quantity] how much each product makes up of the entire product category |
Relative (Growth) |
Relative measure comparison, such as month-over-month-growth. |
[measure]/[measure] {[time.attribute] +-=value} |
[OrderDate: Sum: Quantity]/[OrderDate:
Sum: Quantity] |
Grand Totals |
Relative total. In this case Total is a special column. |
[measure]/[measure] {[dimension.Total]} |
[OrderDate: Sum: Quantity]/[OrderDate:
Sum: Quantity] |
= |
Equals |
= |
[Products.CategoryName]='Beverages' |
< |
Less than |
< |
[Sum: Quantity]<3000 |
> |
Greater than |
> |
[Sum: Quantity]>0 |
<> |
Not equals. Successful when the column on the left does not match the string value. |
<> |
[Products.CategoryName]<>'Beverages' |
<= |
Less than or equal to |
<= |
[Sum: Quantity]<=500 |
>= |
Greater than or equal to |
>= |
[Sum: Quantity]>=1000 |
AND |
Returns true if all filter conditions are met. |
AND |
[OrderDate: Sum: Quantity] WHERE
[Categories.CategoryName] = |
OR |
Returns true if either filter condition is met. |
OR |
[OrderDate: Sum: Quantity] WHERE
[Categories.CategoryName] = |
LIKE |
Searches for a specified pattern in a column. |
LIKE |
[OrderDate: Sum: Quantity] WHERE
[Categories.CategoryName] |
NOT LIKE |
Searches for the non-existence of a specified pattern in a column. |
NOT LIKE |
[OrderDate: Sum: Quantity] WHERE
[Categories.CategoryName] |
IS NULL |
Condition is satisfied if the column value contains a null value, or an expression evaluates to null. |
IS NULL |
[OrderDate: Sum: Quantity] WHERE [Time.Year] IS NULL |
IS NOT NULL |
Condition is satisfied if the column value is not null, or an expression does not evaluate to null. |
IS NOT NULL |
[OrderDate: Sum: Quantity] WHERE [Time.Year] IS NOT NULL |
+ |
Concatenation |
+ |
[Account.First Name] + ' ' + [Account.Last Name] |
% |
Modulo |
[dividend] % [divisor] |
9 % 4 = 1 |
USER |
Session variable that stores the user login for that specific session. |
Use as a value in expressions. |
asmith@birst.com |
LoadDate |
Repository variable that stores the last load date. |
Use as a value in expressions |
08/29/2015 |
LoadDateSFDC |
Repository variable that stores the load date and time of the last Salesforce.com load. |
Use as a value in expressions |
2015-08-29T00:00:00-05.00 |
LoadNumber |
Repository variable that stores the last load number. |
Use as a value in expressions |
1 |
LoadStartTime |
Repository variable that stores the start date and time of the last load for the space. Note: LoadInitiateTime was a previous version of this variable. |
Use as a value in expressions |
2015-08-29T11:46:45-05:00 |
LoadCompletionTime |
Repository variable that stores the last load completion date and time. |
Use as a value in expressions |
2015-08-29T11:46:45-05:00 |
See Also: