Use UDFs in Java
This article provides a step-by-step guide for installing the RisingWave Java UDF SDK, defining functions using Java, starting a Java process as a UDF server, and declaring and using UDFs in RisingWave.
Prerequisites
- Ensure that you have Java Developer’s Kit (JDK) (11 or later) installed on your computer.
- Ensure that you have Apache Maven (3.0 or later) installed on your computer. Maven is a build tool that helps manage Java projects and dependencies.
1. Create a Maven project from template
The RisingWave Java UDF SDK is distributed as a Maven artifact. We have prepared a sample project so you don’t have to create it from scratch. Run the following command to clone the template repository.
2. Define your functions in Java
Scalar functions
A user-defined scalar function maps zero, one, or multiple scalar values to a new scalar value.
In order to define a scalar function, you have to create a new class that implements the ScalarFunction
interface in com.risingwave.functions
and implement exactly one evaluation method named eval(...)
. This method must be declared public and non-static.
Any data type listed in Data type mapping can be used as a parameter or return type of an evaluation method.
Here’s an example of a scalar function that calculates the greatest common divisor (GCD) of two integers:
DIFFERENCES WITH FLINK
- The
ScalarFunction
is an interface instead of an abstract class. - Multiple overloaded
eval
methods are not supported. - Variable arguments such as
eval(Integer...)
are not supported.
Table functions
A user-defined table function maps zero, one, or multiple scalar values to one or multiple rows (structured types).
In order to define a table function, you have to create a new class that implements the TableFunction
interface in com.risingwave.functions
and implement exactly one evaluation method named eval(...)
. This method must be declared public and non-static.
The return type must be an Iterator
of any data type listed in Data type mapping.
Similar to scalar functions, input and output data types are automatically extracted using reflection. This includes the generic argument T of the return value for determining an output data type.
Here’s an example of a table function that generates a series of integers:
DIFFERENCES WITH FLINK
- The
TableFunction
is an interface instead of an abstract class. It has no generic arguments. - Instead of calling
collect
to emit a row, theeval
method returns anIterator
of the output rows. - Multiple overloaded
eval
methods are not supported. - Variable arguments such as
eval(Integer...)
are not supported. - In SQL, table functions can be used in the
FROM
clause directly.JOIN LATERAL TABLE
is not supported.
3. Start a UDF server
Run the following command to create a UDF server and register for the functions you defined.
Run the following command start the UDF server.
The UDF server will start running, allowing you to call the defined UDFs from RisingWave.
4. Declare your functions in RisingWave
In RisingWave, use the CREATE FUNCTION command to declare the functions you defined.
Here are the SQL statements for declaring the two UDFs defined in step 3.
5. Use your functions in RisingWave
Once the UDFs are created in RisingWave, you can use them in SQL queries just like any built-in functions. For example:
Data type mapping
The RisingWave Java UDF SDK supports the following data types:
SQL Type | Java Type | Notes |
---|---|---|
BOOLEAN | boolean, Boolean | |
SMALLINT | short, Short | |
INT | int, Integer | |
BIGINT | long, Long | |
REAL | float, Float | |
DOUBLE PRECISION | double, Double | |
DECIMAL | BigDecimal | |
DATE | java.time.LocalDate | |
TIME | java.time.LocalTime | |
TIMESTAMP | java.time.LocalDateTime | |
INTERVAL | com.risingwave.functions.PeriodDuration | |
VARCHAR | String | |
BYTEA | byte[] | |
JSONB | String | Use @DataTypeHint(“JSONB”) String as the type. See example. |
T[] | T’[] | T can be any of the above SQL types. T’ should be the corresponding Java type. |
STRUCT<> | user-defined class | Define a data class as the type. See example. |
Example - JSONB
Create the function in RisingWave
Example - Struct type
Create the function in RisingWave