Last updated February 4, 2019 at 7:00PM.
Adding new functions to NanoDB is straightforward. NanoDB provides a number of classes for implementing various kinds of functions, which will then be available to use in SQL queries. These classes are in the edu.caltech.nanodb.functions package.
If you want to create a "simple" function that takes zero or more arguments and returns a single value, then you will create a subclass of the SimpleFunction class.
If you want to create an aggregate function, which consumes a sequence of zero or more values and then produces a single aggregate result, then you will create a subclass of the AggregateFunction class.
Currently, NanoDB only supports aggregate functions that take a single argument. All common aggregate functions only take a single argument.
If you want to create a function that returns a tuple-sequence, you will create a subclass of the TableFunction class.
The FunctionDirectory class (also in the functions package) specifies the mapping of function names used in SQL queries, to the actual function classes that implement the operation in Java. A few special conversions are used for function names.
Function names are always capitalized. If the user specifies "cos(x)" then the function name will be converted to "COS(x)".
If an aggregate function supports the DISTINCT keyword (e.g. "count(distinct x)"), the parser converts this to the name "...#DISTINCT" (e.g. "COUNT#DISTINCT"). Aggregates can specify whether they support the DISTINCT keyword with the AggregateFunction.supportsDistinct() method, but functions must also have a mapping from the "...#DISTINCT" name to the function class to support DISTINCT properly.
If an aggregate function supports * as an argument (e.g. "count(*)"), the parser converts this to the name "...#STAR" (e.g. "COUNT#STAR"). Note that the function will still receive a single argument for the wildcard specifier, even though the name also indicates the function's operation.
Make sure that you do not give your function the same name as a SQL keyword. The NanoDB parser cannot handle such circumstances.
Here are the steps for implementing your function.
Implement a class for your function in the edu.caltech.nanodb.functions package. You can name the class whatever you want, but follow the pattern in this package and choose a name that clearly indicates the purpose of the function. Make sure to subclass the appropriate function base-class (see above), based on what your function needs to do.
There are many good examples in the functions package for you to base your implementation off of. For example, you can look at the If class implementation, which provides a SQL function "IF(cond, expr1, expr2)".
Make sure to report an error if your function doesn't receive the correct number of arguments, or the correct types of arguments. These errors are reported directly to the user, and are essential to give users guidance as to the correct usage.
Once you have completed your function class implementation, add it to the FunctionDirectory class, which is used to store and look up all available functions. You will do this in the initBuiltinFunctions() method.
Note that functions are grouped by type, and are in alphabetical order. Simple functions come first, then aggregate functions, and then finally table functions.
If you created an aggregate function that works with or without DISTINCT, make sure you create two entries, one for each usage pattern. (See the COUNT and AVG functions, for example.)
Make sure to use an "ALLCAPS" name for your function, since the parser will convert the function name to all-capital letters before trying to resolve it against the FunctionDirectory.
Once you have completed these steps, your new function should be available for use within NanoDB.