The first step is to download and unpack the kit:

For example, the following command unpacks the utility to a folder in your home directory:

$ tar -zxvf voltdb-ml-v1.0.tar.gz -C $HOME

You can run the voltml utility by itself directly from the installation folder, with or without a full VoltDB database installation. Alternately, you can copy the files for the machine learning utility into an existing VoltDB installation. This option is useful if you install voltml on an existing VoltDB server because:

To install voltml into an existing VoltDB installation after unpacking the kit, simply copy the contents of the /bin and /lib folders into the /bin and /lib folders of the VoltDB installation. For example, if voltml is unpacked into ~/voltdb-ml-v1.0 and VoltDB is installed in ~/voltdb, you can add voltml to the VoltDB installation with the following shell commands:

$ cd ~/voltdb-ml-v1.0
$ cp -r ./lib ~/voltdb/
$ cp -r ./bin ~/voltdb/

The second step is to prepare the VoltDB servers that will be using the resulting user-defined function. To do this, copy the following files from the /lib directory where voltml is installed into the /lib directory where VoltDB is installed on all of the servers that will be participating in the VoltDB database cluster:

For example, if voltml is installed in ~/voltml on one node of a three node VoltDB cluster (svr1, svr2, and svr3) where VoltDB is installed in ~/voltdb, the following command prepares the servers:

$ cd ~/voltml/lib
$ cp * ~/voltdb/lib/
$ scp * srv2:voltdb/lib/
$ scp * srv3:voltdb/lib/

Note that you must copy the files to all of the VoltDB servers in the cluster before starting the database.

To compile your PMML model, use the voltml command. If you installed the utility separately, you can set default to the directory where it is installed and run the command from the /bin directory as bin/voltml. If you copied the installation files into an existing VoltDB installation, so the command is in your PATH, you can use the voltml command from anywhere on the system.

In either case, enter the command and specify the location of your model PMML file as an argument. For example:

$ cd ~/voltdb-ml-1.0
$ bin/voltml mymodel.pmml

Or:

$ cd /dev/workspace
$ voltml mymodel.pmml

By default, the utility compiles the model and creates a JAR file, with the same name as the model file, containing the JAVA class for a user-defined function (UDF). The UDF uses the same name, "mymodel" in this example, for both the class and the method. For example "Mymodel.mymodel".

If you want the UDF to have a different name, you can use the -n or --name flag to specify an alternate name. For example, the following command creates a class and method named "Colormatch.colormatch". Note that class and Method names are case sensitive. voltml starts by converting the implied name to all lower case and then puts an initial capital on the class name.

$ voltml --name="colormatch" mymodel.pmml

You can also rename the output file using the -o or --outputjar flag. For example, the following example creates the UDF class as Mymodel, but creates the output JAR file as myudf.jar:

$ voltml --outputjar="myudf.jar" mymodel.pmml

Table 1, “Arguments to the voltml Command” summarizes the allowable arguments to the voltml command.

Once you compile your model into a user-defined function (UDF), you are ready to load and define the UDF in the VoltDB database. Use the sqlcmd utility to perform this task using the LOAD CLASSES and CREATE FUNCTION statements that voltml displays when it completes its processing. You can just copy and paste the statements into sqlcmd:

$ sqlcmd
> LOAD CLASSES mymodel.jar;
> CREATE FUNCTION mymodel FROM METHOD Mymodel.mymodel;