CREATE FUNCTION

SQLstream provides a number of built-in functions, and also allows users to extend s-Server’s capabilities by means of user-defined functions (UDFs) and user-defined transformations (UDXs). You define both using CREATE FUNCTION. Functions must be declared within schemas, but can be added to a SQL path.

Values passed to (or returned from) a user-defined function or transformation must be exactly the same data types as the corresponding parameter definitions. In other words, implicit casting is not allowed in passing parameters to (or returning values from) a user-defined function or a user-defined transform.

User-defined functions and transformations may be invoked using either the fully-qualified name .<function_name> or by the function name alone if it exists in the current SQL path (see SET PATH and CURRENT_PATH).

s-Server follows standard SQL rules for how SQL scalar parameters in the CREATE FUNCTION statement are mapped to Java method arguments. These are summarized in a table below. See https://db.apache.org/derby/docs/10.12/ref/rrefsqljargmatching.html for more details.

This topic contains information on the following subtopics:

Working with User-Defined Functions (UDFs)

A user-defined function can implement complex calculations or interact with an external system, taking zero or more scalar parameters and returning a scalar result. UDFs operate like built-in functions such as FLOOR() or LOWER(). For each occurrence of a user-defined function within a SQL statement, that UDF is called once per row with scalar parameters (constants or column values in that row).

User-defined functions may be defined either directly in SQL, or externally with Java classes.

Note: any Java class referenced by a UDF must be explicitly defined as part of a package (using a package clause in the source file for the Java class).

Working with SQL User-Defined Functions

Syntax for SQL User-Defined Functions

CREATE FUNCTION ''<function_name>'' ( ''<parameter_list>'' )
RETURNS ''<data type>''
LANGUAGE SQL
[ SPECIFIC ''<specific_function_name>'' ]
[ [NOT] DETERMINISTIC ]
CONTAINS SQL | READS SQL DATA | MODIFIES SQL DATA
[ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]
RETURN ''<SQL-defined function body>''
  • SPECIFIC assigns a specific function name that is unique within the database. Note that the regular function name does not need to be unique (two or more functions may share the same name, as long as they are distinguishable by their parameter list). The specific name may not be used to invoke the function, but is useful when dropping a function (see DROP FUNCTION when the regular function name is not unique.
  • DETERMINISTIC / NOT DETERMINISTIC indicates whether a function will always return the same result for a given set of parameter values. This may be used internally in query optimization.
  • READS SQL DATA and MODIFIES SQL DATA indicate whether the function potentially reads or modifies SQL data, respectively. If a function attempts to read data from tables, streams, or views without READS SQL DATA being specified, or insert to a stream or modify a table without MODIFIES SQL DATA being specified, an exception will be raised.
  • RETURNS NULL ON NULL INPUT and CALLED ON NULL INPUT indicate whether the function is defined as returning null if any of its parameters are null. If left unspecified, the default is CALLED ON NULL INPUT.

A SQL-defined function body consists only of a single RETURN statement.

Example of SQL User-Defined Function

CREATE FUNCTION get_fraction( degrees DOUBLE )
RETURNS DOUBLE
CONTAINS SQL
RETURN degrees - FLOOR(degrees)
;

Working with Java User-Defined Functions

Syntax for Java User-Defined Functions

CREATE FUNCTION <function_name> ( <parameter_list> )
RETURNS <built-in scalar type>
LANGUAGE JAVA
PARAMETER STYLE [SYSTEM DEFINED] JAVA
[ SPECIFIC ''<specific_function_name>'' ]
[ [NOT] DETERMINISTIC ]
NO SQL
[ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]
EXTERNAL NAME ['class <fully qualified static method name> '
| '<qualified jar name>:<fully qualified static method name>']

Any parameters to a Java-defined external function must be specified using built-in data types. While the Java function can return a value, changes to any values passed to the function as parameters only exist internal to the Java function. They are not passed back to the calling SQL.

  • SPECIFIC assigns a specific function name that is unique within the database. Note that the regular function name does not need to be unique (two or more functions may share the same name, as long as they are distinguishable by their parameter list). The specific name may not be used to invoke the function, but is useful when dropping a function (see DROP FUNCTION when the regular function name is not unique.
  • DETERMINISTIC / NOT DETERMINISTIC indicates whether a function will always return the same result for a given set of parameter values. This may be used internally in query optimization.
  • RETURNS NULL ON NULL INPUT and CALLED ON NULL INPUT indicate whether the function is defined as returning null if any of its parameters are null. If left unspecified, the default is CALLED ON NULL INPUT.
  • EXTERNAL NAME is used to define where SQLstream s-Server should look for the Java class implementing the function. Java-defined external functions must be located either in a class file on SQLstream s-Server’s Java classpath, or in an external Java archive (JAR) file loaded into the system using CREATE JAR. In the latter case, the qualified jar name is the name given to the jar as part of CREATE FUNCTION. If the jar name was not defined in the current schema, then the fully qualified . format must be used.

The Java class containing the method must live inside a package.

The following EXTERNAL NAME clauses will work:

EXTERNAL NAME '"FOO_SCHEMA":foo.VarbinaryFunctions.toUTF8String'
<para styleclass="Code Example"></para>
EXTERNAL NAME '"FOO_SCHEMA":foo.bar.VarbinaryFunctions.toUTF8String'

but the following declaration will raise an error when you try to invoke the function:

EXTERNAL NAME '"FOO_SCHEMA":VarbinaryFunctions.toUTF8String'

Examples of Java User-Defined Functions

CREATE JAR "getFraction"
    LIBRARY 'file:/home/aspen/getFraction.jar'
    OPTIONS(0);
--- This code loads the installed Java JAR file

CREATE FUNCTION get_fraction(degrees DOUBLE )
RETURNS DOUBLE
LANGUAGE JAVA
NO SQL
EXTERNAL NAME 'GPSFuncsJavaLib:com.sqlstream.examples.geolocate.Degree.getFraction'
;

CREATE FUNCTION get_fraction( degrees DOUBLE )
RETURNS DOUBLE
LANGUAGE JAVA
NO SQL
EXTERNAL NAME 'class com.sqlstream.examples.geolocate.Degree.getFraction'
;

Note that the above examples only cover the sql CREATE FUNCTION call. To fully define a Java UDF, you need to create and define a Java class (such as com.sqlstream.examples.geolocate.Degree) using CREATE JAR. See the topic GeoLocation: An Example of User-Defined Functions in the s-Server Integration Guide for full examples covering the entire process.

Working with User-Defined Transformations (UDXs)

A user-defined transform (UDX) is an advanced type of user-defined function that reads a set or stream of rows and returns a set or a stream of rows. Its input arguments can be scalars or cursors. A cursor is an object representing a query, from which the UDX can read the result of upstream processing. The query can be relational (finite) or streaming (infinite).

A UDX is always implemented by a Java class, which must be located in a java package.

A UDX is declared by a sql CREATE FUNCTION statement, much like a user-defined function.

The salient differences are:

  • A scalar input is declared as a parameter with a scalar type, just as for a UDF.
  • A subquery input, whether relational or streaming, is declared using the CURSOR type.
  • The rowtype of a cursor is not stated. Indeed, the rowtype of a cursor is dynamic, and is bound when the UDX is applied to a query.
  • In practical use, a UDX is written in Java to expect specific rowtypes. There is no way to state this constraint in the DDL.
  • The output of a UDX is a virtual table or stream. The output columns and types are specified in a RETURNS TABLE clause.
  • When a UDX has an input CURSOR c, the output rowtype can use c.* to mean all the columns from that input, in the same order as in the catalog.
  • A UDX can take any number of relational inputs, and can process their rows in any order (fetching all of one first, and then moving on to the next, or interleaving fetches). Of course if the inputs are streams the UDX should make best efforts to poll each of the streams concurrently to avoid losing data.
  • UDX output is not tied to input processing. A UDX can emit rows as needed - either many outputs per input, or one output per many inputs.

UDXs, Streams, and ROWTIMEs

A stream always has a ROWTIME column. Therefore, a cursor based on a streaming query will have a ROWTIME, but a cursor based on a relational query will not. As a result, the SQL that calls the UDX differs:

```
CURSOR(SELECT STREAM....) has a rowtime
CURSOR(SELECT....) has no rowtime.
```

The declaration of a UDX states its output rowtype, although with the “c.*” construct the output can depend dynamically on the input type. The rowtype of an input cursor is always dynamic.

A UDX is required to set the value of every output column, matching its declared data type. ROWTIME is special:

  • It occurs only in streaming context;
  • It is never null and never decreases;
  • The UDX may set it (often by copying the ROWTIME from an input cursor); OR
  • The UDX may skip it, which means the system will set it to the current stream time.

Good practice for coding a Java UDX is:

  • Check the rowtype of inputs (java.sql.ResultSet) and of the output (java.sql.PreparedStatement).
  • Refer to columns by name, not position.
  • An output ROWTIME indicates the UDX has been called in a streaming context.

Declaring UDXs in s-Server

In order for UDXs to be available in s-Server, you need to declare them in SQL. See the topic CREATE FUNCTION in the Streaming SQL Reference Guide for more details. The following code declares a UDX for the JAR defined above.

This example shows the declaration and use of a UDX that has three inputs: one scalar integer value and two query expressions. Also note that in this example the output is fixed at 3 columns.

CREATE OR REPLACE FUNCTION crossRef(bias INTEGER, c1 CURSOR, c2 CURSOR)
 RETURNS TABLE(leftVal INTEGER, rightVal INTEGER, position DECIMAL(9,2))
 LANGUAGE JAVA
 PARAMETER STYLE SYSTEM DEFINED JAVA
 NO SQL
 EXTERNAL NAME 'class com.sqlstream.udxsample.UdxSample.crossRef';

Usage:

SELECT STREAM res.position
FROM TABLE(crossRef( 33, CURSOR(SELECT STREAM * FROM transmitStream),
CURSOR(SELECT TREAM * FROM recieveStream))) AS res;

Output Row:

leftVal INTEGER
rightVal INTEGER
position DECIMAL(9,2)

The following example has two relational inputs. The output row consists of all columns defined by both CURSORs as well as an additional DECIMAL column.

Note: Result column names must be unique; if you are using the c1.* specification in the RETURNS for each input cursor, you must be sure that all source column names (except ROWTIME) are distinct. If you explicitly list output column names it is easy to enforce distinct output column names for yourself.

CREATE OR REPLACE FUNCTION confirmResults(c1 CURSOR, c2 CURSOR)
 RETURNS TABLE(c1.*, c2.*, confidence DECIMAL(5,2))
 LANGUAGE JAVA
 PARAMETER STYLE SYSTEM DEFINED JAVA
 NO SQL
 EXTERNAL NAME 'class com.sqlstream.udxsample.UdxSample.confirmResults';

Usage:

SELECT STREAM res.position
FROM TABLE(confirmResults(CURSOR(SELECT STREAM * FROM transmitStream),
CURSOR(SELECT STREAM * FROM receiveStream))) AS res;

Output Row:

bytesSent INTEGER
data_sent VARBINARY(1024)
bytesRecieved INTEGER
data_received VARBINARY(1024)
confidence DECIMAL(5,2)

How to build a UDX

For the detailed information on How to build a UDX, see the topic Writing a UDX.