StreamBase Expression Language Features

This topic provides reference information for the StreamBase expression language.

StreamBase provides two types of functions:

StreamBase provides sample applications that feature custom functions for you to load into StreamBase Studio to see how they are built and configured. The custom sample applications are listed in Extending StreamBase Samples.

Back to Top ^

StreamBase Studio provides the following user assistance features to aid writing expressions:

See Properties View for more information on these features.

Back to Top ^

If you do not find a built-in function that you need, you can use the StreamBase custom function APIs to implement your own function and configure your application to use it. Your custom functions can be written by extending the StreamBase APIs for Java or C++. For details on writing your own functions, see these topics in the API Guide:

You can call your custom functions in expressions by calling a function alias you have declared in the server configuration file, or by using calljava() or callcpp().

myCustomFunction(x, y) 

Use the sbd --eval command to evaluate and test your expressions at the command prompt before using them in your StreamBase applications. sbd --eval works with simple functions, but not with aggregate functions. You must evaluate aggregate functions using other methods, such as running a test application and checking the results.

On Windows, be sure to run sbd --eval from the StreamBase Command Prompt, not a standard Windows command prompt.

The following examples show how to use sbd --eval. These examples work as shown at the StreamBase Command Prompt on Windows and at the Bash prompt on Linux. See Using Quotes in Expressions for further details on the quoting rules for StreamBase expressions.

Back to Top ^

Expressions often need quotes around string values to designate those values as strings. The StreamBase expression language is agnostic about whether to use double or single quotes in expressions. For example, StreamBase interprets the following expressions identically when used in an expression in an operator or adapter in StreamBase Studio or in a StreamSQL statement:

strftime("Traded on %b %d, %Y at %H:%M", now())
strftime('Traded on %b %d, %Y at %H:%M', now())

The only rule is that you must escape any instance of the same quote mark if you need to use it again inside a pair of quote marks. You can escape a quote mark with a preceding backslash, or you can surround it with the opposite quote mark. For example, StreamBase interprets the following lines identically in Studio or in StreamSQL:

strftime('Traded at Miller\'s Crossing on %b %d, %Y at %H:%M', now())
strftime("Traded at Miller's Crossing on %b %d, %Y at %H:%M", now())

Works on Windows:
sbd --eval "strftime(\"Traded on %b %d, %Y at %H:%M\", now())"
sbd --eval "strftime('Traded on %b %d, %Y at %H:%M', now())"

Works on Bash under Linux or Cygwin:
sbd --eval "strftime(\"Traded on %b %d, %Y at %H:%M\", now())"
sbd --eval "strftime('Traded on %b %d, %Y at %H:%M', now())"
sbd --eval 'strftime("Traded on %b %d, %Y at %H:%M", now())'

Does NOT work on Bash:
sbd --eval 'strftime(\'Traded on %b %d, %Y at %H:%M\', now())'

Expressions use the StreamBase static data types:

These data types are described in detail in StreamBase Data Types.

Back to Top ^

To recast data types, use one of the StreamBase type conversion functions. For example, to cast a value to a double in an expression, use the double() function. To cast a value to a string, use the string() function, and so on. Casting may not be necessary if type coercion is supported for the data types, as described in the next section.

Back to Top ^

Some StreamBase functions support data type coercion of input arguments from long to double data types. Type coercion is the implicit conversion of a value from one data type to another. For example, the floor() function is listed in this reference as taking a double argument. However, you can enter an integer or long value instead, and the function implicitly converts the value to its double equivalent.

The following are the supported data type coercions:

Observe the following rules for coercion:

Back to Top ^

Expressions are case sensitive. Function names are usually all lowercase, with a few exceptions. If you add custom functions, follow the lowercase convention.

Back to Top ^

StreamBase identifier naming rules apply to the name you assign to any StreamBase component, including schemas, fields, operators, tables, modules, containers, and data source names. The rules are:

StreamBase supports a syntax for escaping identifier names that contain reserved characters. If you enter a name that does not follow the above rules, StreamBase automatically stores the name with escaped identifier syntax. StreamBase Studio shows a warning when it needs to change a name you entered to use the alternate syntax.

The escaped identifier syntax is #"name", a pound or hash symbol, with the string in double quotes. Escaped identifiers work throughout StreamBase for the names of all components. You can use this syntax to name a field the same as a StreamBase reserved word, such as #"AS".

Identifier names can include Unicode characters as long as Unicode support is enabled for both Studio and Server, as described in Unicode Support.

Back to Top ^

When you name fields, do not use the following words, which are reserved for use in the expression language:

In EventFlow applications, StreamBase Studio does not prevent you from naming a field with a reserved word in an input stream's Properties view. However, a schema that contains a reserved word causes one or more typecheck errors in downstream components. The error message in the Typecheck view identifies the offending field's name. To correct the typecheck error, rename the field in the input stream's Properties view.

In StreamSQL applications, Studio prevents you from using a reserved word as a field name when defining schemas, or as a field in an index specification, order-by specification, or gather key.

Although the names of StreamBase data types are not reserved words, StreamBase Systems recommends that you do not use data type names as field names, for clarity when developing and debugging your applications. The data type names are listed in Data Types.

The StreamSQL language has an additional list of reserved words, as shown in StreamSQL Reserved Words.

Back to Top ^

If a name conflict occurs in a field name that is used in an expression within an operator instance, you can qualify the name to clarify the inbound stream you mean.

For example, in the Properties view for a Gather operator, you can qualify the fields as input[port-number].field-name.

Example: input1.is_alarm, input2.is_alarm, input3.is_alarm.

In the Properties view for a Join operator, you can qualify the fields in the two input streams as input1.field-name and input2.field-name. The input1.field-name refers to a field in the stream arriving at the top port (#1). The input2.field-name refers to a field in the stream arriving at the bottom port (#2).

Examples:

input1.SKU
input2.SKU

In the Properties view for a Query operator, you can qualify the fields in the two input streams as input.field-name and old.field-name. The input.field-name refers to the current input tuple, while old.field-name refers to the field's prior value.

Examples:

Table1_current_Name
Nasdaq100Table_old_Symbol

Back to Top ^

You can use +, –, *, /, and %. The ^ expression is not supported.

For example, in the Compliance sample provided in the StreamBase installation, the is_alarm field is a bool. In one of the Compliance application's Map operators, we use the following expression for the is_alarm check on each tuple:

((((sector_in_fund_value_t + (shares_traded * price_at_trade)) * 100) / fund_value_t) > 25)

This expression is designed to execute the 25% sector test, where one sector is not allowed to be more than 25% of the total fund value. is_alarm is set to true if the test fails.

Back to Top ^

The modulus operator (%) finds the remainder of a division operation. Division and modulus are always related such that a/b*b+(a%b) == a, where a/b is an integer division. For example, 15%4 can be resolved as follows: as:

15 / 4 * 4 + MOD == 15
3 * 4 + MOD = 15
12 + MOD = 15
MOD = 3

This relationship is preserved with negative divisors. As a result, whenever the quotient is negative, the modulus is negative. For example:

15 % 4 = 3
15 % -4 = 3
-15 % 4 = -3
-15% -4 = -3

Also note that if you divide a smaller number by a larger number, the modulus is always the smaller number. For example:

4 % 15 = 4

This behavior may be different than modulus in some programming languages.

Back to Top ^

Unary operators act on only one operand in an expression. –a is valid for integer, double, and long types. !a is valid for the bool type. +a is not supported.

Back to Top ^

You can use the <, <=, = or ==, >, >=, and != relational operators. The relational operator <> is not supported.

StreamBase data types are comparable with relational operators in different ways, as listed in the entry for each data type on StreamBase Data Types.

Back to Top ^

You can use && or AND, || or OR, and !.

For related information on Boolean logic and nulls, see Using Nulls.

Back to Top ^

The precedence order of mathematical operators in expressions, from highest to lowest, is as follows:

You can use parentheses in expressions to override the default precedence.

Back to Top ^

The StreamBase parser ignores any spaces, new lines, and tab characters in expressions.

Back to Top ^

You can add comments to your expressions using either C-style comments or StreamSQL-style comments:

The following sample expression illustrates several uses of comments:

/* handle special APPL case */
if (input1.symbol=="APPL.N") then input2.symbol == "APPL" 
/* handle special 
   IBM case */
  else if (input1.symbol=="IBM.L") then input2.symbol == "IBM"
  else input2.symbol == input1.symbol -- accept the rest as given

Back to Top ^

This section describes how to specify literals in expressions, for each data type. (For information about the data types themselves, see StreamBase Data Types.)

Back to Top ^

You can use nulls in the StreamBase expression language, one for each of the simple data types:

blob(null)
bool(null)
double(null)
int(null)
long(null)
string(null)
timestamp(null)

The data type of a null is never implicit. You must specify the data type of any null you are using in the expression.

In general, when you apply any arithmetic operator or function with data-type(null) as one of the arguments, the result is null. Three exceptions are the isnull() and notnull() functions, which test whether an expression evaluates to null, and the coalesce() and coalesce_tuples() functions, which select a non-null value from a set of potentially null arguments.

To specify a null list, use the nulllist() function. See Null Lists for a discussion of null lists compared to empty lists.

To specify a null tuple that uses a named schema, specify the name of the schema with empty parentheses. For example, for the schema named nyse_data, the expression nyse_data() creates a null tuple. See Null Tuples for a discussion of null tuples compared to empty tuples.

For more detailed information, see Using Nulls.

Back to Top ^

In an expression such as: if p then e1 else e2, p must be a valid bool expression, and both e1 and e2 must be expressions that have the same type. If p is true, then e1 is evaluated and the result returned. If p is false, e2 is evaluated and the result returned. In either case, the other sub-expression is not evaluated.

Back to Top ^

You can use combinations of if-then and else-if-then statements to form compound conditional expressions. For example:

if i==0 then "Buy" else if i==1 then "Sell" else if i==2 then "Hold" else "None of the above"

Here is a second example, indented for clarity, where we nest an if then else in a then clause:

if p1
  then
    if p2
      then A
      else B
else
  if p3
    then C
    else D

Notice how each if clause contains a then clause and an else clause.

Back to Top ^

You can enter an expression that performs concatenation. For a string variable, the concatenation expression is

stringvar1 + stringvar2

For a numeric variable with a static string, the concatenation expression is

"staticstring" + numvar

For example: "foo" + a.

For two variables, the concatenation expression is

stringvar + numvar

For example: b+a.

Back to Top ^

When used with comparison operators ( == != > < <= >= ) you must compare time interval-to-interval, or timestamp-to-timestamp. You cannot use the comparison operators with interval-to-timestamp.

To express constant intervals, you can use the seconds() and minutes() functions. For example, if you want to add 60 seconds to a timestamp, enter expressions such as:

t + seconds(60)
t + minutes(1)

For more on comparing timestamp expressions, see timestamp Data Type.

Back to Top ^

You can declare global parameters in the StreamBase Server configuration file, usually named sbd.sbconf, and can define module parameters in the Parameters tab of the EventFlow Editor. You can reference either parameter type in StreamBase expressions. See Constants, Variables, and Parameters for more on the difference between global and module parameters.

To reference a parameter in an expression, wrap the parameter name in braces and prefix the open brace with a dollar sign: ${parameter}. If you are referencing a parameter that is defined as a string, use quotes around the entire reference: "${parameter}"

StreamBase Server Configuration File XML Reference explains how to declare global parameters. For example, consider a server configuration file that defines the following two global parameters:

<operator-parameters>
    <operator-parameter name="MyInt" value="2"/>
    <operator-parameter name="MyString" value="somestring"/>
</operator-parameters>

You could reference the first parameter (for example, in an output field) using an expression like 35 * ${myInt}. The expression would evaluate at run time to 70. The following StreamSQL statement references the second parameter:

SELECT * FROM InputStream1 "${MyString}" AS source

Notice the quotation marks, which are needed so that the expression is resolved as a string.

Back to Top ^